release: v0.2.0 - #4

README.md was a one-line stub since the initial commit. Replace it with
the pitch, the four operations, a per-harness install table linking each
adapter's README, the no-agent create --interactive path, MVP scope
(linking the two ADRs that define it), and a pointer to AGENTS.md.

Add examples/quickstart.md: a full INIT -> RECORD -> CHECK walkthrough
against a small example service, including a real constraints: rule
that CHECK catches a violation of and then confirms clears after a fix.
Every command and JSON block in it is real output from actually running
the commands in a scratch repo, not written from memory.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8

Mark the README-stub item done in improvements.md's Open list, and add
a changelog entry for the v0.1.0 release, Git Flow adoption, the
dogfooded ADRs, and the new README/quickstart example.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8

Task-by-task implementation plans (subagent-driven-development
artifacts: exact code snippets, TDD steps, agent review process) add
little ongoing reference value now that the code itself is the source
of truth, and their volume (6700+ lines across 4 files) would clutter
a first-time visitor's browse of the repo once it goes public.

Kept: docs/superpowers/specs/ — the design spec, which explains product
decisions the way docs/decisions/'s ADRs do, and is genuinely useful to
a reader. Untracked, not deleted: the plan files stay on disk locally
and are still recoverable from git history before this commit; only
future changes stop being tracked.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8

Missed staging this alongside the untrack commit (57d0481) — without
it, the plan files would just get re-added on the next git add -A.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8

Add .DS_Store (found one already loose on disk, uncommitted — this
would have been swept up by the next git add -A), Python virtualenv
directories, editor/IDE folders, .env/.env.*.local (never commit real
credentials), and coverage/build artifacts. None of these are present
in the tracked tree today; this is preventive.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8

Dogfood the ADR toolkit, write README/examples, clean up gitignore

Adds repository-configured eight-locale ADR generation with strict
config/schema validation, portable Unicode filenames with an approved
semantic ASCII slug, closes several CHECK false-clean gaps, and makes
repository-scoped commands resolve relative paths from --root instead
of the caller's CWD. Includes updated docs, the dogfooded ADR history
(ADR-0006 superseding ADR-0003), and the Korean v0.2.0 readiness and
enterprise-adoption reports with local release evidence.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

A manifest that keeps its file but loses its "version" key was silently
skipped by --check, so CI would report no drift even after the tracked
key vanished. A manifest path outside the repo root crashed
require_known_paths() with an unrelated ValueError instead of its
intended SystemExit. JSON writes escaped non-ASCII manifest content
instead of preserving it, which regresses this project's own
multilingual metadata.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

sync_version.py --check reads repository content only; its result
cannot vary by OS or Python interpreter. Running it identically on all
5 pytest matrix legs wasted CI minutes for no additional coverage.
Split it into its own single-run job instead.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

related, index, validate, and check each redefined the same SKIP_FILES
set and re-walked the ADR directory with their own glob/skip/parse
loop. Extract core.adr_directory.iter_adr_files as the single source
of truth for "which files in this directory are candidate ADRs,"
while each command keeps its own bad-filename and frontmatter-error
handling, since those differ deliberately (validate reports a bad
filename as an error; the others skip it silently).

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Re-verified end to end against Codex CLI 0.151.0 with no
adapters/codex/skills/ symlink present at all: codex plugin marketplace
add + codex plugin add + preflight --json all still succeed, because
registering the repo root resolves .claude-plugin/plugin.json as the
plugin manifest, whose sibling skills/ is the real package. Install
step 1 (create that symlink) was therefore dead documentation from an
earlier design plan. Removed it from the install flow and added a
section explaining that .codex-plugin/plugin.json and its symlink are
structural-only, kept for consistency with the other adapters rather
than exercised by the verified path.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Manifest descriptions had drifted the same way versions once did:
.claude-plugin/plugin.json was missing "and existing decisions" that
SKILL.md and the three adapter manifests all carried. Extend
sync_version.py to treat SKILL.md's frontmatter description as
canonical and sync it into every duplicating manifest, with --check
enforcing it the same way version drift already is. Fixes the one
real drift this uncovered.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Every subcommand parsed --json but main() always printed JSON
regardless, matching its own "JSON-only-stdout contract" comment and
every existing test/doc caller. Rather than inventing a human-readable
mode or dropping the flag as a breaking change, made that existing
behavior the deliberate, documented contract: centralized the 14
duplicated --json argument definitions into one helper with clear
--help text, added a regression test proving output is JSON with or
without the flag, and added --json to the three doc examples that had
omitted it.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Same key-set-equality contract test_locale.py already enforces for
every other generated-index string.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

BROKEN_SUPERSESSION_LINK for a dangling target, SUPERSESSION_MISMATCH
for a one-sided edit -- exactly what adr.py supersede's atomic write
normally prevents. Both are errors, matching BROKEN_RELATED_LINK's
existing severity; validate.py has no warnings mechanism and this
doesn't add one for two checks. Verified against this repository's
real 10 ADRs: ok, no errors.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Every shown command was run in a scratch repository first; example
output is real, not hand-written.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

…tion

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

improvements.md gets the full Done entry, project-roadmap.md's "ADR
navigation and scale" item is split into a done bullet (search +
relationship visibility) and three still-deferred ones (rendered
graph, 500+-scale sharding/real search index, semantic retrieval),
and handoff.md reflects the feature as complete with the P0 release
gate as the only remaining open item.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

find_cycles() walks only "supersedes" edges (not "related", which is
symmetric and has no logical cycle concept) via DFS, returning each
cycle's node path. validate.py reports SUPERSESSION_CYCLE, matching
the existing error-only contract. Verified against this repository's
real 10 ADRs: ok, no errors.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

--id combines with other filters via the same AND policy as
keyword/tags/status/path, rather than a separate short-circuit path,
keeping search's combination semantics uniform across every filter.
Verified against a real ADR in this repository.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

README's Search section documented the command but not the design
rationale. Added it: checked how npryce/adr-tools (no search, expects
grep) and log4brains (1.5k+ stars, most-adopted actively maintained
ADR tool, still flat storage + search/graph layered on top) handle
this before deciding. The corollary this repo follows is that
retrieval, not storage layout, is where a growing ADR set gets harder
to use -- folder sharding, a rendered relationship graph, and a real
search index stay deliberately deferred in project-roadmap.md until
ADR count actually demonstrates the need.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

…ault

Windows CI failed test_uncommitted_mode_preserves_unicode_untracked_path_and_content:
a Unicode filename round-tripped through subprocess.run(..., text=True)
without capture as garbage on windows-latest (both 3.9 and 3.12), while
macOS/Ubuntu passed. Root cause: without an explicit encoding=, Python
decodes subprocess output using the platform's preferred locale
encoding, which is UTF-8 on macOS/Linux but not guaranteed on Windows
-- git itself always writes UTF-8. Added encoding="utf-8" to every git
subprocess.run() call in diff.py and git_paths.py. Pre-existing bug
from earlier CHECK-correctness work in this branch; only surfaced now
because this branch's CI had never run before this PR.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

…al gates

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Owner-approved minor release version bump. skills/adr-toolkit/VERSION
is the source of truth; scripts/sync_version.py propagated it to
every manifest that duplicates it (.claude-plugin/plugin.json,
adapters/gemini-cli/gemini-extension.json, SKILL.md's frontmatter).

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

Recorded everything completed this session (ADR search/relationships,
CHECK confidence/exceptions, --json contract, sync_version hardening,
Windows encoding fix, v0.2.0 bump) in changelog.md, which already
serves as this project's durable human-readable history per AGENTS.md.
improvements.md's Done section and handoff.md's long commit-by-commit
walkthrough are redundant with that plus git log, so both are trimmed
to current/active state only -- nothing is lost, it's consolidated
into the file whose stated purpose is exactly this record.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01CeDZgjQakpnGGtsWoC7ijF

…heck-confidence

v0.2.0: multilingual ADR generation, CHECK hardening, and ADR search/relationships

Regenerates docs/decisions/README.md and relationships.mmd/svg to include
ADR-0011, and updates handoff.md with verification results (395 tests,
11 ADRs validated, 6 graph edges) ahead of PR follow-up.

ADR-0011 brought the count to 11; the navigation-and-scale note still
referenced 10.

Baseline open-source hygiene ahead of the repository going public:
a Code of Conduct with report/enforcement contact matching SECURITY.md's
convention, and bug report / feature request issue templates scoped to
this project's commands and existing roadmap/improvements tracking.

Re-ran the same validate/install/list/script-layer checks documented for
the Codex and Gemini CLI adapters, this time against the agy CLI, which is
in fact available in this environment (contrary to the prior README note).
All three script commands (preflight, init, validate) returned "ok": true
from the agy-installed snapshot in an isolated HOME, closing the one real
Harness parity gap: Antigravity was the only adapter with no end-to-end
verification on record.

Existing tests only check that adapter manifests are schema-valid JSON;
nothing catches an upstream CLI change or a manifest edit that breaks real
installation. This job installs the real Codex CLI (0.151.0) and Gemini
CLI (0.46.0) -- the exact versions manually verified in adapters/codex and
adapters/gemini-cli's READMEs -- and drives their own plugin/extension
commands (marketplace add, install, list) against this repo, then runs
preflight/init/validate from the installed snapshot and asserts "ok":
true on each. Every step was dry-run locally against those exact CLI
versions before landing this.

Antigravity CLI (agy) has no npm/package-registry distribution, so it
stays a manually verified adapter only per adapters/antigravity/README.md.

project-roadmap.md's Harness parity section now reflects that Codex/Gemini
CLI install verification is automated in CI; the remaining gaps are
extending coverage past preflight/init/validate and automating Antigravity
once it has an installable distribution. handoff.md rewritten to describe
what this session actually did instead of the stale ADR-0011-in-progress
state, and flags that harness-parity has only run locally, never on a real
GitHub Actions runner yet.

Codex CLI and Gemini CLI now both have stable hook extension points
(hooks.json SessionStart/UserPromptSubmit; gemini hooks migrate), so the
roadmap item's precondition is technically satisfied. Decided not to
pursue it anyway: ADR Toolkit doesn't use a hook even on Claude Code today
(pure skill auto-discovery), an always-on session hook cuts against the
project's own minimal-interruption principle, and the plausible use cases
are already covered by deliberately invoking discover/check. Recorded so
the same discussion doesn't have to happen again from scratch.

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