v0.7.1 — Honest Graph

Patch release for the 0.7.0 knowledge graph. Every fix was verified on a real external project before release: 23 scenarios against the published 0.7.0 — 15 measured improvements, 0 regressions.

Heads-up: asking for the graph over MCP without a focus now returns a compact summary (~2KB) instead of the whole graph (measured 351KB in a single reply). Pass a query for a neighborhood; clad graph export still dumps everything.

Fixed

▸ The after-edit impact card actually appears now. Editors send absolute file paths and the lookup expected relative ones, so the card never rendered in real use. Measured on a real project: 0.7.0 printed nothing — 0.7.1 prints "breaks 63 features · run 83 tests".

▸ Folders that don't use cladding are left alone. A session in a non-cladding folder (or a subfolder of your project) used to get blocked once and a stray .cladding/ folder written into it. Now: silence, nothing written.

▸ Shared files report their full blast radius. A file owned by several features only counted the first one — a real hub file reported 1 regression test where the truth was 125. The answer still fits its token budget and says what it left out.

▸ Failures look like failures. A broken spec gets a 503 with a JSON error instead of a 200 with prose; a busy port prints one clean line instead of a stack trace; a gate that could not run says "unavailable" instead of pretending it passed; a typo'd --format fails loudly instead of silently picking mermaid.

▸ Numbers are honest. clad measure now attributes its "N× smaller context" to the token budget doing the capping, and reports the structural number separately.

Added

▸ The graph says "unknown" instead of "safe". On a freshly adopted project with no declared dependencies, an empty impact answer used to look identical to "verified: nothing breaks". Answers now include the project-wide edge counts, and an empty ledger adds a plain hint: this means unknown — fall back to normal search and run the full suite.

Also

▸ Older feature ids (F-001 style) are visible to the doc graph again · re-exports and dynamic imports now produce dependency edges · three source files that git treated as binary are reviewable again · diagram labels escape their special characters · 0.7.0 release-note claims that described an unshipped prototype were corrected.

Full changelog: 0.7.0...v0.7.1 · Install: npm install -g cladding@0.7.1

v0.7.0 — Knowledge Graph

A knowledge graph over your spec, code, tests, and docs — see it, ask what a change
breaks, measure the context a task needs. Plus two gate upgrades. Minor and additive;
no existing command changes behavior.

Added

• Knowledge graph (#222) — clad graph serve / export to see it, clad impact / clad context to query it, clad measure for context efficiency; a doc-link integrity check; clad infer-deps.
• EARS complex pattern (#208) — the 6th canonical requirement shape (while-precondition + when-trigger), both clauses validated.
• UNVERIFIED_AC detector (#204) — confirms a done AC's tests actually ran and passed (multi-framework JUnit); silent when no report.

Changed

• All four READMEs reworked — enterprise hero, a project-map section with a live graph preview, flat blue-token diagrams, trimmed prose.

---

40 detectors · 199 features (195 done) · 1665/1665 tests · full gate green.

Install: npm install -g cladding · Upgrade: npm update -g cladding

v0.6.3 — Honest Status

In one line: the feature index can no longer lie about a feature's status, and Kotlin Gradle monorepos get a module-scoped gate with selectable Kover/JaCoCo coverage.

Heads-up: nothing breaks for a project that's already green. The status fix closes a case where a finished feature kept reading in progress in spec/index.yaml until the next clad sync. The Kotlin gate is opt-in and backward-compatible — non-Gradle projects, features with no modules[], and gate.scope: repo all behave exactly as before.

Added

▸ Module-scoped gate for Kotlin Gradle monorepos — when a focus feature declares modules[], the command stages (type / lint / unit / coverage) run only that feature's Gradle projects instead of the root aggregate. clad done <id> scopes automatically; clad check --feature <id> opts a manual run in; plain clad check stays whole-repo (CI unchanged). Module paths map to Gradle project paths by walking up to the nearest build.gradle[.kts] + gradle.properties ancestor (worker/agg/app → :worker:agg:app), de-duplicated and run in a single batched ./gradlew :a:test :b:test … invocation. An unmappable path fails loudly — never a silent whole-repo fallback.

▸ Selectable Kotlin coverage (Kover | JaCoCo) — chosen by .cladding/config.yaml gate.coverage (explicit), else auto-detected Kover (root build / settings / version catalog / buildSrc), else JaCoCo. The choice sets both the Gradle task and the report path COVERAGE_DROP reads; scoped runs merge each module's line counters into one aggregate.

▸ First-class Kotlin toolchain — Gradle detection (requires .kt/.kts, so a .java-only Gradle repo is not treated as Kotlin) + Kotlin-aware detectors. Optional gate.{scope,commands} config with a {modules:TASK} token.

(Kotlin work contributed by Hyunsoo Kwon — #188.)

Fixed

▸ clad done keeps the feature index honest — on a kept flip the spec/index.yaml row becomes done immediately (no clad sync needed); on a reverted flip it re-syncs back. The refresh runs before the gate, so the new status-aware check can't red the flip's own write.

▸ The staleness check compares each row's status, not just the id set — a done shard with an in_progress index row is now caught instead of passing clad check --strict green. Both sides default to planned and strip quotes, so a status-less or quoted shard never false-flags. (F-37b4a8)

Verified

▸ typecheck + lint clean · 1500 tests green · full strict pre-push gate green · 37 detectors / 15-stage gate.
▸ External real-terminal verification — a 4-arm Python(control) / Kotlin(treatment) A/B confirmed the module-scoped gate engages only for Gradle/Kotlin and is inert (byte-identical) on non-Gradle projects; the index-status fix was verified end-to-end (kept→done, reverted→re-sync, mismatch caught) with an A/B against 0.6.2.

Install

npm install -g cladding@0.6.3

v0.6.2 — Honest Count

[0.6.2] — 2026-06-25 — Honest Count

In one line: the published number of verification stages was wrong — it said
13 (the CLI said 14) while the gate has been running 15 all along — so this fixes
the number everywhere and makes it derive from the gate itself, so it can't
silently drift again.

Heads-up: nothing changes about how the gate runs — it already ran all 15
stages. Only the advertised count was off; no project behaves differently.

Fixed

• The advertised stage count (13 → 15). The Claude Code manifest's stage list
  was missing two stages the gate actually runs — spec-conformance and
  deliverable-smoke — so it claimed 13; the CLI --tier help said 14; the README
  said 15. Every surface now agrees on 15. Check-instruction examples
  ("13/13 stages clean") now read "15-stage gate green" — on a clean tree the
  gate shows 9 passed and 6 skipped, so a fixed "N/N" would just be wrong a
  different way.
• Two stale code comments corrected to match the code: an impl-blindness
  provenance check marked "deferred" that actually ships (it runs under an oracle
  mandate), and an architecture field said to be no longer emitted that the scan
  still emits. Plus a stale detector count in the check skill (24 → 37).

Added

• A self-check that keeps the count honest. The plugin build now derives the
  published stage list from the single list the gate actually runs, and an
  integrity check fails if any manifest disagrees. The earlier 13-vs-15 gap had
  shipped undetected because nothing guarded that list; it is now a live binding,
  not a hand-maintained number.

Changed

• Contributor flow documented as git-flow with PR-always — every merge lands
  via PR, and develop → main is always a merge commit, never a squash (a past
  squash put release commits outside develop's ancestry and phantom-conflicted
  the next release). Maintainer-facing only (CLAUDE.md).

v0.6.1 — Honest Smoke

Honest smoke — the gate now runs your program, not just checks it started
2026-06-25

Before, cladding's final check only confirmed a finished program didn't crash on startup — so a program could pass every test, start cleanly, exit 0, and still print the wrong answer, yet ship "green". This release makes the gate actually run the finished program the way a user would, check it does the right thing, and honestly say when it can't.

Heads-up: nothing breaks, but a project that only confirmed its program starts will now read amber — "ran, but not really checked" instead of green, until you tell cladding how to verify a real result (a command + the output you expect). To get a green, add a one-line check.

Added

▸ Five honest gate results — passed / failed / couldn't run here (needs a database, a device…) / needs a person to confirm / nothing to run — instead of quietly marking the unknowns green.
▸ Tell cladding how to actually exercise your app — give it a command and the result you expect; it re-runs that itself and only calls it passed when the real output matches.
▸ No silently skipping the check — a finished feature that ships a runnable program with no check is flagged, not a free pass.
▸ Lint config detection — the gate picks the linter your project actually configured (biome / oxlint) instead of always assuming eslint.

Changed

▸ "It started" is no longer "verified" — a program that merely runs without crashing now shows as ran, but not really checked (amber), and turns green only once you give it something real to verify. cladding now holds itself to this too.
▸ "Couldn't run" and "needs a person" now block — honest non-results, never a silent green.
▸ One new check — the published count was updated everywhere it appears (badge, docs, diagrams) and the comparison reports refreshed.

Fixed

▸ The real bug: "passes its tests but is actually broken." A program could ship green while the real thing it runs produced the wrong output (it started, exited cleanly, printed garbage). The gate now re-runs the real program and catches it, for the behaviors you ask it to check — verified on fresh projects and in a 3-way build against the released version, at essentially no extra cost.
▸ A finished program with no real check used to just pass — now it's flagged until you add one.

Install / upgrade: npm install -g cladding@0.6.1 (or npm update -g cladding), then clad update in your project.

v0.6.0 — Structural Harness

[0.6.0] — 2026-06-11 — Structural Harness

In one line: governance stops being a request — hooks enforce it, a committed
attestation stamps what was actually verified, the spec finally renders into
human-readable documents, and the oracle policy controls its own cost.

Added

• Host hooks (Claude Code) — the plugin ships five lifecycle hooks:
  every session starts with the spec map injected; editing status: done into
  a shard by hand is blocked (run clad done — it's earned, not written);
  ending a session on fresh gate failures is blocked once (an identical,
  unfixable failure lets you leave and resurfaces next session); drift nudges
  after edits; natural prompts get a one-line routing suggestion.
• Verification attestation — a GREEN strict pre-push gate writes
  spec/attestation.yaml (a content hash per done feature, committed). The
  new STALE_ATTESTATION detector (#36) flags shipped code that changed since
  its last verified state — on fresh clones, in CI, and across squash/rebase.
• Strict skip-policy demand table — under --strict, a skipped stage the
  spec relies on is RED: declared language + done features demand the type
  check; declared tests demand the runner; declared oracles demand the
  conformance stage; a declared-safe deliverable demands the smoke. No demand →
  skips stay green (no new false REDs).
• test_ref self-healing — clad sync repairs refs whose files moved
  (unique-basename match, anchor preserved) and suggests derived: candidates
  for unannotated done ACs. Suggestions never satisfy the gate — only removing
  the prefix (author confirmation) makes them count.
• clad changelog — the spec renders into documents: capability-grouped
  release notes, --audit (every AC with its verification refs marked
  resolved/missing), --catalog (the whole spec in plain sentences). MCP tool
  clad_changelog + a skill that renders EN+KO in this file's house style.
• clad context / clad_get_context — the working set for one feature in
  one call (focus + ancestors + scenarios + ai_hints + test_refs). Look up by
  id, slug, or module path.
• clad_run_gate — run the real gate pipeline from inside a session
  (the MCP surface could previously only run drift). Mutating MCP tools now
  return the gate state as a JSON field, and payloads carry schema_version.
• blind-author agent — test/oracle authoring with no read tools at all:
  "authored impl-blind" becomes a property of the toolset, not a promise.
• Oracle policy that binds behavior — grown projects (≥8 done features)
  get a report-only risk-weighted mandate (unwanted ACs; enforcement in
  0.7) whose report names the EARS-untagged blind spot; out-of-policy
  clad_author_oracle recordings are labeled voluntary with a cost note;
  guidance keys authoring to clad oracle --required.
• Lifecycle ledger — feature creation, every done attempt (kept or
  reverted), and every gate run land in .cladding/events.log.jsonl with the
  actor identity and git HEAD; logs rotate at 5 MB.
• spec/index.yaml — one generated line per feature: lookup is a 1-file
  grep at any scale (with merge=union friendliness and an INVENTORY_DRIFT
  staleness check).
• Enforcement triggers — clad init --with-hook installs pre-commit AND
  pre-push hooks; clad init --with-ci scaffolds the authoritative CI gate
  (fetch-depth: 0; client hooks are latency reducers, CI is where
  enforcement is real).
• Terminology SSoT — docs/glossary.md (EN + KO) locked by the test
  suite; new feature ids are 8-hex (birthday-safe at thousands of shards).
• Ops visibility polish (F-95a096) — a completion-claim utterance
  ("looks done, wrap it up", "마무리") gets a dedicated earn-path card naming
  clad done (the weakest measured engagement surface in the 0.6.0 A/B);
  clad doctor summarizes the governance ledger (gate runs + last outcome,
  done attempts/rejections, stop blocks, attestation entries) in text and
  --json; clad status gains an att column — attestation freshness per
  feature (✓ current / ! stale-or-unstamped / · n/a / - no attestation yet).

Changed

• Renames with one-release aliases (removal in 0.7): librarian → planner,
  specialists → developer, refine → clarify, panel → status,
  drive → run. The never-implemented work stub is removed.
• SDK model defaults move to the current generation with a 16k output
  ceiling; pin per-project via .cladding/config.yaml agent.model.
• A drift pass loads the spec once instead of once per detector — a
  5,000-shard gate runs in ~1.4 s (machine-enforced budget).

Fixed (found by installing 0.6.0 like a real user)

• clad sync's test_ref repair corrupted paths under the real invocation
  (cwd='.') and looped on its own output — fixed with regression tests that
  run exactly the real way.
• The gate no longer auto-installs npm packages: bare npx tsc on a
  toolchain-less machine fetched and executed the typosquat tsc@2.0.4.
  All toolchain calls are npx --no-install; an absent tool is an honest
  skip the demand table escalates.
• clad serve's banner moved off stdout (the MCP wire) to stderr.

Deprecated

• ai_hints.token_budget_per_session (never had a runtime consumer) — still
  accepted, no longer written; removal in 0.7.

Verified

• Real-user battery 31/31 on a tarball install; three-arm hard-task build
  measured (the full report: docs/benchmarks/v0.6.0-real-user-verification.md)
  — hooks halve the cost of running cladding and produced the only
  defect-free arm; honest readings included (greenfield conformance remains
  tied with vanilla; the premium buys traceability and enforcement).

v0.5.2 — fixes from installing 0.5.1 like a real user

[0.5.2] — 2026-06-08 — Fixes from installing 0.5.1 like a real user

In one line: we installed 0.5.1 the way a new user does — from npm, then through the marketplace
plugin — and fixed the rough edges that surfaced. The Claude Code plugin now works on its own without a
separate global install, a green gate no longer hides "your tests never actually ran," and several error
messages now tell you what to do instead of leaving you to guess. Nothing here changes a green build that was
already honest; it closes the gaps where green wasn't.

Added

• The gate now runs your project's actual entry point. A new check (Deliverable smoke) executes the
  deliverable you declare in spec.yaml (e.g. ./run, your CLI) once a feature is done, and fails if it
  crashes — catching the case where the code's own unit tests pass but the shipped entry point is broken
  (because the tests exercise internals and never invoke the entry). It runs only an entry you explicitly mark
  is_safe_to_smoke: true, with a timeout, and never on every commit — so it never auto-runs arbitrary code. A
  companion detector warns when a finished feature ships code but declares no deliverable to smoke-test. It
  costs nothing extra (no AI involved) — a cheap floor under the opt-in spec-conformance oracle, which still
  owns the harder "runs but produces the wrong answer."

Fixed

• The Claude Code marketplace plugin now works on its own. Installing just the plugin used to leave its
  MCP server dead unless you had also run npm install -g cladding — the server shelled out to a global
  clad that wasn't there. The plugin now ships the engine inside itself and launches it directly, so it
  works with nothing else installed. (Codex and Gemini still use the global clad; the README now says so
  plainly.)
• A green gate can no longer hide "the tests never ran." If the test runner wasn't installed, the gate
  treated the skipped test step as a pass — so a feature marked done could be entirely unverified and still
  go green. Under --strict, a done feature whose tests did not run now fails, with a message telling you
  to install the test framework.
• A missing scanner is a setup gap, not a fake "secret found." When the secret or architecture scanner
  could not run (no config on a fresh project), the gate reported it as if it had found a violation. It now
  correctly says it "couldn't scan" instead of raising a false alarm — and a scanner that genuinely finds
  something still fails the gate.
• Agent personas load on a real install. The five personas (orchestrator, librarian, reviewer,
  observability, specialists) failed to resolve when cladding ran from an npm install rather than the source
  tree; they are now shipped next to the engine and found in every run mode.
• Clearer test_ref errors. A test reference that points at a specific test inside a file
  (tests/x.test.ts#parses a tag) now resolves correctly, and when a reference really is broken the message
  lists the forms it accepts instead of only saying it "resolves to nothing."

Changed

• clad drive is marked experimental and now fails honestly. The headless autonomous loop needs an LLM
  transport that is not built yet, and nothing auto-invokes it — the supported path is host-delegated (your
  AI tool drives the per-feature cadence). A run that produces only empty stubs now says so and exits non-zero
  instead of reporting "all work complete," and clad rollback makes clear that it prints the git command for
  you to run rather than executing it itself.

v0.5.1 — A gate that can catch a hidden bug

In one line: until now, clad check went green whenever your code's own tests passed — even if the
code didn't actually do what the spec asked. 0.5.1 lets the gate run a second, independent check, written
from the spec without looking at the code, so a green gate can finally mean "this matches the spec," not
just "the author's own tests passed." It also fixes a harmless-but-alarming error that showed up in every
project, and makes writing specs a little less fiddly. Everything new here is opt-in — upgrading changes
nothing until you turn it on.

Added

• An independent "did it really match the spec?" check (opt-in). The gate can now run a spec-derived
  test suite that was written without seeing the implementation, and check the code against the spec
  rather than against the author's own assumptions — so a hidden mismatch the author's tests missed turns
  the gate red. Turn it on per project with oracle_policy (off by default). New pieces:
  clad oracle (get the spec-only brief), clad_author_oracle (record the result), the SPEC_CONFORMANCE
  gate check, and a 34th drift detector.
• Spec mistakes are caught the moment you write them. Creating a feature now rejects a malformed
  acceptance criterion right away, instead of letting you find out later when the gate fails.
• clad check --json — machine-readable gate results with the exact file, line, and suggested fix for
  each finding (no more squinting at truncated text).
• A place to write down why a decision was made. Record the reasoning behind a non-obvious choice in
  an acceptance criterion's notes (## Decision / ## Why / ## Trade-off), so a future reader doesn't
  "fix" it the wrong way. Optional — see docs/ssot-model.md.

Changed

• Less noise, cheaper turns. The in-session check returns a short summary by default (full detail on
  request), the spec context is cached between steps, and the heavy gate runs once per feature (at
  clad done) instead of repeatedly.
• You rarely need to run clad sync by hand anymore — creating a feature keeps the inventory current,
  and check / done validate on their own.

Fixed

• No more false "schema.json not found" error. Every project was hitting a spurious error about a
  missing internal file; the gate now simply skips it when absent (it was never actually required).
• A broken spec file can no longer slip through green. A malformed spec shard used to pass the gate
  silently — it now correctly fails.

v0.5.0 — No Vacuous Green

[0.5.0] — 2026-06-01 — No Vacuous Green: honest gates, the per-feature cadence, and an enforced SSoT

The theme: a gate that passes must mean the work was actually verified. This release closes a
family of "Vacuous Green" holes — places where clad check went green without checking anything —
and turns the 4-tier SSoT from an advisory model into an enforced one. It also reshapes development
around a per-feature cadence (spec → code → test → gated done → next) and gives the design tier a
real authoring path. The drift-detector set grows 28 → 33.

Added

• clad done <featureId> — the honest-done floor. status: done was just the host writing YAML,
  so a feature could be "done" while the strict gate was red. clad done flips the shard, runs
  clad check --tier=pre-push --strict with the feature evaluated as done (flip-then-gate, so the
  done-aware detectors apply), and keeps done only if GREEN — reverting otherwise. runCheckCommand
  was split into a shared runCheckStages, so the done gate is provably the check gate.
• clad update — the one-command post-upgrade reconciliation (15th CLI verb). After
  npm update -g cladding, run it from inside a project: it re-wires hosts, refreshes the
  inventory: snapshot, refreshes the cladding-managed CLAUDE.md / AGENTS.md section
  (staleness-based, your own prose preserved — never --force, never an LLM), then reports —
  without blocking or editing your spec — what the now-stricter detectors flag, so a stricter
  release can't quietly fail an unchanged project. It reconciles only the current directory (cd in
  per project) and never self-updates the engine — npm update -g cladding is the user's step.
• clad_link_capability (MCP tool #7) — the deterministic Tier-B firing path. A capability is
  accumulative, so the verb is link (upsert a feature into a capability, creating it if absent),
  not create. Establishes the authoring verb taxonomy: create an entity (feature/scenario) ·
  link a relationship (capability) · refine a document (architecture/project-context).
• Tier-B capabilities in the schema + typed Spec — spec/capabilities.yaml is now merged
  into the loaded Spec and JSON-Schema-validated at parse time (a malformed capability fails
  loadSpec), instead of being read ad-hoc by one soft detector.
• 5 new drift detectors — PLANNED_BACKLOG (#29, too many code-less planned features = the spec
  racing ahead of the code), HOLLOW_GOVERNANCE (#30, a grown project with an empty
  capabilities/architecture design tier), DEPENDENCY_CYCLE (#31, a circular depends_on graph
  that silently deadlocks the drive loop), SCENARIO_COVERAGE (#32, a grown project with no scenarios
  / a hollow scenario / an under-bound scenario whose flow names a feature it never binds),
  PROJECT_CONTEXT_DRIFT (#33, a project-context.md still on the unrefined init template).
• The per-feature cadence as the cycle — docs/feature-cycle.md (the orchestrator's per-feature
  loop, mode-adaptive across conversational / single-feature / /goal / headless), the
  "Feature cycle — one at a time" rule in the always-loaded CLAUDE.md + AGENTS templates, and the
  orchestrator persona's mode gloss.
• docs/ssot-audit.md — the recorded SSoT document-system audit (necessity / structure / firing /
  enforcement) and its fix roadmap. Hash-model acceptance-criterion ids (AC-<hash6>) for
  multi-dev merge safety, matching the feature/scenario hash model.

Changed

• clad_create_feature / clad_create_scenario author rich shards (acceptance_criteria, modules,
  flow) instead of empty stubs, and auto-sync the inventory: block on every create.
• Greenfield init seeds a high-quality baseline — documented docBlockRatio, module purpose
  headers, a "Why > What" conventions section, and a lean-core architecture note (greenfield only;
  existing projects keep their observed conventions).
• INVENTORY_DRIFT now also warns when the inventory: block is absent on a project with shards
  (previously a free pass), closing the hollow-spec loophole from the absent side.
• docs/ssot-model.md reconciled with code — dropped the false "clad_create_feature binds
  scenarios" claim, documented the create/link/refine verb taxonomy, and moved the now-built detectors
  from deferred to enforced.
• Anti-self-cert is now stated honestly across the personas, docs/feature-cycle.md, and spec
  AC-003. The enforced identity layer (checkAc requires human evidence before stage_4; the drive
  loop halts when reviewer identity equals the implementer's) is split from the advisory blindness
  (a test-author not reading the implementation), which no gate enforces — an A/B run found
  test-authors reading impl files in 4/4 features despite the instruction. The test-author dispatch is
  now handed the acceptance criteria + module signatures only (interface-stub, removing the reason
  to peek), the reviewer explicitly owns auditing the blindness, and the overclaim
  "anti-self-cert is structural, not a name check" is dropped.

Fixed (Vacuous Green closures)

• A stage that RAN and failed can no longer pass as a "skip" (exit-2 vs exit-1 discipline).
• Missing secret/architecture scanners now skip honestly (info), never false-report green.
• A hollow done feature (no modules, no acceptance criteria) fails the gate (STATUS_DRIFT).
• A present-but-broken spec.yaml fails ABSENCE_OF_GOVERNANCE instead of slipping through.
• The two-layer design-tier Vacuous Green (empty seeds passing existence + empty-content checks) is
  closed by HOLLOW_GOVERNANCE.

Fixed (cross-platform & release hygiene)

• Windows: clad no longer crashes on every command. bin/clad imported the dist bundle via a
  raw absolute path, which the ESM loader rejects on Windows as URL scheme c:
  (ERR_UNSUPPORTED_ESM_URL_SCHEME); it now resolves through pathToFileURL. Companion hardening:
  host-setup activation spawns run through a shell on Windows (.cmd shims), the inventory: rewrite
  is CRLF-safe, and clad init --scan layer inference splits on / rather than the platform
  separator. CI is POSIX, so a source-level regression guard pins the pathToFileURL shape.
• The marketplace catalog can no longer ship a stale version. .claude-plugin/marketplace.json
  (the version the Claude Code host reads to detect "update available") was neither a version-bump
  site nor a HARNESS_INTEGRITY check, so it lagged silently while the gate stayed green. It is now
  the 9th version-bump site and a dedicated HARNESS_INTEGRITY branch — a half-bumped catalog fails
  the gate.
• The release ritual now reaches existing users. npm publish is a documented release step (the
  engine runs from the global clad, so a tag + GitHub release alone never reached npm users), guarded
  by prepublishOnly: npm run build so a publish can't ship a stale dist/ or stale plugin mirrors.

Why v0.5.0 (minor bump)

Substantial additive, backward-compatible surface: two new CLI verbs (clad done, clad update), a
new MCP tool (clad_link_capability), 5 new detectors, capabilities in the schema, and hash-model AC
ids (the schema accepts both legacy AC-NNN and the new hash). Existing specs, shards, and gates keep
working; the new signals are warn-by-default (blocking only under --strict). No breaking changes.

v0.4.0 — clad setup command + verification cycle hardening

[0.4.0] — 2026-05-27 — clad setup command — split npm install from host wire (F-80d19d)

Reverting F-90d054's npm postinstall side effect. v0.3.60 made npm install -g cladding automatically wire four host AI channels in $HOME (~/.claude/, ~/.gemini/, ~/.codex/, ~/.agents/). The convenience was real — npm-path users got /cladding init for free — but the cost was steep: every npm install touched four global directories whether or not the user had those AI tools, CI sandboxes needed CLADDING_SKIP_POSTINSTALL=1, and clad init carried a fallback retry path. v0.4.0 splits the responsibility: install is install, wire is wire.

Added

• New command clad setup — explicit host channel wirer. One command handles six scenarios in a single run:
  • first wire — create symlinks for detected hosts
  • update — re-wire if the existing symlink target is a different cladding root (e.g. after nvm switch or manifest schema change)
  • delta — wire only the newly detected host when a user installs a new AI tool between runs
  • repair — re-create symlinks deleted by the user or reset by the host AI
  • no-op — print "already wired" without filesystem changes when everything matches
  • conflict — refuse to overwrite directory-copy wires (Windows fallback) with custom changes unless --force is supplied
• src/init/host-setup.ts — TypeScript implementation of the wirer, replacing the scripts/postinstall.mjs JavaScript hook. Detects each host via its home directory (~/.claude/, ~/.gemini/, ~/.codex/, ~/.agents/); undetected hosts are skipped (no surprise $HOME directories).
• ~/.cladding/setup-status.json — records the last cladding_version, wiring report, and errors. clad init reads it to detect version skew.
• Friendly stdout — clad setup always ends with a numbered "다음 단계" block (1. open AI tool → 2. cd to project → 3. /cladding init "..." → 4. start coding).
• spec/features/setup-command-80d19d.yaml (F-80d19d) — 10 acceptance criteria covering install / update / delta / repair / no-op / conflict / not-installed-skip / init-skew-warning / npm-install-no-side-effect / next-step-guidance.
• tests/cli/setup.test.ts — 10 unit tests, one per AC, exercising the wirer against a mocked $HOME.

Changed

• clad init — removed the F-90d054 postinstall-fallback retry path. clad init now never wires host channels on its own. If no setup-status.json exists, it appends a friendly skipped notice ("host channels not wired yet — run clad setup") and continues with spec generation. If the binary version differs from the recorded setup version, it appends a softer notice ("symlinks usually auto-follow, but run clad setup to be sure"). Neither blocks spec creation.
• src/cli/clad.ts — registers .command('setup') with --force and --quiet flags.

Removed

• scripts/postinstall.mjs — deleted. The npm postinstall lifecycle hook is no longer registered in package.json. npm install -g cladding now produces zero filesystem side effects in $HOME.
• src/init/postinstall-fallback.ts — deleted. The retry path inside clad init is gone with it.
• package.json "postinstall" script — removed from scripts. scripts/postinstall.mjs also removed from the files[] publish list.

Why v0.4.0 (minor bump)

Behavioral change for npm-path users (one extra clad setup command between install and init). Backward-safe in practice — existing v0.3.60 wires (symlinks/config.toml entries) survive the upgrade unchanged. Marketplace-path users are unaffected (the marketplace manifest still handles wiring on install).

Migration

• Upgrading from v0.3.60 — npm install -g cladding@0.4.0. Symlinks created by v0.3.60's postinstall already point at the cladding package root, so they auto-follow the upgrade with no action. Re-run clad setup only if you switched node managers (nvm) or moved your home directory.
• Fresh install — npm install -g cladding && clad setup && clad init "...".
• Marketplace — unchanged. /cladding init "..." works as before.

Auto-activation — 5-host plugin install runs automatically

clad setup does not stop at symlinks. After wiring each detected host channel, it auto-invokes the host's plugin activation command (non-interactive, 30s timeout each):

• Claude Code — claude plugin marketplace add ~/.claude/plugins/cladding --scope user + claude plugin install claude-code@cladding --scope user
• Gemini CLI — gemini extensions link ~/.gemini/extensions/cladding (skipped if gemini extensions list already shows cladding)
• Codex CLI skills — auto-detected from ~/.agents/skills/ on Codex restart (no command needed)
• Codex MCP — the TOML entry itself is the registration (no command needed)
• Cursor — the ~/.cursor/mcp.json entry itself is the registration (no command needed)

Each channel's ↳ 활성화: line in stdout reports ✓ 자동 완료 or ✗ 자동 시도 실패 — 수동: followed by the fallback command. If claude or gemini binary isn't on PATH, the manual command is shown instead. Existing v0.3.60 wires are preserved.

Fixed — plugin manifest now declares the MCP server (ISSUE-002, packaging gap)

plugins/claude-code/.claude-plugin/plugin.json now carries an mcpServers field. Prior v0.4.x packages shipped the plugin's commands and agents but not the MCP server declaration — so consumer projects (any project outside cladding's own repo) opened Claude Code with the cladding plugin loaded but the clad_create_feature / clad_list_features / clad_run_check / clad_get_events / clad_create_scenario tools missing. AGENTS.md's "use clad_create_feature MCP tool" guidance was therefore impossible to follow, which contributed to spec drift in adopting projects (see logcat-on docs/cladding-issues.md ISSUE-001).

With the fix, enabling the cladding plugin (claude plugin install claude-code@cladding) auto-starts cladding's MCP server in every project — same model as Codex's ~/.codex/config.toml wire. No claude mcp add user action; no manual server-connect step. The server appears in trust scope of the plugin (it does not surface in claude mcp list — that listing only shows user-added MCP servers, not plugin-declared ones).

Repo root .mcp.json was removed at the same time — it was a v0.3.x leftover from when the plugin lived at the repo root, and after Layer 1 it would just duplicate the canonical declaration in the plugin manifest.

The README's MCP narrative was corrected accordingly: every host gets cladding as an MCP server (only the wire location differs between plugin manifest, Codex's TOML, and Cursor's JSON); the v0.4.0 line claiming "Claude Code and Gemini CLI ... don't need MCP wired" was rationalizing a packaging bug as design intent.

Migration for existing v0.4.0 users: run clad setup --force (or claude plugin install claude-code@cladding --force --scope user) to refresh the plugin cache, then restart Claude Code. The MCP tools should appear in the AI's tool list inside any project where the plugin is enabled.

Fixed — four findings surfaced by end-to-end verification

A multi-host verification pass (Claude Code + Gemini CLI driving /cladding:init across bare / intent / path-intent / existing-adoption scenarios, plus a dev cycle of hand-authored hash-based feature → clad sync → clad check → drift inject) surfaced four issues that v0.4.0 now resolves:

• F1 (high) — spec/architecture.yaml seed emitted version: "0.1" which clad sync rejected. The architecture schema (src/spec/schema.json::definitions.architecture) declares additionalProperties: false with only layers + forbidden_imports allowed, so the seed contradicted the schema and made cladding's own dogfood fail validation. Removed version: "0.1" from renderGreenfieldArchitectureYaml, from the LLM-rendered observed-scan architecture (src/cli/scan/llm.ts), and from both LLM prompt templates (src/cli/scan/llm.ts + src/cli/scan/intent-onboarding.ts). Added a defensive stripArchVersionKey helper applied to LLM-emitted architecture bodies in interpretOnboardingWithFallback + applyRefineDelta so models trained on the older shape don't reintroduce the broken key.
• F2 (medium) — Gemini CLI's extension GEMINI.md did not surface the EARS feature-shard schema loudly enough; the Gemini AI authored ACs with description: and got rejected by clad sync on its first pass. Added an "Authoring feature shards (read before writing one)" section to plugins/gemini-cli/GEMINI.md that lays out the canonical filename (<slug>-<hash6>.yaml), id (F-<hash6>), required body shape, EARS templates for each of the six AC kinds, and the explicit "do NOT use description:" callout.
• F3 (low) — gemini -p --yolo still required --skip-trust to run cladding from non-trusted directories (e.g. CI runners, /tmp workspaces). Documented the headless flag and the GEMINI_CLI_TRUST_WORKSPACE=true env-var alternative in plugins/gemini-cli/GEMINI.md.
• F4 (low) — clad check printed only one-line pass/fail labels per stage, hiding the why of every failure unless the user knew to invoke clad doctor. runCheckCommand now indents the first three error-severity drift findings ([DETECTOR_NAME] path — message) under each failed Drift stage, and the first line of stderr under each non-drift failed stage. A footer hint (ℹ Run \clad doctor` for the event log, or `clad sync` to validate spec shards.) appears whenever any stage fails. Output stays terse enough to scan, while the *cause* of each ✗` is now legible without follow-up commands.

Verification artifacts live at /tmp/clad-verify/REPORT.md (5/5 scenarios passing after the fixes). Test suite: 973/973.

Docs — MCP server's role clarified in README

A short blockquote next to the clad setup 5-host table now states explicitly that the M...