ADR relationship graph, public readiness docs, and harness-parity CI

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Report a defect in ADR Toolkit
+title: ""
+labels: bug
+---
+
+## Summary
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Environment
+
+- Harness: Claude Code / Codex CLI / Gemini CLI / Antigravity CLI / generic / other
+- ADR Toolkit version (`skills/adr-toolkit/VERSION`):
+- OS:
+
+## Relevant Output
+
+Paste the command and its output, including `--json` output where
+applicable.
+
+```
+```
+
+## Scope
+
+- [ ] This affects `adr.py validate`, `create`, `index`, `check`, `graph`,
+      or `search`.
+- [ ] This affects a specific harness adapter (Codex, Gemini CLI,
+      Antigravity, or generic).

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Propose new functionality for ADR Toolkit
+title: ""
+labels: enhancement
+---
+
+## Problem
+
+What are you trying to do that ADR Toolkit does not support today?
+
+## Proposed Solution
+
+## Alternatives Considered
+
+## Additional Context
+
+- [ ] I checked `project-roadmap.md` and `improvements.md` for existing
+      plans that already cover this.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+- 
+
+## ADR Impact
+
+- [ ] I checked whether this changes an accepted architectural decision.
+- [ ] I linked related ADRs, or this PR has no ADR impact.
+- [ ] I ran `adr.py check` when the change touches governed paths.
+
+Related ADRs:
+
+## Verification
+
+- [ ] `python3 -m pytest -q`
+- [ ] `python3 scripts/sync_version.py --check`
+- [ ] `python3 skills/adr-toolkit/scripts/adr.py validate --dir docs/decisions --json`
+- [ ] `python3 skills/adr-toolkit/scripts/adr.py index --dir docs/decisions --json`
+
+## Notes
+
+- 

.github/workflows/test.yml

@@ -42,3 +42,56 @@ jobs:
           python-version: "3.12"
       - name: Check manifest versions and descriptions are in sync
         run: python scripts/sync_version.py --check
+
+  harness-parity:
+    # Installs the real Codex CLI and Gemini CLI and drives their own plugin
+    # commands against this repo, the same way a contributor would. Manifest
+    # JSON shape is already covered by tests/unit/test_*_adapter.py; this job
+    # instead proves discovery -> install -> list -> the installed skill
+    # package's script layer still runs, so an upstream CLI change or a
+    # manifest edit that breaks real installation fails CI instead of
+    # surfacing later as a user-reported install failure. Antigravity CLI
+    # (agy) has no public package registry distribution, so it stays a
+    # manually verified adapter only -- see adapters/antigravity/README.md.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Codex CLI
+        run: npm install -g @openai/codex@0.151.0
+      - name: Install Gemini CLI
+        run: npm install -g @google/gemini-cli@0.46.0
+      - name: Verify Codex CLI adapter end to end
+        run: |
+          set -euo pipefail
+          export CODEX_HOME="$(mktemp -d)"
+          REPO_ROOT="$(pwd)"
+          codex plugin marketplace add "$REPO_ROOT"
+          INSTALLED_PATH="$(codex plugin add adr-toolkit@adr-toolkit-marketplace --json | jq -r '.installedPath')"
+          codex plugin list
+          SCRATCH="$(mktemp -d)"
+          cd "$SCRATCH" && git init -q
+          python3 "$INSTALLED_PATH/skills/adr-toolkit/scripts/adr.py" preflight --json | jq -e '.ok == true'
+          python3 "$INSTALLED_PATH/skills/adr-toolkit/scripts/adr.py" init --dir docs/decisions --json | jq -e '.ok == true'
+          python3 "$INSTALLED_PATH/skills/adr-toolkit/scripts/adr.py" validate --dir docs/decisions --json | jq -e '.ok == true'
+      - name: Verify Gemini CLI adapter end to end
+        run: |
+          set -euo pipefail
+          REPO_ROOT="$(pwd)"
+          mkdir -p adapters/gemini-cli/skills
+          ln -s "$REPO_ROOT/skills/adr-toolkit" adapters/gemini-cli/skills/adr-toolkit
+          export HOME="$(mktemp -d)"
+          gemini extensions validate "$REPO_ROOT/adapters/gemini-cli"
+          printf 'y\ny\n' | gemini extensions install "$REPO_ROOT/adapters/gemini-cli" --consent
+          gemini extensions list
+          INSTALLED_PATH="$HOME/.gemini/extensions/adr-toolkit"
+          SCRATCH="$(mktemp -d)"
+          cd "$SCRATCH" && git init -q
+          python3 "$INSTALLED_PATH/skills/adr-toolkit/scripts/adr.py" preflight --json | jq -e '.ok == true'
+          python3 "$INSTALLED_PATH/skills/adr-toolkit/scripts/adr.py" init --dir docs/decisions --json | jq -e '.ok == true'
+          python3 "$INSTALLED_PATH/skills/adr-toolkit/scripts/adr.py" validate --dir docs/decisions --json | jq -e '.ok == true'

CODE_OF_CONDUCT.md

@@ -0,0 +1,44 @@
+# Code of Conduct
+
+## Our Standard
+
+Participation in this project — issues, pull requests, discussions, and
+reviews — is expected to stay respectful and focused on the technical
+problem. Disagreement about a decision or an approach is normal; personal
+attacks, harassment, discriminatory language, or deliberately derailing a
+discussion are not.
+
+## Expected Behavior
+
+- Assume good faith and give reviewers/contributors the benefit of the
+  doubt.
+- Keep feedback specific to the code, design, or decision under
+  discussion.
+- Accept that maintainers may decline a change and explain why, without
+  that being an invitation to escalate.
+
+## Unacceptable Behavior
+
+- Harassment, insults, or discriminatory remarks directed at a person
+  rather than their contribution.
+- Publishing others' private information without consent.
+- Sustained disruption of issues, pull requests, or reviews.
+
+## Reporting
+
+Report a violation privately to the repository owner rather than escalating
+in a public issue or pull request thread. Include what happened, where
+(link to the issue/PR/comment), and when.
+
+## Enforcement
+
+The repository owner reviews reports and may edit or remove content, warn a
+participant, or restrict further participation in the project's spaces,
+proportional to the violation. Enforcement decisions are not owed a public
+explanation when doing so would expose reporter identity or private
+details.
+
+## Scope
+
+This applies to all project spaces (issues, pull requests, discussions,
+commits, and comments) and to representing the project in public spaces.

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for helping improve ADR Toolkit. This project is intentionally small:
+the agent can reason and draft, but deterministic scripts own file writes,
+IDs, lifecycle transitions, validation, indexes, and machine-readable output.
+
+## Branches
+
+Follow the repository policy in `AGENTS.md`.
+
+- Branch from `develop` for normal work.
+- Use `feature/*`, `fix/*`, or `docs/*` for short-lived work branches.
+- Merge normal work back to `develop` through a pull request.
+- Release branches merge to `master` and back to `develop`.
+- Tags named `v*` are created only from `master`.
+
+## Local Checks
+
+Run the relevant checks before opening a pull request:
+
+```bash
+python3 -m pytest -q
+python3 scripts/sync_version.py --check
+python3 skills/adr-toolkit/scripts/adr.py validate --dir docs/decisions --json
+python3 skills/adr-toolkit/scripts/adr.py index --dir docs/decisions --json
+```
+
+For changes that may affect accepted architectural decisions, also run:
+
+```bash
+python3 skills/adr-toolkit/scripts/adr.py check --uncommitted --dir docs/decisions --json
+```
+
+## ADR Changes
+
+- Keep ADR source files flat under `docs/decisions/`.
+- Do not hand-edit generated indexes or lifecycle links to repair validation
+  errors. Change the source ADR or use the lifecycle command.
+- Use `adr.py create`, `status`, `deprecate`, `supersede`, and `exception` for
+  deterministic mutations.
+- Accepted ADRs are append-only in spirit: use supersession for changed
+  decisions instead of rewriting history.
+
+## Public Repository Hygiene
+
+Public repository branch/tag protection is expected to enforce PRs, required
+checks, conversation resolution, and force-push/deletion restrictions on
+`develop`, `master`, and `v*` tags once the repository is public.

README.md

@@ -190,6 +190,26 @@ untruncated count and `truncated` is `total > count`.
 from `related` (used during RECORD's DISCOVER stage to find precedent for a
 *new* draft, with a broader OR-across-fields match).
 
+## Relationship graph
+
+`index` embeds a Mermaid relationship graph in `docs/decisions/README.md`
+whenever ADRs have `related` or `supersedes` links, so GitHub can render the
+navigation view directly.
+
+For a standalone graph artifact, export Mermaid and SVG files:
+
+```bash
+python skills/adr-toolkit/scripts/adr.py graph --dir docs/decisions --format both --json
+```
+
+This writes `docs/decisions/relationships.mmd` and
+`docs/decisions/relationships.svg`. SVG is the default image artifact because it
+stays sharp when zoomed and does not require Mermaid CLI, Node, or a browser.
+With `--format both`, `--output build/adr-relationships` is treated as a file
+prefix and writes `build/adr-relationships.mmd` plus
+`build/adr-relationships.svg`; relative output paths are resolved from
+`--root`, matching the other repository-scoped commands.
+
 ### Why storage stays flat
 
 ADRs live as `NNNN-slug.md` in one flat `docs/decisions/` directory — no

SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes target the latest released version of ADR Toolkit.
+
+## Reporting a Vulnerability
+
+Please report security issues privately to the repository owner before opening a
+public issue. Include:
+
+- affected version or commit
+- reproduction steps
+- expected impact
+- whether the issue affects generated ADR content, command execution, path
+  handling, release automation, or plugin installation
+
+Do not include exploit details in a public issue until a fix or mitigation is
+available.
+
+## Scope
+
+In scope:
+
+- command injection or unsafe path handling in deterministic scripts
+- release workflow or version provenance problems
+- plugin manifest behavior that can install or expose unintended files
+- validation bugs that silently report clean results for invalid ADR state
+
+Out of scope:
+
+- disagreement with an ADR's architectural recommendation
+- AI-generated prose quality
+- unsupported third-party harness behavior outside this repository's adapters

adapters/antigravity/README.md

@@ -3,6 +3,9 @@
 Antigravity plugins are a `plugin.json` marker file plus optional sibling
 directories (`skills/`, `agents/`, `rules/`), per
 `antigravity.google/docs/cli/plugins/`. This manifest needs only `name`.
+**Manually verified against Antigravity's `agy` CLI 1.1.13** (`agy
+--version`): validate, install, and discovery all work — see "Verification
+status" below.
 
 ## Install
 
@@ -14,18 +17,62 @@ directories (`skills/`, `agents/`, `rules/`), per
    ln -s "$(pwd)/skills/adr-toolkit" adapters/antigravity/skills/adr-toolkit
    ```
 
-2. Install per Antigravity's own plugin-install documentation.
-3. Confirm Antigravity lists `adr-toolkit`, then run
+2. Install with Antigravity's own plugin CLI:
+
+   ```bash
+   agy plugin install "$(pwd)/adapters/antigravity"
+   ```
+
+3. Confirm Antigravity lists `adr-toolkit`:
+
+   ```bash
+   agy plugin list
+   ```
+
+4. Either way, run
    `python skills/adr-toolkit/scripts/adr.py preflight --json` from your
    target repository to confirm the script layer works standalone.
 
-**Verification status:** this adapter's manifest and directory layout are
-verified against Antigravity's published schema, but — unlike the Codex
-and Gemini CLI adapters — no end-to-end install-and-run was performed,
-because no `antigravity` CLI binary was available in the development
-environment that built this adapter. Treat it as unverified until someone
-with the actual CLI confirms it, and update this note when they do.
-
 The symlink is created at install time, not committed to this repo —
 committing a real symlink breaks on Windows checkouts that don't have
 `core.symlinks` enabled, which this project's CI can't assume.
+
+## Verification status
+
+Manually verified against Antigravity's `agy` CLI 1.1.13 (`agy --version`)
+in an isolated `HOME=$(mktemp -d)` so no state was written to the real
+`~/.gemini` (Antigravity's plugin CLI stores state under `.gemini/config/`
+in the active home directory).
+
+```
+$ agy plugin validate "$(pwd)/adapters/antigravity"
+  [ok]    <repo-root>/adapters/antigravity
+          [check] skills      : 1 processed
+          - agents      : skipped (not found)
+          - commands    : skipped (not found)
+          - mcpServers  : skipped (not found)
+          - hooks       : skipped (not found)
+
+$ agy plugin install "$(pwd)/adapters/antigravity"
+  [ok]    adr-toolkit
+          [check] skills      : 1 processed
+
+$ agy plugin list
+{
+  "imports": [
+    {
+      "name": "adr-toolkit",
+      "source": "antigravity",
+      "importedAt": "2026-08-31T06:11:34Z",
+      "components": ["skills"]
+    }
+  ]
+}
+```
+
+The installed snapshot lands under `<HOME>/.gemini/config/plugins/adr-toolkit/`
+and carries the whole `skills/adr-toolkit/` package. The script layer was
+run directly out of it against a scratch git repository, producing correct
+`"ok": true` output for `preflight`, `init --dir docs/decisions`, and
+`validate --dir docs/decisions` — matching the Codex and Gemini CLI
+adapters' verified depth.