Roadmap

Phase 760 — Agent SDK Phase B (local writes, implemented, unreleased)

Adds the Phase B local-write surface described in AGENT-SDK.md: a single learn namespace export grouping three explicit, opt-in local-write verbs (learn.remember, learn.feedback, learn.captureFromCheck). This is the only place the SDK writes files; the 8 Phase A verbs are unchanged and stay read-only — check() in particular gets no capture option, so its read-only contract test still holds. Landed in main as cli/sdk/learn-adapter.mjs; code-complete and gated but not yet released as an npm version.

Delivered

• learn.remember(text, opts?) — records a local learning-profile preference. Adapter over rememberLearning from cli/lib/learn-profile.mjs; always writes source: "sdk".
• learn.feedback(text, opts?) — records keep/avoid/improve feedback as a learning-profile entry. Adapter over recordLearningFeedback; the library normalizes outcome and folds it into the stored entry's text and source.
• learn.captureFromCheck(artifact, opts?) — checks a Markdown artifact, then captures its non-pass results as learning-profile entries. Adapter over checkArtifactContent + buildCheckLearningCapture from cli/lib/check.mjs — the SDK equivalent of the CLI's check --learn --yes. Duplicate captures are skipped (reason: "duplicate-entry-text").
• All three write only the local learning profile (DESIGN_AI_LEARNING_FILE / defaultLearningFile()), never the network; no filePath or now/timestamp option on any of them — consumers target a profile via the env var, exactly like the CLI.
• learn is a frozen object (Object.freeze); cli/sdk/index.mjs re-exports it alongside the 8 unchanged Phase A verbs.
• Input validation reused from cli/sdk/validate.mjs (requireNonEmptyString, requireOptions, optionalString); routeId validated with the same assertKnownRouteId helper the read-only check adapter uses.
• cli/sdk/learn-adapter.test.mjs — per-verb coverage: persistence (re-reading the written profile), remember's source: "sdk", feedback's outcome-to-text/source mapping, captureFromCheck's added/skipped results and duplicate-capture skip, and bad-input rejection. 16 new tests.
• cli/sdk/index.test.mjs contract test updated: the 8 read-only function verbs are pinned unchanged; learn is pinned as a frozen object export with exactly ["captureFromCheck", "feedback", "remember"], plus return-shape keys for each verb (including the full captureLearningEntries result shape: file, dryRun, applied, source, candidateCount, addedCount, skippedCount, count, entries, skipped).
• cli/sdk/types.test.mjs unchanged and passing (it filters to typeof === "function", so the learn object export is naturally excluded); a new assertion added confirming index.d.ts declares export declare const learn:.
• cli/sdk/index.d.ts — hand-written types for LearnRememberOptions, LearnFeedbackOptions, LearnCaptureOptions, LearningProfileEntry, LearningProfile, RememberResult, CaptureSkippedEntry, CaptureResult, and the learn const declaration. Verified to compile under tsc --strict against a transient consumer (zero-toolchain stance preserved — TypeScript is not added to package.json).
• docs/SDK.md — "Phase B — local writes" section replaces the "not yet shipped" placeholder: full reference for all three verbs, options, return shapes, the DESIGN_AI_LEARNING_FILE target, and the write-boundary rationale.
• docs/AGENT-SDK.md Phase B section updated from "only if demand" to shipped.
• npm test (563/563), npm run audit (8/8), npm run release:metadata all pass.

Remaining

• Release decision: bundle Phase B into the next npm version alongside or after Phase 759's TypeScript declarations.
• Optional follow-up: extend the packed-tarball SDK smoke (tools/audit/package-smoke.py) to exercise learn.remember against a temp DESIGN_AI_LEARNING_FILE.

Phase 759 — Agent SDK TypeScript declarations (implemented, unreleased)

Ships hand-written type declarations for the eight SDK verbs so TypeScript and editor tooling resolve @design-ai/cli/sdk with full types — no @types package, no build step (the .d.ts is maintained by hand to preserve the zero-toolchain stance). Landed in main as cli/sdk/index.d.ts; additive (types only), pending bundling into the next npm version.

Delivered

• cli/sdk/index.d.ts — precise signatures + return interfaces for all eight verbs (incl. search ranked/plain overloads, the RouteConfidence union, and optional learningContext/recall/relatedKnowledge fields), derived from the runtime shapes the contract test pins.
• exports types condition ("./sdk": { "types": …, "default": … }) so the subpath resolves declarations under moduleResolution: node16/nodenext/bundler.
• cli/sdk/types.test.mjs — zero-dependency guard asserting the .d.ts declares exactly the runtime-exported verbs (drift anchor). Declarations independently verified to compile under tsc --strict against a real consumer.
• docs/SDK.md TypeScript section.

Remaining

• Release: bundle into the next npm version (with Phase B, or standalone).

Phase 758 — Agent SDK Phase A Release (v4.59.0) ✓ ready

Ships the Agent SDK Phase A work (Phase 757) as an npm version: the curated, semver-stable @design-ai/cli/sdk surface — eight read-only adapter verbs (route, prompt, pack, search, recall, check, routes, version) over the same cli/lib functions the CLI and MCP already call. No new capabilities, no runtime dependencies, no network, no telemetry; read-only, deterministic, backward-compatible.

Verified

• All 8 audits passed.
• npm run release:check (unit tests incl. 61 SDK tests, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke that imports @design-ai/cli/sdk).
• npm run release:metadata.
• git diff --check.
• Main-branch GitHub Actions (Design-AI audit, Deploy doc site) passed for the constituent commits.

Versions

• package.json + .claude-plugin/plugin.json: 4.58.0 → 4.59.0.
• vscode-extension/package.json: remains 0.4.1.

What this enables

• design-ai's routing, prompt/pack generation, ranked search, recall, and artifact checks become plain importable functions for agent runtimes, build scripts, and custom tools — deterministic, in-process, zero-dependency — behind a semver-stable contract that insulates callers from internal cli/lib refactors.

What's still ahead

• Phase B explicit local-write adapters (learn.remember/feedback, capture) — implemented and landed in main (see Phase 760); pending release.
• Hand-written cli/sdk/index.d.ts TypeScript declarations shipped after this release (see Phase 759).

Phase 757 — Agent SDK (Phase A implemented, unreleased)

Opens the Agent SDK phase — the fast-follow chosen in NEXT-SURFACE-DECISION.md, unblocked now that the recall interface has been stable across two releases (v4.57.0/v4.58.0). Scope, the stable surface, packaging, and the stability contract are defined in AGENT-SDK.md. No new capabilities, no runtime dependencies, no network, no telemetry; the SDK is a thin, semver-stable adapter over the same cli/lib functions the CLI and MCP already call.

Phase A landed in main (commit 326ed0a) as cli/sdk/; it is code-complete and gated but not yet released as an npm version — shipping it is the next release decision.

Delivered (Phase A)

• Read-only SDK core at @design-ai/cli/sdk — route, prompt, pack, search (incl. ranked), recall, check, routes, version as pure adapters with stable signatures; exports map added; no file writes / no network. check operates on artifact content (not a path), so it reads and writes nothing.
• Unit coverage per adapter (signature, defaults, return-shape keys, determinism, CLI --json parity) plus an SDK contract test (cli/sdk/index.test.mjs) pinning exported names and return-shape keys — the semver anchor. 61 new tests, 540/540 total.
• Packed-tarball smoke (package-smoke.py) that imports @design-ai/cli/sdk from the installed package and exercises route/search ranked/recall/version/routes/prompt/pack/check, asserting determinism and the Phase A no-learningUsage guarantee.
• docs/SDK.md public reference + README/README.ko "Node.js / Agent SDK" install-table row + mkdocs nav.
• Open questions from AGENT-SDK.md resolved: bare root . not exported (only ./sdk); usage sidecar never written in Phase A; check is in Phase A (read-only). TS .d.ts deferred — adapters carry JSDoc; a hand-written sdk/index.d.ts remains an optional follow-up.

Remaining

• Release decision: bundle Phase A into the next npm version (e.g. v4.59.0) — version bump, CHANGELOG, registry-smoke parity after publish.
• Optional follow-up: hand-written cli/sdk/index.d.ts type declarations for the 8 verbs (zero-build stance preserved).
• Phase B (optional, deferred until an adopter needs it): explicit local-write adapters (learn.remember/feedback, capture).

Phase 756 — Retrieval Across Surfaces and Corpus Depth Release (v4.58.0) ✓ ready

Groups the post-v4.57.0 retrieval completion and corpus work into one release: route --explain related-knowledge enrichment (retrieval now spans every surface), recall exclusion of generated index/meta files, the async-control and Korean B2B density knowledge files, and the registry-smoke assertion fix that realigns the live post-publish smoke with the shared scorer. Defaults are unchanged; the release is additive and backward-compatible.

Changed

• route --explain gains an advisory related-knowledge section (routing unchanged), completing retrieval across search/prompt/pack/learn/route; carried to MCP via the existing design_ai_route explain parameter.
• Recall injection excludes generated index/meta files so injected context is real design knowledge; raw search --ranked is unchanged.
• Added knowledge/patterns/async-control.md and knowledge/i18n/korean-density-conventions.md (corpus now 94 files), closing the remaining dogfood-named gaps.
• Fixed the stale registry-smoke.py learn-relevance token-order assertion so the live post-publish registry smoke matches the published package.

Verified

• All 8 audits passed.
• npm run release:check (unit tests, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke).
• npm run release:metadata.
• git diff --check.
• Main-branch GitHub Actions (Design-AI audit, Deploy doc site) passed for the constituent commits.

Versions

• package.json + .claude-plugin/plugin.json: 4.57.0 → 4.58.0.
• vscode-extension/package.json: remains 0.4.1.

What this enables

• Retrieval is uniform across every design-ai surface and injects real design knowledge, not index tables; the Korean corpus gains async-control and B2B density depth.
• Publishing v4.58.0 realigns main with the published package so the live registry smoke verifies cleanly.

What's still ahead

• Push the v4.58.0 tag, then verify npm publish (provenance), GitHub Release, public npm run registry:smoke (now skew-free), and docs deployment.
• Refresh the Homebrew formula SHA-256 and the external-status.md / README distribution status from published 4.57.0 to 4.58.0 after the tag tarball exists.

Phase 755 — Local Retrieval Memory Release (v4.57.0) ✓ ready

Groups the Phase 754 A+B retrieval work, the MCP ranked-search parameter, the refs/ reference-page migration, and the docs-deploy retry hardening into one public package release. Scope and data boundaries are defined in AI-LEARNING-PHASE2.md; defaults are unchanged, so the release is additive and backward-compatible.

Changed

• Shipped deterministic local retrieval (design-ai index, search --ranked, shared BM25 learning selection), Hangul-aware tokenization, and the version-2 source-keyed index sidecar.
• Shipped the opt-in, local-only embedding rerank backend (search --ranked --embeddings, ~/.design-ai/config.json) with graceful lexical degradation and no network path.
• Added the MCP design_ai_search opt-in ranked parameter and the design_ai_prompt / design_ai_pack opt-in withRecall parameters, moved refs/ links behind docs/reference/ pages, and hardened Deploy doc site with a single automatic retry.
• Added prompt --with-recall / pack --with-recall: brief-relevant corpus knowledge recalled into prompts/packs via the shared lexical scorer (opt-in; default output unchanged) — the first CLI-deepening increment from NEXT-SURFACE-DECISION.md.
• Added design-ai learn --recall <query>, the read-side companion completing the retrieval verb pair (learn --recall + pack --with-recall) named in NEXT-SURFACE-DECISION.md: a read-only combined corpus + learning recall view.
• Extended packed-tarball and public-registry smoke to cover the index build/status/verify round-trip, ranked-search determinism, and embeddings off-by-default fallback.

Verified

• All 8 audits passed.
• npm run release:check (unit tests, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke).
• npm run release:metadata.
• git diff --check.
• Main-branch GitHub Actions (Design-AI audit, Deploy doc site) passed for the constituent Phase 754 commits.

Versions

• package.json + .claude-plugin/plugin.json: 4.56.0 → 4.57.0.
• vscode-extension/package.json: remains 0.4.1.

What this enables

• Users get deterministic ranked corpus/learning retrieval (Korean included) and an optional local embedding rerank, with zero new dependencies and no behavior change unless they opt in.
• Maintainers can publish a retrieval-capable release whose new CLI, MCP, and workspace surfaces are smoke-covered on both the packed tarball and the public registry.

What's still ahead

• Push the v4.57.0 release commit and tag, then verify npm publish (provenance), GitHub Release, public npm run registry:smoke, and docs deployment workflows.
• Refresh the Homebrew formula SHA-256 after the v4.57.0 tag tarball is available, then update external-status.md and the README distribution status from published 4.56.0 to 4.57.0.

Phase 754 — AI learning depth: local retrieval memory (planning)

Opens the deeper AI-learning phase chosen in Product Readiness ("Recommended next decision", option 2): deterministic local retrieval memory over the shipped knowledge corpus and the local learning profile, with an optional local-only embedding backend. Scope, data boundaries, and privacy constraints are defined in AI-LEARNING-PHASE2.md. Fine-tuning, training on user artifacts, external embedding APIs, background learning without explicit CLI commands, and telemetry stay out of scope; the README stance ("Not a model. Not a fine-tune.") is unchanged.

Plan

• Phase A: zero-dependency lexical retrieval index (tokenized BM25-style scoring) over knowledge/, examples/, skills/, docs/, agents/, commands/, and learning.json, built only by an explicit design-ai index --build.
• Phase A: opt-in design-ai search --ranked ranked corpus search with deterministic, fully ordered output.
• Phase A: shared lexical scorer behind prompt --with-learning / pack --with-learning selection, gated by learn --eval --strict checkpoints before and after. Selection-drift callout: tf-aware BM25 ranking can reorder entries that the old containment scorer tied (text-relevant entries now outrank category-only matches); checkpoints record ranker: "lexical" so eval templates regenerate against the shared scorer.
• Phase A: design-ai index --status/--verify staleness and digest reporting, plus workspace readiness integration.
• Phase A: verification gates — npm test unit coverage, npm run audit 8/8, npm run release:metadata, and release:check packed-tarball smoke for index build/verify round-trip and ranked-search determinism.
• Phase B (optional, after Phase A review): opt-in local embedding rerank via a user-supplied local provider executable (~/.design-ai/config.json and/or --provider), never a default, never external HTTP, with graceful degradation to Phase A on any absence/failure/staleness.
• Phase B: deterministic stub-provider test coverage (cli/lib/embedding-provider.test.mjs, cli/lib/embedding-index.test.mjs, cli/lib/embedding-rerank.test.mjs, cli/lib/search-ranked.test.mjs) and package:smoke coverage proving off-by-default, missing-provider fallback, and a real stub-provider round-trip.
• Answer the open questions in AI-LEARNING-PHASE2.md (ranked-search default, index location, route boundary, Korean tokenization, Phase B configuration home) before scheduling Phase B. Answered in the Phase A implementation review; Hangul tokenization (FU-1) and index source-identity keying (FU-2) landed before Phase B.

Phase 753 — MCP Protocol Hardening Release (v4.56.0) ✓ ready

The next public package release groups the post-v4.55 MCP protocol hardening work and the published MCP client evidence refresh into one versioned handoff.

Changed

• Hardened JSON-RPC envelope, method, id, params, notification, initialize, and tools/call validation paths so malformed MCP requests fail before CLI execution.
• Preserved existing Claude Code, Codex, Website Improvement, package smoke, and registry smoke contracts while making invalid inputs easier to diagnose.
• Refreshed public npm MCP entrypoint evidence and local Claude/Codex MCP client connection evidence.

Verified

• All 8 audits passed.
• npm run release:check.
• npm run release:metadata.
• npm run audit:strict.
• git diff --check.
• Main-branch GitHub Actions passed for Design-AI audit and Deploy doc site after the MCP evidence refresh.

Versions

• package.json + .claude-plugin/plugin.json: 4.55.0 → 4.56.0.
• vscode-extension/package.json: remains 0.4.1.

What this enables

• Claude Code and Codex users get deterministic MCP protocol errors for malformed requests while valid local stdio tool calls stay unchanged.
• Maintainers can publish the hardened MCP server with current evidence for public npm and local client connection paths.

What's still ahead

• Push the v4.56.0 release commit and tag, then verify npm publish, GitHub Release, registry smoke, and docs deployment workflows.
• Refresh Homebrew formula SHA-256 after the v4.56.0 tag tarball is available.

Phase 752 — Published MCP Client Connection Evidence Refresh (unreleased)

The external distribution status now includes current proof that the published npm MCP entrypoint and local Claude Code / Codex MCP client registrations are usable.

Changed

• Refreshed npm registry and VS Code Marketplace status evidence for the current published versions.
• Added public npm design-ai-mcp protocol-smoke evidence from a clean temporary directory.
• Added local Claude Code and Codex MCP client status evidence for the clone-backed design-ai server.
• Documented the npm one-shot verification gotcha when running from inside the package source checkout.

Impact

• Operators can distinguish already-published package state from actions that would fail by republishing the same version.
• Claude Code and Codex setup guidance now has current evidence for both client connection and public npm entrypoint behavior.
• No runtime code, package version, public API, or release workflow behavior changed.

Verification Plan

• npm view @design-ai/cli version name time.modified dist-tags --json
• VS Code Marketplace Gallery API query for sungjin.design-ai-vscode
• Public npm MCP protocol smoke with npm exec --yes --package=@design-ai/cli@4.55.0 -- design-ai-mcp
• codex mcp get design-ai
• claude mcp list
• git diff --check

Phase 751 — design-ai MCP Initialize Blank Protocol Version Guard (unreleased)

The MCP stdio server now rejects blank-only initialize.params.protocolVersion strings with JSON-RPC -32602, so version negotiation inputs must be meaningful strings when provided.

Changed

• Added a blank-string guard for initialize.params.protocolVersion.
• Added unit coverage for whitespace-only protocol versions.
• Preserved fallback behavior for unsupported but non-empty protocol version strings.

Impact

• Claude Code, Codex, and other MCP clients get clear invalid-params feedback for malformed initialize version negotiation.
• Valid initialize requests, omitted initialize params, unsupported non-empty string protocol versions, notifications, ping, tools/list, tools/call, resources/list, prompts/list, package smoke, Website Improvement readiness behavior, and CLI runtime failure reporting stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 750 — design-ai MCP Blank String Argument Guard (unreleased)

The MCP stdio server now rejects blank-only string arguments for schema fields that declare minLength, so required text inputs fail as JSON-RPC -32602 before CLI invocation instead of surfacing later as tool execution errors.

Changed

• Added whitespace-only validation for MCP string inputs with minLength.
• Added unit coverage proving a blank design_ai_route.brief is rejected before the CLI runner is called.
• Kept optional string fields without minLength on their existing CLI-mapping path.

Impact

• Claude Code, Codex, and other MCP clients get immediate invalid-params feedback for blank required text fields.
• Valid non-empty strings, optional string omission, initialize, notifications, ping, tools/list, tools/call success, resources/list, prompts/list, package smoke, Website Improvement readiness behavior, and CLI runtime failure reporting stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 749 — design-ai MCP Notification Namespace Guard (unreleased)

The MCP stdio server now treats the whole notifications/ method namespace consistently: notification messages must not include request ids, and valid id-less notifications are ignored without writing a response.

Changed

• Added a small notification-method predicate for the notifications/ namespace.
• Generalized the request-id rejection from notifications/initialized to every notifications/* method.
• Preserved silent handling for valid id-less notifications, including unsupported notification names that the local server does not need to act on.
• Added unit and subprocess coverage for notifications/progress with and without ids.

Impact

• Claude Code, Codex, and other MCP clients get deterministic -32600 feedback when a notification is accidentally sent as a request.
• Valid initialized notifications, progress-style notifications without ids, initialize, ping, tools/list, tools/call, resources/list, prompts/list, package smoke, Website Improvement readiness behavior, and CLI runtime failure reporting stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 748 — design-ai MCP Initialize Protocol Version Type Guard (unreleased)

The MCP stdio server now rejects non-string initialize.params.protocolVersion values with JSON-RPC -32602, so malformed initialize payloads get the same explicit invalid-params handling as other MCP request parameter mistakes.

Changed

• Added a focused initialize params validator that keeps optional params supported while checking protocolVersion when provided.
• Added unit coverage for numeric protocolVersion values so the server no longer silently falls back when the client sends the wrong JSON type.

Impact

• Claude Code, Codex, and other MCP clients get deterministic feedback when initialize version negotiation is malformed.
• Valid initialize requests, omitted initialize params, unsupported string protocol versions, initialized notifications, ping, tools/list, tools/call, resources/list, prompts/list, package smoke, Website Improvement readiness behavior, and CLI runtime failure reporting stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 747 — design-ai MCP Tool Argument Invalid Params Guard (unreleased)

The MCP stdio server now returns JSON-RPC -32602 for schema-invalid tools/call.params.arguments payloads before CLI execution, so known-tool argument errors use the same invalid-params response shape as malformed tools/call.params.

Changed

• Added pre-execution tool schema argument validation inside the tools/call request branch.
• Converted unknown tool arguments and wrong argument types from successful MCP tool-result errors to JSON-RPC invalid params errors.
• Preserved CLI failure reporting as successful MCP tool results with isError: true.
• Updated package and registry smoke assertions so publish-time MCP protocol checks verify the JSON-RPC invalid-params response shape.

Impact

• Claude Code, Codex, and other MCP clients can handle known-tool schema mistakes through standard JSON-RPC invalid-params handling.
• Valid initialize, id-less initialized notifications, ping, tools/list, resources/list, prompts/list, id-bearing tools/call, request id validation, output truncation, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, learning write behavior, and CLI runtime failure reporting stay unchanged.
• Package and registry smoke coverage now treats schema-invalid known-tool arguments as JSON-RPC invalid params instead of successful MCP tool-result errors.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 746 — design-ai MCP Response Request ID Guard (unreleased)

The MCP stdio server now requires request ids for every response-bearing MCP method, so initialize, ping, tools/list, tools/call, resources/list, and prompts/list cannot be sent as silent notifications.

Changed

• Added an explicit response-method set for MCP methods that must include a request id.
• Reused the same request-id guard across initialize, ping, list methods, and tools/call.
• Added unit and subprocess coverage for id-less response-bearing MCP methods while preserving silent handling for valid initialized notifications.

Impact

• Claude Code, Codex, and other MCP clients get deterministic feedback when response-bearing MCP requests are accidentally sent without correlation ids.
• Valid initialize, id-less initialized notifications, ping, tools/list, resources/list, prompts/list, id-bearing tools/call, request id validation, argument validation, output truncation, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 745 — design-ai MCP Tool Call Request ID Guard (unreleased)

The MCP stdio server now rejects tools/call payloads that omit a request id before any CLI work starts, so request-shaped tool execution cannot run silently as a JSON-RPC notification.

Changed

• Added a tools/call request-id requirement guard before tool lookup or CLI invocation.
• Preserved normal tools/call behavior for valid string, number, and null ids.
• Added unit and subprocess coverage proving id-less tools/call receives -32600 feedback and does not execute the CLI.

Impact

• Claude Code, Codex, and other MCP clients get deterministic feedback when a tool invocation is accidentally sent without a correlation id.
• Valid initialize, id-less initialized notifications, ping, tools/list, resources/list, prompts/list, id-bearing tools/call, request id validation, argument validation, output truncation, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 744 — design-ai MCP Optional Params Container Guard (unreleased)

The MCP stdio server now validates optional params containers for ping, tools/list, resources/list, and prompts/list, so malformed array, string, null, or boolean params receive deterministic -32602 feedback instead of being silently accepted.

Changed

• Added a shared optional object-params guard for no-body MCP methods that still accept future object-shaped params.
• Preserved successful handling for omitted params and {} params on ping and tools/list.
• Added unit coverage for malformed optional params on ping, tools/list, resources/list, and prompts/list.

Impact

• Claude Code, Codex, and other MCP clients get clearer invalid-params feedback when list or ping requests carry malformed params.
• Valid initialize, id-less initialized notifications, ping, tools/list, resources/list, prompts/list, tools/call, request id validation, argument validation, output truncation, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 743 — design-ai MCP Initialized Notification ID Guard (unreleased)

The MCP stdio server now rejects notifications/initialized payloads that include an id, so request-shaped initialized notifications receive deterministic -32600 feedback instead of being silently dropped.

Changed

• Added a notification-shape guard for notifications/initialized.
• Preserved silent handling for valid id-less initialized notifications.
• Added unit and subprocess coverage for request-shaped initialized notification payloads.

Impact

• Claude Code, Codex, and other MCP clients get a clear protocol error when an initialized notification is accidentally sent as a request.
• Valid id-less notifications, initialize, tools/list, tools/call, request id validation, argument validation, output truncation, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 742 — design-ai MCP Request ID Guard (unreleased)

The MCP stdio server now validates JSON-RPC request ids before dispatch, so malformed object, array, or boolean ids receive deterministic -32600 feedback with id: null instead of being echoed back to clients.

Changed

• Added a JSON-RPC request id guard for string, number, and null ids.
• Normalized invalid request ids to id: null in protocol error responses.
• Added unit and subprocess coverage for invalid object, array, and boolean id payloads while preserving explicit id: null requests.

Impact

• Claude Code, Codex, and other MCP clients get clearer protocol feedback when request correlation ids are malformed.
• Valid string, number, and null ids, notifications, initialize, tools/list, tools/call, argument validation, output truncation, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 741 — design-ai MCP JSON-RPC Envelope Guard (unreleased)

The MCP stdio server now rejects requests without jsonrpc: "2.0" before method dispatch, so malformed clients cannot reach normal initialize/list/call handlers with an invalid JSON-RPC envelope.

Changed

• Added a JSON-RPC envelope guard before MCP method validation.
• Preserved deterministic -32600 responses for id-less malformed requests.
• Added unit and subprocess coverage for missing and unsupported jsonrpc payloads.

Impact

• Claude Code, Codex, and other MCP clients get clearer protocol feedback when a malformed JSON-RPC envelope reaches the stdio server.
• Valid JSON-RPC 2.0 initialize, notifications, tools/list, tools/call, argument validation, output truncation, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 740 — design-ai MCP Request Method Shape Guard (unreleased)

The MCP stdio server now treats non-string or empty request methods as JSON-RPC invalid requests, so malformed notification-like payloads without ids still receive deterministic -32600 feedback while valid notifications remain silent.

Changed

• Added a request-method shape guard before MCP method dispatch.
• Updated stdio response writing so id-less -32600 invalid requests are emitted without also responding to valid unknown-method notifications.
• Added unit and subprocess coverage for numeric and empty method payloads.

Impact

• Claude Code, Codex, and other MCP clients get clearer protocol feedback when a malformed request method reaches the stdio server.
• Valid notifications, unknown-method notifications without ids, initialize, tools/list, tools/call, argument validation, output truncation, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 739 — design-ai MCP Tool Arguments Container Guard (unreleased)

The MCP server now rejects malformed tools/call.params.arguments containers before tool lookup or CLI execution, so omitted arguments still default to {} while explicit null, array, or primitive argument payloads return JSON-RPC -32602 feedback.

Changed

• Added a tools/call.params.arguments object-shape check to the MCP request boundary.
• Preserved omitted arguments support for no-argument tools such as design_ai_version.
• Added unit coverage for arguments: null and array argument payloads.

Impact

• Claude Code, Codex, and other MCP clients get clearer protocol feedback when a tool call includes a malformed arguments container.
• Normal tools/call execution, tool-schema argument validation, unknown-tool handling, initialize, notifications, tools/list, package smoke, Website Improvement readiness behavior, external MCP call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke:self-test
• npm run release:check
• git diff --check

Phase 738 — design-ai MCP Invalid Request Stdio Response (unreleased)

The MCP stdio server now distinguishes valid notifications from malformed request objects without ids, so invalid JSON-RPC payloads such as {}, [], or null receive deterministic -32600 responses with id: null while normal notifications/initialized messages remain silent.

Changed

• Added a small response-write predicate for MCP stdio output.
• Preserved silent handling for valid JSON-RPC notifications.
• Added subprocess coverage for invalid request objects without ids.

Impact

• Claude Code, Codex, and other MCP clients get clearer protocol feedback when a malformed payload reaches the stdio server.
• Valid initialize requests, notifications, tools/list, tools/call, CLI argument mapping, output truncation, Website Improvement readiness behavior, external call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 737 — design-ai MCP Request Param Guard (unreleased)

The MCP server now rejects malformed initialize and tools/call request parameters at the protocol boundary, so Claude Code and Codex clients get clear JSON-RPC -32602 errors instead of less specific request handling or internal exceptions.

Changed

• Added a small MCP request-boundary guard for tools/call params.
• Added a matching MCP request-boundary guard for initialize params.
• Added unit coverage for malformed initialize params, tools/call params: null, and missing params.name.

Impact

• Malformed MCP clients receive deterministic protocol errors instead of falling into less specific request handling.
• Valid tool calls, tool schemas, CLI argument mapping, output truncation, protocol version fallback, Website Improvement readiness behavior, external call boundaries, target-repo mutation rules, and learning write behavior stay unchanged.

Verification Plan

• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 736 — design-ai MCP Test Subprocess Readability (unreleased)

MCP stdio subprocess tests now share one small response collector, so parse-error and route-call smoke tests read as protocol scenarios instead of repeated stream plumbing.

Changed

• Added a focused MCP subprocess test helper for stdout line buffering and JSON-RPC response collection.
• Reused the helper in stdio parse-error and initialize/list/route subprocess tests.
• Kept timeout cleanup explicit so failed subprocess tests do not leave a child process running.

Impact

• MCP test code is easier to scan while preserving the same runtime behavior and assertions.
• No MCP server implementation, protocol response shape, tool schema, CLI mapping, package contents, Website Improvement readiness output, external call boundary, or learning write behavior changes.

Verification Plan

• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 735 — design-ai MCP Negative Response Coverage (unreleased)

The MCP server test suite now pins common client failure paths, so malformed Claude/Codex requests keep returning deterministic JSON-RPC errors without starting the design-ai CLI unnecessarily.

Changed

• Added coverage for unknown MCP tool calls to prove the CLI runner is not invoked.
• Added request-level error coverage for missing and unsupported MCP methods.
• Added stdio subprocess coverage for invalid JSON input and parse-error responses.

Impact

• Claude Code and Codex integrations get stronger regression coverage for setup mistakes and malformed client messages.
• The existing MCP runtime behavior, tool names, schemas, protocol version fallback, CLI command mappings, output truncation, and typed tool argument validation stay unchanged.
• No package names, Website Improvement readiness outputs, external MCP calls, target-repo mutation rules, or learning writes change.

Verification Plan

• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check
• npm run release:self-test
• npm run release:check

Phase 734 — design-ai MCP Public Registry Smoke Coverage (unreleased)

Public registry smoke now verifies the published design-ai-mcp bin through npm exec --package @design-ai/cli@<version>, so the post-publish gate covers the same Claude Code and Codex stdio server path as the packed-tarball release smoke.

Changed

• Moved the MCP protocol smoke input and response assertion into shared smoke helpers.
• Added public registry design-ai-mcp protocol coverage after npm exec version metadata checks.
• Added registry smoke self-test coverage for the MCP server name, expected tools, and typed invalid-argument response.

Impact

• Public npm verification now catches a missing design-ai-mcp bin, broken stdio startup, missing design-ai tools, or lost typed validation after publish.
• Package smoke and registry smoke share the same MCP protocol assertion for Claude/Codex setup paths.
• No CLI command names, package names, Website Improvement readiness outputs, external MCP calls, target-repo mutation rules, or learning writes change.

Verification Plan

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run package:smoke:self-test
• npm run registry:smoke:self-test
• npm run release:self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 733 — design-ai MCP Package Entrypoint Smoke Coverage (unreleased)

Packed-tarball release smoke now verifies the standalone design-ai-mcp bin after package installation and through one-shot npm exec, so Claude Code and Codex MCP setup cannot silently lose the stdio server entrypoint.

Changed

• Added a package-smoke MCP protocol helper that sends initialize, tools/list, and invalid tools/call JSON-RPC messages over stdin.
• Verified the installed node_modules/.bin/design-ai-mcp shim and the one-shot npm exec --package <tarball> -- design-ai-mcp path.
• Added self-test coverage for the MCP protocol assertion so typed argument validation remains visible in package smoke failures.

Impact

• Release smoke now covers the actual MCP server bin that Claude Code and Codex configuration examples use.
• The smoke keeps the same protocol version, tool names, JSON-RPC response shape, and typed validation message checked by unit tests.
• No CLI commands, package names, Website Improvement readiness outputs, external MCP calls, target-repo mutation rules, or learning writes change.

Verification Plan

• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke:self-test
• npm run package:check
• npm run release:self-test
• npm run release:check
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 732 — design-ai MCP Tool Argument Validation (unreleased)

The design-ai MCP server now validates tool arguments before invoking the CLI, so Claude Code and Codex get immediate, typed feedback for malformed tool calls instead of opaque downstream command failures.

Changed

• Added MCP tool argument validation for required fields, unknown fields, string length, boolean values, and integer ranges.
• Added MCP server tests proving invalid arguments are rejected before the CLI runner is called.
• Added troubleshooting notes for common Claude/Codex MCP setup and tool-call failures.

Impact

• design-ai mcp and design-ai-mcp keep the same tool names, schemas, protocol version, JSON-RPC response shape, and CLI command mappings.
• Claude Code and Codex integrations now fail earlier and with clearer messages when a client sends malformed tool input.
• No external MCP calls, target-repo mutation, learning writes, CLI flags, package bin names, or Website Improvement readiness contracts change.

Verification Plan

• node --check cli/lib/mcp-server.mjs
• node --test cli/lib/mcp-server.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 731 — Website Improvement Bundle Handoff Next Stage Command Summary Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook next-stage command summary now groups stage classification, command metadata, and execution context into named internal snapshots before returning the same fields.

Changed

• Added internal next-stage snapshots for stage classification, command metadata, and execution context.
• Replaced the long inline nextStageCommandSummary assembly with ordered snapshot spreads while keeping the existing returned field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same nextStage* command and execution contract.
• Website Improvement handoff wrappers and tests can continue to consume the same next-stage kind, required flag, run policy, safety level, command lists, output files, command/manual state, and mutation boundary fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action/evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 730 — Website Improvement Bundle Handoff Next Action Summary Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook next-action summary now groups action basics, evidence-capture metadata, payload mapping, validation state, field rules, counts, and run context into named internal snapshots before returning the same fields.

Changed

• Added internal next-action snapshots for core action state, evidence-capture field metadata, payload templates and bindings, validation state, field rules, field counts, and run context.
• Replaced the long inline nextActionSummary assembly with ordered snapshot spreads while keeping the existing returned field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same nextAction* and nextActionEvidenceCapture* contract.
• Website Improvement handoff wrappers and tests can continue to consume the same next-action status, dependency, evidence, evidence-capture, run policy, and safety fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action/evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 729 — Website Improvement Bundle Handoff Next Stage Evidence Capture Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook next-stage evidence capture now groups field metadata, payload mapping, validation state, field rules, and field counts into named internal snapshots before returning the same fields.

Changed

• Added internal next-stage evidence-capture snapshots for field metadata, payload templates and bindings, validation state, field rules, and field counts.
• Replaced the long inline nextStageEvidenceCapture assembly with ordered snapshot spreads while keeping the existing returned field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same nextStageActionEvidenceCapture* contract.
• Website Improvement handoff wrappers and tests can continue to consume the same next-stage evidence-capture fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action/evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 728 — Website Improvement Bundle Handoff Next Stage Human Line Summary Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook next-stage identity now prepares the next-stage human-line summary as a named internal snapshot before returning the same identity fields.

Changed

• Added an internal nextStageHumanLineSummary snapshot for the next-stage line, evidence-progress status, progress label, and first unchecked evidence label.
• Replaced the nested inline nextStageHumanLineSummary assembly inside nextStageIdentity with a direct snapshot reference while keeping the existing returned field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same nextStageHumanLineSummary and nextStageIdentity contract.
• Website Improvement handoff wrappers and tests can continue to consume the same next-stage human-line summary fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action/evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 727 — Website Improvement Bundle Handoff Human Line Summary Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook human-line summary now groups count, evidence-progress, and first-value fields into named internal snapshots before returning the same summary fields.

Changed

• Added internal human-line summary snapshots for base counts, evidence-progress counts, and first stage/line values.
• Replaced the long inline stageHumanLineSummary assembly with snapshot spreads while keeping the existing summary field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same stageHumanLineSummary contract.
• Website Improvement handoff wrappers and tests can continue to consume the same human-line count, progress, and first-value summary fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action/evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 726 — Website Improvement Bundle Handoff Human Line Display Row Summary Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook human-line display row summary now groups count, action-status, evidence-progress, and first-key fields into named internal snapshots before returning the same summary fields.

Changed

• Added internal display-row summary snapshots for base counts, action-status counts, evidence-progress counts, and first matching row keys.
• Replaced the long inline stageHumanLineDisplayRowSummary assembly with snapshot spreads while keeping the existing summary field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same stageHumanLineDisplayRowSummary contract.
• Website Improvement handoff wrappers and tests can continue to consume the same count, status, progress, and first-key summary fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action/evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 725 — Website Improvement Bundle Handoff Human Line Display Row Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook human-line display rows now group row identity, execution context, action status, and evidence progress fields into named internal snapshots before returning the same display-row fields.

Changed

• Added internal display-row snapshots for stage identity, execution context, action status, and evidence progress metadata.
• Replaced the long inline stageHumanLineDisplayRows return assembly with snapshot spreads while keeping the existing display-row field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same stageHumanLineDisplayRows[*] contract.
• Website Improvement handoff wrappers can continue to consume the same stage line, required/manual, command count, action status, and evidence-progress display fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 724 — Website Improvement Bundle Handoff Action Row Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook action rows now group action identity, status, dependency, evidence, evidence-capture, and execution fields into named internal snapshots before returning the same row fields.

Changed

• Added internal action-row snapshots for action identity, status, dependency/completion metadata, and execution metadata.
• Replaced the long inline action-row return assembly with snapshot spreads while keeping the existing action-row field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same stageActionRows[*] contract.
• Website Improvement handoff wrappers can continue to consume the same action identity, status, dependency, evidence, evidence-capture, command, safety, and boundary fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 723 — Website Improvement Bundle Handoff Stage Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook stage assembly now groups stage identity, command metadata, and safety metadata into named internal snapshots before returning the same public stage fields.

Changed

• Added internal stage snapshots for stage identity, command summary, and safety summary inside buildStage.
• Replaced the long inline stage return assembly with snapshot spreads while keeping the existing stage field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same top-level stages[*] contract.
• Website Improvement handoff wrappers can continue to consume the same stage identity fields, command lists, command counts, run policies, safety levels, output files, and safety flags without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 722 — Website Improvement Bundle Handoff Command Manifest Return Snapshot Cleanup (unreleased)

Website Improvement bundle handoff command manifest return assembly now groups command counts, selected task ids, and strict task command keys into named internal snapshots before returning the same public fields.

Changed

• Added internal return snapshots for command manifest counts, task selection ids, and strict task command keys.
• Replaced the long inline command manifest return assembly with snapshot spreads while keeping the existing returned field names unchanged.

Impact

• buildBundleHandoffCommandManifest keeps the same top-level command manifest contract.
• Website Improvement bundle handoff wrappers can continue to consume the same command counts, task ids, strict task command keys, and commands array without migration.
• No CLI flags, bundle files, command entries, command scopes, run policies, safety flags, task selection behavior, output-file selection, target-repo mutation rules, external-call boundaries, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 721 — Website Improvement Bundle Handoff Runbook Return Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook return assembly now groups count, stage identity, human-line, action, evidence-capture, execution, and next-step fields into named internal snapshots before returning the same public fields.

Changed

• Added internal return snapshots for runbook counts, stage identity maps, human-line maps, action status maps, action dependency maps, action evidence maps, evidence-capture maps, stage execution maps, and next-step summary fields.
• Replaced the long inline operator runbook return assembly with snapshot spreads while keeping the existing returned field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same top-level operator runbook contract.
• Website Improvement handoff wrappers can continue to consume the same stage maps, action maps, evidence-capture maps, actionSummary, next-stage fields, next-command fields, and stages array without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, human runbook lines, or generated output files change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 720 — Website Improvement Bundle Handoff Runbook Action Summary Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook action summary now groups action count, dependency, evidence, evidence-capture, validation, human-line, lookup, and boundary aggregates into named internal snapshots.

Changed

• Added internal action summary snapshots for action counts, dependency/completion metadata, evidence target counts, evidence-capture field counts, payload counts, validation counts, initial validation counts, checklist counts, human-line display counts, validated field counts, run-policy counts, first-action lookups, and boundary flags.
• Replaced the long inline actionSummary assembly with snapshot spreads while keeping the existing action summary field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same returned actionSummary contract.
• Website Improvement handoff wrappers can continue to consume the same action count, evidence-capture, validation, next-action, first-action lookup, and boundary fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 719 — Website Improvement Bundle Handoff Runbook Action Row Evidence Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook action rows now group evidence and evidence-capture assembly into named internal snapshots before returning the same row fields.

Changed

• Added an internal actionEvidenceSummary snapshot for evidence requirements, evidence-required state, and evidence target metadata.
• Added an internal actionEvidenceCaptureSummary snapshot for evidence-capture fields, field metadata, payload templates, validation metadata, checklist summaries, and capture counts.
• Replaced the long inline stageActionRows evidence assembly with snapshot spreads while keeping the existing action-row field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same stageActionRows[*].actionEvidence* and stageActionRows[*].actionEvidenceCapture* contract.
• Downstream Website Improvement handoff wrappers can continue to consume the same action-row evidence fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 718 — Website Improvement Bundle Handoff Runbook Action Summary Next Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook action summary now groups the internal nextAction* assembly into a named snapshot object before returning the same public fields.

Changed

• Added a grouped internal nextActionSummary snapshot for next-action status, dependency/completion metadata, evidence metadata, evidence-capture metadata, and stage linkage metadata.
• Replaced the long inline actionSummary assembly for nextAction* fields with the grouped snapshot spread.
• Kept the existing next-action accessor helpers and public field names unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same returned actionSummary.nextAction* contract.
• Website Improvement handoff wrappers can continue to consume the same runbook next-action summary fields without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run package:check
• npm run release:self-test
• npm run release:check

Phase 717 — Website Improvement Bundle Handoff Runbook Next Snapshot Cleanup (unreleased)

Website Improvement bundle handoff runbook next-stage output now groups the internal nextStage*, nextStageAction*, evidence-capture, and nextCommand* assembly into named snapshot objects before returning the same public fields.

Changed

• Renamed generic next-action and next-stage accessors so scalar, list, object, number, and boolean reads are explicit at the call site.
• Added grouped internal snapshots for next-stage identity, action status, dependency/completion metadata, evidence metadata, evidence-capture metadata, command-stage metadata, and next-command metadata.
• Replaced the long inline return assembly for nextStage* and nextCommand* fields with those grouped snapshots.

Impact

• buildBundleHandoffOperatorRunbook keeps the same returned nextStage*, nextStageAction*, nextCommand*, evidence-capture, command, safety, and stage fields.
• Website Improvement handoff wrappers can continue to consume the same runbook next-step contract without migration.
• No CLI flags, bundle files, command manifest fields, stage/action field names, evidence field names, validation status values, next-action keys, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 716 — Website Improvement Bundle Handoff Runbook Evidence Predicate Cleanup (unreleased)

Website Improvement bundle handoff evidence-capture summaries now use named predicates for evidence field input type, value shape, payload mapping, validation state, display state, and checklist item state.

Changed

• Added evidence-capture field predicates for input type, value shape, multi-value behavior, empty values, placeholder, ARIA label, help text, section membership, payload mapping, and validation rules.
• Added shared required/optional and multi-value predicates for evidence payload bindings, validation specs, and checklist items.
• Added initial validation state, display row, and checklist item predicates for valid/invalid, blocking/non-blocking, checked/unchecked, and completion-blocking summary counts.
• Reused those predicates in evidence-capture summary counts and first evidence-capture action lookups.

Impact

• buildBundleHandoffOperatorRunbook keeps the same evidence-capture summary fields and first-action lookup fields.
• Website Improvement handoff wrappers can continue to consume the same runbook evidence summary contract without migration.
• No CLI flags, bundle files, command manifest fields, stage fields, action field names, evidence field names, evidence targets, validation status values, first-action keys, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 715 — Website Improvement Bundle Handoff Runbook Action Predicate Cleanup (unreleased)

Website Improvement bundle handoff action summaries now use named predicates for action enabled state, prerequisites, evidence targets, evidence-capture presence, and first-action lookups.

Changed

• Added action-row predicates for enabled, disabled, manual-disabled, prerequisite, dependency, blocking, completion-criteria, and evidence-required states.
• Added action evidence-target predicates for local command output, local output file, target repo working tree, and handoff evidence record.
• Added evidence-capture predicates for field presence, required/optional field presence, multiple sections, multiple payload namespaces, and payload template presence.
• Reused those predicates in action summary counts and first-action lookup fields.

Impact

• buildBundleHandoffOperatorRunbook keeps the same action summary fields and first-action lookup fields.
• Website Improvement handoff wrappers can continue to consume the same runbook action summary contract without migration.
• No CLI flags, bundle files, command manifest fields, stage fields, action field names, evidence field names, evidence targets, first-action keys, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 714 — Website Improvement Bundle Handoff Runbook Display Row Predicate Cleanup (unreleased)

Website Improvement bundle handoff display-row summaries now use named predicates for required/manual rows, command rows, action status, and evidence-progress status.

Changed

• Added display-row predicates for required, optional, command-backed, and manual rows.
• Added display-row predicates for ready, optional, manual, and blocked action statuses.
• Added display-row predicates for evidence-progress presence plus blocked and ready evidence-progress states.
• Reused those predicates in display-row status key maps, summary counts, and first-row lookups.

Impact

• buildBundleHandoffOperatorRunbook keeps the same display-row summary fields.
• Website Improvement handoff wrappers can continue to consume the same human-line display row contract without migration.
• No CLI flags, bundle files, command manifest fields, stage fields, action fields, evidence field names, status labels, evidence-progress values, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 713 — Website Improvement Bundle Handoff Runbook Scope and Safety Predicate Cleanup (unreleased)

Website Improvement bundle handoff command and operator summaries now use named predicates for command scope, safety flags, required stages, and external/target-repo boundary counts.

Changed

• Added command-manifest predicates for source-bundle and task-handoff scope counts.
• Added command-manifest safety predicates for external calls, target-repo mutation, clean-workspace requirements, and review-before-mutation requirements.
• Added runbook-stage predicates for required/optional stages and external/target-repo boundary checks.
• Reused those predicates in manifest counts, action summaries, first-stage lookups, returned stage counts, and top-level boundary booleans.

Impact

• buildBundleHandoffCommandManifest keeps the same command count and safety count fields.
• buildBundleHandoffOperatorRunbook keeps the same stage count, action summary, first-stage key, and boundary fields.
• Website Improvement handoff wrappers can continue to consume the same manifest and runbook contracts without migration.
• No CLI flags, bundle files, command manifest field names, target-repo mutation rules, external-call boundaries, evidence field names, action counts, first-stage keys, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 712 — Website Improvement Bundle Handoff Runbook Run Policy Predicate Cleanup (unreleased)

Website Improvement bundle handoff command and operator summaries now use named predicates for read-only and local-output run policy counts.

Changed

• Added command-manifest run policy predicates for read-only and local-output command counts.
• Added a runbook-stage usesReadOnlyRunPolicy predicate beside the existing local-output predicate.
• Reused those predicates for manifest counts, action summary counts, and returned command-stage summary counts.

Impact

• buildBundleHandoffCommandManifest keeps the same command count fields.
• buildBundleHandoffOperatorRunbook keeps the same read-only and local-output summary fields.
• Website Improvement handoff wrappers can continue to consume the same manifest and runbook contracts without migration.
• No CLI flags, bundle files, command manifest field names, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 711 — Website Improvement Bundle Handoff Runbook Output Predicate Cleanup (unreleased)

Website Improvement bundle handoff operator stage summaries now use named predicates for local-output run policy and output-file checks.

Changed

• Added local usesLocalOutputRunPolicy for writes-local-file run-policy checks.
• Added local hasOutputFile for output-file presence checks.
• Reused those predicates in action summary and returned command-stage summary counts.

Impact

• buildBundleHandoffOperatorRunbook keeps the same local-output and output-file count fields.
• Website Improvement handoff wrappers can continue to consume the same runbook summary contract without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 710 — Website Improvement Bundle Handoff Runbook Display Row Summary Cleanup (unreleased)

Website Improvement bundle handoff operator action summaries now reuse the prepared human-line display-row summary for display-row counts.

Changed

• Reused stageHumanLineDisplayRowSummary.count for humanLineDisplayRowCount.
• Reused stageHumanLineDisplayRowSummary.byKeyCount for humanLineDisplayRowByKeyCount.
• Removed repeated direct display-row length and by-key object counting inside actionSummary.

Impact

• buildBundleHandoffOperatorRunbook keeps the same human-line display-row action summary fields.
• Website Improvement handoff wrappers can continue to consume the same action summary contract without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 709 — Website Improvement Bundle Handoff Runbook Initial Validation Summary Cleanup (unreleased)

Website Improvement bundle handoff operator action summaries now route initial validation summary and checklist summary aggregations through named local helpers.

Changed

• Added local countActionsBySummary and sumSummaryValues helpers for action-row summary objects.
• Added local initial-validation summary wrappers for field-count, status, completion, and blocking totals.
• Added local initial-checklist summary wrappers for item-count, status, completion, checked, unchecked, and blocking-unchecked totals.
• Replaced repeated direct actionEvidenceCaptureInitialValidationSummary and actionEvidenceCaptureInitialValidationChecklistSummary accesses inside actionSummary.

Impact

• buildBundleHandoffOperatorRunbook keeps the same initial validation summary and checklist summary fields.
• Website Improvement handoff wrappers can continue to consume the same action summary contract without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 708 — Website Improvement Bundle Handoff Runbook Action Item Count Cleanup (unreleased)

Website Improvement bundle handoff operator action summaries now name repeated item-count and item-value aggregations before assembling evidence-capture totals.

Changed

• Added local countActionsWithItems for action rows that contain at least one item in a named list field.
• Added local sumActionItems for total item counts across action rows.
• Added local sumActionItemValues for numeric totals derived from list item values.
• Replaced repeated .length > 0, .length, and nested reduce summary calculations with the named helpers.

Impact

• buildBundleHandoffOperatorRunbook keeps the same payload binding, validation spec, initial validation state, display metadata, checklist, and minimum-length summary fields.
• Website Improvement handoff wrappers can continue to consume the same action summary fields without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 707 — Website Improvement Bundle Handoff Runbook Payload Summary Cleanup (unreleased)

Website Improvement bundle handoff operator action summaries now name the payload template and unique-list summary calculations before returning the runbook payload.

Changed

• Added local uniqueActionListValueCount for unique action-list summary counts.
• Added local payloadTemplatePathCount for payload flat-template path counts.
• Replaced inline flatMap/Object.keys(...).length summary calculations with the named helpers.

Impact

• buildBundleHandoffOperatorRunbook keeps the same payload template path counts, unique section counts, unique payload namespace counts, action summary fields, and returned runbook contract.
• Website Improvement handoff wrappers can continue to consume the same summary fields without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 706 — Website Improvement Bundle Handoff Runbook Action Item Summary Cleanup (unreleased)

Website Improvement bundle handoff operator action summaries now use shared local item-summary helpers for repeated evidence item counts and first-action lookups.

Changed

• Added local countActionItems and maxActionItemValue helpers near the actionSummary assembly.
• Reused the item-summary helpers for evidence capture fields, payload bindings, validation specs, initial validation state rows, display rows, and checklist items.
• Added firstActionWithEvidenceCaptureField for first-action evidence field lookups.

Impact

• buildBundleHandoffOperatorRunbook keeps the same action summary counts, first-action keys, evidence capture metadata, and returned runbook contract.
• Website Improvement handoff wrappers can continue to consume the same summary fields without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 705 — Website Improvement Bundle Handoff Runbook Evidence Field Value Cleanup (unreleased)

Website Improvement bundle handoff operator action rows now read evidence-capture field values through one local helper before assembling the row payload.

Changed

• Added a local evidenceFieldValues helper inside the stageActionRows mapper.
• Replaced repeated evidenceCaptureFields.map(...) field extraction calls with evidenceFieldValues.
• Reused the same helper for evidence capture section labels and payload namespaces before returning action row metadata.

Impact

• buildBundleHandoffOperatorRunbook keeps the same evidence-capture field arrays, section metadata, payload namespace metadata, validation metadata, and action row contract.
• Website Improvement handoff wrappers can continue to consume the same stage action evidence fields without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence field names, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 704 — Website Improvement Bundle Handoff Runbook Manual Stage Predicate Cleanup (unreleased)

Website Improvement bundle handoff operator stages now use named predicates for command-backed and manual stage checks instead of repeating commandCount comparisons inline.

Changed

• Added local hasCommands and isManualStage predicates inside buildBundleHandoffOperatorRunbook.
• Replaced repeated stage.commandCount > 0 checks with hasCommands.
• Replaced repeated stage.commandCount === 0 checks with isManualStage.

Impact

• buildBundleHandoffOperatorRunbook keeps the same command-stage counts, manual-stage counts, lookup maps, next-action summary fields, and stage lists.
• Website Improvement handoff wrappers can continue to consume the same stage and action fields without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence fields, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 703 — Website Improvement Bundle Handoff Runbook Stage Command Safety Cleanup (unreleased)

Website Improvement bundle handoff operator stages now read first-command run policy and safety metadata through named local values before assembling each stage record.

Changed

• Added local firstCommand, firstCommandSafety, and commandHasSafetyFlag values inside buildStage.
• Replaced repeated stageCommands[0]?.* lookups with the named first-command values.
• Replaced repeated stage-command safety flag predicates with commandHasSafetyFlag.

Impact

• buildBundleHandoffOperatorRunbook keeps the same stage run policy, safety level, local-output, external-call, and target-repo mutation metadata.
• Website Improvement handoff wrappers can continue to consume the same stage and command fields without migration.
• No CLI flags, bundle files, command manifest fields, target-repo mutation rules, external-call boundaries, evidence fields, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 702 — Website Improvement Bundle Handoff Command Manifest Fallback Cleanup (unreleased)

Website Improvement bundle handoff command manifest entries now read source-bundle and task command metadata through small local fallback helpers before assembling each command record.

Changed

• Added a local sourceValue helper inside buildBundleHandoffCommandManifest for source-bundle command, args, run-policy, and safety metadata.
• Read source-bundle safety once per source command so strict comes from the same object that is returned in the command manifest.
• Added a local taskValue helper inside pushTaskCommand and read task safety once before deriving strict task command metadata and output file fallback.

Impact

• buildBundleHandoffCommandManifest keeps the same command keys, task ids, output file fallback, strict flags, safety metadata, and manifest JSON contract.
• Website Improvement handoff wrappers can continue to consume the same command manifest fields without migration.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, operator runbook fields, evidence fields, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 701 — Website Improvement Bundle Handoff Runbook Next Stage Return Cleanup (unreleased)

Website Improvement target-repo handoff runbook next-stage and next-command return metadata now use the same local fallback style as the next-action fields.

Changed

• Added local nextStageList, nextStageFlag, nextCommandValue, and nextCommandList helpers inside buildBundleHandoffOperatorRunbook.
• Precomputed the next-stage human line, display row, command count, and command safety before assembling the returned runbook payload.
• Replaced the remaining repeated nextStage?.* and nextCommandEntry?.* fallback expressions in the return object with named values or helper calls.

Impact

• buildBundleHandoffOperatorRunbook keeps the same next-stage labels, command metadata, safety metadata, human-line summary, and JSON contract.
• Target-repo handoff wrappers can continue to consume the same next-stage and next-command fields without migration.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, lookup maps, evidence fields, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• npm run release:check

Phase 700 — Website Improvement Bundle Handoff Runbook Next Action Fallback Cleanup (unreleased)

Website Improvement target-repo handoff runbook next-action metadata now uses small local fallback helpers instead of repeating the same optional-chaining defaults in actionSummary and the returned runbook payload.

Changed

• Added local nextActionValue, nextActionList, nextActionObject, nextActionCount, nextActionFlag, nextStageValue, and nextStageCommandList helpers inside buildBundleHandoffOperatorRunbook.
• Replaced repeated nextAction* and nextStageAction* fallback expressions with helper calls while keeping every exported field name unchanged.
• Read the nested next-stage evidence progress summary once before writing the human-line summary fields.

Impact

• buildBundleHandoffOperatorRunbook keeps the same next-action, next-stage action, evidence progress, command metadata, and JSON contract.
• Target-repo handoff wrappers can continue to consume the same next-action and next-stage fields without migration.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, lookup maps, evidence fields, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 699 — Website Improvement Bundle Handoff Runbook Stage Command Lookup Cleanup (unreleased)

Website Improvement target-repo handoff runbook stage command lookup maps now use named helpers instead of repeating command-list mapping expressions inline.

Changed

• Added local commandListByKey and stageKeysBy helpers inside buildBundleHandoffOperatorRunbook.
• Replaced repeated stage command label, command string, command args, run policy, and safety-level lookup map construction with commandListByKey.
• Replaced command/manual stage key list construction with stageKeysBy while keeping the exported arrays unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same command lookup maps, stage key arrays, action summaries, and JSON contract.
• Target-repo handoff wrappers can continue to consume the same stage command metadata without migration.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, evidence fields, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 698 — Website Improvement Bundle Handoff Runbook Human Line Summary Cleanup (unreleased)

Website Improvement target-repo handoff runbook human-line display summaries and first-action key fields now use small named helpers instead of repeating row and action scans inline.

Changed

• Added local display-row count, key-list, first-key, and action first-key helpers inside buildBundleHandoffOperatorRunbook.
• Replaced repeated human-line display row status counts, evidence-progress counts, and first-row lookups with named helper calls.
• Replaced repeated first action key lookups in actionSummary with the shared firstActionKey helper while keeping every exported field name unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same human-line summary, display-row summary, first-action key fields, and JSON contract.
• Target-repo handoff wrappers can continue to consume the same stage human-line, evidence-progress, and first-action metadata without migration.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, lookup maps, evidence fields, action counts, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 697 — Website Improvement Bundle Handoff Runbook Action Summary Count Cleanup (unreleased)

Website Improvement target-repo handoff runbook action summary count and aggregate calculations now use named local helpers instead of repeating filter, reduce, max, and evidence-capture traversal expressions.

Changed

• Added local countActions, sumActions, maxActionValue, and evidence-capture aggregate helpers inside buildBundleHandoffOperatorRunbook.
• Replaced repeated action summary count, sum, max, payload binding, validation spec, validation state, display metadata, and checklist aggregate expressions with named helper calls.
• Kept the action summary object keys and computed values unchanged.

Impact

• buildBundleHandoffOperatorRunbook keeps the same actionSummary JSON contract while the summary section reads as a set of named aggregate calculations.
• Target-repo handoff wrappers can continue to consume the same summary fields without migration.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, lookup maps, evidence fields, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 696 — Website Improvement Bundle Handoff Runbook Lookup Assembly Cleanup (unreleased)

Website Improvement target-repo handoff runbook lookup map assembly now uses a small shared helper instead of repeating the same Object.fromEntries pattern through the assembly body.

Changed

• Added local byKey, fieldByKey, stageFieldByKey, and actionFieldByKey helpers inside buildBundleHandoffOperatorRunbook.
• Replaced repeated stage/action lookup map construction with named helper calls while keeping every exported lookup object and key unchanged.
• Kept nested command lookup maps explicit where they derive arrays from stage commands.

Impact

• buildBundleHandoffOperatorRunbook keeps the same lookup maps, action rows, summaries, next-action fields, and JSON contract.
• Target-repo handoff wrappers can continue to read the same stage*ByKey and stageAction*ByKey objects without migration.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, evidence fields, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 695 — Website Improvement Bundle Handoff Runbook Stage Metadata Split (unreleased)

Website Improvement target-repo handoff runbook stage dependency and requirement metadata now lives outside the runbook assembly body.

Changed

• Moved stage prerequisite, blocked-stage, dependency reason, completion criteria, and evidence requirement helpers into cli/lib/site-bundle-handoff-runbook-stage-metadata.mjs.
• Kept cli/lib/site-bundle-handoff-runbook.mjs focused on building stages, action rows, lookup maps, summaries, and the final operator runbook payload.
• Reworked action row assembly to compute prerequisite, blocking, completion, evidence requirement, and evidence capture values once per stage before writing the public row fields.

Impact

• buildBundleHandoffOperatorRunbook keeps the same stage action dependency, completion criteria, evidence requirement, and evidence capture JSON contract.
• Target-repo handoff wrappers can continue to read the same prerequisite keys, blocked-stage labels, dependency reason codes, completion criteria, evidence requirements, payload templates, and validation metadata.
• No CLI flags, bundle files, target-repo mutation rules, external-call boundaries, or human runbook lines change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook-stage-metadata.mjs && node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 694 — Website Improvement Bundle Handoff Runbook Evidence Field Split (unreleased)

Website Improvement target-repo handoff runbook stage-specific evidence field definitions now live outside the runbook assembly body.

Changed

• Moved stage-specific evidence capture field definitions and field enrichment into cli/lib/site-bundle-handoff-runbook-evidence-fields.mjs.
• Kept cli/lib/site-bundle-handoff-runbook.mjs focused on assembling stage action rows, summaries, lookup maps, and the final operator runbook payload.
• Reused the existing action metadata and generic evidence helper modules so evidence targets, field shapes, payload paths, sections, and validation metadata stay consistent.

Impact

• buildBundleHandoffOperatorRunbook keeps the same evidence capture fields and JSON contract while the runbook assembly reads as a shorter flow.
• Target-repo handoff wrappers can continue to consume the same field keys, placeholders, examples, validation hints, payload paths, and section metadata.
• No CLI flags, bundle files, target-repo mutation rules, or external-call boundaries change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook-evidence-fields.mjs && node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 693 — Website Improvement Bundle Handoff Runbook Evidence Helper Split (unreleased)

Website Improvement target-repo handoff runbook evidence capture helper logic now lives outside the runbook assembly body.

Changed

• Moved evidence capture field shape, section, payload binding, validation spec, and initial checklist/summary helpers into cli/lib/site-bundle-handoff-runbook-evidence.mjs.
• Kept stage-specific evidence field selection in cli/lib/site-bundle-handoff-runbook.mjs, where it still has access to the current runbook stage context.
• Preserved existing evidence capture payload paths, validation labels, section keys, checklist summaries, and next-action metadata.

Impact

• buildBundleHandoffOperatorRunbook keeps the same evidence capture JSON contract while the generic evidence helper code has a focused module boundary.
• Target-repo handoff wrappers can continue to consume the same payload template, flat template, validation specs, checklist rows, and summary fields.
• No CLI flags, bundle files, target-repo mutation rules, or external-call boundaries change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook-evidence.mjs && node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 692 — Website Improvement Bundle Handoff Runbook Action Metadata Split (unreleased)

Website Improvement target-repo handoff runbook action metadata now lives outside the runbook assembly body.

Changed

• Moved stage action type, labels, instructions, button labels, affordances, status metadata, disabled reasons, and evidence target labels into cli/lib/site-bundle-handoff-runbook-actions.mjs.
• Kept cli/lib/site-bundle-handoff-runbook.mjs focused on command manifest input, stage assembly, evidence capture rows, and the final runbook payload.
• Preserved the existing runbook JSON keys and human output by importing the same helper behavior from the new action metadata module.

Impact

• buildBundleHandoffOperatorRunbook keeps its current public contract while the stage action wording and UI-oriented metadata have a focused module boundary.
• Target-repo handoff wrappers can still consume the same action fields, status labels, evidence targets, and disabled reason codes.
• No bundle files, CLI flags, target-repo mutation rules, or external-call boundaries change.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook-actions.mjs && node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 691 — Website Improvement Bundle Handoff Runbook Formatter Split (unreleased)

Website Improvement target-repo handoff runbook line formatting now lives outside the runbook assembly module.

Changed

• Moved operator runbook human line formatting into cli/lib/site-bundle-handoff-runbook-format.mjs.
• Kept cli/lib/site-bundle-handoff-runbook.mjs responsible for command manifest and operator runbook assembly.
• Re-exported the existing public formatter from the runbook module so current imports keep working.

Impact

• buildBundleHandoffOperatorRunbook keeps the same JSON contract and stage metadata.
• Human runbook lines remain available through the same public helper while formatting logic has a smaller module boundary.
• Target-repo handoff command manifest, runbook stages, evidence capture metadata, and existing CLI output contracts are unchanged.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook-format.mjs && node --check cli/lib/site-bundle-handoff-runbook.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 690 — Website Improvement Bundle Repair Report Split (unreleased)

Website Improvement bundle repair report orchestration now lives outside the public site helper surface.

Changed

• Moved bundle repair preview, repair bundle creation, applied repair report assembly, and JSON/human repair formatters into cli/lib/site-bundle-repair-report.mjs.
• Kept cli/lib/site.mjs as a public compatibility surface by re-exporting repair report helpers.
• Avoided a circular dependency with cli/lib/site-bundle-check.mjs by keeping repair guidance helpers in cli/lib/site-bundle-repair.mjs and repair orchestration in a separate module.

Impact

• cli/lib/site.mjs now acts as a compact Website Improvement public export surface instead of owning bundle workflow bodies.
• design-ai site <bundle-dir> --bundle-repair continues to expose the same preview/apply report contracts.
• Bundle check, repair guidance, and repair report orchestration remain separated by dependency direction.

Verification Plan

• node --check cli/lib/site-bundle-repair-report.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 689 — Website Improvement Bundle Handoff Report Split (unreleased)

Website Improvement target-repo handoff report construction now lives outside the main site workflow module.

Changed

• Moved target-repo handoff workspace loading, prompt assembly, task selection handling, command manifest/runbook wiring, and JSON/human formatters into cli/lib/site-bundle-handoff.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting bundle handoff helpers.
• Removed local imports from cli/lib/site.mjs that were only needed by handoff report construction.

Impact

• cli/lib/site.mjs no longer owns the target-repo handoff report body.
• design-ai site <bundle-dir> --bundle-handoff continues to expose the same prompt and JSON report contracts.
• Handoff report assembly now sits beside the handoff summary and operator runbook helpers instead of remaining in the workflow orchestration module.

Verification Plan

• node --check cli/lib/site-bundle-handoff.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 688 — Website Improvement Bundle Compare Report Split (unreleased)

Website Improvement handoff bundle comparison report construction now lives with the compare helpers.

Changed

• Moved buildSiteBundleCompareReport into cli/lib/site-bundle-compare.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting the compare report builder.
• Preserved compare issue ids, digest comparison, metadata diffing, changed file reporting, and JSON/human formatter contracts.

Impact

• cli/lib/site.mjs no longer owns bundle comparison report assembly.
• design-ai site <bundle-dir> --bundle-compare other-bundle-dir continues to use the same report shape and formatter outputs.
• Bundle comparison logic is grouped with its checksum/metadata diff helpers instead of remaining in the workflow orchestration module.

Verification Plan

• node --check cli/lib/site-bundle-compare.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 687 — Website Improvement Bundle Check Module Split (unreleased)

Website Improvement handoff bundle validation now lives outside the main site workflow module.

Changed

• Moved bundle directory validation, summary/checksum verification, MCP recomputation checks, generated contract checks, and bundle check formatting into cli/lib/site-bundle-check.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting bundle check helpers.
• Removed local imports that were only needed by the moved bundle check implementation.

Impact

• cli/lib/site.mjs no longer owns the large bundle check validation body.
• Bundle repair, bundle compare, and target-repo handoff flows continue to consume the same buildSiteBundleCheckReport shape.
• Bundle validation now sits with the bundle-specific helper modules instead of being embedded in the remaining workflow orchestration file.

Verification Plan

• node --check cli/lib/site-bundle-check.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 686 — Website Improvement Generated Contract Helper Split (unreleased)

Website Improvement generated bundle contract helpers now live outside the main site workflow module.

Changed

• Moved generated contract construction, drift issue creation, and drift summary formatting into cli/lib/site-bundle-contract.mjs.
• Kept cli/lib/site.mjs focused on bundle check and handoff orchestration by importing the generated contract helpers.
• Preserved generated bundle contract comparison behavior, digest formatting, repair guidance inputs, and bundle check report shape.

Impact

• cli/lib/site.mjs no longer owns the generated bundle contract helper bodies.
• Bundle check, bundle repair, bundle compare, and target-repo handoff flows continue to receive the same generatedContract data.
• Generated contract logic now sits beside bundle file/checksum helpers instead of being embedded in the main workflow module.

Verification Plan

• node --check cli/lib/site-bundle-contract.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 685 — Website Improvement Handoff Bundle Builder Split (unreleased)

Website Improvement handoff bundle assembly now lives outside the main site workflow module.

Changed

• Moved buildSiteHandoffBundle into cli/lib/site-bundle-build.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting the bundle builder.
• Preserved bundle summary, file ordering, checksums, README generation, MCP artifacts, and prompt artifacts without changing output contracts.

Impact

• cli/lib/site.mjs no longer owns the handoff bundle file assembly body.
• Existing imports from cli/lib/site.mjs, design-ai site --bundle, bundle repair, generated-contract comparison, and bundle handoff flows remain behavior-compatible.
• Bundle construction is now grouped with its deterministic artifact dependencies while bundle check/repair orchestration remains in the main workflow module.

Verification Plan

• node --check cli/lib/site-bundle-build.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 684 — Website Improvement Task and Workflow Graph Helper Split (unreleased)

Website Improvement generated task planning and portable workflow graph rendering now live outside the main site workflow module.

Changed

• Moved deterministic refactor task generation into cli/lib/site-tasks.mjs.
• Moved workflow graph node/edge construction plus JSON/Markdown graph formatters into cli/lib/site-workflow-graph.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting task and graph helpers.

Impact

• cli/lib/site.mjs no longer owns generated task prompt bodies or graph rendering bodies.
• Existing imports from cli/lib/site.mjs, design-ai site --tasks, and design-ai site --graph remain behavior-compatible.
• Task planning can now be reused by graph and bundle orchestration without forcing those deterministic helpers to stay in the main workflow module.

Verification Plan

• node --check cli/lib/site-tasks.mjs && node --check cli/lib/site-workflow-graph.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 683 — Website Improvement Analysis Helper Split (unreleased)

Website Improvement workspace validation, summary generation, JSON loading, and report formatting now live outside the main site workflow module.

Changed

• Moved raw workspace validation, issue status reduction, summary counts, analyzeSiteWorkspace, loadSiteWorkspaceInput, buildSiteReport, and formatSiteJson into cli/lib/site-analysis.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting the existing analysis/report helper API.
• Imported addIssue, statusFromIssues, analyzeSiteWorkspace, and loadSiteWorkspaceInput back into cli/lib/site.mjs for bundle repair/check/handoff orchestration.

Impact

• cli/lib/site.mjs no longer owns schema validation, report input loading, or workspace summary construction bodies.
• Existing imports from cli/lib/site.mjs, report JSON output, strict workspace validation, and bundle consistency checks remain behavior-compatible.
• Analysis rules now sit beside workspace normalization while bundle orchestration remains in the main site workflow module.

Verification Plan

• node --check cli/lib/site-analysis.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 682 — Website Improvement Workspace Builder Split (unreleased)

Website Improvement workspace initialization, intake parsing, and normalization now live outside the main site workflow module.

Changed

• Moved real-project --init workspace construction, filled intake Markdown parsing, and workspace normalization into cli/lib/site-workspace.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting workspace builder helpers.
• Imported only normalizeSiteWorkspace and normalizeObject back into cli/lib/site.mjs for report validation and bundle summary orchestration.

Impact

• cli/lib/site.mjs no longer owns workspace creation, intake table parsing, or schema normalization bodies.
• Existing imports from cli/lib/site.mjs, design-ai site --init, and design-ai site --from-intake remain behavior-compatible.
• Workspace construction is grouped with its defaults and normalization rules, leaving the main site module focused on analysis, reports, graphs, and bundle orchestration.

Verification Plan

• node --check cli/lib/site-workspace.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 681 — Website Improvement Starter Artifact Helper Split (unreleased)

Website Improvement intake template and sample workspace builders now live outside the main site workflow module.

Changed

• Moved intake template Markdown/JSON rendering and sample workspace construction into cli/lib/site-starter.mjs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting the starter helper API.
• Preserved the sample workspace as the normalization fallback by importing it from the starter module.

Impact

• cli/lib/site.mjs no longer owns starter artifact bodies for --intake-template and --sample.
• Intake template output, sample workspace output, CLI import paths, and normalization fallback behavior remain behavior-compatible.
• Starter artifacts now live with their static content dependencies instead of mixing with workspace analysis and bundle orchestration.

Verification Plan

• node --check cli/lib/site-starter.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 680 — Website Improvement Bundle README Helper Split (unreleased)

Website Improvement bundle README and strict handoff guidance builders now live outside the main site workflow module.

Changed

• Moved bundle handoff guidance construction and bundle README Markdown assembly into cli/lib/site-bundle-readme.mjs.
• Kept bundle generation orchestration, checksum creation, and artifact ordering in cli/lib/site.mjs.
• Reused the existing target-repo execution checklist contract from cli/lib/site-bundle-handoff-summary.mjs.

Impact

• cli/lib/site.mjs no longer owns bundle README copy or strict/draft handoff command guidance.
• Bundle contents, README text, handoff readiness metadata, and existing bundle check behavior remain behavior-compatible.
• The remaining bundle generation flow is easier to scan because artifact orchestration is separated from README prose assembly.

Verification Plan

• node --check cli/lib/site-bundle-readme.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 679 — Website Improvement CLI Argument Parser Split (unreleased)

Website Improvement CLI argument parsing now lives outside the main site workflow module.

Changed

• Moved SITE_OPTIONS, option value parsing, and parseSiteArgs into cli/lib/site-args.mjs.
• Exported shared Website Improvement option enums from cli/lib/site-options.mjs so parsing, intake, normalization, and validation use the same catalogs.
• Kept cli/lib/site.mjs as the public compatibility surface by re-exporting the parser API.

Impact

• cli/lib/site.mjs no longer owns command-line parsing rules.
• design-ai site argument behavior, error messages, and existing imports from cli/lib/site.mjs remain behavior-compatible.
• The remaining site workflow module is easier to scan because CLI parsing is separated from workspace construction and report generation.

Verification Plan

• node --check cli/lib/site-args.mjs && node --check cli/lib/site-options.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 678 — Website Improvement Prompt Helper Consolidation (unreleased)

Website Improvement prompt template formatters and bundle implementation prompt fallback now live with the prompt builders.

Changed

• Moved prompt template JSON/human formatters and bundle implementation prompt fallback rendering into cli/lib/site-prompts.mjs.
• Kept cli/lib/site.mjs as the public re-export surface and bundle orchestration caller for existing imports.
• Reused the existing prompt builder helpers for the no-task bundle fallback instead of keeping prompt body composition in the site workflow module.

Impact

• cli/lib/site.mjs no longer owns prompt-template display or bundle implementation prompt body construction.
• Prompt list CLI output, prompt bundle generation, and handoff bundle codex-implementation.md content remain behavior-compatible.
• Prompt-related rendering is grouped with the rest of the prompt/handoff report code, making the remaining site workflow module easier to scan.

Verification Plan

• node --check cli/lib/site-prompts.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 677 — Website Improvement Bundle Handoff Summary Helper Split (unreleased)

Website Improvement bundle handoff task catalog and source summary helpers now live outside the main site workflow module.

Changed

• Moved target-repo execution checklist, bundle task catalog summaries, selected-task summary, handoff issue/task catalog line formatting, handoff boundaries, and source bundle command summary into cli/lib/site-bundle-handoff-summary.mjs.
• Kept bundle workspace loading, task selection orchestration, handoff prompt construction, and final handoff report assembly in cli/lib/site.mjs.
• Reused the extracted summary helpers in bundle readme/check validation and target-repo handoff output paths without changing the JSON or Markdown contracts.

Impact

• cli/lib/site.mjs no longer owns task catalog shaping or source bundle command summary construction.
• Bundle check validation, handoff prompt checklist text, selected-task command metadata, and command manifest inputs remain behavior-compatible.
• This makes the remaining handoff flow easier to scan because catalog/source summary data is separated from report orchestration.

Verification Plan

• node --check cli/lib/site-bundle-handoff-summary.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 676 — Website Improvement Bundle Handoff Runbook Helper Split (unreleased)

Website Improvement bundle handoff command manifest and operator runbook helpers now live outside the main site workflow module.

Changed

• Moved bundle handoff command manifest construction, operator runbook assembly, and runbook Markdown line formatting into cli/lib/site-bundle-handoff-runbook.mjs.
• Kept bundle validation, task selection, prompt construction, and final handoff report assembly in cli/lib/site.mjs.
• Reused the extracted runbook helpers from the existing bundle handoff report path without changing JSON or human-readable output contracts.

Impact

• cli/lib/site.mjs no longer owns the large deterministic operator runbook payload builder.
• Bundle handoff JSON snapshots, task command manifests, evidence capture metadata, and target-repo prompt output remain behavior-compatible.
• This leaves the remaining handoff flow easier to read because report orchestration is separated from runbook payload construction.

Verification Plan

• node --check cli/lib/site-bundle-handoff-runbook.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 675 — Website Improvement Bundle Compare Helper Split (unreleased)

Website Improvement bundle compare summary, diff, and formatter helpers now live outside the main site workflow module.

Changed

• Moved bundle compare summaries, metadata/file diff builders, and JSON/Markdown compare formatters into cli/lib/site-bundle-compare.mjs.
• Kept bundle check orchestration and compare report assembly in cli/lib/site.mjs because compare report creation still depends on strict bundle validation.
• Re-exported compare formatters from cli/lib/site.mjs so existing imports keep their public API.

Impact

• cli/lib/site.mjs no longer owns deterministic compare formatting or checksum diff construction.
• Bundle compare JSON and human-readable output keep the existing output contract.
• This narrows the remaining bundle orchestration surface before larger check/handoff boundaries are split.

Verification Plan

• node --check cli/lib/site-bundle-compare.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 674 — Website Improvement Bundle Repair Helper Split (unreleased)

Website Improvement bundle repair guidance helpers now live outside the main site workflow module.

Changed

• Moved bundle repair command guidance, repair guidance Markdown lines, and before/after repair check summaries into cli/lib/site-bundle-repair.mjs.
• Kept repair preview, repair bundle regeneration, applied repair verification, and bundle check orchestration in cli/lib/site.mjs.
• Reused the extracted repair guidance in bundle check reports, repair reports, and target-repo handoff prompts.

Impact

• cli/lib/site.mjs no longer owns repair command construction or repair check summary formatting.
• Bundle repair preview/apply, strict bundle check, and handoff prompt repair sections keep their existing JSON/Markdown output contract.
• This leaves repair execution in the orchestrator while moving deterministic repair guidance into a smaller module.

Verification Plan

• node --check cli/lib/site-bundle-repair.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 673 — Website Improvement Bundle File Helper Split (unreleased)

Website Improvement bundle file, digest, and lightweight validation helpers now live outside the main site workflow module.

Changed

• Moved SHA-256 digest creation, bundle checksum manifest hashing, bundle file reads, JSON parsing, Markdown fragment checks, short digest rendering, and array equality checks into cli/lib/site-bundle-files.mjs.
• Kept bundle generation, generated-contract comparison, repair, check, compare, and target-repo handoff report assembly in cli/lib/site.mjs.
• Reused the extracted helpers for bundle creation checksums, strict bundle verification, generated file drift reporting, and handoff prompt context reads.

Impact

• cli/lib/site.mjs no longer owns low-level bundle file parsing or checksum mechanics.
• Bundle check, repair, compare, handoff, and checksum validation keep the existing JSON/Markdown output contract.
• This keeps the next bundle split safer because filesystem and digest helpers are now isolated from workspace analysis and report assembly.

Verification Plan

• node --check cli/lib/site-bundle-files.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 672 — Website Improvement Bundle Command Helper Split (unreleased)

Website Improvement bundle handoff command and safety helpers now live outside the main site workflow module.

Changed

• Moved bundle task handoff command args, check/handoff command args, shell quoting, output-file naming, and command safety policy helpers into cli/lib/site-bundle-commands.mjs.
• Kept bundle check, repair, compare, and target-repo handoff report assembly in cli/lib/site.mjs so this split stays limited to deterministic command construction.
• Reused the same helper outputs for task catalogs, operator runbooks, repair guidance, and source bundle verification prompts.

Impact

• cli/lib/site.mjs no longer owns low-level bundle command string construction or local/read-only safety policy payloads.
• Bundle repair guidance, strict bundle checks, task-specific handoff commands, and target-repo handoff prompts keep the existing command and JSON contract.
• This prepares the remaining bundle check/repair/handoff logic for smaller future module boundaries without changing external behavior.

Verification Plan

• node --check cli/lib/site-bundle-commands.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 671 — Website Improvement Prompt Module Split (unreleased)

Website Improvement prompt and handoff report builders now live outside the main site workflow module.

Changed

• Moved Codex/Claude prompt rendering, task selection, ordered refactor-task sorting, and Website Improvement handoff report Markdown into cli/lib/site-prompts.mjs.
• Moved audit category catalog and category lookup into cli/lib/site-options.mjs so prompts, workflow graphs, task normalization, and reports share one source.
• Moved default implementation risk normalization into cli/lib/site-evidence.mjs so handoff reports and workspace normalization share the same evidence defaults.
• Re-exported prompt and handoff helpers from cli/lib/site.mjs so existing imports keep working.

Impact

• cli/lib/site.mjs no longer owns Codex/Claude prompt body composition or final handoff report rendering.
• Bundle creation, bundle handoff, workflow graph, and prompt CLI flows keep their existing output contracts and local-only safety boundaries.
• This keeps the Website Improvement CLI moving toward smaller, readable modules without weakening verification, evidence, or MCP readiness tracking.

Verification Plan

• node --check cli/lib/site-options.mjs && node --check cli/lib/site-evidence.mjs && node --check cli/lib/site-prompts.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 670 — Website Improvement Next Actions Module Split (unreleased)

Website Improvement next-action reports now live outside the main site workflow module.

Changed

• Moved standard, init, and intake next-action report builders plus next-action JSON/human formatting into cli/lib/site-next-actions.mjs.
• Moved implementation evidence key/count helpers into cli/lib/site-evidence.mjs so next-action reports, bundles, and bundle checks share the same evidence counting rules.
• Re-exported next-action helpers from cli/lib/site.mjs so existing imports keep working.

Impact

• cli/lib/site.mjs no longer owns operator next-action prioritization or setup command rendering.
• Website Improvement init, intake, readiness, task generation, prompt, handoff, and bundle guidance keep their existing command and output contracts.
• This continues the split toward smaller modules while preserving verification, handoff evidence, and local-only safety boundaries.

Verification Plan

• node --check cli/lib/site-evidence.mjs && node --check cli/lib/site-next-actions.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 669 — Website Improvement MCP Report Module Split (unreleased)

Website Improvement MCP readiness reports and action plans now live outside the main site workflow module.

Changed

• Moved MCP status combination, MCP key normalization, task/MCP gap detection, readiness check report formatting, and MCP action plan rendering into cli/lib/site-mcp-report.mjs.
• Moved shared MCP item and priority option catalogs into cli/lib/site-options.mjs so site.mjs and MCP report helpers can share them without circular imports.
• Re-exported the public MCP report/action-plan helpers from cli/lib/site.mjs so existing imports keep working.

Impact

• cli/lib/site.mjs no longer owns MCP readiness report construction or action-plan Markdown rendering.
• Website Improvement MCP check, probe-aware MCP check, MCP action plan, next-actions, workflow graph, bundle, and handoff flows keep the same output contract.
• This leaves site.mjs closer to orchestration while MCP handoff logic is grouped in a dedicated module for Claude/Codex MCP use.

Verification Plan

• node --check cli/lib/site-options.mjs && node --check cli/lib/site-mcp-report.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 668 — Website Improvement String Helper Split (unreleased)

Website Improvement string normalization and Markdown rendering helpers now live outside the main site workflow module.

Changed

• Moved normalizeStringArray, markdownTable, and markdownList into cli/lib/site-strings.mjs.
• Kept the existing Markdown output shape for MCP action plans, workflow graphs, bundle READMEs, handoff reports, and prompt bundles.
• Left browser-console helpers in docs/website-console/app.js untouched because this change only affects the CLI module boundary.

Impact

• cli/lib/site.mjs no longer owns low-level string cleanup and Markdown table/list rendering.
• Future Website Improvement action-plan and bundle modules can share the same small formatting helpers without circular imports.
• Existing CLI JSON/human/Markdown output contracts remain unchanged.

Verification Plan

• node --check cli/lib/site-strings.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 667 — Website Improvement MCP Command Helper Split (unreleased)

Website Improvement MCP readiness command strings now live outside the main site workflow module.

Changed

• Moved MCP probe command generation, next-action command generation, and stdin command-target normalization into cli/lib/site-mcp-commands.mjs.
• Kept the existing command names and output paths unchanged for --mcp-check, --mcp-plan, --tasks, --prompt, --report, and --bundle flows.
• Left report assembly in cli/lib/site.mjs so this split stays limited to deterministic command construction.

Impact

• cli/lib/site.mjs no longer owns repeated MCP/readiness command string construction.
• MCP readiness reports, action plans, next-actions output, and bundle handoff guidance keep their current CLI command contract.
• This continues the Website Improvement module split toward a cleaner Claude/Codex MCP handoff surface without changing runtime behavior.

Verification Plan

• node --check cli/lib/site-mcp-commands.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 666 — Website Improvement MCP Readiness Helper Split (unreleased)

Website Improvement MCP readiness scoring now lives outside the main site workflow module.

Changed

• Moved MCP readiness evidence collection, readiness item construction, and aggregate check status scoring into cli/lib/site-mcp-readiness.mjs.
• Kept task/MCP gap detection in cli/lib/site.mjs because it still depends on normalized task metadata and local workspace structures.
• Left the existing buildSiteMcpCheckReport JSON and human report contract unchanged.

Impact

• cli/lib/site.mjs is smaller and now focuses on command/report assembly rather than low-level MCP readiness rules.
• MCP readiness, probe output, task gap warnings, and generated next actions keep the same behavior for existing Website Improvement workspaces.
• This continues the incremental Website Improvement module split while preserving MCP handoff evidence and verification surfaces.

Verification Plan

• node --check cli/lib/site-mcp-readiness.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 665 — Website Improvement MCP Probe Helper Split (unreleased)

Website Improvement read-only MCP probe logic now lives outside the main site workflow module.

Changed

• Moved URL parsing, GitHub/Figma reference parsing, local repo directory probe checks, probe item construction, and buildSiteMcpProbeReport into cli/lib/site-mcp-probes.mjs.
• Re-exported buildSiteMcpProbeReport from cli/lib/site.mjs so existing tests and consumers keep the same helper import surface.
• Kept broader MCP readiness scoring and task/MCP gap logic in cli/lib/site.mjs for now because it still depends on workspace normalization and task ranking helpers.

Impact

• cli/lib/site.mjs is smaller and its MCP readiness section now focuses on report assembly rather than low-level URL/path probe mechanics.
• The probe report remains read-only, makes no external MCP calls, and keeps the same JSON/human output contract.
• This continues the incremental Website Improvement module split without changing CLI flags, bundle checks, or handoff evidence surfaces.

Verification Plan

• node --check cli/lib/site-mcp-probes.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 664 — Website Improvement Intake Template Content Split (unreleased)

Website Improvement intake template Markdown now lives with the static content catalog instead of the main workflow module.

Changed

• Moved English and Korean intake template Markdown plus the intake section list into cli/lib/site-content.mjs.
• Kept buildSiteIntakeTemplateMarkdown and formatSiteIntakeTemplateJson in cli/lib/site.mjs so command behavior and public helper names remain unchanged.

Impact

• cli/lib/site.mjs no longer carries the long intake template bodies inline, making the executable workflow code easier to scan.
• The generated English/Korean intake Markdown, JSON metadata, CLI flags, and tests remain unchanged.
• This continues the incremental split of static Website Improvement content without reducing validation, bundle, or handoff evidence surfaces.

Verification Plan

• node --check cli/lib/site-content.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 663 — Website Improvement Static Content Module Split (unreleased)

Website Improvement prompt and bundle catalogs now live outside the main site workflow module.

Changed

• Moved Website Improvement prompt template ids, prompt template metadata, bundle file manifest, and bundle checksum manifest into cli/lib/site-content.mjs.
• Re-exported the public constants from cli/lib/site.mjs so existing tests and consumers keep the same import surface.
• Kept the prompt template ordering assertion next to the catalog data it protects.

Impact

• cli/lib/site.mjs is smaller and its executable workflow logic is easier to scan.
• No CLI behavior, JSON contract, bundle manifest, prompt catalog, or test import path changes.
• This is the first low-risk split toward reducing the oversized Website Improvement module without reducing verification or evidence surfaces.

Verification Plan

• node --check cli/lib/site-content.mjs && node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 662 — VS Code Extension Dev Dependency Audit Hygiene (unreleased)

VS Code extension development dependencies now install with a clean npm audit report.

Changed

• Pinned the Mocha integration-test harness at 11.3.0 to avoid the vulnerable newer diff range while keeping the extension e2e runner on the current major.
• Added npm overrides for js-yaml and serialize-javascript so transitive Mocha audit findings resolve without changing extension runtime dependencies.
• Refreshed vscode-extension/package-lock.json from the updated dependency policy.

Impact

• npm audit --prefix vscode-extension --audit-level=moderate now reports zero vulnerabilities.
• The published VSIX runtime surface remains unchanged because the extension still has no production dependencies.
• The integration test harness still uses Mocha and remains covered by the VS Code extension e2e test.

Verification Plan

• npm audit --prefix vscode-extension --audit-level=moderate
• npm run compile --prefix vscode-extension
• npm test --prefix vscode-extension
• npm run test:e2e --prefix vscode-extension
• npm test
• npm run audit:strict
• git diff --check

Phase 661 — Website Console Revalidation Gate JSON Action Labels (unreleased)

Website Console revalidation gate action buttons now identify that they produce compact gate JSON.

Added

• Renamed the Source Bundle revalidation gate row actions from generic gate labels to gate JSON labels.
• Kept action ids and generated gate JSON payloads unchanged.

Impact

• Operators can distinguish focused provenance JSON from compact revalidation gate JSON before copying or exporting.
• The change improves UI clarity without changing local state, export payloads, or target-repo handoff behavior.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 660 — Website Console Source Bundle Artifact Action Labels (unreleased)

Website Console Source Bundle action buttons now identify whether they produce Markdown or provenance JSON.

Added

• Renamed Source Bundle header actions from generic bundle/JSON labels to artifact-specific Markdown and provenance JSON labels.
• Kept action ids and generated artifact formats unchanged.

Impact

• Operators can distinguish source-bundle Markdown, focused provenance JSON, and gate JSON workflows more quickly before copying or exporting.
• The change improves UI clarity without changing local state, export payloads, or target-repo handoff behavior.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 659 — Website Console Source Bundle Source Copy Action (unreleased)

Website Console Source Bundle detail review now lets operators copy the current runbook source marker directly.

Added

• Added a copy-ready Source row in the Source Bundle provenance detail table.
• Added a copy-runbook-source-marker action that copies the normalized Operator Runbook source with a provenance fallback.

Impact

• Operators can pass source marker evidence to follow-up notes, QA logs, or wrapper tools without copying a larger Markdown/JSON artifact.
• The source marker workflow now supports scan, export, import, and single-value copy paths.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 658 — Website Console Source-Aware Empty Runbook Markdown (unreleased)

Website Console provenance-only Operator Runbook Markdown now keeps the source marker in the empty stage message.

Added

• Added source-aware text to the provenance-only empty Stages section.
• Keeps the existing filtered-empty message unchanged.

Impact

• Markdown snippets that include only the Stages section still identify whether the artifact came from focused provenance or gate-only import state.
• Source marker consistency now covers metadata, notices, detail rows, compact JSON, focused Markdown, and empty runbook Markdown.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 657 — Website Console Focused Provenance Import Source Refresh (unreleased)

Website Console focused source-bundle provenance imports now refresh provenance-only runbook source markers.

Added

• Updates existing provenance-only Operator Runbooks to source-bundle-provenance when a focused source-bundle provenance JSON artifact is imported.
• Keeps full bundle handoff runbook sources unchanged when stage rows already exist.

Impact

• Importing focused provenance JSON after a gate-only JSON review no longer leaves stale source-bundle-revalidation-gate metadata in the browser UI.
• Source marker behavior is now symmetric between gate-only import and focused provenance import for provenance-only reviews.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 656 — Website Console Provenance-Only Notice Source Marker (unreleased)

Website Console provenance-only Operator Runbook notices now show the source marker inline.

Added

• Added a Source line to the provenance-only notice block.
• Uses the current Operator Runbook source with a source-bundle-provenance fallback for focused source-bundle imports.

Impact

• Gate-only and focused provenance imports remain identifiable even when an operator screenshots or copies only the provenance-only notice area.
• The notice now matches the source marker convention used by metadata pills, detail tables, Markdown, and JSON exports.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 655 — Website Console Operator Runbook Metadata Source Pill (unreleased)

Website Console Operator Runbook metadata now shows the current source marker in the top pill row.

Added

• Added a Source pill to the Operator Runbook metadata strip.
• Uses the normalized Operator Runbook source with a bundle-handoff fallback for legacy/full runbooks.

Impact

• Operators can identify full handoff, focused provenance, or gate-only import state before scanning the Source Bundle detail table.
• The visible UI now matches source markers already present in runbook Markdown, source-bundle Markdown, and compact JSON exports.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 654 — Website Console Source Bundle Detail Source Marker (unreleased)

Website Console Source Bundle detail review now shows the Operator Runbook source marker in the browser table.

Added

• Added a Source row to the Source Bundle provenance detail table.
• Uses the current Operator Runbook source with a source-bundle-provenance fallback so full handoff, focused provenance, and gate-only import states remain visible in the UI.

Impact

• Operators can confirm provenance directly in the browser without opening Markdown or JSON exports.
• The Source Bundle detail table now matches the source marker convention used by compact JSON and focused Markdown artifacts.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 653 — Website Console Source Bundle Markdown Source Marker (unreleased)

Website Console focused source-bundle Markdown exports now include the Operator Runbook source marker.

Added

• Added a Source row to focused source-bundle Markdown copy/export output.
• Passes the current Operator Runbook source into source-bundle Markdown generation so full handoff, focused provenance, and gate-only import states remain distinguishable.

Impact

• Markdown-only handoffs preserve the same provenance signal already available in JSON payloads and Operator Runbook metadata.
• Operators can inspect archived source-bundle Markdown and tell whether it came from bundle-handoff, source-bundle-provenance, or source-bundle-revalidation-gate state.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 652 — Website Console Focused Provenance JSON Source Marker Export (unreleased)

Website Console focused source-bundle provenance JSON exports now include an explicit source marker.

Added

• Added top-level source: "source-bundle-provenance" to website-improvement-source-bundle-provenance JSON copy/export payloads.
• Keeps the existing payload type, sourceBundle, and revalidationGate contract intact for backward-compatible import.

Impact

• Operators and wrapper automation can distinguish focused source-bundle provenance payloads from gate-only payloads using the same source-marker convention.
• Compact source-bundle JSON export/import now uses consistent provenance language across payload, browser state, and Markdown metadata.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 651 — Website Console Gate-Only JSON Source Marker Export (unreleased)

Website Console gate-only revalidation JSON exports now include the same source marker that imports store in Operator Runbook state.

Added

• Added top-level source: "source-bundle-revalidation-gate" to website-improvement-source-bundle-revalidation-gate JSON copy/export payloads.
• Keeps the existing payload type, sourceBundle, and revalidationGate contract intact for backward-compatible import.

Impact

• Operators and wrapper automation can identify compact gate-only payloads by source marker without relying only on type.
• Gate-only JSON export/import now carries consistent provenance language across payload, browser state, and Markdown metadata.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 650 — Website Console Gate-Only Import Source Marker (unreleased)

Website Console gate-only revalidation JSON imports now preserve a distinct Operator Runbook source marker.

Added

• Added source-bundle-revalidation-gate as the provenance-only source for imported website-improvement-source-bundle-revalidation-gate artifacts.
• Updates existing provenance-only runbooks to the gate-only source marker when a compact gate artifact is imported.
• Keeps full bundle handoff runbook sources unchanged when stage rows already exist.
• Clarifies the provenance-only notice for gate-only imports.

Impact

• Operators can distinguish compact gate-only imports from focused source-bundle provenance imports in UI state and Markdown exports.
• Company website pilots can track whether a Report tab review came from a full handoff, focused provenance JSON, or compact revalidation gate JSON.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 649 — Website Console Gate-Only JSON Diagnostic Count Preservation (unreleased)

Website Console gate-only revalidation JSON now preserves warning and issue counts during compact export/import roundtrips.

Added

• Added revalidationGate.warningCount to gate-only JSON output.
• Added revalidationGate.issueCount to gate-only JSON output.
• Rehydrates warning and issue counts during gate-only JSON import so the Source Bundle diagnostics row stays consistent with the compact gate artifact.

Impact

• Operators can import gate-only artifacts without losing non-failing diagnostic totals in the Source Bundle detail table.
• Automation and wrapper layers keep a compact revalidation payload while preserving enough diagnostic context for review.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 648 — Website Console Gate-Only JSON Source Context Preservation (unreleased)

Website Console gate-only revalidation JSON now preserves source workspace and site name context during export/import roundtrips.

Added

• Added sourceBundle.sourceWorkspace to website-improvement-source-bundle-revalidation-gate JSON exports.
• Added sourceBundle.siteName to the same compact gate-only JSON exports.
• Rehydrates those fields during gate-only JSON import so provenance-only review keeps source context.

Impact

• Operators can inspect compact gate artifacts without losing the source workspace or site name in the Source Bundle detail table.
• Automation and wrapper layers can keep a small gate-only payload while retaining enough human context for review.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 647 — Website Console Source Bundle Revalidation Gate JSON Import (unreleased)

Website Console now imports compact source-bundle revalidation gate JSON artifacts back into Operator Runbook review.

Added

• Added import detection for website-improvement-source-bundle-revalidation-gate JSON payloads.
• Rehydrates minimal source-bundle provenance from gate identity, normalized status, validity, failure count, and strict check command metadata.
• Opens the Report tab with provenance-only Operator Runbook review when no full runbook is already loaded.

Impact

• Operators can round-trip gate-only artifacts without exporting or importing full source-bundle provenance.
• Automation and wrapper layers can hand a compact gate artifact back to the console for visual review before target-repo execution.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 646 — Website Console Source Bundle Revalidation Gate JSON Export (unreleased)

Website Console now lets operators copy or export only the source-bundle revalidation gate as a compact JSON artifact.

Added

• Added Copy gate and Export gate controls to the Source Bundle Revalidation gate detail row.
• Added a dedicated website-improvement-source-bundle-revalidation-gate JSON payload with source-bundle identity and revalidationGate metadata.
• Added guarded click handlers so unavailable gate state reports a clear message instead of exporting an empty artifact.

Impact

• Automation and wrapper layers can consume a small gate-only artifact without receiving the full source-bundle provenance payload.
• Company website pilots can pass the strict-check block reason between local tools before target-repo execution.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 645 — Website Console Operator Runbook Gate Metadata Badge (unreleased)

Website Console Operator Runbook metadata now shows source-bundle revalidation state before the detail table.

Added

• Added a Gate: not required pass badge when imported source-bundle provenance is valid and failure-free.
• Added a Gate: required warn badge when imported source-bundle provenance is invalid or has bundle-check failures.
• Reused the existing source-bundle revalidation predicate so metadata badges, detail rows, warning blocks, Markdown, and JSON gate metadata stay aligned.

Impact

• Operators can see source-bundle gate state immediately in the runbook metadata strip.
• Provenance-only imports and full bundle handoff imports now expose the same first-scan revalidation signal.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 644 — Website Console Source Bundle JSON Gate Reason Metadata (unreleased)

Website Console source-bundle JSON exports now include explicit revalidation reason and strict-check command availability metadata.

Added

• Added revalidationGate.strictCheckCommandAvailable to focused source-bundle JSON copy/export payloads.
• Added revalidationGate.reason values for missing provenance, required revalidation, missing strict-check command, and not-required state.
• Kept the existing sourceBundle payload and existing revalidationGate.required/status/message fields intact for backward compatibility.

Impact

• Automation and wrapper layers can distinguish missing strict-check commands from ready strict-check gates without parsing command strings.
• Company website pilots get a clearer machine-readable reason when compact provenance artifacts block target-repo execution.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 643 — Website Console Source Bundle Revalidation Gate Badges (unreleased)

Website Console Source Bundle detail review now uses badges for revalidation gate state.

Added

• Added a pass badge for source bundles where strict revalidation is not required.
• Added a warn badge for source bundles where strict revalidation is required.
• Added muted helper text beside the badge so the table remains scannable while preserving the actionable gate summary.

Impact

• Operators can distinguish clear versus blocked source-bundle gate state without reading a long text cell.
• The detail table now aligns with the existing dense dashboard badge language used across readiness, status, and runbook surfaces.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 642 — Website Console Source Bundle Revalidation Detail Row (unreleased)

Website Console Source Bundle detail review now shows revalidation gate state in the provenance table.

Added

• Added a Revalidation gate row to the Operator Runbook Source Bundle detail table.
• Shows not required for valid/failure-free source bundles.
• Shows a required strict-check summary when imported provenance is invalid, failing, or missing the strict check command.

Impact

• Operators can confirm normal source-bundle gate state without relying on the absence of a warning block.
• Incomplete provenance still surfaces a clear strict-check requirement in the same detail table as diagnostics and commands.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 641 — Website Console Source Bundle Strict Command Copy Guards (unreleased)

Website Console now guards source-bundle strict command copy actions when imported provenance lacks command strings.

Added

• Added click-handler guards for strict source-bundle check command copy.
• Added click-handler guards for strict source-bundle handoff command copy.
• Reports an unavailable-command message instead of copying an empty string and showing a false success state.

Impact

• Imported or hand-edited provenance artifacts cannot accidentally produce empty command clipboard state with a success toast.
• Operators get clearer feedback when source-bundle provenance is incomplete before target-repo execution.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 640 — Website Console Source Bundle JSON Revalidation Gate (unreleased)

Website Console focused source-bundle JSON exports now include machine-readable revalidation gate metadata.

Added

• Added revalidationGate to website-improvement-source-bundle-provenance JSON copy/export payloads.
• Reports whether strict source-bundle revalidation is required, the normalized bundle status, validity, failure count, strict check command, and an operator message.
• Keeps the existing sourceBundle payload intact so existing imports and wrappers remain backward-compatible.

Impact

• Automation and follow-up tools can gate target-repo execution without parsing Markdown strings or browser UI copy.
• Company website pilots can pass compact source-bundle provenance between tools while preserving a structured invalid-bundle stop signal.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 639 — Website Console Source Bundle Revalidation Markdown Gate (unreleased)

Website Console copied/exported Markdown artifacts now preserve the same source-bundle revalidation gate shown in the browser UI.

Added

• Added a Source bundle revalidation line to full and filtered Operator Runbook Markdown exports.
• Added a Revalidation gate row to focused source-bundle provenance Markdown exports.
• Reused one deterministic revalidation helper so UI warning blocks and Markdown exports agree on invalid/failing bundle state.

Impact

• Company website pilots keep the strict source-bundle check gate visible even after copying or exporting runbooks outside the browser.
• Operators can share provenance artifacts without losing the invalid-bundle stop signal.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 638 — Website Console Source Bundle Revalidation Warning Gate (unreleased)

Website Console now surfaces invalid or failing source-bundle provenance as an explicit revalidation gate before target-repo execution.

Added

• Added a Source Bundle warning block when imported provenance is not valid or reports bundle-check failures.
• Shows the source-bundle status, failure count, and strict bundle-check command when available.
• Keeps the warning visible for both full bundle handoff runbooks and provenance-only source-bundle imports.

Impact

• Company website pilots get a clear stop signal before entering the target website repo with an invalid handoff bundle.
• Operators can copy or rerun the strict bundle-check command without hunting through raw JSON or Markdown exports.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 637 — Website Console Operator Runbook Provenance-Only Markdown Markers (unreleased)

Website Console copied/exported Operator Runbook Markdown now distinguishes provenance-only reviews from full bundle handoff runbooks.

Added

• Added a Provenance-only: yes/no line to Operator Runbook Markdown headers.
• Added a provenance-only empty-stage explanation when a full runbook export contains source-bundle metadata but no stage rows.
• Kept filtered exports using the existing filtered-empty message because filtered output is only available when stage rows exist.

Impact

• Archived runbook Markdown clearly communicates whether it is a compact source-bundle provenance artifact or a target-repo execution runbook.
• Operators can share full runbook exports from provenance-only reviews without recipients mistaking missing stage rows for data loss.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 636 — Website Console Operator Runbook Filtered-Row Action Guard (unreleased)

Website Console now guards filtered-row copy/export actions when an imported runbook has no stage rows.

Added

• Disabled Copy filtered rows and Export filtered .md when operatorRunbook.stageHumanLineDisplayRows is empty.
• Added click-handler fallbacks that report Filtered runbook rows unavailable instead of producing empty filtered artifacts.
• Kept full runbook export and source-bundle Markdown/JSON export available for provenance-only reviews.

Impact

• Provenance-only source-bundle imports no longer expose misleading filtered-row artifact actions.
• Operators can still archive provenance while stage-specific actions remain available only for full bundle handoff runbooks.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 635 — Website Console Operator Runbook Next-Line Action Guard (unreleased)

Website Console now guards the Copy next line action when an imported runbook has no next stage line.

Added

• Disabled the Copy next line button when operatorRunbook.nextStageHumanLine is unavailable.
• Added a click-handler fallback that reports Next runbook line unavailable instead of copying an empty string.
• Added a shared disabled style for Website Console buttons so disabled actions are visually clear and keyboard-safe.

Impact

• Provenance-only source-bundle imports no longer expose a misleading next-line copy action.
• Operators get a clearer distinction between source-bundle provenance review and full target-repo execution runbooks.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 634 — Website Console Provenance-Only Runbook Review State (unreleased)

Website Console now distinguishes source-bundle provenance-only imports from full bundle handoff runbooks.

Added

• Added a provenance-only notice in the Operator Runbook panel when imported source-bundle JSON contains bundle identity and guard commands but no stage rows.
• Hid row filter controls when a runbook has no display rows, avoiding irrelevant action/evidence filter UI for provenance-only reviews.
• Kept source-bundle detail, Markdown/JSON copy/export, and strict source command copy available for provenance-only imports.

Impact

• Company website pilots can tell the difference between a compact source-bundle provenance artifact and a full target-repo execution runbook.
• Operators avoid mistaking a valid source-bundle JSON import for a broken or incomplete bundle handoff import.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 633 — Website Console Source Bundle JSON Import (unreleased)

Website Console import now accepts focused source-bundle provenance JSON artifacts exported from Operator Runbook review.

Added

• Added import detection for website-improvement-source-bundle-provenance JSON payloads.
• Rehydrates source-bundle provenance into the current Operator Runbook when one is already loaded.
• Creates a provenance-only Operator Runbook when no runbook exists, so the Report tab can still review bundle identity, diagnostics, and guard commands.

Impact

• Company website pilots can round-trip source-bundle provenance as a compact JSON artifact without replacing the whole browser-local workspace.
• Operators can refresh source-bundle identity after regenerating or revalidating a bundle while keeping existing workspace notes, tasks, and evidence intact.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 632 — Website Console Source Bundle JSON Export (unreleased)

Website Console operator runbook review now lets operators copy or export source-bundle provenance as a focused portable JSON artifact.

Added

• Added Copy JSON and Export JSON actions to the Operator Runbook Source Bundle detail block.
• Added a dedicated source-bundle JSON payload with type, version, and normalized sourceBundle metadata.
• Kept the JSON artifact separate from full workspace export and full/filtered operator runbook export so follow-up tools can ingest provenance without unrelated browser-local state.

Impact

• Company website pilots can pass verified source-bundle identity and guard-command metadata into later local tooling without exposing the whole Website Console workspace.
• Operators can choose between human-readable Markdown provenance and machine-readable JSON provenance from the same Report tab.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 631 — Website Console Source Bundle Markdown Export (unreleased)

Website Console operator runbook review now lets operators archive source-bundle provenance as its own focused Markdown artifact.

Added

• Added Copy bundle and Export bundle actions to the Operator Runbook Source Bundle detail block.
• Added a dedicated source-bundle Markdown formatter with directory, source workspace, site name, status, workspace/MCP status, checksum digest, checksum/generated-file counts, diagnostics totals, and strict source commands.
• Kept the artifact separate from full/filtered operator runbook Markdown so provenance can be attached to handoff notes or target-repo issues without all stage rows.

Impact

• Company website pilots can preserve source bundle identity and guard commands as a compact audit artifact before target-repo execution.
• Operators can share bundle provenance independently from the detailed implementation runbook.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 630 — Website Console Operator Runbook Source Bundle Detail Review (unreleased)

Website Console operator runbook review now surfaces source-bundle diagnostics and strict source commands as copy-ready operator controls.

Added

• Added a Source Bundle detail block to the Operator Runbook panel with status, workspace/MCP state, checksum digest, checksum-file counts, generated-file counts, and diagnostics totals.
• Added copy-ready strict bundle check and strict bundle handoff command controls when those commands are present in imported sourceBundle metadata.
• Added strict source commands to full and filtered operator runbook Markdown exports.

Impact

• Company website pilots can revalidate the exact local handoff bundle before target-repo execution without opening raw JSON.
• Operators can copy source-bundle guard commands from the same Report tab used for stage-by-stage handoff review.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 629 — Website Console Operator Runbook Source Bundle Provenance (unreleased)

Website Console operator runbook review now preserves and displays source-bundle provenance from imported bundle handoff JSON.

Added

• Preserved optional source bundle metadata during operator runbook normalization, including directory, source workspace, site name, bundle status, validity, workspace/MCP status, checksum algorithm, bundle digest, generated-file counts, issue counts, and strict source commands.
• Imported sibling sourceBundle metadata from design-ai site <bundle-dir> --bundle-handoff --json output into the stored browser-local operator runbook.
• Added source bundle status, digest, and generated-file count chips to the Operator Runbook panel.
• Added source bundle status, digest, and directory to full and filtered runbook Markdown copy/export output.

Impact

• Company website pilots can verify the exact source bundle identity and validation state before entering the target repo.
• Operators can archive or paste runbook Markdown with bundle digest provenance, reducing ambiguity when multiple handoff bundles exist.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 628 — Website Console Operator Runbook Task Provenance Display (unreleased)

Website Console operator runbook review now preserves and displays task/command provenance from imported bundle handoff JSON.

Added

• Preserved optional effectiveTaskId, effectiveStrictTaskCommandKey, command/manual stage counts, read-only command stage counts, and local-output command stage counts during runbook normalization.
• Added metadata chips for effective task, strict command key, command stages, manual stages, read-only stages, and local-output stages in the Operator Runbook panel.
• Added effective task and strict task command key to full and filtered runbook Markdown copy/export output.

Impact

• Company website pilots can confirm which bundled task and strict handoff command the imported runbook targets before moving into the target repo.
• Operators can distinguish command-bearing, manual, read-only, and local-output stage shape without scanning every row.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 627 — Website Console Operator Runbook Row Markdown Export (unreleased)

Website Console operator runbook review now lets operators save one structured handoff stage as its own Markdown file.

Added

• Added per-row Export row actions beside Copy row and Copy line in the Operator Runbook table.
• Reused the row Markdown formatter so exported row files include the same stage heading, key, action status, evidence status, optional next evidence item, and copy-ready line as copied row Markdown.
• Added a small filename segment sanitizer so row exports use stable website-operator-runbook.<stage-key>.md filenames.

Impact

• Company website pilots can attach one focused stage artifact to an issue, implementation note, or target-repo handoff without exporting the full or filtered runbook.
• Operators can choose full export, filtered export, row export, row copy, or raw line copy depending on how much context the next tool needs.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 626 — Website Console Operator Runbook Row Markdown Copy (unreleased)

Website Console operator runbook review now lets operators copy one stage as Markdown with metadata, not only the raw copy-ready line.

Added

• Added per-row Copy row actions beside each Copy line action in the Operator Runbook table.
• Added a shared row Markdown formatter that includes stage heading, stable key, action status, action label, evidence status, evidence progress label, optional next evidence item, and the copy-ready line.
• Reused the same row formatter in full and filtered runbook Markdown output so row-level and document-level copy stay aligned.

Impact

• Company website pilots can paste a single structured handoff stage into an issue, implementation note, or target-repo Codex prompt without copying the entire runbook.
• Operators can choose between raw line copy for quick execution and row Markdown copy for context-rich handoff.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 625 — Website Console Operator Runbook Reset Filters (unreleased)

Website Console operator runbook review now includes a one-step reset control for action/evidence row filters.

Added

• Added a Reset filters button inside the Operator Runbook filter summary.
• Disabled the reset button with aria-disabled when both action and evidence filters are already all.
• Reset both browser-local runbook filters to all and re-render the full imported handoff row set in one action.
• Added compact reset styling with a 44px minimum touch target.

Impact

• Company website pilots can quickly return from a focused manual/evidence-blocked subset to the full handoff runbook.
• Operators no longer need to click both filter groups back to All individually before copying or exporting the complete view.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 624 — Website Console Operator Runbook Row Line Copy (unreleased)

Website Console operator runbook review now lets operators copy an individual stage line directly from the filtered runbook table.

Added

• Added per-row Copy line actions beside each copy-ready operator runbook stage line.
• Wired row copy through stageHumanLineDisplayRowByKey so filtered rows still copy the canonical imported row line by stable stage key.
• Added compact row-action styling with a 44px minimum touch target for keyboard and mobile use.

Impact

• Company website pilots can copy only one selected handoff stage without copying the next global line, the filtered subset, or the full runbook.
• The action works with filtered views because it uses the row key instead of table position.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 623 — Website Console Operator Runbook Markdown Export (unreleased)

Website Console operator runbook review now lets operators save full and filtered bundle handoff runbooks as Markdown files from the Report tab.

Added

• Added Export runbook .md for the full imported operator runbook.
• Added Export filtered .md for the currently visible action/evidence-filtered row subset.
• Reused the same Markdown builder as the copy actions so saved files include source, stage count, included row count, active filters, next stage, next command, and copy-ready stage lines.

Impact

• Company website pilots can archive the full handoff runbook or save a focused filtered runbook before moving into the target repo.
• Operators can attach the filtered runbook to internal notes, issues, or implementation records without manually copying from the browser.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 622 — Website Console Operator Runbook Filtered Copy (unreleased)

Website Console operator runbook review now lets operators copy only the currently visible action/evidence-filtered rows as Markdown while preserving full-runbook copy.

Added

• Added a Copy filtered rows action beside the full runbook and next-line copy actions.
• Added filtered Markdown output that records source, total stages, included row count, active action filter, active evidence filter, next stage, and next command.
• Reset browser-local runbook filters to all when importing or clearing a runbook so stale filters do not hide newly imported bundle handoff rows.

Impact

• Company website pilots can hand off only manual target-repo stages, evidence-blocked stages, or another focused filtered subset without copying the full runbook.
• Operators keep the full-copy path for archival handoff while gaining a narrower copy path for immediate execution.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• npm test
• git diff --check

Phase 621 — Website Console Operator Runbook Row Filters (unreleased)

Website Console operator runbook review now exposes action-status and evidence-progress row filters backed by the existing bundle handoff status-index contract.

Added

• Added browser-local runbook filter state for action status and evidence progress.
• Added accessible filter chips with row counts for all, ready, optional, manual, blocked, and evidence-ready/evidence-blocked rows.
• Updated the Operator Runbook table to render filtered rows while preserving all imported runbook data in localStorage/export JSON.
• Added an empty filtered-state message when no rows match the selected filters.

Impact

• Company website pilots can focus on manual target-repo actions or evidence-blocked rows before switching repositories.
• The Website Console now consumes the operatorRunbook.stageHumanLineDisplayRowKeysByActionStatus and stageHumanLineDisplayRowKeysByEvidenceProgressStatus contract directly instead of only showing summary chips.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 620 — Website Console Operator Runbook Import Handoff UX (unreleased)

Website Console operator runbook import now guides the operator directly into the Report tab after importing bundle handoff JSON, making the browser-local review step easier to discover before target-repo execution.

Added

• Updated the sidebar import copy to state that both workspace JSON and runbook JSON are accepted.
• Added nested bundle.operatorRunbook fallback support when normalizing imported JSON.
• Added Report-tab auto-navigation after a bundle handoff runbook import.
• Added report navigation count support for imported runbook stages when implementation evidence is not recorded yet.
• Documented the save-and-import workflow for design-ai site <bundle-dir> --bundle-handoff --strict --json --out target-repo-handoff.json --force.

Impact

• Company website pilots can round-trip from CLI bundle handoff JSON back into the static console without hunting for the Report tab.
• Operators can see that the Report section has imported runbook content even before target-repo verification evidence exists.
• The change remains browser-local, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• npm run audit:strict
• npm run release:metadata
• git diff --check

Phase 619 — Website Console Operator Runbook Import UI (unreleased)

The static Website Console can now import design-ai site <bundle-dir> --bundle-handoff --json output and render the embedded operatorRunbook in the Report tab, turning the CLI handoff contract into a browser-local review surface before target-repo execution.

Added

• Added optional operatorRunbook workspace persistence with normalization for bundle-handoff JSON imports.
• Added Report-tab Operator Runbook metrics for stage count, manual steps, blocked evidence rows, next stage, and next command.
• Added status-index chips for action status and evidence-progress status.
• Added display-ready runbook row rendering with stage key, action status, evidence progress, and copy-ready line text.
• Added copy actions for the full operator runbook Markdown and the next runbook line, plus a clear action.

Impact

• Company website pilots can inspect the verified handoff bundle runbook in the same local console used for audit, MCP readiness, tasks, prompts, and final report notes.
• CLI bundle handoff JSON now has a direct browser UI consumer, reducing the gap between machine-readable contract work and solo/company operator workflows.
• The change stays browser-local, uses localStorage/export/import, adds no dependency, calls no external MCP, and does not mutate target repositories.

Verification Plan

• node --check docs/website-console/app.js
• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 618 — Website Bundle Handoff Runbook Human Line Display Row Status Indexes (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes status-key indexes for display-ready operator runbook human line rows, so wrappers can render action-status tabs and evidence-progress filters without reducing stageHumanLineDisplayRows.

Added

• Added operatorRunbook.stageHumanLineDisplayRowKeysByActionStatus with stable row-key arrays for ready, optional, manual, and blocked action states.
• Added operatorRunbook.stageHumanLineDisplayRowKeysByEvidenceProgressStatus with stable row-key arrays for blocked and ready evidence-progress states.
• Added unit and packed-tarball smoke assertions for status index ordering and empty blocked-action semantics.

Impact

• Website Console and VS Code wrappers can render runbook row filters from keyed indexes and then hydrate rows through stageHumanLineDisplayRowByKey.
• Company website pilots keep the same local/read-only handoff flow while gaining simpler UI navigation for ready, optional, manual, and evidence-blocked stages.
• The change is additive JSON metadata only; it adds no external MCP calls, no target repo mutation, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 617 — Website Bundle Handoff Runbook Human Line Display Row Summaries (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes compact summaries for display-ready operator runbook human line rows, so wrappers can render row totals, action-status chips, and evidence-progress summary badges without reducing stageHumanLineDisplayRows.

Added

• Added operatorRunbook.stageHumanLineDisplayRowSummary with row counts, required/optional counts, command/manual counts, action-status counts, evidence-progress counts, and first-row keys.
• Added action-summary display-row totals for blocked/ready evidence progress and ready/manual action rows.
• Added unit and packed-tarball smoke assertions for the display-row summary contract.

Impact

• Website Console and VS Code wrappers can render runbook summary chips from one object instead of reducing display rows.
• Company website pilots keep the same local/read-only handoff flow while gaining a simpler row-summary UI contract.
• The change is additive JSON metadata only; it adds no external MCP calls, no target repo mutation, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 616 — Website Bundle Handoff Runbook Human Line Display Rows (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes display-ready rows for copy-ready operator runbook human lines, so wrappers can render labels, action status, and evidence-progress badges without joining stageHumanLines, stageActionRows, and checklist summary maps.

Added

• Added operatorRunbook.stageHumanLineDisplayRows with stage key, label, line, required/manual flags, command count, action status metadata, and evidence-progress display metadata.
• Added operatorRunbook.stageHumanLineDisplayRowByKey so wrappers can retrieve display-ready rows by stable stage key.
• Added operatorRunbook.nextStageHumanLineDisplayRow for the first strict source-bundle gate.
• Added action-summary display-row totals for row count, keyed row count, and evidence-progress row count.
• Added unit and packed-tarball smoke assertions for the display-row contract.

Impact

• Website Console and VS Code wrappers can render runbook table rows and badges from one object per stage instead of joining parallel JSON arrays.
• Company website pilots keep the same local/read-only source-bundle handoff flow while gaining a denser UI contract for the first gate.
• The change is additive JSON metadata only; it adds no external MCP calls, no target repo mutation, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 615 — Website Bundle Handoff Runbook Human Line Summaries (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes compact summaries for copy-ready operator runbook human lines, so wrappers can render header counts, evidence-progress badges, and next-stage previews without reducing stageHumanLines.

Added

• Added operatorRunbook.stageHumanLineSummary with line counts, required/optional counts, command/manual counts, evidence-progress counts, and first-stage keys.
• Added operatorRunbook.nextStageHumanLineSummary so wrappers can render the first strict source-bundle gate line plus evidence progress status from one object.
• Added action-summary human-line totals for line count, key count, evidence-progress line count, blocked evidence-progress line count, and ready evidence-progress line count.
• Added unit and packed-tarball smoke assertions for the new summary contract.

Impact

• Website Console and VS Code wrappers can render runbook count badges and first-action previews without scanning line arrays or parsing Markdown prompt text.
• Company website pilots keep the same deterministic local handoff flow while gaining a simpler UI contract.
• The change is additive JSON metadata only; it adds no external MCP calls, no target repo mutation, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 614 — Website Bundle Handoff Runbook Human Line JSON Mirrors (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes the same copy-ready operator runbook lines that human Markdown output uses, so Website Console and VS Code wrappers can render exact stage guidance without parsing the prompt string.

Added

• Added ordered operatorRunbook.stageHumanLines entries for every bundle handoff runbook stage.
• Added operatorRunbook.stageHumanLineByKey so wrappers can retrieve each stage's copy-ready line by stable stage key.
• Added operatorRunbook.nextStageHumanLine as a direct mirror for the first strict source-bundle gate.
• Reused the same formatter for JSON mirrors and human Markdown output so evidence checklist progress copy stays aligned.

Impact

• Wrappers can show the same runbook copy as CLI Markdown while still consuming structured JSON.
• Target-repo company pilots can render source-bundle, optional snapshot, prompt-output, target-repo, and evidence-recording guidance without prompt parsing.
• The change is additive JSON metadata only; it adds no external MCP calls, no target repo mutation, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 613 — Website Bundle Handoff Runbook Human Evidence Checklist Progress (unreleased)

design-ai site <bundle-dir> --bundle-handoff now includes evidence checklist progress in the human-readable operator runbook lines, so target-repo operators can see first-render evidence completion state without opening the JSON contract.

Added

• Added per-stage evidence progress text to human runbook lines when an action has evidence capture checklist metadata.
• Included progress label, checklist status label, and the first unchecked evidence item label for blocked stages.
• Added unit and packed-tarball human smoke assertions so installed-bin handoff prompts keep exposing source-bundle, optional snapshot, and target-repo evidence progress.

Impact

• Operators can scan handoff prompts and immediately see which evidence item blocks each runbook stage.
• Website Console wrappers still use the richer JSON contract, while CLI-only company pilots get the same checklist status in copy-ready Markdown.
• The change is additive human-output metadata only; it adds no external MCP calls, no target repo mutation, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run package:smoke
• git diff --check

Phase 612 — Website Bundle Handoff Runbook Action Evidence Capture Initial Validation Checklist Summaries (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes compact progress summaries for action evidence capture initial validation checklists in the Website bundle operator runbook, so wrappers and GUI surfaces can render checklist badges, progress labels, and first-unchecked guidance without reducing checklist rows.

Added

• Added operatorRunbook.stageActionEvidenceCaptureInitialValidationChecklistSummaryByKey so wrappers can consume per-action checklist status, label, tone, icon, CTA label, helper text, item counts, checked/unchecked counts, required/optional counts, blocking counts, completion percentage, progress label, initial completion booleans, and first unchecked item metadata.
• Added row-level actionEvidenceCaptureInitialValidationChecklistSummary to every stageActionRows[] item.
• Added actionSummary totals for checklist-summary-bearing actions, blocked/ready checklist summaries, complete/incomplete initial checklist summaries, checked/unchecked items, and blocking unchecked items.
• Added matching nextActionEvidenceCaptureInitialValidationChecklistSummary and nextStageActionEvidenceCaptureInitialValidationChecklistSummary mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for checklist summary maps, optional/required checklist summary semantics, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can render checklist progress from one compact summary object instead of recomputing progress from every checklist row.
• Company website pilots get deterministic first-load checklist progress for source bundle verification, optional handoff snapshot refresh, prompt output, target-repo implementation evidence, and final evidence recording.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 611 — Website Bundle Handoff Runbook Action Evidence Capture Initial Validation Checklists (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes first-render checklist rows for action evidence capture initial validation states in the Website bundle operator runbook, so wrappers and GUI surfaces can render completion-oriented evidence checklists without reducing validation state arrays.

Added

• Added operatorRunbook.stageActionEvidenceCaptureInitialValidationChecklistByKey so wrappers can consume per-action checklist rows with field key, label, status, display metadata, required/blocking state, completion-blocking state, initial checked state, disabled state, message, and payload path.
• Added row-level actionEvidenceCaptureInitialValidationChecklist to every stageActionRows[] item.
• Added actionSummary totals for checklist-bearing actions, checklist item count, checked/unchecked initial rows, blocking/non-blocking rows, and required/optional rows.
• Added matching nextActionEvidenceCaptureInitialValidationChecklist and nextStageActionEvidenceCaptureInitialValidationChecklist mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for checklist maps, optional/required checklist semantics, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can render checkbox-style evidence completion lists from one compact checklist array while preserving full validation states, display metadata, and summaries for more detailed form surfaces.
• Company website pilots get deterministic initial checklist state for source bundle verification, optional handoff snapshot refresh, prompt output, target-repo implementation evidence, and final evidence recording.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 610 — Website Bundle Handoff Runbook Action Evidence Capture Initial Validation Summaries (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action-level initial validation summaries for evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can render blocked/ready form state without reducing per-field validation rows.

Added

• Added operatorRunbook.stageActionEvidenceCaptureInitialValidationSummaryByKey so wrappers can consume per-action status, label, tone, icon, CTA label, helper text, field counts, required/optional counts, valid/invalid counts, blocking counts, missing-required counts, optional-empty counts, pristine state, completion gate, and first blocking field metadata.
• Added row-level actionEvidenceCaptureInitialValidationSummary to every stageActionRows[] item.
• Added actionSummary totals for initial validation summary actions, blocked/ready summary actions, completable/non-completable actions, blocking fields, missing-required fields, and optional-empty fields.
• Added matching nextActionEvidenceCaptureInitialValidationSummary and nextStageActionEvidenceCaptureInitialValidationSummary mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for summary maps, optional/required summary semantics, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can gate action completion and render form-level status from one compact summary object instead of recomputing state from every evidence field.
• Company website pilots get deterministic first-render action status for source bundle verification, optional handoff snapshot refresh, prompt output, target-repo implementation evidence, and final evidence recording.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 609 — Website Bundle Handoff Runbook Action Evidence Capture Initial Validation Display Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes display metadata for action evidence capture initial validation states in the Website bundle operator runbook, so wrappers and GUI surfaces can render first-load required/optional evidence states without maintaining a separate status-to-label or status-to-tone map.

Added

• Added operatorRunbook.stageActionEvidenceCaptureInitialValidationDisplayMetadataByKey so wrappers can consume per-action display rows with field key, label, status, status label, status tone, icon name, action label, helper text, blocking state, required state, and message.
• Added row-level actionEvidenceCaptureInitialValidationDisplayMetadata to every stageActionRows[] item.
• Added display metadata fields directly to each actionEvidenceCaptureInitialValidationStates[] row so full state consumers do not need to join a parallel display array.
• Added actionSummary totals for initial validation display metadata actions, total display rows, danger/info tones, blocking rows, and non-blocking rows.
• Added matching nextActionEvidenceCaptureInitialValidationDisplayMetadata and nextStageActionEvidenceCaptureInitialValidationDisplayMetadata mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for display metadata maps, optional/required status display semantics, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can render Website bundle handoff evidence forms with stable badges, icons, helper text, and CTA labels for missing-required and optional-empty states from the CLI JSON contract alone.
• Company website pilots get consistent first-render evidence form copy for required strict bundle output, bundle digest, prompt output, selected task id, changed files, verification results, viewport/accessibility notes, final evidence, and remaining risks while optional handoff JSON remains visibly non-blocking.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 608 — Website Bundle Handoff Runbook Action Evidence Capture Initial Validation States (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes initial validation state objects for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can initialize form validity, blocking status, and empty-state messages without running a separate validator before first render.

Added

• Added operatorRunbook.stageActionEvidenceCaptureInitialValidationStatesByKey so wrappers can consume per-action initial state rows with field key, label, rule id, status, validity, blocking state, severity, required state, empty-value policy, pristine flags, min length, value shape, payload path, and message.
• Added row-level actionEvidenceCaptureInitialValidationStates to every stageActionRows[] item.
• Added actionSummary totals for initial validation-state actions, total states, valid/invalid states, blocking states, optional-empty states, missing-required states, and pristine states.
• Added matching nextActionEvidenceCaptureInitialValidationStates and nextStageActionEvidenceCaptureInitialValidationStates mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for initial validation-state maps, optional/required state semantics, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can render Website bundle handoff evidence forms with deterministic first-render validity and blocking state from the CLI JSON contract alone.
• Company website pilots get consistent required-field blocking for strict bundle output, bundle digest, prompt output, selected task id, changed files, verification results, viewport/accessibility notes, final evidence, and remaining risks while optional handoff JSON starts as non-blocking.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 607 — Website Bundle Handoff Runbook Action Evidence Capture Validation Specs (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes compact validation spec objects for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can validate required and optional evidence values without maintaining a separate rule schema.

Added

• Added operatorRunbook.stageActionEvidenceCaptureValidationSpecsByKey so wrappers can consume per-action validation rows with field key, label, rule id, severity, required state, empty-value policy, min length, value shape, multiplicity, user-facing message, and failure message.
• Added row-level actionEvidenceCaptureValidationSpecs to every stageActionRows[] item.
• Added actionSummary totals for validation-spec actions, total specs, required specs, optional specs, error/info specs, and multi-value specs.
• Added matching nextActionEvidenceCaptureValidationSpecs and nextStageActionEvidenceCaptureValidationSpecs mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for validation spec maps, optional spec severity, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can validate Website bundle handoff evidence forms from the CLI JSON contract without translating validation rule ids into separate local schema objects.
• Company website pilots get deterministic form checks for strict bundle output, bundle digest, optional handoff JSON, prompt output, selected task id, changed files, verification results, viewport/accessibility notes, final evidence, and remaining risks.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 606 — Website Bundle Handoff Runbook Action Evidence Capture Payload Bindings (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes compact payload binding objects for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can bind controls to payload paths, value shapes, validation, sections, and accessible labels without zipping parallel arrays.

Added

• Added operatorRunbook.stageActionEvidenceCapturePayloadBindingsByKey so wrappers can consume per-action binding rows that join field key, label, payload namespace/path, input type, value shape, multiplicity, required state, empty value, validation rule, section metadata, and ARIA label.
• Added row-level actionEvidenceCapturePayloadBindings to every stageActionRows[] item.
• Added actionSummary totals for payload-bound actions, total bindings, required bindings, optional bindings, and multi-value bindings.
• Added matching nextActionEvidenceCapturePayloadBindings and nextStageActionEvidenceCapturePayloadBindings mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for binding maps, row-level binding projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can render and persist Website bundle handoff evidence forms from one compact binding array instead of recombining keys, labels, payload paths, validation rules, sections, and accessibility copy from separate arrays.
• Company website pilots get a lower-risk handoff form contract for source bundle verification, prompt output, target-repo implementation evidence, viewport/accessibility QA, final evidence, and remaining risks.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 605 — Website Bundle Handoff Runbook Action Evidence Capture Payload Templates (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes nested and flat payload templates for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can initialize handoff evidence payload objects without constructing nested storage objects from field paths.

Added

• Added operatorRunbook.stageActionEvidenceCapturePayloadTemplateByKey so wrappers can initialize per-action nested evidence payloads such as sourceBundle.verification, handoffPrompt, targetRepo, and handoffEvidence.
• Added operatorRunbook.stageActionEvidenceCapturePayloadFlatTemplateByKey so wrappers can also initialize path-keyed form stores with deterministic empty values.
• Added row-level actionEvidenceCapturePayloadTemplate and actionEvidenceCapturePayloadFlatTemplate to every stageActionRows[] item.
• Added actionSummary totals for payload-template actions, total payload-template paths, and max payload-template paths per action.
• Added matching nextAction* and nextStageAction* payload-template mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for nested templates, flat templates, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can bootstrap Website bundle handoff evidence form state directly from the CLI JSON contract without maintaining local nested-object construction logic.
• Company website pilots can carry source bundle verification, refreshed handoff JSON, prompt output, target repo change/verification/QA values, final evidence, and remaining risks through a stable payload shape.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 604 — Website Bundle Handoff Runbook Action Evidence Capture Payload Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes payload metadata for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can persist evidence form values without hard-coding source-bundle, handoff prompt, target-repo, or final handoff record paths.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldPayloadNamespacesByKey so wrappers can group evidence payload writes by stable namespaces such as sourceBundle, handoffPrompt, targetRepo, and handoffEvidence.
• Added operatorRunbook.stageActionEvidenceCaptureFieldPayloadPathsByKey so evidence form values can be written to deterministic payload paths without deriving storage destinations from field keys.
• Added operatorRunbook.stageActionEvidenceCapturePayloadNamespacesByKey and stageActionEvidenceCapturePayloadNamespaceCountByKey so compact dashboards can show per-action payload destinations without reducing field arrays.
• Added row-level actionEvidenceCaptureFieldPayload* and actionEvidenceCapturePayload* arrays to every stageActionRows[] item.
• Added actionSummary totals for payload-mapped fields, unique payload namespaces, multi-namespace actions, and max payload namespaces per action.
• Added matching nextAction* and nextStageAction* mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for payload namespace maps, payload path maps, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can save Website bundle handoff evidence into a consistent machine-readable payload without local field-key-to-path maps.
• Company website pilots can carry strict bundle verification, prompt output, target repo implementation, viewport/accessibility QA, final evidence, and remaining-risk values across CLI, browser, or GUI wrappers with less glue code.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 603 — Website Bundle Handoff Runbook Action Evidence Capture Section Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes section metadata for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can group evidence inputs without hard-coding source-bundle, handoff-output, target-repo, QA, final-evidence, or risk sections.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldSectionKeysByKey so wrappers can read per-field evidence section ids from stable stage keys.
• Added operatorRunbook.stageActionEvidenceCaptureFieldSectionLabelsByKey so evidence forms can render section labels without local id-to-copy maps.
• Added operatorRunbook.stageActionEvidenceCaptureSectionKeysByKey and stageActionEvidenceCaptureSectionLabelsByKey so wrappers can render unique per-action sections without reducing field-level arrays.
• Added operatorRunbook.stageActionEvidenceCaptureSectionCountByKey plus row-level actionEvidenceCaptureSection* arrays and counts for compact dashboards.
• Added actionSummary totals for sectioned fields, unique evidence sections, multi-section actions, and max sections per action.
• Added matching nextAction* and nextStageAction* mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for field section maps, unique section maps, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can group Website bundle handoff evidence forms into source bundle verification, handoff snapshot, prompt output, target repo changes, target repo verification, viewport/accessibility QA, final evidence, and risk sections from the CLI JSON contract alone.
• Company website pilots get denser evidence capture layouts without duplicating section mapping rules outside design-ai.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 602 — Website Bundle Handoff Runbook Action Evidence Capture Display Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes display metadata for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can render accessible evidence forms without deriving placeholder text, required/optional copy, ARIA labels, or helper text from full field objects.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldPlaceholdersByKey so wrappers can render per-action evidence field placeholders from stable stage keys.
• Added operatorRunbook.stageActionEvidenceCaptureFieldRequirementLabelsByKey so evidence forms can show required/optional copy without local boolean-to-label maps.
• Added operatorRunbook.stageActionEvidenceCaptureFieldAriaLabelsByKey so browser and GUI wrappers can wire accessible input labels directly from the JSON contract.
• Added operatorRunbook.stageActionEvidenceCaptureFieldHelpTextsByKey so forms can show helper copy without reusing validation metadata implicitly.
• Added row-level display arrays to every stageActionRows[] item.
• Added actionSummary totals for placeholder, ARIA label, and helper-text evidence capture fields.
• Added matching nextAction* and nextStageAction* mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for display maps, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can build Website bundle handoff evidence forms from compact display maps without scanning full capture field objects.
• Company website pilots get consistent accessible labels and helper copy for strict bundle output, bundle digest, prompt output, target-repo files, verification notes, viewport/accessibility notes, final evidence, and risk records.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 601 — Website Bundle Handoff Runbook Action Evidence Capture Default Value Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes default/empty-value metadata for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can initialize evidence forms without local value-shape default maps.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldDefaultValuesByKey so wrappers can initialize per-action evidence form values from stable stage keys.
• Added operatorRunbook.stageActionEvidenceCaptureFieldEmptyValuesByKey so wrappers can reset evidence form values without deriving defaults from inputType or valueShape.
• Added row-level actionEvidenceCaptureFieldDefaultValues and actionEvidenceCaptureFieldEmptyValues to every stageActionRows[] item.
• Added actionSummary totals for empty-string and empty-list evidence capture fields.
• Added matching nextAction* and nextStageAction* mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for default-value maps, empty-value maps, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can create and reset Website bundle handoff evidence forms from the CLI JSON contract without duplicating string-list -> [] and text/file-path -> "" initialization rules.
• Company website pilots can preserve list-shaped target-repo changed-file evidence while keeping text, file-path, and textarea fields initialized consistently.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 600 — Website Bundle Handoff Runbook Action Evidence Capture Value Shape Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes value-shape metadata for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can render text areas, short text inputs, file-path inputs, and multi-value lists without local inputType mapping.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldValueShapesByKey so wrappers can read stable value shapes per action.
• Added operatorRunbook.stageActionEvidenceCaptureFieldAcceptsMultipleByKey so evidence forms can distinguish single-value fields from list-style multi-value capture.
• Added row-level actionEvidenceCaptureFieldValueShapes and actionEvidenceCaptureFieldAcceptsMultiple to every stageActionRows[] item.
• Added actionSummary totals for long-text, short-text, file-path value, string-list, multi-value, single-value, and first multi-value action lookup.
• Added matching nextAction* and nextStageAction* mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for value-shape maps, accepts-multiple maps, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can render Website bundle handoff evidence forms from the CLI JSON contract without duplicating textarea/text/file-path/list translation rules.
• Company website pilots can capture target-repo changed files as an explicit string-list while keeping verification, viewport/accessibility, risk, and final evidence as long-text records.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 599 — Website Bundle Handoff Runbook Action Evidence Capture Validation Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes validation metadata for action evidence capture fields in the Website bundle operator runbook, so wrappers and GUI surfaces can validate evidence forms without scanning full field objects or carrying local schema maps.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldValidationRulesByKey so wrappers can apply stable validation rule ids per action.
• Added operatorRunbook.stageActionEvidenceCaptureFieldMinLengthsByKey so evidence forms can enforce minimum text length or list item count from the JSON contract.
• Added operatorRunbook.stageActionEvidenceCaptureFieldExamplesByKey and stageActionEvidenceCaptureFieldValidationHintsByKey so forms can show compact operator guidance without hard-coded field copy.
• Added row-level actionEvidenceCaptureFieldValidationRules, actionEvidenceCaptureFieldMinLengths, actionEvidenceCaptureFieldExamples, and actionEvidenceCaptureFieldValidationHints.
• Added actionSummary validation totals for all, required, optional, total min-length, max min-length, and first validation-rule action lookup.
• Added matching nextAction* and nextStageAction* mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for validation rule maps, min-length maps, examples, hints, row-level projections, summary totals, and next-stage mirrors.

Impact

• Wrappers can render and validate bundle handoff evidence capture forms from the CLI JSON contract alone.
• Company website pilots get clearer validation for strict bundle output, digest, prompt output, target-repo files, verification results, viewport/accessibility notes, final evidence, and remaining risk records.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 598 — Website Bundle Handoff Runbook Action Evidence Capture Field Indexes (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action evidence capture field index metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render required-only, optional-only, and input-type-specific evidence forms without scanning full capture field arrays.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldLabelsByKey so wrappers can render per-action field labels from stable stage keys.
• Added operatorRunbook.stageActionEvidenceCaptureFieldInputTypesByKey so form layouts can distinguish textarea, text, file-path, and list fields without scanning full field objects.
• Added operatorRunbook.stageActionRequiredEvidenceCaptureFieldKeysByKey and stageActionOptionalEvidenceCaptureFieldKeysByKey so wrappers can split required and optional evidence inputs directly.
• Added operatorRunbook.stageActionOptionalEvidenceCaptureFieldCountByKey and row-level actionOptionalEvidenceCaptureFieldCount for compact optional-field summaries.
• Added row-level actionEvidenceCaptureFieldLabels, actionEvidenceCaptureFieldInputTypes, actionRequiredEvidenceCaptureFieldKeys, and actionOptionalEvidenceCaptureFieldKeys.
• Added actionSummary totals for required/optional capture fields plus textarea, text, file-path, and list field counts.
• Added matching nextAction* and nextStageAction* mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for capture field index maps, row-level field indexes, summary totals, and next-stage mirrors.

Impact

• Wrappers can build denser evidence capture UIs without local enum-to-form schema maps.
• Company website pilots can separate optional refreshed handoff JSON evidence from required bundle, prompt, target-repo, and final evidence fields.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 597 — Website Bundle Handoff Runbook Action Evidence Capture Fields (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action evidence capture field metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render evidence input forms for command output, prompt files, target-repo implementation proof, verification results, viewport/accessibility notes, risks, and final handoff records without hard-coded field schemas.

Added

• Added operatorRunbook.stageActionEvidenceCaptureFieldsByKey so wrappers can render per-action evidence input schemas from stable stage keys.
• Added operatorRunbook.stageActionEvidenceCaptureFieldKeysByKey, stageActionEvidenceCaptureFieldCountByKey, stageActionRequiredEvidenceCaptureFieldCountByKey, and stageActionHasEvidenceCaptureFieldsByKey for compact dashboards and conditional evidence form UI.
• Added actionEvidenceCaptureFields, actionEvidenceCaptureFieldKeys, actionEvidenceCaptureFieldCount, actionRequiredEvidenceCaptureFieldCount, and actionHasEvidenceCaptureFields to each stageActionRows[] item.
• Added nextStageActionEvidenceCaptureFields, nextStageActionEvidenceCaptureFieldKeys, nextStageActionEvidenceCaptureFieldCount, nextStageActionRequiredEvidenceCaptureFieldCount, and nextStageActionHasEvidenceCaptureFields as top-level mirrors for the first strict source-bundle gate.
• Added actionSummary.actionWithEvidenceCaptureFieldCount, totalActionEvidenceCaptureFieldCount, totalRequiredActionEvidenceCaptureFieldCount, maxActionEvidenceCaptureFieldCount, and first capture-field action keys for evidence dashboards.
• Added unit and packed-tarball smoke assertions for capture field lookup maps, row-level capture metadata, summary fields, and next-stage mirrors.

Impact

• Wrappers can render evidence capture textareas, file-path fields, text fields, and list fields directly from the JSON contract.
• Company website pilots get clearer handoff evidence collection before target-repo changes are considered ready for review.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 596 — Website Bundle Handoff Runbook Action Evidence Targets (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action evidence target metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can distinguish local command output, local output files, target-repo working-tree evidence, and final handoff evidence records without hard-coded evidence source rules.

Added

• Added operatorRunbook.stageActionEvidenceTargetByKey so wrappers can route each handoff action to the correct evidence source.
• Added operatorRunbook.stageActionEvidenceTargetLabelByKey so compact dashboards can render source labels without local string maps.
• Added actionEvidenceTarget and actionEvidenceTargetLabel to each stageActionRows[] item.
• Added nextStageActionEvidenceTarget and nextStageActionEvidenceTargetLabel as top-level mirrors for the first strict source-bundle gate.
• Added actionSummary.localCommandEvidenceActionCount, localOutputEvidenceActionCount, targetRepoEvidenceActionCount, handoffRecordEvidenceActionCount, firstTargetRepoEvidenceActionKey, and firstLocalOutputEvidenceActionKey for evidence capture dashboards.
• Added unit and packed-tarball smoke assertions for evidence target lookup maps, row-level evidence target metadata, summary fields, and next-stage mirrors.

Impact

• Wrappers can render different evidence capture affordances for command output, local prompt files, target-repo implementation proof, and final handoff evidence records.
• Company website pilots get clearer separation between design-ai repo evidence and target website repo evidence before implementation starts.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 595 — Website Bundle Handoff Runbook Action Evidence Requirements (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action evidence requirement metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render exactly what evidence should be captured after bundle validation, prompt output, target-repo implementation, and evidence recording without hard-coded company handoff rules.

Added

• Added operatorRunbook.stageActionEvidenceRequirementsByKey so wrappers can render per-action evidence capture requirements from stable stage keys.
• Added operatorRunbook.stageActionEvidenceRequirementCountByKey and stageActionRequiresEvidenceByKey so compact dashboards can show evidence counts and conditional evidence UI without counting arrays.
• Added actionEvidenceRequirements, actionEvidenceRequirementCount, and actionRequiresEvidence to each stageActionRows[] item.
• Added nextStageActionEvidenceRequirements, nextStageActionEvidenceRequirementCount, and nextStageActionRequiresEvidence as top-level mirrors for the first strict source-bundle gate.
• Added actionSummary.actionRequiringEvidenceCount, totalActionEvidenceRequirementCount, maxActionEvidenceRequirementCount, firstActionRequiringEvidenceKey, firstManualActionRequiringEvidenceKey, and firstEvidenceRecordingActionKey for evidence dashboards and manual-step summaries.
• Added unit and packed-tarball smoke assertions for evidence requirement lookup maps, row-level evidence metadata, summary fields, and next-stage mirrors.

Impact

• Wrappers can show what evidence must be captured for each handoff action before a company website pilot moves into target-repo work.
• Target-repo implementation steps now carry explicit changed-file, verification-result, viewport, and accessibility evidence expectations.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 594 — Website Bundle Handoff Runbook Action Completion Criteria (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action completion criteria metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render deterministic done-checklists for bundle verification, prompt output, target-repo implementation, and evidence capture without hard-coded handoff rules.

Added

• Added operatorRunbook.stageActionCompletionCriteriaByKey so wrappers can render per-action completion criteria from stable stage keys.
• Added operatorRunbook.stageActionCompletionCriteriaCountByKey and stageActionHasCompletionCriteriaByKey so compact dashboards can show done-criteria counts and conditional UI without counting arrays.
• Added actionCompletionCriteria, actionCompletionCriteriaCount, and actionHasCompletionCriteria to each stageActionRows[] item.
• Added nextStageActionCompletionCriteria, nextStageActionCompletionCriteriaCount, and nextStageActionHasCompletionCriteria as top-level mirrors for the first strict source-bundle gate.
• Added actionSummary.actionWithCompletionCriteriaCount, totalActionCompletionCriteriaCount, maxActionCompletionCriteriaCount, firstActionWithCompletionCriteriaKey, and firstManualActionWithCompletionCriteriaKey for completion dashboards and manual-step summaries.
• Added unit and packed-tarball smoke assertions for completion criteria lookup maps, row-level completion metadata, summary fields, and next-stage mirrors.

Impact

• Wrappers can show exactly what marks each handoff action done before the operator moves into company target-repo work.
• Company website pilots get clearer stop/go criteria for strict bundle validation, local prompt output, target-repo implementation, and evidence return.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 593 — Website Bundle Handoff Runbook Action Dependency Reasons (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action dependency reason and blocked-action count metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can explain why a handoff action depends on earlier steps and which downstream actions a completed stage unlocks without scanning row arrays.

Added

• Added operatorRunbook.stageActionDependencyReasonCodeByKey so wrappers can distinguish prerequisite-driven dependency messages from disabled-command reasons.
• Added operatorRunbook.stageActionDependencyReasonByKey so wrappers can render stable dependency copy for local prompt output, target-repo implementation, and evidence-return actions.
• Added operatorRunbook.stageActionBlockedStageCountByKey and stageActionBlocksStagesByKey so wrappers can show unlock counts and conditional downstream dependency UI without counting blocked-stage arrays.
• Added actionDependencyReasonCode, actionDependencyReason, actionBlockedStageKeys, actionBlockedStageLabels, actionBlockedStageCount, and actionBlocksStages to each stageActionRows[] item.
• Added nextStageActionDependencyReasonCode, nextStageActionDependencyReason, nextStageActionBlockedStageKeys, nextStageActionBlockedStageLabels, nextStageActionBlockedStageCount, and nextStageActionBlocksStages as top-level mirrors for the first strict source-bundle gate.
• Added actionSummary.actionWithDependencyReasonCount, actionBlockingOtherActionCount, maxActionBlockedStageCount, firstActionWithDependencyReasonKey, and firstActionBlockingOtherActionKey for compact dependency dashboards.
• Added unit and packed-tarball smoke assertions for dependency reason lookup maps, blocked-stage counts, row-level dependency metadata, summary fields, and next-stage mirrors.

Impact

• Wrappers can render "do this first" copy and downstream unlock counts directly from the JSON contract.
• Company website pilots get clearer operator guidance before moving from bundle validation to prompt output, target-repo work, and evidence capture.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 592 — Website Bundle Handoff Runbook Action Prerequisite Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action prerequisite metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render the strict bundle gate, selected prompt output, target-repo implementation, and evidence-return sequence without hard-coded stage dependency rules.

Added

• Added operatorRunbook.stageActionPrerequisiteKeysByKey so wrappers can read the required upstream action keys for each handoff stage.
• Added operatorRunbook.stageActionPrerequisiteLabelsByKey so dependency chips can render human-readable prerequisite labels without dereferencing stage objects.
• Added operatorRunbook.stageActionPrerequisiteCountByKey and stageActionHasPrerequisitesByKey for compact dependency counts and conditional UI rendering.
• Added operatorRunbook.stageActionBlockedStageKeysByKey and stageActionBlockedStageLabelsByKey so wrappers can show which downstream actions are blocked by a stage.
• Added actionPrerequisiteKeys, actionPrerequisiteLabels, actionPrerequisiteCount, and actionHasPrerequisites to each stageActionRows[] item.
• Added nextStageActionPrerequisiteKeys, nextStageActionPrerequisiteLabels, nextStageActionPrerequisiteCount, and nextStageActionHasPrerequisites as top-level mirrors for the first strict source-bundle gate.
• Added actionSummary.actionWithPrerequisiteCount, maxActionPrerequisiteCount, and first prerequisite-bearing action keys for local output, manual target-repo, and evidence stages.
• Added unit and packed-tarball smoke assertions for prerequisite lookup maps, row metadata, blocked-stage inverse lookups, and next-stage mirrors.

Impact

• Wrappers can render ordered handoff checklists and dependency chips from the JSON contract instead of hard-coding verify -> write prompt -> target repo -> evidence.
• Company website pilots get clearer operator sequencing before moving from local bundle validation into target-repo implementation.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 591 — Website Bundle Handoff Runbook Action Readiness Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action readiness metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render enabled command buttons, optional action status, manual-step badges, disabled reasons, and status tones without recomputing command availability from lower-level stage fields.

Added

• Added operatorRunbook.stageActionEnabledByKey so wrappers can distinguish local command actions from target-repo/manual evidence steps without scanning command arrays.
• Added operatorRunbook.stageActionStatusByKey, stageActionStatusLabelsByKey, and stageActionStatusToneByKey with ready, optional, and manual action states for compact button/badge rendering.
• Added operatorRunbook.stageActionDisabledReasonCodeByKey and stageActionDisabledReasonByKey so manual target-repo and evidence stages carry explicit no-local-command guidance.
• Added actionEnabled, actionStatus, actionStatusLabel, actionStatusTone, actionDisabledReasonCode, and actionDisabledReason to each stageActionRows[] item.
• Added nextStageActionEnabled, nextStageActionStatus, nextStageActionStatusLabel, nextStageActionStatusTone, nextStageActionDisabledReasonCode, and nextStageActionDisabledReason as top-level mirrors for the first strict source-bundle gate.
• Added actionSummary.enabledActionCount, disabledActionCount, manualDisabledActionCount, and next-action readiness/status mirrors.
• Added unit and packed-tarball smoke assertions for action readiness lookup maps, row metadata, disabled reasons, and next-stage mirrors.

Impact

• Wrappers can render action buttons and manual checklist steps with consistent enabled state, badge labels, tones, and disabled copy from the JSON contract.
• Company website pilots get clearer separation between local design-ai commands and target-repo/manual evidence work before handoff.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 590 — Website Bundle Handoff Runbook Action Affordance Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes action guidance and UI affordance metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render command buttons, optional refresh controls, local-output actions, manual target-repo steps, and evidence-return steps without hard-coded copy.

Added

• Added operatorRunbook.stageActionInstructionsByKey for stable stage-key to operator guidance copy lookup.
• Added operatorRunbook.stageActionButtonLabelsByKey so wrappers can render button labels for run, refresh, local output, target repo, and evidence actions without local string maps.
• Added operatorRunbook.stageActionAffordanceByKey with primary-command-button, secondary-command-button, local-output-button, manual-target-repo-step, and manual-evidence-step values.
• Added actionInstruction, actionButtonLabel, and actionAffordance to each stageActionRows[] item.
• Added nextStageActionInstruction, nextStageActionButtonLabel, and nextStageActionAffordance as top-level mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for action guidance, button label, affordance, and next-stage mirror metadata.

Impact

• Wrappers can render Website bundle handoff controls with consistent operator copy and affordance types from the JSON contract.
• Company website pilots get clearer UI guidance for local validation, prompt output generation, target-repo work, and evidence return.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 589 — Website Bundle Handoff Runbook Action Summary (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes compact action metadata for the Website bundle operator runbook, so wrappers and GUI surfaces can render the local run gate, optional refresh, local prompt output, manual target-repo implementation, and evidence return actions without scanning ordered stage arrays.

Added

• Added operatorRunbook.stageActionRows, a compact per-stage action list with action type, action label, required state, run policy, safety level, command keys, output files, and mutation boundary flags.
• Added operatorRunbook.stageActionTypeByKey and stageActionLabelByKey for stable stage-key lookups covering run-local-gate, refresh-local-preview, write-local-output, manual-target-repo, and manual-evidence.
• Added operatorRunbook.actionSummary with action counts, next action metadata, first local-output/manual/evidence stage keys, and target-repo/evidence-return requirements.
• Added nextStageActionType and nextStageActionLabel as top-level mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for action row ordering, action summary counts, and next-stage action metadata.

Impact

• Wrappers can render run buttons, refresh previews, output-file actions, manual target-repo steps, and evidence return affordances from one compact contract.
• Company website pilots get clearer handoff UI state before moving from local bundle validation into the target repo.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 588 — Website Bundle Handoff Runbook Stage Command Lookups (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes stage command lookup maps, so wrappers and GUI surfaces can render copy-ready commands, execution argv, run policies, and command safety levels for each runbook stage without scanning ordered stage arrays.

Added

• Added operatorRunbook.stageCommandKeysByKey for stable stage-key to command-key list lookup.
• Added operatorRunbook.stageCommandLabelsByKey and stageCommandStringsByKey so wrappers can render stage command labels and copy-ready command text without opening stage objects.
• Added operatorRunbook.stageCommandArgsByKey so automation can retrieve stage-level argv arrays without parsing command strings.
• Added operatorRunbook.stageCommandRunPoliciesByKey and stageCommandSafetyLevelsByKey for command-level gate chips within each stage.
• Added nextStageCommandLabels, nextStageCommands, nextStageCommandArgsList, nextStageCommandRunPolicies, and nextStageCommandSafetyLevels as top-level mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for stage command lookup parity against the command manifest.

Impact

• Wrappers can render stage command rows, copy buttons, and execution previews directly from lookup maps.
• Company website pilots get a clearer operator UI contract for the strict bundle-check gate and selected task handoff prompt generation.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 587 — Website Bundle Handoff Runbook Stage Capability Flags (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes stage capability flags as stable lookup maps, so wrappers and GUI surfaces can distinguish command-bearing stages, manual target-repo stages, local output writes, external calls, and target-repo mutation boundaries without scanning ordered stage arrays.

Added

• Added operatorRunbook.stageHasCommandsByKey for stable stage-key to command-bearing boolean lookup.
• Added operatorRunbook.stageManualByKey so wrappers can mark target-repo/manual stages without reducing stages[].
• Added operatorRunbook.stageWritesLocalFileByKey, stageExternalCallsByKey, and stageTargetRepoMutationByKey so wrappers can gate local output, external-call, and target-repo mutation affordances from compact maps.
• Added nextStageHasCommands, nextStageManual, nextStageWritesLocalFile, nextStageExternalCalls, and nextStageTargetRepoMutation as top-level mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for stage capability lookup parity and next-stage capability metadata.

Impact

• Wrappers can render action buttons, manual badges, local-output warnings, and mutation boundary chips without scanning operatorRunbook.stages.
• Company website pilots get clearer stage capability metadata before moving a Website bundle task into the target repo.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 586 — Website Bundle Handoff Runbook Stage Gating Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes stage gating fields as stable lookup maps, so wrappers and GUI surfaces can render stage status, run policy, safety, command counts, and output targets without scanning ordered stage arrays.

Added

• Added operatorRunbook.stageKindByKey for stable stage-key to stage-kind lookup.
• Added operatorRunbook.stageRequiredByKey so wrappers can mark required and optional stages without reducing stages[].
• Added operatorRunbook.stageRunPolicyByKey and stageSafetyLevelByKey so local operators can gate read-only, local-output, and manual target-repo stages from compact maps.
• Added operatorRunbook.stageCommandCountByKey and stageOutputFilesByKey for stage badge counts and local output-file previews.
• Added nextStageKind, nextStageRequired, nextStageRunPolicy, nextStageSafetyLevel, nextStageCommandCount, and nextStageOutputFiles as top-level mirrors for the first strict source-bundle gate.
• Added unit and packed-tarball smoke assertions for stage gating lookup parity and next-stage mirror metadata.

Impact

• Wrappers can render stage chips, disabled/enabled state, safety badges, and output-file preview affordances without scanning operatorRunbook.stages.
• Company website pilots get clearer local gate metadata before handing a selected Website bundle task into the target repo.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 585 — Website Bundle Handoff Runbook Display Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes stage display copy as stable lookup fields, so wrappers and GUI surfaces can render runbook labels and summaries without scanning or dereferencing full stage objects.

Added

• Added operatorRunbook.stageLabelByKey for stable stage-key to display-label lookup.
• Added operatorRunbook.stageSummaryByKey for stable stage-key to operator guidance summary lookup.
• Added operatorRunbook.nextStageLabel and nextStageSummary so the first strict source-bundle gate can be rendered directly from top-level next-stage metadata.
• Kept operatorRunbook.stages, stageByKey, nextStage, and existing command metadata intact for backward compatibility.
• Added unit and packed-tarball smoke assertions for display-label parity, summary parity, and next-stage display metadata.

Impact

• Wrappers can render stage tabs, checklist labels, and next-step descriptions without scanning stages[] or opening stageByKey.
• Company website pilots get a simpler handoff UI contract for showing the next local read-only gate before target-repo work starts.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• git diff --check

Phase 584 — Website Bundle Handoff Runbook Lookup Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now makes the Website bundle operator runbook easier for wrappers and GUI surfaces to consume without scanning ordered arrays.

Added

• Added operatorRunbook.stageKeys to preserve the validated stage order as a compact top-level list.
• Added operatorRunbook.stageByKey so each runbook stage is addressable by stable key.
• Added operatorRunbook.commandStageKeys and operatorRunbook.manualStageKeys so wrappers can separate executable local commands from manual target-repo stages.
• Added operatorRunbook.nextStage, nextStageCommandKeys, nextCommand, nextCommandArgs, nextCommandRunPolicy, nextCommandSafetyLevel, nextCommandSafety, and nextCommandEntry for the first strict source-bundle gate.
• Kept operatorRunbook.stages, nextStageKey, and nextCommandKey intact for backward compatibility.
• Added unit and packed-tarball smoke assertions for lookup parity, next-command metadata, active task prompt stage lookup, and mirrored bundle JSON.

Impact

• Wrappers can render or execute the first local read-only gate from one self-contained command object.
• Company website pilots can distinguish stage-order display, command-bearing stages, and manual target-repo stages without rebuilding maps client-side.
• The change is additive and remains local/read-only with respect to target repos; it adds no external MCP calls, no target repo mutation by design-ai, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 583 — Website Bundle Handoff Operator Runbook (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now includes an operator runbook derived from the unified command manifest, so wrappers and company website pilots can follow one staged handoff sequence.

Added

• Added top-level operatorRunbook and mirrored bundle.operatorRunbook to bundle handoff JSON.
• Added five stages: strict source-bundle verification, optional strict handoff JSON refresh, effective task prompt local output, manual target-repo execution, and manual evidence recording.
• Added stage counts for command/manual stages, required/optional stages, read-only/local-output stages, and mutation boundary checks.
• Linked the runbook to commandManifest.effectiveStrictTaskCommandKey, so default and explicit --task handoffs generate the correct active task prompt stage.
• Added human target-repo prompt guidance under ## Operator Runbook.
• Added unit and packed-tarball smoke assertions for runbook shape, active command keys, local output files, and manual target-repo stage boundaries.

Impact

• Wrappers, GUI surfaces, and operators can render a ready-to-follow sequence without deriving execution order from raw command lists.
• Company website pilots get a clearer boundary between local design-ai validation/output commands and the manual implementation that happens in the target website repo.
• The change is additive and keeps design-ai commands local: no external MCP calls, no target repo mutation by design-ai, no crawler/Lighthouse/axe execution, and no dependency changes.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 582 — Website Bundle Handoff Command Manifest (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now includes a unified command manifest for source-bundle revalidation and selectable task handoff commands.

Added

• Added top-level commandManifest and mirrored bundle.commandManifest to bundle handoff JSON.
• Added source command entries for default/strict bundle-check and default/strict bundle-handoff JSON generation.
• Added task command entries for default/strict handoff prompt generation for every task in bundle.taskCatalog.items[].
• Added manifest-level command counts, source/task command counts, read-only/local-output counts, mutation boundary counts, default/selected/effective task ids, and active strict task command keys.
• Preserved existing sourceBundle, taskCatalog, defaultTask, selectedTask, and effectiveTask command fields for backward compatibility.
• Added unit and packed-tarball smoke assertions for command manifest shape and safety metadata.

Impact

• Wrappers, GUI surfaces, and automation layers can render or execute handoff commands from one ordered manifest instead of scanning several JSON branches.
• Company website pilots can distinguish source-bundle read-only commands from task-level local output-file commands before any target-repo work.
• The change is additive and local/read-only with respect to target repos; it does not call external MCPs, mutate target repos, crawl pages, run Lighthouse/axe, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 581 — Website Bundle Source Command Safety Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now includes source-bundle command safety metadata alongside source command strings and argv arrays.

Added

• Added checkCommandRunPolicy, strictCheckCommandRunPolicy, handoffCommandRunPolicy, and strictHandoffCommandRunPolicy to sourceBundle and its mirrored bundle.sourceBundle.
• Added checkCommandSafety, strictCheckCommandSafety, handoffCommandSafety, and strictHandoffCommandSafety objects with read-only mutation boundaries, external-call flags, target-repo mutation flags, and strict-mode markers.
• Kept the existing source command strings and command argument arrays for backward compatibility.
• Added unit and packed-tarball smoke assertions for source-bundle read-only safety metadata.

Impact

• Wrappers, GUI surfaces, and automation layers can gate source bundle revalidation and handoff prompt generation without inferring safety from command text.
• Company website pilots can distinguish read-only bundle-check / bundle-handoff JSON generation from local output-file task handoff commands before target-repo work.
• The change is additive and local/read-only; it does not call external MCPs, mutate target repos, crawl pages, run Lighthouse/axe, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 580 — Website Bundle Task Command Safety Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now includes task-level handoff command safety metadata alongside task command strings and argv arrays.

Added

• Added handoffCommandRunPolicy and strictHandoffCommandRunPolicy to bundle.taskCatalog.items[], bundle.defaultTask, bundle.selectedTask, and bundle.effectiveTask.
• Added handoffCommandSafety and strictHandoffCommandSafety objects with local output-file mutation boundaries, external-call flags, target-repo mutation flags, output file names, and strict-mode markers.
• Kept the existing task command strings and command argument arrays for backward compatibility.
• Added unit and packed-tarball smoke assertions for task-level safety metadata.

Impact

• Wrappers, GUI surfaces, and automation layers can gate task handoff execution without inferring safety from command text.
• Company website pilots can distinguish local prompt-file generation from target-repo implementation work before running selected task handoffs.
• The change is local/read-only with respect to target repos; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 579 — Website Bundle Task Command Args (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now includes structured task-level command argument arrays alongside the copy-ready task handoff command strings.

Added

• Added handoffCommandArgs and strictHandoffCommandArgs to bundle.taskCatalog.items[].
• Added the same structured command argument arrays to bundle.defaultTask, bundle.selectedTask, and bundle.effectiveTask.
• Kept the existing task handoffCommand and strictHandoffCommand strings for human copy/paste and backward compatibility.
• Added unit and packed-tarball smoke assertions for task-level command argument contracts.

Impact

• Wrappers, GUI surfaces, and automation layers can execute selected Website bundle task handoffs without parsing shell-quoted command strings.
• Company website pilots can move from verified bundle review to one focused target-repo task with a stable argv payload.
• The change is local/read-only; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 578 — Website Bundle Source Command Args (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now includes structured source-bundle command argument arrays alongside the copy-ready command strings.

Added

• Added sourceBundle.checkCommandArgs, sourceBundle.strictCheckCommandArgs, sourceBundle.handoffCommandArgs, and sourceBundle.strictHandoffCommandArgs.
• Mirrored the same structured command argument arrays under bundle.sourceBundle.
• Kept the existing sourceBundle.*Command strings for human copy/paste and backward compatibility.
• Added unit and packed-tarball smoke assertions for the command argument contract.

Impact

• Wrappers, GUI surfaces, and automation layers can execute source-bundle revalidation without parsing shell-quoted strings.
• Operators still get the same human-readable command strings in JSON and prompts.
• The change is local/read-only; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 577 — Website Bundle Source Verification Commands (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now includes copy-ready source-bundle verification commands.

Added

• Added sourceBundle.checkCommand, sourceBundle.strictCheckCommand, sourceBundle.handoffCommand, and sourceBundle.strictHandoffCommand.
• Mirrored the same command metadata under bundle.sourceBundle.
• Added the strict bundle-check command to the human target-repo handoff prompt.
• Added unit and packed-tarball smoke assertions for source-bundle command metadata and prompt wording.

Impact

• Wrappers can render reverify/rehandoff actions directly from the handoff payload without rebuilding shell commands from the bundle directory.
• Operators can copy the strict source-bundle check from the target-repo prompt before implementation.
• The change is local/read-only; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 576 — Website Bundle Handoff Source Provenance (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes the verified source bundle summary as first-class provenance metadata.

Added

• Added top-level sourceBundle and mirrored bundle.sourceBundle metadata for bundle handoff reports.
• Added source bundle provenance to the human target-repo handoff prompt.
• Added unit and packed-tarball smoke assertions for source workspace, status, checksum counts, generated contract counts, and prompt provenance wording.

Impact

• Wrappers and operators can confirm which verified bundle directory and digest/status produced the target-repo handoff without recomputing fields from separate report sections.
• The change is local/read-only; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 575 — Website Bundle Effective Task Human Smoke Coverage (unreleased)

Packed-tarball smoke now verifies human --bundle-handoff output keeps effective-task command metadata in both default and selected task flows.

Added

• Added installed-bin human smoke coverage for default and explicit --task Website Console bundle handoff prompts.
• Added one-shot npm exec --package <tarball> human smoke coverage for the same effective-task prompt contract.
• Added focused unit assertions for human stdout and output-file handoff prompts.

Impact

• Package smoke now catches regressions where JSON keeps bundle.effectiveTask but human target-repo prompts lose the copy-ready strict command.
• The change only strengthens local verification; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 574 — Website Bundle Effective Task Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes the actual task used by the handoff prompt as bundle.effectiveTask.

Added

• Added JSON bundle.effectiveTask for both bundled-default and explicit --task handoff flows.
• Added an “Effective task strict command” line to the target-repo handoff prompt.
• Added unit and packed-tarball smoke assertions for effective-task command metadata.

Impact

• Operators and wrappers can read one field for the task that the handoff prompt will execute, instead of branching between defaultTask and selectedTask.
• The output remains deterministic and local; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 573 — Website Bundle Default Task Command Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --json now exposes the bundled default refactor task as a first-class JSON object.

Added

• Added JSON bundle.defaultTask with handoffOutFile, handoffCommand, and strictHandoffCommand.
• Added a “Default task strict command” line to the target-repo handoff prompt.
• Added unit and packed-tarball smoke assertions for default-task command metadata.

Impact

• Operators and wrappers can read the default implementation task directly without assuming taskCatalog.items[0] is the active default.
• The output remains deterministic and local; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 572 — Website Bundle Selected Task Command Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff --task <id-or-number> --json now makes the selected refactor task self-contained for wrappers and company website pilots.

Added

• Added handoffOutFile, handoffCommand, and strictHandoffCommand to JSON bundle.selectedTask when an explicit bundle handoff task is selected.
• Added a “Selected task strict command” line to the target-repo handoff prompt for explicit task handoffs.
• Added unit and packed-tarball smoke assertions for selected-task command metadata.

Impact

• Operators and wrappers no longer need to cross-reference bundle.taskCatalog.items[] after selecting a specific task; the selected task carries its own copy-ready handoff command.
• The change remains deterministic and local; it does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 571 — Website Bundle Handoff Task Commands (unreleased)

design-ai site <bundle-dir> --bundle-handoff now turns the bundle task catalog into copy-ready follow-up commands for each selectable refactor task.

Added

• Added handoffOutFile, handoffCommand, and strictHandoffCommand to each JSON bundle.taskCatalog.items[] entry.
• Added each task's strict handoff command to the “Available Bundle Tasks” section in the target-repo prompt.
• Added unit and packed-tarball smoke assertions for the per-task handoff command contract.

Impact

• Company website pilots can inspect one verified bundle handoff output and immediately copy the strict command for task 1, task 2, or a named task.
• The command metadata is deterministic and local; it does not call external MCPs, mutate target repos, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 570 — Website Bundle Handoff Task Catalog (unreleased)

design-ai site <bundle-dir> --bundle-handoff now includes a task catalog before target-repo implementation, so company website pilots can choose the right refactor task without opening website-workspace.tasks.json manually.

Added

• Added JSON bundle.taskCatalog metadata with task numbers, ids, priority, impact, effort, pages, recommended MCPs, default task id, selected task id, and selection mode.
• Added an “Available Bundle Tasks” section to the target-repo handoff prompt.
• Preserved default handoff behavior while making the implicit bundled default task visible.
• Added unit and packed-tarball smoke assertion coverage for the task catalog contract.

Impact

• Operators can generate one verified bundle, inspect the task catalog in the handoff output, then re-run --bundle-handoff --task <number-or-id> for the chosen implementation task.
• The catalog is local/read-only and does not call external MCPs, mutate target repos, crawl pages, or add dependencies.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• git diff --check

Phase 569 — Website Bundle Handoff Task Selection (unreleased)

design-ai site <bundle-dir> --bundle-handoff --task <id-or-number> now lets company website pilots choose a specific refactor task from a verified handoff bundle before pasting the target-repo Codex prompt.

Added

• Allowed --task with --bundle-handoff while preserving the existing --prompt codex-implementation --task behavior.
• Regenerated the handoff implementation prompt from bundled website-workspace.tasks.json when a task selector is provided.
• Added bundle.selectedTask JSON metadata so wrappers can display which task was selected for target-repo execution.
• Added command help, Website Improvement docs, company dogfood docs, and packed-tarball installed-bin/one-shot smoke coverage for selected-task bundle handoff.

Impact

• Internal company website pilots can keep one verified bundle, then hand off task 1, task 2, or a named task without editing generated Markdown manually.
• The flow remains deterministic and local: it does not call external MCPs, mutate the target website repo, run Lighthouse/axe, crawl pages, or add dependencies.

Verification Plan

• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm run release:metadata
• npm run package:smoke
• npm run audit:strict
• git diff --check

Phase 568 — Website From-Intake Task Bundle Command (unreleased)

design-ai site --from-intake file.md|--stdin --bundle --tasks --out <dir> now gives company website pilots a task-explicit one-command path from filled intake Markdown to a local handoff bundle.

Added

• Allowed --from-intake ... --bundle --tasks while keeping ordinary workspace --bundle --tasks rejected.
• Updated command help, Website Improvement docs, company dogfood docs, and release-facing policy docs to show the task-explicit handoff bundle command.
• Added installed-bin and one-shot npm exec --package <tarball> smoke coverage for file and stdin from-intake task handoff bundles.
• Added release metadata guard wording so release-facing docs preserve the from-intake task handoff bundle package smoke contract.

Impact

• Company website pilots can use one copy/paste command that communicates the intended output: a handoff bundle with generated refactor tasks from grounded intake findings.
• The command still does not call external MCPs or mutate the target website repo; it only writes local handoff artifacts.

Verification Plan

• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm run release:metadata
• git diff --check

Phase 567 — Website From-Intake Task Generation (unreleased)

design-ai site --from-intake file.md|--stdin --tasks now converts filled company website intake Markdown with grounded initial audit findings into a task-ready website-workspace.tasks.json workspace without requiring an intermediate workspace command.

Added

• Added --from-intake ... --tasks as a deterministic local task generation mode for filled English/Korean intake Markdown.
• Added command-specific help examples for file and stdin task output.
• Added installed-bin and one-shot npm exec --package <tarball> smoke coverage for from-intake task JSON stdout and stdin task JSON --out file persistence.
• Added release metadata guard wording so release-facing docs preserve the from-intake task generation package smoke contract.

Impact

• Company website pilots can move from a completed intake document to starter refactor tasks in one command before target-repo implementation.
• The flow still does not call external MCPs or mutate the target website repo; it only reads local intake Markdown and writes local operator artifacts.

Verification Plan

• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm run release:metadata
• npm run package:smoke
• npm run audit:strict
• git diff --check

Phase 566 — Website From-Intake Stdin Help Discovery Guard (unreleased)

design-ai site --help now lists the piped from-intake commands for saving workspace JSON, creating the next-actions runbook, and writing a handoff bundle, so company website pilots can discover the stdin intake workflow without reading long-form docs first.

Added

• Added command-specific help examples for cat company-website-intake.ko.md | design-ai site --from-intake --stdin --out website-workspace.json --force.
• Added command-specific help examples for cat company-website-intake.ko.md | design-ai site --from-intake --stdin --next-actions --out website-next-actions.md --force.
• Added command-specific help examples for cat company-website-intake.ko.md | design-ai site --from-intake --stdin --bundle --tasks --out website-handoff-bundle.
• Added unit, shared smoke assertion, and release metadata guard coverage so release-facing docs keep the from-intake stdin help examples.

Impact

• Operators can move from a filled Korean company intake Markdown file to workspace, runbook, or bundle commands from CLI help alone.
• The change is documentation and smoke-guard only; it does not call external MCPs, mutate target repos, or change site command behavior.

Verification Plan

• node --test cli/lib/help-command.test.mjs cli/lib/site.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

Phase 565 — Website From-Intake Stdin Next-Actions Smoke Coverage (unreleased)

design-ai site --from-intake --stdin --next-actions now has packed-tarball smoke coverage for JSON stdout, JSON --out, and human Markdown --out, so piped intake workflows can produce a verified operator checklist before target-repo implementation.

Added

• Added installed-bin and one-shot npm exec --package <tarball> smoke coverage for --from-intake --stdin --next-actions --json.
• Added installed-bin and one-shot smoke coverage for --from-intake --stdin --next-actions --json --out <file>.
• Added installed-bin and one-shot smoke coverage for --from-intake --stdin --next-actions --out <file> human Markdown output.
• Added release metadata guard wording so release-facing docs preserve stdin next-actions JSON stdout, JSON output-file persistence, and human output-file persistence coverage.

Impact

• Company website pilots can pipe a filled intake document and get a durable website-next-actions.md runbook without first writing an intake file.
• The flow remains deterministic and local; it does not call external MCPs or mutate the target website repo.

Verification Plan

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run package:smoke
• npm run audit:strict
• git diff --check

Phase 564 — Website From-Intake Stdin Artifact Smoke Coverage (unreleased)

design-ai site --from-intake --stdin now has packed-tarball smoke coverage for saved workspace JSON and handoff bundle outputs, closing the remaining stdin artifact path before company website dogfood.

Added

• Added installed-bin and one-shot npm exec --package <tarball> smoke coverage for --from-intake --stdin --out <file>.
• Added installed-bin and one-shot smoke coverage for --from-intake --stdin --bundle --out <dir>.
• Added release metadata guard wording so release-facing docs preserve stdin workspace JSON stdout, stdin output-file persistence, and stdin handoff bundle coverage.

Impact

• Company website pilots can pipe intake Markdown from secure notes or generated streams and still produce durable website-workspace.json and handoff bundles from the packaged CLI.
• The target website repo remains untouched; this phase only verifies local artifact generation and release documentation.

Verification Plan

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 563 — Website From-Intake Stdin Import (unreleased)

design-ai site --from-intake --stdin now accepts filled company website intake Markdown from stdin, so operators can pipe a reviewed intake document directly into workspace JSON or next-actions generation before company dogfood.

Added

• Added --from-intake --stdin as a deterministic local intake import source alongside --from-intake file.md.
• Added stdin-aware provenance and next-actions commands so generated workspace notes and runbooks preserve the input path boundary.
• Added unit coverage plus installed-bin and one-shot npm exec --package <tarball> package smoke coverage for stdin workspace JSON stdout.

Impact

• Company website pilots can avoid temporary intake copies when working from secure notes or generated Markdown streams.
• Existing workspace JSON design-ai site --stdin behavior remains unchanged; stdin is treated as intake Markdown only when combined with --from-intake.

Verification Plan

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run package:smoke
• npm run release:metadata
• git diff --check

Phase 562 — Website From-Intake Package Smoke Coverage (unreleased)

design-ai site --from-intake now has packed-tarball smoke coverage and release metadata guard coverage, closing the gap between the filled intake import feature and the package paths used before company dogfood.

Added

• Added installed-bin and one-shot npm exec --package <tarball> smoke coverage for filled Markdown intake import to workspace JSON stdout.
• Added --from-intake --out <file> smoke coverage so workspace JSON output-file persistence is verified from the packed tarball.
• Added --from-intake --bundle --out <dir> smoke coverage and release metadata phrase guards for from-intake handoff bundle generation.

Impact

• Company website pilots can rely on the packaged CLI to turn filled intake documents into workspace JSON or handoff bundles before target-repo implementation.
• Release-facing docs now fail metadata checks if they drop the from-intake package smoke contract.

Verification Plan

• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

Phase 561 — Website Intake Markdown Import (unreleased)

design-ai site --from-intake file.md now turns a filled company website intake Markdown file into a Website Improvement workspace, next-actions runbook, or handoff bundle without retyping the same project fields into --init.

Added

• Added --from-intake file.md as a workspace-free Website Improvement mode that accepts English or Korean intake Markdown.
• Parsed Site Profile fields, priority pages, primary user flows, brand/content notes, MCP readiness statuses, and initial audit findings into the existing workspace schema.
• Added --from-intake ... --next-actions so operators get a save-first runbook, and --from-intake ... --bundle --out <dir> so filled intake files can create handoff bundles directly.

Impact

• Company website pilots can move from a completed intake document to website-workspace.json and website-handoff-bundle without duplicating data entry.
• The feature stays deterministic/local: it reads Markdown from disk, does not call external MCPs, and does not mutate the target website repo.

Verification Plan

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm test
• npm run audit:strict
• git diff --check

Phase 560 — Korean Website Intake Template CLI Output (unreleased)

design-ai site --intake-template now supports --language ko so Korean company pilots can generate the same intake artifact from the CLI without copying the docs template manually.

Added

• Added --language en|ko to the workspace-free Website Improvement intake template mode.
• Added Korean Markdown output, JSON language metadata, and company-website-intake.ko.md as the recommended Korean file name.
• Added unit coverage plus packed-tarball installed-bin and one-shot smoke coverage for Korean JSON/Markdown output and Korean Markdown --out.

Impact

• Company website pilots can start with a Korean intake artifact while preserving the deterministic local/no-external-MCP boundary.
• Existing English intake-template output remains the default for compatibility.

Verification Plan

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm run package:smoke
• npm run release:metadata
• git diff --check

Phase 559 — Website Intake Template Release Metadata Guard (unreleased)

Release-facing policy docs now preserve the design-ai site --intake-template package smoke contract alongside the packed-tarball coverage added in Phase 558.

Added

• Added release metadata guard term groups for design-ai site --intake-template Website Console intake template coverage.
• Updated README, Korean README, Distribution docs, Korean Distribution docs, Release Checklist, and Product Readiness release confidence wording to mention JSON stdout, Markdown stdout, Markdown --out, and JSON --out coverage in installed-bin and one-shot package paths.
• Added release metadata self-test fixture coverage so removing the intake-template smoke phrase fails deterministically.

Impact

• Release docs cannot silently drop the company website intake template distribution guarantee before company dogfood starts.
• The guard remains local/deterministic and does not add dependencies, call external MCPs, or mutate target website repos.

Verification Plan

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/release-metadata.py
• git diff --check

Phase 558 — Website Intake Template Package Smoke Coverage (unreleased)

design-ai site --intake-template is now covered by packed-tarball smoke tests across installed-bin and one-shot npm exec --package execution paths.

Added

• Added smoke assertions for intake template JSON shape, Markdown content, privacy flags, section metadata, and follow-up command hints.
• Added installed-bin smoke coverage for JSON stdout, Markdown stdout, Markdown --out, and JSON --out.
• Added one-shot npm exec --package <tarball> smoke coverage for the same intake template output modes.

Impact

• Release packaging now fails if the company website intake template command is missing from the tarball, emits the wrong payload shape, drops privacy boundaries, or regresses file-output behavior.
• The guard remains deterministic/local and does not call external MCPs, mutate target website repos, or add dependencies.

Verification Plan

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm run package:smoke
• git diff --check

Phase 557 — Website Intake Template CLI Export (unreleased)

design-ai site --intake-template now emits the company website intake template directly from the CLI, with optional JSON metadata for wrappers that need the template content, privacy boundary, and next commands in one payload.

Added

• Added --intake-template [--json] [--out file] [--force] as a workspace-free Website Improvement CLI mode.
• Added Markdown output for the blank company-site intake form and JSON output with template metadata, section ids, privacy flags, recommended file name, follow-up commands, and Markdown content.
• Updated command-specific help, top-level help catalog, Website Improvement docs, release-facing command lists, and unit coverage.

Impact

• Company pilots can generate a blank intake artifact from terminal before the real site metadata is known.
• Wrappers can consume the same template without scraping docs or carrying their own copy.
• The mode remains deterministic/local and does not call external MCPs, mutate target website repos, add dependencies, or store private project details.

Verification Plan

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/link-check.py
• python3 -B tools/audit/korean-copy-check.py
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 556 — Company Website Intake Template (unreleased)

Company-site pilots now have fill-in intake templates before bundle generation, reducing ambiguity around live URL, target repo, priority pages, user flows, MCP readiness, initial findings, and target-repo verification gates.

Added

• Added English and Korean Company Website Intake Template docs with site profile fields, priority page tables, user-flow tables, brand/content notes, MCP readiness notes, audit finding rows, first bundle commands, verification plan rows, and stop-condition questions.
• Linked the templates from Website Improvement docs and the Company Website Dogfood Runbook.
• Added the intake template to MkDocs Website Improvement navigation.

Impact

• Company project setup can start from a safe blank form instead of mixing private project details into chat history.
• Operators can fill the minimum fields required for design-ai site --init --bundle before switching to the target website repo.

Verification Plan

• python3 -B tools/audit/link-check.py
• python3 -B tools/audit/korean-copy-check.py
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 555 — Company Website Dogfood Runbook (unreleased)

The first real company-site pilot now has a documented runbook that turns Website Improvement bundle readiness into a concrete operator sequence before target-repo implementation begins.

Added

• Added English and Korean Company Website Dogfood Runbook docs covering required intake, workspace/bundle creation, bundle verification, target-repo execution, evidence return, stop conditions, and first-pilot done criteria.
• Linked the runbook from Website Improvement docs and added it to MkDocs navigation.
• Kept the process aligned with the existing boundary: design-ai remains the planning and handoff control tower, while actual code edits happen inside the target website repo.

Impact

• Company dogfood can start from a repeatable checklist instead of ad hoc commands.
• The runbook reduces the chance of editing the wrong repo, skipping bundle verification, or losing implementation evidence after the target-repo pass.

Verification Plan

• python3 -B tools/audit/link-check.py
• python3 -B tools/audit/korean-copy-check.py
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check

Phase 554 — Website Bundle Target-Repo Execution Checklist (unreleased)

Website Console handoff bundles now carry an explicit target-repo execution checklist so company dogfood implementation starts with repo confirmation, architecture inspection, focused task scope, verification gates, and evidence recording.

Added

• Added summary.json.handoff.executionChecklist with stable ids, labels, required flags, and evidence expectations for target-repo implementation.
• Added the same checklist to generated bundle README files and bundle-handoff target-repo prompts.
• Added bundle-check validation and unit/packed-tarball smoke assertions so generated bundles fail closed if the execution checklist contract drifts.

Impact

• Company website implementation handoffs now tell Codex exactly what must be confirmed before editing and what evidence must be returned after verification.
• The flow remains deterministic/local: it does not call external MCPs, mutate target website repos from design-ai, add dependencies, or run automatic Lighthouse/axe/visual-diff checks.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• git diff --check

Phase 553 — Website Bundle Handoff Readiness Guidance (unreleased)

Website Console handoff bundles now explain whether the generated bundle is strict-ready or should be treated as a draft handoff while readiness warnings remain.

Added

• Added summary.json.handoff metadata with strictReady, readiness state, recommended command, strict command, draft command, verify command, and operator note.
• Added a README Handoff Readiness section to every generated Website Console bundle.
• Added unit and packed-tarball smoke assertions so init-generated warning bundles recommend the non-strict draft handoff command while pass-state bundles recommend the strict handoff command.

Impact

• Company dogfood operators can generate an init bundle, see why --bundle-handoff --strict may exit non-zero while MCP readiness is still warning, and use the draft handoff only for planning until the strict gate passes.
• The flow stays deterministic/local and does not call external MCPs, mutate target website repos, add dependencies, or change bundle file membership.

Verification Plan

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• git diff --check

Phase 552 — Website Project Init Handoff Bundle (unreleased)

design-ai site --init --bundle --out <dir> now turns company website intake fields into a complete local handoff bundle without requiring a separate workspace save step first.

Added

• Added --bundle --out <dir> support to the site --init flow while preserving default workspace JSON output and the init next-actions runbook mode.
• Added one-shot bundle generation from deterministic Site Profile, audit checklist, MCP readiness, implementation evidence placeholders, and generated bundle artifacts.
• Added parser, command, help, and bundle-check coverage for init-generated handoff bundles.

Impact

• Operators can create a portable company dogfood handoff kit from known site facts in one command before switching to the target website repo.
• The flow stays deterministic/local and does not call external MCPs, mutate target website repos, add dependencies, or run automatic website audits.

Verification Plan

• node --check cli/lib/site.mjs cli/commands/site.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm test
• npm run audit:strict
• git diff --check

Phase 551 — Website Project Init Next-Actions Runbook (unreleased)

design-ai site --init --next-actions now turns real project intake fields into an immediate company dogfood runbook before target-repo implementation starts.

Added

• Added --next-actions support to the site --init flow while preserving the default site --init workspace JSON output.
• Added an init-specific next-action report mode that prepends a durable site --init ... --out website-workspace.json save command before MCP checks, task generation, handoff reports, and bundle export commands.
• Added human, JSON, and --out coverage for the init next-action runbook.

Impact

• Operators can paste known company site facts once and immediately get the exact save-and-continue sequence for Website Improvement dogfood.
• The flow stays deterministic/local and does not call external MCPs, mutate target website repos, add dependencies, or run automatic website audits.

Verification Plan

• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• git diff --check

Phase 550 — Website Project Init Workspace Generation (unreleased)

design-ai site --init now creates a real-project Website Improvement workspace JSON from CLI fields so company dogfood can start from actual site metadata instead of editing the sample fixture by hand.

Added

• Added design-ai site --init --name ... --live-url ... with optional repo, local path, Figma, brand notes, deploy provider, Sentry, CMS, database, repeatable page, repeatable flow, repeatable viewport, --out, and --force support.
• Added deterministic workspace generation for Site Profile, audit checklist notes, MCP readiness, implementation evidence placeholders, and report provenance while keeping refactor tasks empty until audit findings exist.
• Added unit coverage for parser validation, generated workspace shape, CLI stdout output, CLI file output, and help text.
• Added packed-tarball smoke coverage for installed-bin and one-shot npm exec --package paths.

Impact

• Operators can bootstrap a company website improvement workspace directly from known project facts.
• The command remains deterministic/local and does not call external MCPs, mutate target website repos, add dependencies, or run automatic website audits.

Verification Plan

• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

Phase 549 — Apply-Plan Decision Manual Apply Status Tones (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose manual-apply status tone fields for output artifacts in the selected optional preview branch. Phase 548 added display labels; this phase lets wrappers style apply badges without maintaining their own status-to-tone map.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactManualApplyStatusToneByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactManualApplyStatusTone.
• The tone lookup currently maps reviewCheckReport to neutral and proposalPatchPreview to warning.
• The possible tones are neutral, warning, and success.
• Kept manual-apply status labels, status enums, blocked reasons, readiness booleans, manual-apply candidate flags, precondition state counts, compact precondition rows, total/required counts, review gates, clean-workspace gates, artifact metadata, and selected command metadata intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch manual-apply status tone metadata.

Impact

• Wrappers can style apply badges from decision.commandOutputArtifactManualApplyStatusToneByKey.<key> without shipping a duplicate status-tone map.
• Tone is a display hint; the status enum remains the canonical machine-readable state.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose manual-apply status tones, manual-apply status labels, manual-apply status, manual-apply blocked reasons, manual-apply readiness, apply-precondition state counts, apply-precondition counts, compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 548 — Apply-Plan Decision Manual Apply Status Labels (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose manual-apply status display labels for output artifacts in the selected optional preview branch. Phase 547 added status enums; this phase lets wrappers render apply badges without maintaining their own enum-to-label map.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactManualApplyStatusLabelByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactManualApplyStatusLabel.
• The label lookup currently maps reviewCheckReport to Review only and proposalPatchPreview to Blocked.
• The possible labels are Review only, Blocked, and Ready to apply.
• Kept manual-apply status enums, blocked reasons, readiness booleans, manual-apply candidate flags, precondition state counts, compact precondition rows, total/required counts, review gates, clean-workspace gates, artifact metadata, and selected command metadata intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch manual-apply status label metadata.

Impact

• Wrappers can render apply badge copy from decision.commandOutputArtifactManualApplyStatusLabelByKey.<key> without shipping a duplicate enum display map.
• The status enum remains the machine-readable state, while label fields are the display surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose manual-apply status labels, manual-apply status, manual-apply blocked reasons, manual-apply readiness, apply-precondition state counts, apply-precondition counts, compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 547 — Apply-Plan Decision Manual Apply Status (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose manual-apply status enum fields for output artifacts in the selected optional preview branch. Phase 546 added blocked reason code/message fields; this phase lets wrappers render apply badges without recomputing readiness, applicability, and blocked state from multiple booleans.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactManualApplyStatusByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactManualApplyStatus.
• The status enum is not-applicable, blocked, or ready.
• The lookup currently maps reviewCheckReport to not-applicable and proposalPatchPreview to blocked.
• Kept manual-apply blocked reasons, manual-apply readiness booleans, manual-apply candidate flags, precondition state counts, compact precondition rows, total/required counts, review gates, clean-workspace gates, artifact metadata, and selected command metadata intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch manual-apply status metadata.

Impact

• Wrappers can render apply status badges from decision.commandOutputArtifactManualApplyStatusByKey.<key> without deriving status from readiness and blocked reason fields.
• The status remains fail-closed for current generated patch previews until required apply preconditions are satisfied.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose manual-apply status, manual-apply blocked reasons, manual-apply readiness, apply-precondition state counts, apply-precondition counts, compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 546 — Apply-Plan Decision Manual Apply Blocked Reasons (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose manual-apply blocked reason code/message fields for output artifacts in the selected optional preview branch. Phase 545 added readiness booleans; this phase lets wrappers render disabled patch-apply copy without recomputing the readiness explanation from candidate flags and precondition counts.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactManualApplyBlockedReasonByKey.
• Added operatorRunbook.stageSelection.decision.commandOutputArtifactManualApplyBlockedReasonCodeByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactManualApplyBlockedReason.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactManualApplyBlockedReasonCode.
• The lookup currently maps reviewCheckReport to not-manual-apply-candidate and proposalPatchPreview to required-preconditions-pending.
• Kept manual-apply readiness booleans, manual-apply candidate flags, precondition state counts, compact precondition rows, total/required counts, review gates, clean-workspace gates, artifact metadata, and selected command metadata intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch manual-apply blocked reason metadata.

Impact

• Wrappers can render disabled apply button copy from decision.commandOutputArtifactManualApplyBlockedReasonByKey.<key> without deriving explanation text from several fields.
• The blocked reason is explicit and fail-closed for current generated patch previews until required apply preconditions are satisfied.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose manual-apply blocked reasons, manual-apply readiness, apply-precondition state counts, apply-precondition counts, compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 545 — Apply-Plan Decision Manual Apply Readiness (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose manual-apply readiness booleans for output artifacts in the selected optional preview branch. Phase 544 added satisfied and pending precondition counts; this phase lets wrappers gate patch-apply affordances without recomputing the manual-apply candidate flag and required-pending precondition state.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactManualApplyReadyByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactManualApplyReady.
• manualApplyReady is true only when the artifact is a manual-apply candidate and requiredPendingApplyPreconditionCount is 0.
• The lookup currently maps reviewCheckReport to false because it is not a manual-apply candidate and proposalPatchPreview to false because its required manual-review and clean-workspace preconditions are pending by default.
• Kept manual-apply candidate flags, state counts, compact precondition rows, total/required counts, split id/label arrays, review gates, clean-workspace gates, artifact metadata, and selected command metadata intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch manual-apply readiness metadata.

Impact

• Wrappers can show or disable patch-apply buttons from decision.commandOutputArtifactManualApplyReadyByKey.<key> without deriving readiness from several fields.
• The readiness boolean is fail-closed for current generated patch previews until manual review and clean-workspace preconditions are explicitly satisfied.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose manual-apply readiness, apply-precondition state counts, apply-precondition counts, compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 544 — Apply-Plan Decision Apply Precondition State Counts (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose apply-precondition state counts for output artifacts in the selected optional preview branch. Phase 543 added total and required counts; this phase lets wrappers render checklist progress, pending summaries, and disabled apply affordances without reducing the row-level precondition objects.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactSatisfiedApplyPreconditionCountByKey.
• Added operatorRunbook.stageSelection.decision.commandOutputArtifactPendingApplyPreconditionCountByKey.
• Added operatorRunbook.stageSelection.decision.commandOutputArtifactRequiredPendingApplyPreconditionCountByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactSatisfiedApplyPreconditionCount.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactPendingApplyPreconditionCount.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactRequiredPendingApplyPreconditionCount.
• The lookup currently maps reviewCheckReport to 0 state counts and proposalPatchPreview to 0 satisfied / 2 pending / 2 required-pending preconditions.
• Kept compact precondition rows, total/required counts, split id/label arrays, apply gates, artifact metadata, and selected command metadata intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch apply-precondition state count metadata.

Impact

• Wrappers can render checklist progress and disabled apply copy from count fields without iterating over decision.commandOutputArtifactApplyPreconditionsByKey.
• A precondition counts as satisfied only when it explicitly carries satisfied: true; current patch-preview preconditions remain pending by default.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose apply-precondition state counts, apply-precondition counts, compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 543 — Apply-Plan Decision Apply Precondition Counts (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose apply-precondition summary counts for output artifacts in the selected optional preview branch. Phase 542 added compact checklist objects; this phase lets wrappers render checklist summaries without recounting those objects.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactApplyPreconditionCountByKey.
• Added operatorRunbook.stageSelection.decision.commandOutputArtifactRequiredApplyPreconditionCountByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactApplyPreconditionCount.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactRequiredApplyPreconditionCount.
• The lookup currently maps reviewCheckReport to 0 counts and proposalPatchPreview to 2 total / 2 required preconditions.
• Kept decision.commandOutputArtifactApplyPreconditionsByKey, split id/label arrays, apply gates, artifact metadata, and selected command metadata intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch apply-precondition count metadata.

Impact

• Wrappers can show checklist summary copy from count fields without iterating over decision.commandOutputArtifactApplyPreconditionsByKey.
• The compact { id, label, required } objects remain the row-level checklist surface, while count fields are the stable summary surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose apply-precondition counts, compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 542 — Apply-Plan Decision Compact Apply Preconditions (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose compact apply-precondition objects for output artifacts in the selected optional preview branch. Phase 541 added labels beside ids; this phase lets wrappers consume { id, label, required } checklist items without zipping parallel arrays.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactApplyPreconditionsByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactApplyPreconditions.
• The lookup currently maps reviewCheckReport to [] and proposalPatchPreview to required manual-review and clean-workspace checklist objects.
• Kept decision.commandOutputArtifactApplyPreconditionLabelsByKey, decision.commandOutputArtifactApplyPreconditionIdsByKey, decision.commandOutputArtifactRequiresCleanWorkspaceBeforeApplyByKey, decision.commandOutputArtifactReviewInstructionByKey, decision.commandOutputArtifactRequiresManualReviewByKey, decision.commandOutputArtifactManualApplyCandidateByKey, decision.commandOutputArtifactDispositionByKey, decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch compact apply-precondition metadata.

Impact

• Wrappers can render patch-apply checklist rows from decision.commandOutputArtifactApplyPreconditionsByKey.proposalPatchPreview without pairing id and label arrays.
• decision.commandOutputArtifactApplyPreconditionIdsByKey.<key> and decision.commandOutputArtifactApplyPreconditionLabelsByKey.<key> remain available for consumers that prefer split automation/display surfaces.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose compact apply preconditions, apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 541 — Apply-Plan Decision Apply Precondition Labels (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose ordered apply-precondition labels for output artifacts in the selected optional preview branch. Phase 540 added stable ids; this phase lets wrappers render checklist copy without hard-coding labels for those ids.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactApplyPreconditionLabelsByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactApplyPreconditionLabels.
• The lookup currently maps reviewCheckReport to [] and proposalPatchPreview to ["Manual review completed", "Clean workspace confirmed"].
• Kept decision.commandOutputArtifactApplyPreconditionIdsByKey, decision.commandOutputArtifactRequiresCleanWorkspaceBeforeApplyByKey, decision.commandOutputArtifactReviewInstructionByKey, decision.commandOutputArtifactRequiresManualReviewByKey, decision.commandOutputArtifactManualApplyCandidateByKey, decision.commandOutputArtifactDispositionByKey, decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch apply-precondition label metadata.

Impact

• Wrappers can render checklist copy from decision.commandOutputArtifactApplyPreconditionLabelsByKey.proposalPatchPreview without maintaining a local label map for precondition ids.
• decision.commandOutputArtifactApplyPreconditionIdsByKey.<key> remains the stable automation/checklist-id surface, while commandOutputArtifactApplyPreconditionLabelsByKey.<key> is the stable display-copy surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose apply precondition labels, apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 540 — Apply-Plan Decision Apply Precondition IDs (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose ordered apply-precondition ids for output artifacts in the selected optional preview branch. Phase 539 separated preview safety from manual apply safety; this phase gives wrappers a stable checklist surface without recombining review and clean-workspace booleans.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactApplyPreconditionIdsByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactApplyPreconditionIds.
• The lookup currently maps reviewCheckReport to [] and proposalPatchPreview to ["manual-review", "clean-workspace"].
• Kept decision.commandOutputArtifactRequiresCleanWorkspaceBeforeApplyByKey, decision.commandOutputArtifactReviewInstructionByKey, decision.commandOutputArtifactRequiresManualReviewByKey, decision.commandOutputArtifactManualApplyCandidateByKey, decision.commandOutputArtifactDispositionByKey, decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch apply-precondition metadata.

Impact

• Wrappers can render ordered patch-apply checklist items from decision.commandOutputArtifactApplyPreconditionIdsByKey.proposalPatchPreview without re-deriving them from multiple booleans.
• decision.commandOutputArtifactRequiresManualReviewByKey.<key> and decision.commandOutputArtifactRequiresCleanWorkspaceBeforeApplyByKey.<key> remain the stable boolean gates, while commandOutputArtifactApplyPreconditionIdsByKey.<key> is the stable ordered checklist surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose apply preconditions, clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 539 — Apply-Plan Decision Clean Workspace Apply Gates (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose clean-workspace-before-apply flags for output artifacts in the selected optional preview branch. Phase 538 added artifact review instructions; this phase separates preview command safety from manual patch-apply safety so wrappers do not infer apply requirements from the preview command's requiresCleanWorkspace: false.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactRequiresCleanWorkspaceBeforeApplyByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactRequiresCleanWorkspaceBeforeApply.
• The lookup currently maps reviewCheckReport to false and proposalPatchPreview to true.
• Kept decision.commandOutputArtifactReviewInstructionByKey, decision.commandOutputArtifactRequiresManualReviewByKey, decision.commandOutputArtifactManualApplyCandidateByKey, decision.commandOutputArtifactDispositionByKey, decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch clean-workspace apply-gate metadata.

Impact

• Wrappers can require a clean workspace before manual patch application from decision.commandOutputArtifactRequiresCleanWorkspaceBeforeApplyByKey.proposalPatchPreview without blocking the preview-generation command itself.
• decision.nextCommandSafety.requiresCleanWorkspace remains scoped to running the selected command, while decision.nextCommandOutputArtifactRequiresCleanWorkspaceBeforeApply is scoped to applying the generated artifact after review.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose clean-workspace apply gates, review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 538 — Apply-Plan Decision Output Artifact Review Instructions (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose artifact-specific review instructions for output artifacts in the selected optional preview branch. Phase 537 added manual-review-required flags; this phase lets wrappers render review guidance for Markdown reports and patch previews without hard-coding command keys, artifact names, or copy.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactReviewInstructionByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactReviewInstruction.
• The lookup currently maps reviewCheckReport to Markdown readiness report review guidance and proposalPatchPreview to unified diff manual-review guidance before skill-file edits.
• Kept decision.commandOutputArtifactRequiresManualReviewByKey, decision.commandOutputArtifactManualApplyCandidateByKey, decision.commandOutputArtifactDispositionByKey, decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch review-instruction metadata.

Impact

• Wrappers can render guidance from decision.commandOutputArtifactReviewInstructionByKey.reviewCheckReport, decision.commandOutputArtifactReviewInstructionByKey.proposalPatchPreview, and decision.nextCommandOutputArtifactReviewInstruction.
• decision.commandOutputArtifactRequiresManualReviewByKey.<key> remains the stable review-gate surface, while commandOutputArtifactReviewInstructionByKey.<key> is the stable review-copy surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose review instructions, manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 537 — Apply-Plan Decision Manual Review Gates (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose manual-review-required flags for output artifacts in the selected optional preview branch. Phase 536 added manual-apply candidate flags; this phase lets wrappers require human review before applying patch previews without parsing command keys, disposition strings, or manual-apply candidate flags.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactRequiresManualReviewByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactRequiresManualReview.
• The lookup currently maps reviewCheckReport to false and proposalPatchPreview to true.
• Kept decision.commandOutputArtifactManualApplyCandidateByKey, decision.commandOutputArtifactDispositionByKey, decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch manual-review gate metadata.

Impact

• Wrappers can branch review gates, confirmation copy, or disabled apply states from decision.commandOutputArtifactRequiresManualReviewByKey.reviewCheckReport, decision.commandOutputArtifactRequiresManualReviewByKey.proposalPatchPreview, and decision.nextCommandOutputArtifactRequiresManualReview.
• decision.commandOutputArtifactManualApplyCandidateByKey.<key> remains the stable boolean affordance surface, while commandOutputArtifactRequiresManualReviewByKey.<key> is the stable review-gate surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose manual-review gates, manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 536 — Apply-Plan Decision Manual Apply Candidate Flags (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose manual-apply candidate flags for output artifacts in the selected optional preview branch. Phase 535 added artifact dispositions; this phase lets wrappers show manual-apply affordances only for patch previews without parsing disposition strings or hard-coding command keys.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactManualApplyCandidateByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactManualApplyCandidate.
• The lookup currently maps reviewCheckReport to false and proposalPatchPreview to true.
• Kept decision.commandOutputArtifactDispositionByKey, decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch manual-apply candidate metadata.

Impact

• Wrappers can branch manual-apply buttons, warning banners, or copy from decision.commandOutputArtifactManualApplyCandidateByKey.reviewCheckReport, decision.commandOutputArtifactManualApplyCandidateByKey.proposalPatchPreview, and decision.nextCommandOutputArtifactManualApplyCandidate.
• decision.commandOutputArtifactDispositionByKey.<key> remains the stable post-render handling surface, while commandOutputArtifactManualApplyCandidateByKey.<key> is the stable boolean affordance surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose manual-apply candidate flags, decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 535 — Apply-Plan Decision Output Artifact Dispositions (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose output artifact dispositions for the selected optional preview branch. Phase 534 added media types; this phase lets wrappers distinguish review-only artifacts from manual-apply previews without hard-coding command keys, parsing file names, or inferring behavior from media types.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactDispositionByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactDisposition.
• The lookup currently maps reviewCheckReport to review-only and proposalPatchPreview to manual-apply-preview.
• Kept decision.commandOutputArtifactMediaTypeByKey, decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch output artifact disposition metadata.

Impact

• Wrappers can branch post-render copy, warning text, or manual-apply affordances from decision.commandOutputArtifactDispositionByKey.reviewCheckReport, decision.commandOutputArtifactDispositionByKey.proposalPatchPreview, and decision.nextCommandOutputArtifactDisposition.
• decision.commandOutputArtifactMediaTypeByKey.<key> remains the stable content-type surface, while commandOutputArtifactDispositionByKey.<key> is the stable post-render handling surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision output artifact dispositions, decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 534 — Apply-Plan Decision Output Artifact Media Types (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose output artifact media types for the selected optional preview branch. Phase 533 added preview actions; this phase lets wrappers configure Markdown and diff viewers, clipboard behavior, or download content types without parsing file extensions, artifact type strings, command strings, or argv arrays.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactMediaTypeByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactMediaType.
• The lookup currently maps reviewCheckReport to text/markdown and proposalPatchPreview to text/x-diff.
• Kept decision.commandOutputArtifactActionByKey, decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch output artifact media type metadata.

Impact

• Wrappers can branch viewer/editor/download content handling from decision.commandOutputArtifactMediaTypeByKey.reviewCheckReport, decision.commandOutputArtifactMediaTypeByKey.proposalPatchPreview, and decision.nextCommandOutputArtifactMediaType.
• decision.commandOutputArtifactActionByKey.<key> remains the stable preview behavior surface, while commandOutputArtifactMediaTypeByKey.<key> is the stable content-type surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision output artifact media types, decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 533 — Apply-Plan Decision Output Artifact Actions (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose output artifact handling actions for the selected optional preview branch. Phase 532 added artifact types; this phase lets wrappers choose Markdown report rendering or unified diff preview rendering without deriving UI behavior from type strings, file names, command strings, or argv arrays.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactActionByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactAction.
• The lookup currently maps reviewCheckReport to render-markdown-report and proposalPatchPreview to render-unified-diff-preview.
• Kept decision.commandOutputArtifactTypeByKey, decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch output artifact action metadata.

Impact

• Wrappers can branch UI behavior from decision.commandOutputArtifactActionByKey.reviewCheckReport, decision.commandOutputArtifactActionByKey.proposalPatchPreview, and decision.nextCommandOutputArtifactAction.
• decision.commandOutputArtifactTypeByKey.<key> remains the stable artifact type surface, while commandOutputArtifactActionByKey.<key> is the stable preview behavior surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision output artifact actions, decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 532 — Apply-Plan Decision Output Artifact Types (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose output artifact types for the selected optional preview branch. Phase 531 added artifact target names; this phase lets wrappers distinguish Markdown review reports from unified diff previews without parsing file extensions, command strings, or argv arrays.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactTypeByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifactType.
• The lookup currently maps reviewCheckReport to markdown-report and proposalPatchPreview to unified-diff.
• Kept decision.commandOutputArtifactByKey, decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch output artifact type metadata.

Impact

• Wrappers can branch rendering or download behavior from decision.commandOutputArtifactTypeByKey.reviewCheckReport, decision.commandOutputArtifactTypeByKey.proposalPatchPreview, and decision.nextCommandOutputArtifactType.
• decision.commandOutputArtifactByKey.<key> remains the stable file target surface, while commandOutputArtifactTypeByKey.<key> is the stable artifact rendering/type surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision output artifact types, decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 531 — Apply-Plan Decision Output Artifact Lookup (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose output artifact targets for the selected optional preview branch. Phase 530 added command descriptions; this phase lets wrappers display generated artifact names without parsing --out arguments from command strings or argv arrays.

Changed

• Added operatorRunbook.stageSelection.decision.commandOutputArtifactByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandOutputArtifact.
• The lookup currently maps reviewCheckReport to skill-proposal-review-check.md and proposalPatchPreview to skill-proposals.patch.
• Kept decision.commandArgsByKey, decision.commandStringByKey, decision.commandDisplayLabelByKey, and decision.commandDescriptionByKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch output artifact metadata.

Impact

• Wrappers can render selected preview artifact targets from decision.commandOutputArtifactByKey.reviewCheckReport, decision.commandOutputArtifactByKey.proposalPatchPreview, and decision.nextCommandOutputArtifact.
• decision.commandArgsByKey.<key> remains the automation execution surface, while commandOutputArtifactByKey.<key> is the stable UI/export target surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision output artifact lookup, decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 530 — Apply-Plan Decision Command Descriptions (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose descriptions for the selected optional preview branch. Phase 529 added display labels; this phase lets wrappers render tooltips or secondary command descriptions without hard-coding command semantics or scanning decision.commands.

Changed

• Added operatorRunbook.stageSelection.decision.commandDescriptionByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandDescription.
• The lookup currently maps reviewCheckReport to Generate a Markdown review-check artifact for accepted proposal readiness. and proposalPatchPreview to Generate a unified diff preview for accepted skill proposal edits..
• Kept decision.commandDisplayLabelByKey, decision.commandStringByKey, decision.commandArgsByKey, and decision.nextCommandDisplayLabel intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch description metadata.

Impact

• Wrappers can render selected preview command tooltips or secondary copy from decision.commandDescriptionByKey.reviewCheckReport, decision.commandDescriptionByKey.proposalPatchPreview, and decision.nextCommandDescription.
• decision.commandDisplayLabelByKey.<key> remains the UI label surface, decision.commandStringByKey.<key> remains the copy/display command surface, and decision.commandArgsByKey.<key> remains the automation execution surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command descriptions, display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 529 — Apply-Plan Decision Command Display Labels (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose display labels for the selected optional preview branch. Phase 528 added key-to-command-string lookup; this phase lets wrappers render stable human-readable labels without deriving UI copy from camelCase command keys or scanning decision.commands.

Changed

• Added operatorRunbook.stageSelection.decision.commandDisplayLabelByKey.
• Added operatorRunbook.stageSelection.decision.nextCommandDisplayLabel.
• The lookup currently maps reviewCheckReport to Review check Markdown report and proposalPatchPreview to Skill proposal patch preview.
• Kept decision.commandKeys, decision.commandStringByKey, decision.commandArgsByKey, and decision.nextCommandKey intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch display label metadata.

Impact

• Wrappers can render selected preview command labels from decision.commandDisplayLabelByKey.reviewCheckReport, decision.commandDisplayLabelByKey.proposalPatchPreview, and decision.nextCommandDisplayLabel.
• decision.commandStringByKey.<key> remains the human-readable command copy surface, while decision.commandArgsByKey.<key> remains the automation execution surface.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command display labels, command string lookup, command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 528 — Apply-Plan Decision Command String Lookup (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose a compact key-to-command-string lookup for the selected optional preview branch. Phase 527 added key-to-argv lookup; this phase lets wrappers display or copy selected preview command strings by key without scanning decision.commands, opening decision.commandByKey, or jumping to the top-level commands object.

Changed

• Added operatorRunbook.stageSelection.decision.commandStringByKey.
• The lookup currently maps reviewCheckReport and proposalPatchPreview to their full shell command strings.
• Kept decision.commands[*].command, decision.commandByKey.<key>.command, decision.nextCommand, and top-level commands intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch command-string lookup metadata.

Impact

• Wrappers can display or copy selected preview commands from decision.commandStringByKey.reviewCheckReport and decision.commandStringByKey.proposalPatchPreview without reducing arrays.
• decision.commandArgsByKey.<key> remains the safer execution surface for automation, while commandStringByKey is optimized for human-readable display/copy handoffs.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command string lookup, decision command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 527 — Apply-Plan Decision Command Args Lookup (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose a compact key-to-argv lookup for the selected optional preview branch. Phase 526 added key-to-safety-level lookup; this phase lets wrappers retrieve selected preview command args by key without scanning decision.commands, opening decision.commandByKey, or jumping to the top-level commandArgs object.

Changed

• Added operatorRunbook.stageSelection.decision.commandArgsByKey.
• The lookup currently maps reviewCheckReport and proposalPatchPreview to their full structured argv arrays.
• Kept decision.commands[*].commandArgs, decision.commandByKey.<key>.commandArgs, decision.nextCommandArgs, and top-level commandArgs intact for existing consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch command-args lookup metadata.

Impact

• Wrappers can execute or display selected preview commands from decision.commandArgsByKey.reviewCheckReport and decision.commandArgsByKey.proposalPatchPreview without reducing arrays.
• decision.commandByKey.<key> remains available for full command objects, and commandSequenceByKey.<key> remains the canonical full ordered command contract.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command args lookup, decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 526 — Apply-Plan Decision Command Safety Level Lookup (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose a compact key-to-safety-level lookup for the selected optional preview branch. Phase 525 added key-to-run-policy lookup; this phase lets wrappers validate selected command safety levels by key without scanning decision.commands or opening commandByKey.

Changed

• Added operatorRunbook.stageSelection.decision.commandSafetyLevelByKey.
• The lookup currently maps reviewCheckReport and proposalPatchPreview to local-output.
• Kept decision.commands[*].safetyLevel, decision.commandByKey.<key>.safetyLevel, decision.nextCommandSafetyLevel, and full nested safety objects intact.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch safety-level lookup metadata.

Impact

• Wrappers can validate selected preview command safety from decision.commandSafetyLevelByKey.reviewCheckReport and decision.commandSafetyLevelByKey.proposalPatchPreview without reducing arrays.
• decision.commandByKey.<key>.safety and commandSequenceByKey.<key>.safety remain available for full safety objects.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command safety-level lookup, decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 525 — Apply-Plan Decision Command Run Policy Lookup (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose a compact key-to-run-policy lookup for the selected optional preview branch. Phase 524 added key-to-step lookup; this phase lets wrappers validate selected command execution policy by key without scanning decision.commands or loading the full commandSequence.

Changed

• Added operatorRunbook.stageSelection.decision.commandRunPolicyByKey.
• The lookup currently maps reviewCheckReport and proposalPatchPreview to output-artifact.
• Kept decision.commands[*].runPolicy, decision.commandByKey.<key>.runPolicy, decision.nextCommandRunPolicy, and commandSequenceByKey.<key>.runPolicy intact.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch run-policy lookup metadata.

Impact

• Wrappers can validate selected preview command run policy from decision.commandRunPolicyByKey.reviewCheckReport and decision.commandRunPolicyByKey.proposalPatchPreview without reducing arrays.
• commandSequence and commandSequenceByKey remain the canonical full ordered command contract.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command run-policy lookup, decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 524 — Apply-Plan Decision Command Step Lookup (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose a compact key-to-step lookup for the selected optional preview branch. Phase 523 added step metadata to compact command objects; this phase lets wrappers validate selected command order by key without scanning decision.commands or loading the full commandSequence.

Changed

• Added operatorRunbook.stageSelection.decision.commandStepByKey.
• The lookup currently maps reviewCheckReport to step 2 and proposalPatchPreview to step 3.
• Kept decision.commands[*].step, decision.commandByKey.<key>.step, decision.nextCommandEntry.step, and decision.nextCommandStep intact for object-based consumers.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch step lookup metadata.

Impact

• Wrappers can validate command order from decision.commandStepByKey.reviewCheckReport and decision.commandStepByKey.proposalPatchPreview without reducing arrays.
• commandSequence and commandSequenceByKey remain the canonical full ordered command contract.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command step lookup, decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 523 — Apply-Plan Decision Command Step Metadata (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decision commands now carry their original command-sequence step numbers. Phase 522 made the selected preview command's safety available from the nextCommand* field family; this phase lets wrappers preserve command order and display step context without reading the full commandSequence.

Changed

• Added step to compact operatorRunbook.stageSelection.decision.commands entries.
• Added step to decision.commandByKey.<key> and decision.nextCommandEntry.
• Added decision.nextCommandStep for wrappers consuming the separate nextCommand* fields.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves selected-branch step metadata.

Impact

• Wrappers can show or execute the selected optional preview branch with stable command-sequence step context.
• decision.nextCommandStep currently reports 2 for reviewCheckReport, matching the full command sequence after the read-only reviewCheckJson gate.
• commandSequence and commandSequenceByKey remain the canonical full ordered command contract.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command step metadata, selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 522 — Apply-Plan Decision Next Command Safety (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose the selected preview command's full safety object next to the existing nextCommand* fields. Phase 521 made compact decision command objects self-contained; this phase lets wrappers that already consume decision.nextCommandKey, decision.nextCommand, decision.nextCommandArgs, and decision.nextCommandRunPolicy gate the same command without reading nextCommandEntry.

Changed

• Added operatorRunbook.stageSelection.decision.nextCommandSafety.
• The field mirrors decision.nextCommandEntry.safety for the selected optional preview command, currently reviewCheckReport.
• Kept decision.nextCommandSafetyLevel and flattened fields for backward compatibility.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves the selected next-command safety object.

Impact

• Wrappers can gate the selected optional preview handoff from the nextCommand* field family alone.
• decision.nextCommandEntry.safety, decision.commandByKey.<key>.safety, and commandSequenceByKey.<key>.safety remain available for full object and lookup-based consumers.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose selected next-command safety, decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 521 — Apply-Plan Decision Command Safety Objects (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decision commands now carry their own nested command-level safety objects. Phase 520 exposed the selected optional preview command as nextCommandEntry; this phase makes decision.commands, decision.commandByKey, and decision.nextCommandEntry self-contained for safety gating without requiring wrappers to jump to commandSequenceByKey.

Changed

• Added nested safety objects to compact decision command summaries.
• Preserved existing safetyLevel and flattened write/mutation/external-AI flags for backward compatibility.
• Kept the command-level safety.reason on selected preview commands, distinguishing local output artifact writes from learning profile, review file, skill file, external AI, embedding, and fine-tuning mutations.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves nested decision command safety objects.

Impact

• Wrappers can gate selected optional preview commands directly from decision.commands[*].safety, decision.commandByKey.<key>.safety, or decision.nextCommandEntry.safety.
• commandSequenceByKey remains the canonical full command lookup, but decision command objects now carry enough safety detail for selected-branch rendering and approval checks.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command safety objects, selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 520 — Apply-Plan Decision Next Command Entry (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose the selected optional preview command as one compact object. Phase 519 added direct lookup and separate nextCommand* fields; this phase removes the need for wrappers to reconstruct the first preview command from separate fields before rendering or execution.

Changed

• Added operatorRunbook.stageSelection.decision.nextCommandEntry.
• The entry mirrors the first decision.commands item, currently reviewCheckReport, including command string, structured args, run policy, safety level, write/mutation flags, external-AI flags, and clean-workspace requirement.
• Kept existing nextCommandKey, nextCommand, nextCommandArgs, nextCommandRunPolicy, and nextCommandSafetyLevel fields for backward compatibility.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON preserves the selected command entry contract.

Impact

• Wrappers can branch on decision.action, gate on decision.safety, then consume decision.nextCommandEntry as the first optional local-output preview handoff.
• decision.commandByKey remains available for explicit operator choices, and commandSequenceByKey remains the canonical full command lookup.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose selected command entries, decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 519 — Apply-Plan Decision Command Lookup (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now expose direct command lookup metadata for the selected optional preview branch. Phase 518 added compact decision commands; this phase makes the first command and per-key command lookup addressable without scanning arrays.

Changed

• Added operatorRunbook.stageSelection.decision.commandByKey.
• Added decision.nextCommandKey, decision.nextCommand, decision.nextCommandArgs, decision.nextCommandRunPolicy, and decision.nextCommandSafetyLevel.
• Rendered the decision next command key in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the decision command lookup contract.

Impact

• Automation can branch on decision.action, gate on decision.safety, then fetch reviewCheckReport or proposalPatchPreview directly from decision.commandByKey.
• Wrappers can offer the first optional preview command from decision.nextCommand* without scanning decision.commands.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command lookup, decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 518 — Apply-Plan Decision Command Handoff (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now include compact command handoffs for the selected branch. Phase 517 made the decision safe to gate; this phase makes the optional preview branch executable without requiring wrappers to look up commandSequenceByKey.

Changed

• Added operatorRunbook.stageSelection.decision.commandCount and decision.commands.
• Each decision command reports key, command string, structured commandArgs, runPolicy, safetyLevel, local-output flags, mutation flags, external-AI flags, and clean-workspace requirement.
• Rendered decision command keys in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the decision command handoff.

Impact

• Automation can read one decision object to choose the optional preview branch, inspect safety, and run or offer the two local-output preview commands.
• commandSequenceByKey remains the canonical full command lookup; decision commands are a compact first-branch handoff.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision command handoffs, decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 517 — Apply-Plan Decision Safety Summary (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection decisions now carry their own safety summary. Phase 516 added the branch decision enum; this phase lets wrappers evaluate the selected decision's local-output and mutation boundary without jumping to the selected-stage detail object.

Changed

• Added operatorRunbook.stageSelection.decision.safety.
• The decision safety summary reports level, local file writes, output artifact writes, local-state mutation, profile/review/skill mutation, external-AI calls, clean-workspace requirement, and reason.
• Rendered decision safety in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the decision safety contract.

Impact

• Automation can branch on decision.action and immediately gate execution from decision.safety.
• The current selected decision is explicitly local-output: optional preview artifacts may write files, but learning profiles, review files, skill files, external AI APIs, embeddings, and fine-tuning remain untouched.
• Invalid command contracts still fail closed with an empty stageSelection object.
• Existing selected-stage summaries and stage lookup fields remain additive and backward compatible.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose decision safety summaries, branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 516 — Apply-Plan Stage Decision Enum (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection output now exposes a compact decision enum for the current branch. Phase 515 made selected stages self-describing; this phase adds a single machine-readable action that tells local AI/agent wrappers what to offer first.

Changed

• Added operatorRunbook.stageSelection.decision for valid apply-plan command contracts.
• The decision reports action: offer-optional-preview, selected stageKey, stageKind, required, hasCommands, commandKeys, runPolicy, required follow-up stage keys, and whether operator action is required before required commands.
• Rendered the decision action in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the decision enum.

Impact

• Automation can branch on one enum instead of combining strategy text, selected-stage summaries, and required-stage keys.
• The first branch remains optional local preview artifacts; the mandatory path still begins with manual skill edits before read-only command gates.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose branch decision enums, selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 515 — Apply-Plan Selected Stage Summaries (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan stage-selection output now includes compact summaries for the selected optional preview stage, first required manual stage, and first required command-bearing stage. Phase 514 grouped the branch strategy into one object; this phase makes each selected branch self-describing without requiring wrappers to scan stageByKey.

Changed

• Added stageSelection.nextStage, stageSelection.nextRequiredStage, and stageSelection.nextRequiredCommandStage.
• Each selected-stage summary reports key, step, label, kind, required, command count, command keys, local-output flags, mutation flags, external-AI flags, clean-workspace requirement, and reason.
• Rendered the selected optional stage in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the selected-stage summary contract.

Impact

• Automation can decide whether the selected branch is optional, manual, command-bearing, local-output-producing, read-only, or external-call-free without scanning the full stage list.
• The summary stays compact and additive; stageByKey remains the canonical full stage lookup.
• Invalid command contracts still fail closed with an empty stageSelection object.
• The change does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose selected-stage summaries, stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 514 — Apply-Plan Stage Selection Summary (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan operator runbooks now expose a compact stage-selection summary. Phase 513 added direct required-stage handoff fields; this phase groups the optional preview path, first required manual stage, and first required command-bearing gate into one machine-readable object.

Changed

• Added operatorRunbook.stageSelection for valid apply-plan command contracts.
• The selection summary reports strategy, stageOrder, nextStageKey, optional preview command keys, nextRequiredStageKey, and nextRequiredCommandStageKey.
• Rendered the stage-selection strategy in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the stage-selection contract.

Impact

• Automation can read one object to decide whether to offer optional preview artifacts, route the operator to manual skill edits, or continue to the read-only review gate.
• The strategy value makes the optional-before-required policy explicit without parsing prose.
• Invalid command contracts stay fail-closed with an empty stageSelection object.
• The change remains additive and does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose stage-selection strategy, optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 513 — Apply-Plan Required Stage Handoff Index (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan operator runbooks now separate the optional next stage from the first required operator stage. Phase 512 made every stage addressable by key; this phase lets local AI/agent wrappers branch directly to manualSkillEdit or the next required command-bearing gate without scanning stage metadata.

Changed

• Added operatorRunbook.nextRequiredStageKey and operatorRunbook.nextRequiredStageCommandKeys.
• Added operatorRunbook.nextRequiredCommandStageKey and operatorRunbook.nextRequiredCommandStageCommandKeys.
• Rendered the next required stage and next required command stage in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the required-stage handoff contract.

Impact

• Automation can distinguish optional previewArtifacts output generation from required manualSkillEdit work.
• Wrappers can jump to the next required command-bearing stage, reviewReadiness, after the manual edit is complete.
• Invalid command contracts stay fail-closed with empty required-stage handoff fields.
• The change remains additive and does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose optional stages, required stages, command-bearing gates, operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 512 — Apply-Plan Operator Runbook Stage Index (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan operator runbooks now expose a stable stage key index. Phase 511 added the ordered runbook stages; this phase lets local AI/agent wrappers retrieve previewArtifacts, manualSkillEdit, reviewReadiness, or strictGate directly without scanning the stages array.

Changed

• Added operatorRunbook.stageKeys to preserve validated operator stage order as a top-level list.
• Added operatorRunbook.stageByKey so each runbook stage is addressable by its stable key.
• Rendered runbook stage keys in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the stage-index contract.

Impact

• Automation can select a named operator stage directly while still using operatorRunbook.stages for deterministic execution order.
• The index mirrors the existing commandSequenceKeys / commandSequenceByKey contract at the higher operator-runbook layer.
• Invalid command contracts stay fail-closed with an empty stage key list and empty stage map.
• The change remains additive and does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose operator stage lookup, operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 511 — Apply-Plan Operator Runbook Contract (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now expose a staged operator runbook for accepted skill proposal handoffs. Phase 510 made named command lookup direct; this phase makes the higher-level operator order explicit: optional preview artifacts, manual skill edits, review readiness, then strict gate.

Changed

• Added operatorRunbook to apply-plan command contracts.
• The runbook reports executable/blocked state, stage counts, required stage counts, command-bearing stage counts, next stage metadata, and ordered stages.
• Added four deterministic stages: previewArtifacts, manualSkillEdit, reviewReadiness, and strictGate.
• Rendered runbook summaries and stage lists in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the operator runbook contract.

Impact

• Local AI/agent wrappers can follow the reviewed apply-plan workflow without inferring stage order from prose or from the raw command sequence.
• The runbook distinguishes optional local preview artifacts from the required manual skill-file edit and required read-only verification gates.
• Invalid command contracts stay fail-closed with zero stages and blocked runbook state.
• The change remains additive and does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose operator stage order, command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 510 — Apply-Plan Command Sequence Key Index (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now expose a key index for the follow-up command sequence. Phase 509 added aggregate sequence safety; this phase lets local AI/agent wrappers jump directly to reviewCheckJson, reviewCheckReport, proposalPatchPreview, or strictGate without scanning the ordered array.

Changed

• Added commandSequenceKeys to preserve the validated follow-up command key order as a top-level list.
• Added commandSequenceByKey so each sequence item is addressable by its stable key.
• Rendered command sequence keys in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the key-index contract.

Impact

• Automation can retrieve named follow-up commands directly while still using commandSequence for deterministic execution order.
• The index remains fail-closed: invalid command contracts expose an empty key list and empty key map.
• The change remains additive and does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose command choice, ordered execution, key lookup, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 509 — Apply-Plan Command Sequence Summary Contract (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now expose a top-level summary for the full follow-up command sequence. Phase 508 made each step executable from structured args; this phase lets local AI/agent wrappers decide whether the whole sequence is executable, blocked, read-only, local-output-producing, mutating, or external-call-free without reducing the full array.

Changed

• Added commandSequenceSummary to apply-plan command contracts.
• The summary reports executable, blocked, step counts, read-only vs local-output counts, local write/output flags, mutation flags, external AI API flags, clean-workspace requirements, and an aggregate run policy.
• Rendered sequence summary fields in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the summary contract.

Impact

• Automation can branch on the full sequence boundary before running any follow-up command.
• Wrappers can distinguish local preview artifact writes from profile/review/skill mutation.
• The change remains additive and does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose command choice, ordered execution, aggregate safety, per-command safety, readiness counts, and failure recovery guidance.

Phase 508 — Apply-Plan Follow-Up Command Sequence Contract (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now expose the full follow-up command sequence. Phase 507 made the first next command safety-checkable; this phase lets local AI/agent wrappers run the complete operator handoff in a deterministic order without reparsing human prose.

Changed

• Added commandSequenceCount and commandSequence to valid apply-plan command contracts.
• Each sequence item includes step, key, command, commandArgs, runPolicy, and per-command safety metadata.
• Marked pure validation commands as read-only and local --out preview commands as local-output, preserving explicit writesLocalFiles and writesOutputArtifact booleans.
• Kept invalid command contracts fail-closed by returning an empty command sequence when contract checks fail.
• Rendered command sequence count and ordered command sequence in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the sequence contract.

Impact

• Automation can execute the review-check JSON command first, produce optional local report/patch preview artifacts, and finish with the strict readiness gate from structured commandArgs.
• Wrappers can distinguish read-only validation commands from local output artifact commands before execution.
• The change remains additive and does not mutate learning profiles, review files, skill files, external AI APIs, embeddings, or fine-tuning jobs.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose command choice, ordered execution, per-command safety, readiness counts, and failure recovery guidance.

Phase 507 — Apply-Plan Next Command Safety Metadata (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now describe the selected next command's run policy and safety profile. Phase 506 made the first safe follow-up command directly executable from nextCommandArgs; this phase lets local AI/agent wrappers verify that the selected command is read-only and non-mutating before running it.

Changed

• Added nextCommandRunPolicy: "preview-only" for valid apply-plan command contracts.
• Added nextCommandSafety metadata for the selected next command, including read-only level, no local file writes, no local-state mutation, no learning/review/skill file mutation, no external AI calls, and no clean-workspace requirement.
• Kept invalid command contracts fail-closed by returning an empty run policy and empty safety object when contract checks fail.
• Rendered next-command policy and safety level in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the safety contract.

Impact

• Automation can execute commandContract.nextCommandArgs only after confirming nextCommandSafety.level === "read-only" and nextCommandRunPolicy === "preview-only".
• Manual operators see whether the recommended follow-up command is safe before copying it.
• The change remains additive and read-only: no learning profile, review file, skill file, external AI API, embedding, or fine-tuning mutation is introduced.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose command choice, execution policy, safety metadata, readiness counts, and failure recovery guidance.

Phase 506 — Apply-Plan Next Command Contract Handoff (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now identify the first safe follow-up command directly. Earlier phases exposed reproducible command strings, structured args, contract validity, failure diagnostics, and pass/warn/fail counts; this phase adds the single next-command handoff fields that local AI/agent wrappers can execute without reparsing command prose.

Changed

• Added nextCommandKey, nextCommand, and nextCommandArgs to valid apply-plan command contracts.
• Kept invalid contracts non-executable by returning empty next-command fields when any command-contract check fails.
• Rendered the next command key and command in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the next-command contract.

Impact

• Automation can run the first read-only review-check command from commandContract.nextCommandArgs without selecting from the full command map.
• Invalid command contracts remain fail-closed, so wrappers can avoid running follow-up commands until contract failures are fixed.
• The change remains additive and read-only: no learning profile, review file, skill file, external AI API, embedding, or fine-tuning mutation is introduced.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• git diff --check

What's still ahead

• Continue local AI/agent learning development from apply-plan contracts that expose both readiness diagnostics and a fail-closed next-command handoff.

Phase 505 — Apply-Plan Command Contract Check Summary Counts (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now expose top-level check summary counts. Phase 504 made failures easy to recover from; this phase also makes the valid/pass path cheap for local AI/agent wrappers to summarize without scanning the full checks array.

Changed

• Added checkCount, passCount, and warningCount next to the existing failureCount apply-plan command contract diagnostics.
• Added warnings to commandContract.summary so nested summaries and top-level counts stay aligned.
• Rendered check, pass, and warning counts in human and Markdown apply-plan command contract summaries.
• Extended unit coverage and package-smoke self-test fixtures so packaged JSON, Markdown, and human outputs preserve the count contract.

Impact

• Automation can branch on pass/warn/fail counts directly instead of reducing the full contract check list.
• Operators see the whole contract health summary before running read-only follow-up commands.
• The change is additive and keeps apply-plan read-only: no learning profile, review file, skill file, external AI API, embedding, or fine-tuning mutation is introduced.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• git diff --check

What's still ahead

• Continue local AI/agent learning development from command contracts that expose direct pass, warn, and fail readiness counts.

Phase 504 — Apply-Plan Command Contract Failure Diagnostics (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contracts now include fail-focused diagnostics in addition to the full check list. Local AI/agent wrappers can branch on failureCount, failedCheckIds, and failedChecks, while human and Markdown outputs show a concise failed-check summary and a deterministic next action.

Changed

• Added failureCount, failedCheckIds, failedChecks, and nextAction to apply-plan commandContract metadata.
• Rendered failure count, failed-check ids, and next action in human and Markdown apply-plan command contract summaries.
• Added unit coverage for both valid contracts and missing-review-file contract failures.
• Extended packed-tarball smoke assertions so packaged apply-plan JSON, Markdown, and human output preserve the new diagnostics.

Impact

• Automation no longer has to scan every command-contract check to decide whether the apply-plan follow-up command set is usable.
• Operators get explicit recovery guidance when the command contract fails, while valid contracts continue to point at reviewCheckJson followed by strictGate.
• The change is additive and keeps the read-only apply-plan boundary intact.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from command contracts that expose both pass summaries and fail-focused recovery metadata.

Phase 503 — Apply-Plan Human Command Contract Release Guard (unreleased)

Release metadata now protects the packed-tarball smoke wording for the default human design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan command contract summary. Phase 502 added the console output and package smoke assertion; this phase makes release-facing docs fail metadata checks if they stop mentioning the human apply-plan Command contract path.

Changed

• Added a release metadata term group for the human apply-plan command contract smoke phrase.
• Updated release-facing English and Korean docs so packed-tarball smoke guidance mentions the default human --apply-plan Command contract section alongside JSON and Markdown outputs.
• Added release metadata self-test drift coverage for missing human apply-plan command contract wording.

Impact

• The human console contract added in Phase 502 is now protected by the same release metadata guard family as apply-plan JSON and Markdown report coverage.
• Release docs can no longer silently describe only --json and --report apply-plan paths while omitting the default operator-facing command contract.

Verification Plan

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Continue local AI/agent learning development from a release-guarded apply-plan command contract across human, JSON, and Markdown surfaces.

Phase 502 — Skill Proposal Apply-Plan Human Command Contract Smoke (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan now prints the same command contract summary that JSON and Markdown report outputs expose. Operators running the default human console path can see whether the follow-up command set is valid, which command keys are required, whether a review file is required, and which write/apply flags remain forbidden before copying any command.

Changed

• Added a Command contract section to the default human apply-plan output.
• Extended unit coverage so human output must show contract validity, status, required keys, and forbidden flags.
• Added packed-tarball smoke coverage for the apply-plan human output path, including installed-bin and one-shot npm exec --package <tarball> execution.
• Added package-smoke self-test drift coverage for missing human command contract wording.

Impact

• Manual operators no longer need --json or --report to inspect the apply-plan command contract.
• Local automation and human review now see the same read-only follow-up command boundary across JSON, Markdown, and console output.
• Existing apply-plan JSON and Markdown schemas remain additive and unchanged from Phase 501.

Verification Plan

• node --check cli/commands/learn.mjs cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue local AI/agent learning development from a consistent apply-plan command contract across every output mode.

Phase 501 — Skill Proposal Apply-Plan Command Contract Metadata (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json now emits an explicit commandContract block next to commands and commandArgs. The apply plan remains read-only, but local automation can now verify the required follow-up command keys, base command, review-file context, expected action suffixes, and forbidden write/apply flags without reparsing prose or rebuilding the contract externally.

Changed

• Added deterministic apply-plan command contract metadata for the four follow-up commands: reviewCheckJson, reviewCheckReport, proposalPatchPreview, and strictGate.
• Added per-command contract checks for design-ai learn --propose-skills base arguments, configured review-file preservation, expected suffix flags, and forbidden --yes usage.
• Rendered the command contract summary in Markdown apply-plan reports.
• Extended unit and package-smoke self-test coverage so packaged apply-plan JSON and Markdown reports must preserve the command contract shape.

Impact

• Local AI/agent wrappers can inspect commandContract.valid and commandContract.checks before offering or executing follow-up commands.
• Manual skill proposal apply plans keep the existing read-only boundary while making the automation contract self-describing.
• The contract is additive and does not change existing commands, commandArgs, task, review, or privacy fields.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Continue broader local AI/agent learning development from a self-describing manual apply-plan command contract.

Phase 500 — Skill Proposal Apply-Plan CommandArgs Contract Coverage (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json now treats every follow-up command as a structured automation contract. The apply plan already exposed human command strings and machine-readable commandArgs; this phase ensures all four follow-up paths stay aligned under unit tests and packed-tarball smoke self-tests.

Changed

• Consolidated apply-plan follow-up command generation so commands and commandArgs are derived from the same command map.
• Extended unit coverage for reviewCheckJson, reviewCheckReport, proposalPatchPreview, and strictGate argument arrays.
• Extended package-smoke self-test fixtures and assertions so packaged apply-plan JSON cannot silently drop any follow-up commandArgs path.

Impact

• Local AI/agent skill proposal handoffs remain read-only while becoming safer for automation wrappers that execute commandArgs directly.
• Manual apply plans now have stronger drift protection between human command strings and structured command arrays.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Continue AI/agent learning development from the verified proposal handoff contract.

Phase 499 — Skill Proposal Apply-Plan Context Commands (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan now carries the active proposal context into its follow-up commands. The apply plan already named the next review-check, report, patch-preview, and strict-gate commands; those commands now preserve --file, --usage-file, --from-file, and --review-file so operators can reproduce the same local signal context after manual skill edits.

Changed

• Added shell-safe, context-preserving follow-up command generation for apply-plan output.
• Added machine-readable commandArgs alongside the human command strings so local automation can run the same review-check or strict-gate commands without parsing shell text.
• Extended unit tests and package-smoke self-tests to verify the apply-plan command context contract.

Impact

• Manual skill proposal application remains read-only in design-ai: no learning profile, review file, skill file, target repo, external AI API, embedding, or fine-tuning mutation is introduced.
• Operators get reproducible follow-up commands tied to the same learning profile, usage sidecar, signal directory, and review file used to create the apply plan.

Verification Plan

• node --check cli/lib/skill-proposals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Continue broader AI/agent learning development from a reproducible manual apply handoff baseline.

Phase 495 — Learning Readiness Status Count Release Evidence (unreleased)

The full release gate now passes after the learning readiness status-count index landed.

Changed

• Recorded full npm run release:check evidence after Phase 494 added readiness status-count indexes to learning signal and focused agent backlog reports.
• Confirmed the release gate covers CLI unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke after the status-count contract change.

Impact

• The branch has fresh pre-push release evidence after extending local AI/agent readiness metadata.
• Local AI/agent development can continue from a verified baseline where the packaged CLI preserves the new status-count JSON and Markdown report contract.

Verified

• npm run release:check

What's still ahead

• Run post-publish npm run registry:smoke after a real npm publish, because that command requires the public package to exist in npm.

Phase 494 — Learning Readiness Status Count Index (unreleased)

Learning readiness JSON and Markdown now expose status-count indexes for required and optional checks.

Changed

• Added checkCountByStatus, requiredCheckCountByStatus, and optionalCheckCountByStatus to design-ai learn --signals and focused design-ai learn --agent-backlog readiness JSON.
• Rendered the same status-count index lines in learning signal and focused agent backlog Markdown reports.
• Extended packed-tarball smoke assertions so packaged learn signals and agent backlog outputs must preserve the status count index shape.

Impact

• Local AI/agent automation can branch on readiness pass/info/warn/fail distribution without scanning the full checks array.
• Human Markdown handoffs now show whether optional evidence gaps are only informational or whether required checks are warning/failing.
• Existing readiness schemas remain backward compatible because the new fields are additive.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Run post-publish npm run registry:smoke after a real npm publish, because that command requires the public package to exist in npm.

Phase 493 — Public Registry Learning Readiness Release Evidence (unreleased)

The full release gate now passes after the public registry learning readiness Markdown report smoke guard.

Changed

• Recorded full npm run release:check evidence after Phase 492 added public registry smoke coverage for learning readiness Markdown report check indexes.
• Confirmed the release gate covers CLI unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke after the registry smoke guard change.

Impact

• The branch has fresh pre-push release evidence after extending public registry learning readiness Markdown smoke coverage.
• Local AI/agent development can continue from a verified release baseline rather than only focused registry and metadata self-tests.

Verified

• npm run release:check

What's still ahead

• Run post-publish npm run registry:smoke after a real npm publish, because that command requires the public package to exist in npm.

Phase 492 — Public Registry Learning Readiness Markdown Check Index Smoke (unreleased)

Public registry smoke now protects the readiness check index sections in learning readiness Markdown reports after publish.

Changed

• Added public registry smoke coverage for learn --signals --report --out Markdown reports.
• Added public registry smoke coverage for focused learn --agent-backlog --report --out Markdown reports.
• Added registry smoke self-test drift fixtures for missing readiness Markdown check index lines.
• Updated release-facing docs and release metadata phrase guards for public registry learning readiness Markdown report coverage.

Impact

• Published-package npm exec --package @design-ai/cli@<version> paths now verify the same human review readiness contract as packed tarball smoke.
• Release-facing registry smoke guidance cannot silently drop the learning readiness Markdown check index coverage phrase.

Verified

• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run registry:smoke:self-test
• npm run release:self-test
• npm run audit:strict
• git diff --check

What's still ahead

• Run post-publish npm run registry:smoke after a real publish, because that command requires the public package to exist in npm.

Phase 491 — Learning Readiness Markdown Check Index Package Smoke (unreleased)

Packed-tarball smoke now protects the readiness check index sections in learning readiness Markdown reports.

Changed

• Added package smoke assertions for the Readiness check index section in learn --signals --report Markdown output.
• Added package smoke assertions for the same section in focused learn --agent-backlog --report Markdown output, including no-command optional-gap reports.
• Added package smoke self-test drift fixtures for missing Markdown check index sections.
• Updated release-facing docs and release metadata phrase guards for Markdown check index section coverage.

Impact

• Installed-bin and one-shot package paths now verify that human review artifacts expose the same check index contract as JSON.
• Release-facing smoke guidance cannot silently drop the Markdown check index section coverage phrase.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Keep future Markdown readiness sections aligned with package and release metadata guards.

Phase 490 — Learning Readiness Check Index Markdown Reports (unreleased)

Learning readiness Markdown reports now expose the same id-based check index that JSON automation consumes.

Changed

• Added a shared readiness check index renderer for learning signal and focused agent backlog Markdown reports.
• Reports now list required ids, optional ids, status lookup, and required lookup next to the existing per-check summaries.
• Added unit coverage for learn --signals --report and learn --agent-backlog --report check index sections.

Impact

• Operators can compare human reports with machine-readable requiredCheckIds, optionalCheckIds, checkStatusById, and checkRequiredById without opening JSON.
• Local AI/agent handoffs keep the same readiness contract visible in both automation and review artifacts.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• npm test
• npm run audit:strict
• git diff --check

What's still ahead

• Package smoke coverage was added in Phase 491; keep future Markdown readiness sections aligned with package and release metadata guards.

Phase 489 — Learning Readiness Check Index Release Guard (unreleased)

Release metadata now protects the release-facing package smoke wording for the learning readiness check index added in Phase 488.

Changed

• Added release metadata phrase coverage for packed-tarball check index JSON field coverage.
• Updated README, Korean README, distribution docs, and release checklist wording so packaged learn --agent-backlog smoke guidance names the check index contract.
• Updated release metadata self-test drift fixtures so dropping the check index phrase fails the release guard.

Impact

• Release-facing docs cannot silently mention generic readiness summaries while omitting the machine-readable check index contract.
• Local AI/agent automation keeps one documented packaged output contract for id-based readiness status lookup.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Keep release metadata phrase groups aligned when new readiness indexes or machine-readable gate fields are added.

Phase 488 — Learning Readiness Check Index (unreleased)

Learning readiness JSON now exposes a deterministic check index for local automation.

Changed

• Added requiredCheckIds and optionalCheckIds to design-ai learn --signals and design-ai learn --agent-backlog readiness JSON.
• Added checkStatusById and checkRequiredById so automation can inspect a specific readiness check without scanning checks.
• Extended package smoke self-test coverage so focused agent backlog readiness output must preserve the check index.

Impact

• Local AI/agent runners can branch on check-capture, agent-development, or workspace readiness directly from machine-readable fields.
• Existing consumers of the checks array remain compatible because the array shape is unchanged.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Keep the check index stable as additional readiness checks are added.

Phase 487 — Optional Gap Details Package Smoke Guard (unreleased)

Packed-tarball smoke now protects the focused agent backlog optionalGapDetails readiness contract added in Phase 486.

Changed

• Added package smoke assertions for no-command design-ai learn --agent-backlog readiness optionalGapDetails.
• Verified missing check-capture optional gaps keep structured reason, next condition, and automation policy fields.
• Added release metadata phrase coverage so release-facing docs retain the optionalGapDetails package smoke contract.

Impact

• Installed-bin and one-shot package paths are guarded against dropping the machine-readable optional gap detail payload.
• Local AI/agent automation can rely on packaged no-command backlog output to distinguish advisory missing check captures from required blockers.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run package:smoke
• npm run audit:strict
• git diff --check

What's still ahead

• Keep this smoke guard aligned as additional machine-readable readiness detail fields are added.

Phase 486 — Learning Readiness Optional Gap Details (unreleased)

Learning signal readiness now explains advisory optional gaps with structured machine-readable detail and Markdown operator guidance.

Changed

• Added readiness.optionalGapDetails to design-ai learn --signals --json for optional gaps such as missing check-capture evidence.
• Kept the existing readiness.optionalGaps id list for compatibility while adding reason, next condition, and automation policy fields for each optional gap.
• Rendered the same optional gap detail section in learning signal and focused agent backlog Markdown reports.

Impact

• Local AI/agent automation can distinguish advisory missing evidence from required blockers without parsing prose.
• Operators can see that missing check captures require real reviewed warn/fail artifacts and should not trigger placeholder check --learn --yes mutation commands.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• node cli/bin/design-ai.mjs learn --signals --from-file . --json
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --report

What's still ahead

• Keep package smoke and release metadata guards aligned as additional optional readiness gaps are added.

Phase 485 — Agent Backlog Readiness Release Check Evidence (unreleased)

The agent backlog readiness metadata guard now has full release-gate evidence after the focused package smoke and release metadata guard phases.

Changed

• Recorded the full npm run release:check result after Phase 484 added release metadata phrase coverage for the focused agent backlog readiness contract.
• Confirmed the release gate covered CLI unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
• Confirmed packed-tarball smoke still exercises installed-bin and one-shot package execution paths, including check --learn, learning feedback, restore/diff/curate, agent backlog, and skill proposal flows.

Impact

• The current branch has fresh pre-push release evidence after the latest local AI/agent readiness guard work.
• Internal AI/agent development can continue from a verified package baseline rather than only targeted unit or metadata checks.

Verified

• npm run release:check

What's still ahead

• Choose the next product surface intentionally: deeper AI learning architecture, Website Console expansion, VS Code integration, Figma integration, or agent SDK work.

Phase 484 — Agent Backlog Readiness Release Metadata Guard (unreleased)

Release metadata now protects the release-facing docs wording for focused agent backlog readiness smoke coverage.

Changed

• Added release metadata phrase coverage for packed-tarball design-ai learn --agent-backlog readiness summaries.
• Required release policy docs to retain check-capture optional-gap semantics next to the focused backlog smoke guidance.
• Added a release metadata self-test drift fixture that fails when README drops the agent-backlog readiness smoke phrase.

Impact

• Release-facing docs cannot silently keep generic agent backlog smoke wording while dropping the readiness summary contract added in Phase 482 and package-smoke-verified in Phase 483.
• Internal AI/agent development handoffs keep one documented packaged output contract for required gates and optional evidence gaps.

Verification

• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata

Phase 483 — Agent Backlog Readiness Package Smoke Coverage (unreleased)

Packed-tarball smoke now protects the focused agent backlog readiness pass-through added in Phase 482.

Changed

• Added package smoke JSON assertions for design-ai learn --agent-backlog readiness summaries.
• Verified normal backlog payloads keep check-capture as a passing optional check when real check captures exist.
• Verified no-command backlog payloads keep missing check captures as optional evidence gaps, not blocking actions.
• Added Markdown smoke assertions for the Signal Readiness section in agent backlog reports.
• Added package smoke self-test drift coverage for missing backlog readiness payloads.

Impact

• Installed-bin and one-shot package paths are now guarded against dropping the focused backlog readiness summary.
• Local AI/agent automation can rely on packaged learn --agent-backlog output to carry readiness metadata without a second learn --signals parse.

Verified

• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke

What's still ahead

• Keep the broader release checks in the next full release evidence pass after adjacent learning/agent changes settle.

Phase 482 — Agent Backlog Readiness Pass-Through (unreleased)

Focused design-ai learn --agent-backlog reports now include the same signal readiness summary exposed by learn --signals.

Changed

• Passed the signal registry readiness object through to agent backlog JSON output.
• Added a Signal Readiness section to agent backlog Markdown reports.
• Preserved the existing agent backlog action plan, safety queue, handoff, and strict status behavior.

Impact

• Local AI/agent automation can consume one focused backlog payload and still see required readiness gates, blocking check ids, optional evidence gaps, and per-check summaries.
• Operators reviewing learn --agent-backlog --report can distinguish required blockers from advisory check-capture gaps before running any follow-up command.
• The change remains read-only and does not mutate learning profiles, usage sidecars, eval files, skill files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --report

What's still ahead

• Run broader repo gates after finalizing the tracked changes, then re-check clean-tree focused backlog state.

Phase 481 — Learning Signal Readiness Summary (unreleased)

design-ai learn --signals now exposes a structured readiness summary that separates required local AI/agent gates from optional evidence gaps.

Changed

• Added a readiness object to learning signal registry JSON with required check counts, blocking check ids, optional gap ids, and per-check summaries.
• Classified learning profile, eval signals, workspace readiness, and agent development backlog as required readiness checks.
• Kept usage sidecar and check-capture evidence as optional checks so missing real check:* captures remain advisory instead of blocking pass-state development.
• Added the same readiness summary to design-ai learn --signals --report Markdown output.

Impact

• Local automation can determine whether agent learning evidence is gate-ready without re-deriving status from recommendations or nested payloads.
• Operators can see that missing check-capture entries are optional evidence gaps while real workspace or eval warnings remain required review items.
• The change stays local and read-only; it does not mutate learning.json, usage sidecars, skill files, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• node cli/bin/design-ai.mjs learn --signals --from-file . --json

What's still ahead

• Run broader repo gates after the tracked changes are finalized, then decide whether the next product surface should be Website Console expansion, VS Code integration, Figma integration, or deeper agent SDK work.

Phase 480 — Agent Backlog Full Release Gate Evidence Closeout (unreleased)

The optional refresh-only agent backlog closeout now has full npm run release:check evidence recorded after the post-commit release evidence and focused backlog clear-state checks.

Changed

• Recorded the full release gate result after the Phase 479 release evidence closeout.
• Confirmed the release gate covered CLI unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
• Confirmed packed-tarball smoke still exercises installed-bin and one-shot package execution paths after the optional refresh-only agent backlog no-command assertion landed.

Impact

• The current branch has a fresh pre-push release baseline before the next product or AI/agent feature phase starts.
• Local AI/agent development remains clear of required backlog actions, so the next step can be a deliberate scope choice instead of another backlog hardening pass.

Verified

• npm run release:check
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --strict --json

What's still ahead

• Choose the next product surface intentionally: push/Real-CI, deeper AI learning architecture, Website Console expansion, VS Code surface, Figma integration, or agent SDK.

Phase 479 — Agent Backlog Refresh-Only Release Evidence Closeout (unreleased)

The optional refresh-only agent backlog package smoke work now has post-commit release evidence recorded alongside the focused backlog clear-state check.

Changed

• Recorded release self-test and package contents verification after the packed-tarball no-command smoke assertion landed.
• Confirmed the focused agent backlog still reports actions: 0, empty execution queue, no handoff command, and optional refresh-only status metadata after the Phase 478 commit.
• Closed the Phase 478 follow-up item that asked for a post-commit focused backlog re-check.

Impact

• Release evidence now covers both the new package smoke assertion and the broader release self-test/package contents gates.
• Local AI/agent backlog automation remains clear after the guard changes, with no additional runtime work required.

Verified

• npm run release:self-test
• npm run package:check
• node cli/bin/design-ai.mjs learn --signals --from-file . --json
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --strict --json

What's still ahead

• Continue with the next local AI/agent development surface once a new non-empty backlog action or product requirement appears.

Phase 478 — Agent Backlog Refresh-Only Package Smoke Assertion (unreleased)

Packed-tarball smoke now verifies the optional refresh-only design-ai learn --agent-backlog --strict --json no-command contract in installed-bin and one-shot npm exec --package <tarball> paths.

Changed

• Added a no-command agent backlog JSON smoke assertion for empty focused backlogs.
• Verified operatorRunbook.nextCommandSelection.reason preserves the status-metadata wording for optional refresh-only runbook commands.
• Added package smoke self-test drift coverage for the old misleading refresh-stage selection reason.

Impact

• Release docs and package smoke are now aligned: the packed tarball actually verifies the no-command refresh-only runbook semantics.
• Local AI/agent automation gets stronger packaged-path protection for the completed backlog state.

Verified

• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke

What's still ahead

• Closed by Phase 479 post-commit release evidence and focused backlog re-check.

Phase 477 — Agent Backlog Refresh-Only Runbook Release Guard (unreleased)

Release metadata now protects the optional refresh-only design-ai learn --agent-backlog runbook selection semantics in release-facing policy docs.

Changed

• Added a release metadata phrase guard for optional refresh-only runbook selection reasons.
• Updated README, Korean README, Distribution docs, and Release checklist guidance to state that no-command refresh output is status metadata, not an executable handoff command.
• Added self-test drift coverage for the new release-facing docs phrase.

Impact

• Future release doc edits cannot silently drop the no-command refresh-only runbook semantics.
• Packed-tarball smoke guidance remains aligned with the JSON contract stabilized in Phase 476.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/release-metadata.py
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Re-check focused agent backlog status after this release metadata guard is committed.

Phase 476 — Agent Backlog Optional Refresh Runbook Selection Reason (unreleased)

design-ai learn --agent-backlog now explains optional refresh-only operator runbook selection without implying that a backlog handoff command was selected.

Changed

• Updated operatorRunbook.nextCommandSelection.reason when the only runbook command is an optional refresh check.
• Preserved operatorRunbook.nextCommand, nextStage: "refresh", and nextCommandRequired: false for automation that wants a status refresh command.
• Extended no-command regression coverage for JSON and Markdown runbook selection output.

Impact

• Local AI/agent automation can keep reading the optional refresh command while treating the focused backlog as complete.
• The runbook selection, next-command alignment, and handoff reason now use the same no-command semantics.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Re-check the clean-tree focused backlog state after this runbook selection reason contract is committed.

Phase 475 — Agent Backlog Optional Refresh Handoff Reason (unreleased)

design-ai learn --agent-backlog now explains no-command operator handoff states without implying that optional refresh metadata is an executable handoff command.

Changed

• Updated operatorHandoff.reason for no-command states with an available optional refresh command.
• Kept operatorHandoff.command empty and operatorHandoff.refreshCommandRequired: false, preserving the completed backlog contract.
• Extended no-command regression coverage for JSON and Markdown handoff reason output.

Impact

• Local AI/agent automation can distinguish "no handoff command is required" from "refresh metadata is available."
• Optional refresh remains useful for re-checking status without becoming required work.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Re-check the clean-tree focused backlog state after this handoff reason contract is committed.

Phase 474 — Agent Backlog Optional Refresh Alignment Reason (unreleased)

design-ai learn --agent-backlog now explains optional refresh-only no-command states consistently in nextCommandAlignment.reason.

Changed

• Added an explicit alignment reason for cases where the operator runbook exposes only an optional refresh command while the safety-ordered execution queue is empty.
• Preserved the existing queue and runbook command fields so automation can keep reading the optional refresh command without treating it as runnable backlog work.
• Extended the no-command regression test to verify both JSON and Markdown alignment wording.

Impact

• Local AI/agent automation no longer receives a contradictory "no operator runbook command" reason when operatorRunbook.nextCommand contains the optional refresh command.
• Completed no-command backlog states remain non-mutating and do not require refresh before being treated as complete.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Re-check the clean-tree focused backlog state after this alignment reason contract is committed.

Phase 473 — Agent Backlog Optional Refresh Runbook Alignment (unreleased)

design-ai learn --agent-backlog now keeps no-command completion semantics aligned across the operator handoff, command-effect review, and operator runbook sections.

Changed

• Marked refresh-only gate commands as optional when the focused backlog has no command-bearing actions.
• Kept the refresh command visible as follow-up metadata while avoiding required runbook counts in completed no-command states.
• Extended the no-command regression test to verify commandEffectReview.gatePhaseSummary, refresh runbook required, operatorRunbook.requiredCommandCount, and Markdown summary output.

Impact

• Local automation can treat no-command backlog states as complete without receiving a contradictory required refresh from the operator runbook.
• Command-bearing backlog states still require refresh after execution, preserving the existing review and verification flow.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Re-check the clean-tree focused backlog state after this runbook alignment lands.

Phase 472 — Agent Backlog No-Command Handoff Completion (unreleased)

design-ai learn --agent-backlog now treats a pass-state backlog with no runnable actions as an explicit completed handoff state instead of a refresh-required non-ready state.

Changed

• Added hasCommand and complete to actionPlan.executionQueue.operatorHandoff.state.
• Marked no-command handoff states as ready: true, hasCommand: false, complete: true, and requiresRefresh: false.
• Kept the refresh command available as optional follow-up metadata while avoiding a required refresh flag when there is no handoff command to run.
• Added Markdown output for the operator handoff summary so human reports explain that the focused backlog is clear.
• Extended package smoke JSON contract checks to require the new handoff state fields.

Impact

• Local AI/agent automation can distinguish "no work remains" from "not ready yet" without parsing prose.
• Existing command-bearing handoff states still require refresh after execution and retain their review/gate behavior.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Rerun focused backlog on a clean tracked tree after this contract change lands.

Phase 471 — Agent Backlog Test Expectation Stabilization (unreleased)

design-ai learn --agent-backlog test coverage now derives expected action counts from the actual generated payload when workspace readiness is environment-dependent.

Changed

• Updated the agent backlog JSON/human/Markdown regression test to validate workspace readiness targets only when that action is present.
• Derived safety summary, execution queue, command effect, report, and human-output counts from the JSON payload instead of hard-coding environment-sensitive totals.
• Updated the missing-profile ranking test to assert that profile initialization remains first and eval checkpoint generation follows it, while allowing workspace readiness to appear between them when the temp workspace emits readiness warnings.

Impact

• npm test no longer fails when local temp workspace readiness differs between focused and full test runs.
• The tests still verify the core contract: profile initialization ranks first, eval checkpoint generation remains present, workspace readiness target metadata is correct when emitted, and --with-learning remains mutation-reviewed.

Verified

• node --test cli/lib/learn.test.mjs
• npm test
• npm run release:check

What's still ahead

• Continue the next AI/agent development phase after this release gate stabilization is committed.

Phase 470 — Advisory Check-Capture Seed Backlog Cleanup (unreleased)

design-ai learn --agent-backlog no longer emits a placeholder design-ai check artifact.md --learn --yes command when no check-capture learning entries exist.

Changed

• Kept the no-check-capture guidance as an info-level signal registry recommendation.
• Removed the synthetic agent-check-capture-seed action from focused backlog output when checkCapture.count is zero.
• Preserved agent-skill-proposal-preview when real check:* learning entries exist, so repeated warn/fail captures still become preview-only skill proposal handoffs.
• Added regression coverage proving that a clean registry with passing usage/eval/workspace gates has zero backlog actions even when no check captures exist.

Impact

• A pass-state focused backlog no longer exposes a mutation-capable placeholder command as the next action.
• Operators still see that check --learn --yes is useful only when there are real warning/failure artifacts to capture.
• Local learning profile mutation remains explicit and tied to actual check results.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs

What's still ahead

• Continue strengthening real check-capture proposal review once repeated production warn/fail captures exist.

Phase 469 — Agent Eval Replay Report Alignment (unreleased)

design-ai learn --agent-backlog now turns template-only learning eval checkpoints into concrete report-generation handoffs and treats sibling executed reports as the evidence that clears the template replay warning.

Changed

• Added sibling learning-eval-report.json discovery beside the selected learning profile's learning-eval.json checkpoint.
• Changed agent-eval-template-replay from a generic learn --signals refresh command to a concrete learn --eval --from-file <checkpoint> --file <profile> --strict --json --out <report> handoff.
• Added report/template pairing so a template file no longer emits a replay warning when a same-directory same-kind executed eval report exists.
• Kept rawTemplates in signal JSON for observability while using unresolved templates for readiness and backlog decisions.
• Added regression coverage for template-only replay command metadata and report-backed template suppression.

Impact

• Local AI/agent automation can clear eval-template setup debt by running one explicit file-write command.
• Focused backlog output no longer loops on agent-eval-template-replay after an executed learning-eval-report.json exists.
• The registry remains read-only; only the emitted follow-up command writes the report file.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs

What's still ahead

• Continue using real check --learn --yes captures only when actual warn/fail artifacts are available, then promote repeated signals through skill proposal review.

Phase 468 — Workspace Local Artifact Readiness Split (unreleased)

design-ai workspace now separates active git changes from known local portfolio/evidence artifacts so internal dogfood readiness is not blocked by intentionally local output files from a separate thread.

Changed

• Added git status splitting for untracked portfolio/evidence artifacts while preserving the full raw status in allStatusShort.
• Added ignoredStatusShort, ignoredLocalArtifactCount, and hasIgnoredLocalArtifacts to workspace JSON so automation can show ignored local artifacts without treating them as active changes.
• Kept tracked modifications and unknown untracked files in active statusShort so strict readiness still blocks on real development changes.
• Updated human workspace output and next actions to report ignored local artifacts as an info item instead of a dirty-workspace warning.
• Extended workspace unit coverage and smoke JSON assertions for the expanded git contract.

Impact

• Local portfolio/evidence files can remain in the working tree while design-ai development continues.
• workspace --strict remains conservative for tracked edits, unknown files, upstream drift, learning warnings, and release-script failures.

Verified

• node --check cli/lib/workspace.mjs
• node --check cli/commands/workspace.mjs
• node --test cli/lib/workspace.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test

What's still ahead

• Continue clearing the focused agent backlog by generating the local learning eval checkpoint and recording privacy-preserving usage sidecar events after the current code changes are committed.

Phase 467 — Agent Backlog Workspace Usage Target Classification (unreleased)

design-ai learn --agent-backlog now classifies workspace readiness --learning-usage arguments as usage sidecar targets, matching the command's actual learning usage input contract.

Changed

• Added --learning-usage to agent backlog usage target extraction.
• Added regression coverage that verifies agent-workspace-readiness-review exposes --learning-file as a profile target and --learning-usage as a usage sidecar target.
• Updated aggregate command effect assertions so workspace, skill proposal, and --with-learning usage-record sidecar targets are all visible in the execution queue summary.

Impact

• Local operators and automation can see the usage sidecar path for workspace readiness commands without parsing shell strings.
• The command remains read-only; this only fixes target metadata classification.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs

What's still ahead

• Continue aligning every agent backlog follow-up command with explicit target metadata before automating local learning/eval handoffs.

Phase 466 — Agent Backlog With-Learning Usage Mutation Classification (unreleased)

design-ai learn --agent-backlog now treats follow-up commands that run prompt or pack with --with-learning as local-state mutations because they record privacy-preserving usage sidecar events.

Changed

• Classified --with-learning backlog commands as mutates-local-state with review-before-mutation run policy.
• Added env target extraction for DESIGN_AI_LEARNING_FILE and DESIGN_AI_LEARNING_USAGE_FILE so profile and usage sidecar targets appear in commandSafety, commandEffects, and aggregate effect summaries.
• Changed the generated agent-learning-usage-record command to set both learning env vars before running design-ai prompt 'audit a design artifact' --with-learning --json.
• Added regression coverage for the usage-record command string, structured commandArgs, env target metadata, mutation flags, and human/Markdown output.

Impact

• Local automation no longer mistakes usage sidecar recording for a preview-only command.
• Operators can review the exact learning profile and usage sidecar path before running the usage-record handoff.
• The focused backlog report itself remains read-only; only the emitted follow-up command is classified as mutation-capable.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs

What's still ahead

• Continue dogfooding the usage/eval/check-capture loop until the focused backlog can clear without manual target-path interpretation.

Phase 465 — Agent Backlog Learning Eval Sibling Checkpoint Alignment (unreleased)

design-ai learn --agent-backlog now aligns its learning eval checkpoint bootstrap with design-ai workspace: generated learning eval checkpoints target the active learning profile's sibling learning-eval.json path instead of a repo-relative output file.

Changed

• Changed agent-eval-checkpoint-generate follow-up commands to use defaultLearningEvalPath(<learning-profile>) for --out.
• Added evalOutputFile evidence so JSON consumers can show the exact checkpoint target without parsing the shell command.
• Updated signal registry eval discovery to include the active learning profile's sibling learning-eval.json even when the --from-file signal source points at a separate repository or report directory.
• Added regression coverage for sibling learning eval auto-detection and for missing-profile backlog actions emitting the sibling checkpoint output path.

Impact

• Local AI/agent automation no longer needs to choose between the workspace-recommended checkpoint path and the backlog-recommended checkpoint path.
• The agent backlog report remains read-only; only the emitted follow-up command target changed.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs

What's still ahead

• Continue tightening usage-sidecar and eval-checkpoint handoffs so the local learning loop can be dogfooded without writing incidental files into target repositories.

Phase 464 — Agent Backlog Profile Init Apply Command Metadata (unreleased)

design-ai learn --agent-backlog now separates first-run learning profile initialization into an explicit preview command and reviewed apply metadata. The handoff can safely present learn --init --dry-run, while automation can still find the confirmed learn --init --yes command and its mutation-review safety details without guessing.

Changed

• Changed the missing-profile backlog action command to design-ai learn --init --dry-run --file <profile> so preview semantics are explicit.
• Added optional applyCommand, applyCommandArgs, applyCommandSafety, and applyRequiresReviewBeforeMutation metadata to action-plan steps and execution queue manifest entries.
• Rendered apply commands in Markdown reports under "Apply command after review" with the apply safety level and mutation-review requirement.
• Extended package-smoke assertions so packed consumers validate optional apply-command metadata when it appears.

Impact

• Local AI/agent automation can distinguish a safe preview handoff from the confirmed profile-write command needed to clear the missing-profile backlog item.
• The report remains read-only: it does not initialize learning.json, edit skills, write eval checkpoints, mutate target repositories, or call external AI APIs.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --strict --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:check
• npm run release:self-test
• npm run package:smoke

What's still ahead

• Continue tightening first-run local learning bootstrap flows so preview, apply, and refresh steps stay explicit for automation and human operators.

Phase 463 — Agent Backlog Current-Command Gate Scoping (unreleased)

design-ai learn --agent-backlog now scopes operator handoff gates to the current next queue command. A read-only preview command can be reported as ready even when later queued commands still require file-write or mutation review.

Changed

• Updated operatorHandoff selection so before-stage operator gates only block the handoff when the current nextQueueCommand itself requires review.
• Added nextQueueCommandRequiresGate and operatorGateAppliesToNextQueueAction booleans to the handoff payload for automation that needs to explain why a gate did or did not apply.
• Extended package-smoke assertions so packed consumers accept both operator-runbook and execution-queue handoff sources and verify the new gate-scope booleans.

Impact

• Local automation can present safe read-only next commands without forcing a clean-workspace gate that only protects later file-write or mutation commands.
• Later risky commands still retain commandEffectReview, run-policy, and clean-workspace review metadata in the same execution queue.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --strict --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:check
• npm run release:self-test
• npm run package:smoke

What's still ahead

• Continue tightening the local AI/agent readiness loop so gates are precise per handoff step while aggregate risk remains visible.

Phase 462 — Agent Backlog Profile Bootstrap Ranking (unreleased)

design-ai learn --signals now ranks missing learning profile initialization ahead of eval checkpoint bootstrap when both actions are p1. This keeps the ranked next action, safety-ordered execution queue, and operator handoff story aligned during first-run local AI/agent setup.

Changed

• Added deterministic action-id tie-breaking to the agent development backlog sorter so profile audit/init work wins before workspace, eval, usage, and skill-evolution follow-ups at the same priority.
• Added a no-profile runLearn --signals regression test that verifies agent-learning-profile-init is rank 1 before agent-eval-checkpoint-generate.

Impact

• First-run operators see the same bootstrap sequence in ranked actions and safe queue guidance: initialize/review the local learning profile before generating eval checkpoint files.
• The change remains deterministic and local; it only changes action ordering and does not mutate learning profiles, usage sidecars, eval files, skill files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• node --test cli/lib/learn.test.mjs
• node cli/bin/design-ai.mjs learn --signals --file <tmp>/missing-learning.json --usage-file <tmp>/missing-learning.usage.json --from-file <tmp> --json

What's still ahead

• Continue closing the local AI/agent learning readiness loop with non-mutating bootstrap guidance before any profile or eval-file apply step.

Phase 461 — Agent Backlog Operator Handoff State Metadata (unreleased)

design-ai learn --agent-backlog operator handoff now includes compact state metadata for automation. This lets local runners decide whether a handoff command is ready, blocked by a required gate, requires operator review, or has no command without parsing Markdown or reason prose.

Changed

• Added actionPlan.executionQueue.operatorHandoff.state with status, ready, canRunWithoutReview, requiresGate, requiresRefresh, and summary.
• Rendered the handoff state in Markdown reports next to the existing operator handoff and refresh command lines.
• Strengthened unit tests and package-smoke assertions so packed and one-shot CLI consumers can rely on the new state contract.

Impact

• Local AI/agent automation can branch on a compact status enum before running or presenting the next handoff command.
• The change remains deterministic and local; it only changes emitted metadata and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --file /tmp/design-ai-phase461-learning.json --usage-file /tmp/design-ai-phase461-learning.usage.json --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 460 — Agent Backlog Context-Aware Refresh Command (unreleased)

design-ai learn --agent-backlog refresh metadata now preserves the same signal source, learning profile, and usage sidecar paths that produced the current backlog report. This keeps post-handoff refreshes deterministic even when operators run from another working directory or use non-default learning files.

Changed

• Built the refresh command from the active backlog context: --from-file, --file, --usage-file, --strict, and --json.
• Reused that context-aware refresh command in operatorHandoff, operatorRunbook, commandEffectReview, and action-plan verification metadata.
• Strengthened unit tests and package-smoke assertions to validate refresh command semantics through commandArgs instead of relying on a context-free shell string.

Impact

• Local AI/agent automation can run the selected handoff command and then refresh the exact same backlog scope without reconstructing source/profile/usage paths.
• The change remains deterministic and local; it only changes emitted metadata and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --file /tmp/design-ai-phase460-learning.json --usage-file /tmp/design-ai-phase460-learning.usage.json --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 459 — Agent Backlog Operator Handoff Refresh Metadata (unreleased)

design-ai learn --agent-backlog operator handoff now exposes the refresh command that should be run after the selected handoff command. This lets local automation re-check focused backlog state without traversing the full operator runbook stage list.

Changed

• Added refreshCommand, refreshCommandArgs, refreshCommandLabel, and refreshCommandRequired to actionPlan.executionQueue.operatorHandoff.
• Clarified Markdown reports with an operator handoff refresh line so humans can see the follow-up status check.
• Strengthened unit tests and package-smoke assertions so packed and one-shot CLI consumers can rely on the refresh metadata contract.

Impact

• Local AI/agent automation can execute or present the selected handoff command, then immediately know which deterministic read-only command refreshes the focused backlog state.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 458 — Agent Backlog Operator Handoff Decision Enum (unreleased)

design-ai learn --agent-backlog operator handoff now exposes an explicit decision enum. This lets local automation branch on the next safe action without parsing reason prose or recomputing handoff state from gate and queue fields.

Changed

• Added actionPlan.executionQueue.operatorHandoff.decision with deterministic values: run-operator-gate, run-shared-command, run-operator-command, run-queue-command, and none.
• Clarified Markdown reports by including the handoff decision next to the operator handoff reason.
• Strengthened unit tests and package-smoke assertions so packed and one-shot CLI consumers can rely on the decision enum.

Impact

• Local AI/agent automation can branch directly on one enum before deciding whether to present a gate command, shared command, operator-only command, or queue fallback command.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 457 — Agent Backlog Operator Handoff Decision Metadata (unreleased)

design-ai learn --agent-backlog execution queue now includes a single operator handoff decision. This lets local automation consume the next command to present or run without rebuilding that decision from the safety queue, operator runbook, and alignment metadata.

Changed

• Added actionPlan.executionQueue.operatorHandoff with source, phase, label, command metadata, action metadata, gate state, queue fallback metadata, review state, and a human-readable reason.
• Clarified Markdown reports with an operator handoff line so humans can see the active next-command decision directly.
• Strengthened unit tests and package-smoke assertions so packed and one-shot CLI consumers can rely on the handoff contract.

Impact

• Local AI/agent automation can read one deterministic handoff object before deciding whether to run a before-stage gate or the queue command.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 456 — Agent Backlog Next Command Alignment Metadata (unreleased)

design-ai learn --agent-backlog execution queue now compares the operator runbook's first command with the safety-ordered queue command. This makes it explicit when both surfaces point to the same command and when the operator must run a before-stage gate first.

Changed

• Added actionPlan.executionQueue.nextCommandAlignment with operator command metadata, queue command metadata, ranked next-action metadata, match booleans, and a human-readable reason.
• Clarified Markdown reports with an operator/queue next-command alignment line so humans can see whether the two handoff surfaces agree or intentionally differ.
• Strengthened unit tests and package-smoke assertions so packed and one-shot CLI consumers can rely on the alignment contract.

Impact

• Local AI/agent automation can avoid comparing command strings manually before deciding whether to run the queue command or a required operator gate.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 455 — Agent Backlog Operator Runbook Selection Metadata (unreleased)

design-ai learn --agent-backlog operator runbook now explains how its next operator command was selected. This makes the runbook-level nextCommand stage order explicit, separate from the execution queue's safety-ordered recommended command.

Changed

• Added actionPlan.executionQueue.operatorRunbook.nextCommandSelection with the stage-order strategy, selected stage, label, command metadata, action metadata when available, and a human-readable reason.
• Clarified Markdown reports with an operator next-command selection line so humans can see why a before, execute, after, or refresh command is first.
• Strengthened unit tests and package-smoke assertions so packed and one-shot CLI consumers can rely on the operator runbook selection contract.

Impact

• Local AI/agent automation can distinguish the operator runbook's first executable command from the queue-level recommended backlog command and the ranked action-plan next step.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 454 — Agent Backlog Next Command Selection Metadata (unreleased)

design-ai learn --agent-backlog execution queue now explains how the recommended queue command was selected. This makes the difference between the ranked action-plan next step and the safety-ordered execution queue explicit for local automation.

Changed

• Added actionPlan.executionQueue.nextCommandSelection with the selection strategy, safety order, selected action metadata, ranked plan-next metadata, and a human-readable reason.
• Clarified Markdown reports with a recommended next-command selection line and whether the selected command matches the ranked next action.
• Strengthened unit tests and package-smoke assertions so queue consumers can rely on the selection metadata.

Impact

• Local AI/agent automation can distinguish priority ranking from safe execution ordering before running or prompting an operator for the next command.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 453 — Agent Backlog Queue Next Command Args (unreleased)

design-ai learn --agent-backlog execution queue now exposes nextCommandArgs beside the existing nextCommand and nextCommandRunPolicy fields. This gives local automation a structured args array for the safest queued next action, not only for the operator runbook next command.

Changed

• Added actionPlan.executionQueue.nextCommandArgs, derived from the same queue item as nextCommand.
• Kept nextCommand, nextActionId, and nextCommandRunPolicy as the existing human-readable / policy fields.
• Strengthened unit tests and package-smoke self-test assertions so the queue-level next-command structured args cannot drift from the command manifest.

Impact

• Local AI/agent automation can start from either the high-level execution queue or the operator runbook without reparsing shell strings.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 452 — Agent Backlog Structured Command Args (unreleased)

design-ai learn --agent-backlog command handoff now includes structured args arrays alongside shell-rendered command strings. This lets local automation read commandArgs / nextCommandArgs directly from reviewed backlog output instead of reparsing quoted shell text.

Changed

• Added commandArgs to generated agent backlog actions, action-plan steps, execution queue items, command manifest entries, verification commands, gate commands, and operator runbook commands.
• Added operatorRunbook.nextCommandArgs so scripts can start from the same first reviewed command that humans see in nextCommand.
• Kept existing command strings unchanged as the human-readable and copy/paste surface.
• Strengthened unit tests and package-smoke self-test assertions around structured operator command args.

Impact

• Local AI/agent operator tooling can consume reviewed commands more safely without shell-string parsing.
• The feature remains deterministic and local; it emits metadata only and does not execute commands, call external AI APIs, or mutate learning profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 451 — Agent Backlog Operator Next Command Metadata (unreleased)

design-ai learn --agent-backlog operator runbook now exposes the first command an operator should run across before, execute, after, and refresh stages. This keeps mutation-review flows from skipping the clean-workspace gate when the queue-level next action points at the first backlog command.

Changed

• Added operatorRunbook.nextStage, nextCommand, nextCommandLabel, nextCommandRequired, and nextCommandRunPolicy.
• Surfaced the operator next command in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke assertions so operator next-command drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is safer because local scripts and operators can distinguish the first reviewed runbook command from the first backlog action command.
• This remains deterministic and local; it only emits metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file .
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 450 — Agent Backlog Operator Runbook (unreleased)

design-ai learn --agent-backlog execution queue now includes a deterministic operator runbook. Local operators and scripts can read before, execute, after, and refresh stages directly instead of combining gate buckets with the command manifest by hand.

Changed

• Added executionQueue.operatorRunbook with ordered before, execute, after, and refresh stages.
• Included command counts, required counts, review level, operator-review flag, and per-stage commands in the runbook payload.
• Surfaced operator runbook counts in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke assertions so operator runbook drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to execute because the reviewed gate commands and backlog commands are exposed as one ordered runbook.
• This remains deterministic and local; it only emits metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file .
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 449 — Agent Backlog Gate Runbook Buckets (unreleased)

design-ai learn --agent-backlog command effect review output now includes deterministic gate runbook buckets. Local runbook tooling can read before, after, refresh, and other gate command groups directly instead of filtering the flat gateCommands array.

Changed

• Added commandEffectReview.gateRunbook with before, after, refresh, and other command buckets.
• Surfaced gate runbook bucket counts in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke assertions so gate runbook drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to execute from scripts and operator checklists because each gate phase now has a direct command bucket.
• This remains deterministic and local; it only emits metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file .
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 448 — Agent Backlog Gate Phase Summary (unreleased)

design-ai learn --agent-backlog command effect review output now includes deterministic gate phase summary metadata. Local runbook tooling can read gate counts, required counts, optional counts, and before/after/refresh coverage directly instead of parsing gate command labels.

Changed

• Added commandEffectReview.gatePhaseSummary with count, requiredCount, optionalCount, phases, hasBefore, hasAfter, and hasRefresh.
• Surfaced gate phase summary in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke assertions so gate phase summary drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to consume from scripts and operator checklists because gate coverage is explicit structured metadata.
• This remains deterministic and local; it only emits metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file . --json
• node cli/bin/design-ai.mjs learn --agent-backlog --from-file .
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 447 — Agent Backlog Gate Command Timing Metadata (unreleased)

design-ai learn --agent-backlog gate commands now include deterministic timing metadata. Each command effect gate carries a phase and required flag so operators and local runbook tooling can distinguish before-execution checks, after-execution diff inspection, and backlog-refresh verification.

Changed

• Added phase and required metadata to commandEffectReview.gateCommands.
• Tagged clean-workspace checks as before, diff inspection as after, and backlog refresh as refresh.
• Surfaced the gate phase in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so timing metadata drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to convert into an operator runbook because each suggested gate now has explicit execution timing.
• This remains deterministic and local; it only emits metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 446 — Agent Backlog Command Effect Gate Commands (unreleased)

design-ai learn --agent-backlog command effect review guidance now includes deterministic gateCommands. Operators can see the clean-workspace, diff-inspection, and backlog-refresh commands that should frame command-bearing action execution.

Changed

• Added commandEffectReview.gateCommands metadata to focused agent backlog execution queues.
• Derived gate commands from command effect review level and target/mutation exposure.
• Surfaced command effect gate summaries in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so gate-command drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to execute safely because review guidance now includes concrete verification commands instead of checklist prose only.
• This remains deterministic and local; it only emits suggested gate commands and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 445 — Agent Backlog Command Effect Review (unreleased)

design-ai learn --agent-backlog execution queues now include deterministic commandEffectReview guidance. Operators can read a queue-level review headline and checklist derived from command target exposure before running command-bearing actions.

Changed

• Added commandEffectReview metadata to focused agent backlog execution queues.
• Derived review level, operator-review requirement, headline, and checklist from commandEffectSummary.
• Surfaced command effect review guidance in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so review guidance drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to operationalize because target/mutation exposure now becomes a concrete review instruction.
• This remains deterministic and local; it only interprets already-emitted command metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 444 — Agent Backlog Command Effect Summary (unreleased)

design-ai learn --agent-backlog execution queues now include a queue-level commandEffectSummary. Operators and local automation can scan aggregate output targets, learning profile targets, usage sidecar targets, and mutation flags before opening every command manifest entry.

Changed

• Added deterministic commandEffectSummary metadata to focused agent backlog execution queues.
• Aggregated unique output/profile/usage targets and mutation flags from command manifest commandEffects.
• Surfaced command effect target counts in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so queue-level command effect summary drift is caught.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to review at queue level before inspecting each command-bearing action.
• This remains deterministic and local; it only summarizes already-emitted command metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 443 — Agent Backlog Command Effects Manifest (unreleased)

design-ai learn --agent-backlog command manifests now include explicit effect metadata for command-bearing actions. Operators and local automation can inspect output targets, learning profile targets, usage sidecar targets, mutation flags, and review reasons without parsing shell text.

Changed

• Added commandSafety.outputTargets, profileTargets, usageTargets, and mutationFlags to focused agent backlog action-plan steps.
• Added commandEffects to execution queue items and command manifest entries so target hints travel with runPolicy.
• Surfaced compact effect summaries in human learn --agent-backlog output and Markdown command manifest reports.
• Strengthened unit tests and package-smoke self-test assertions so command effect metadata drift is caught in JSON and Markdown paths.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is safer for operators and local automation because command effects are explicit alongside run policy.
• This remains deterministic and local; it only emits effect metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 442 — Agent Backlog Command Manifest (unreleased)

design-ai learn --agent-backlog execution queues now expose a command manifest with explicit run policies for command-bearing actions. Operators and local automation can distinguish preview-only, review-before-file-write, and review-before-mutation commands without reclassifying shell text from the grouped queue.

Changed

• Added actionPlan.executionQueue.commandManifest, commandManifestCount, and nextCommandRunPolicy.
• Added runPolicy to execution queue items so ordered, preview, file-write, and mutation buckets share the same execution policy vocabulary.
• Surfaced the recommended command policy and command manifest in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so command manifest drift is caught in JSON, human, and Markdown paths.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is safer for operators and local automation because command execution policy is explicit instead of inferred from command text.
• This remains deterministic and local; it only emits manifest metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 441 — Agent Backlog Ordered Execution Queue (unreleased)

design-ai learn --agent-backlog execution queues now preserve an explicit ordered command list in addition to grouped safety buckets. Operators and local automation can read the recommended next action and queue order directly from JSON, human output, or Markdown reports without reconstructing the sequence from preview/file-write/mutation groups.

Changed

• Added actionPlan.executionQueue.ordered, orderedCount, and nextActionId.
• Surfaced the recommended next action and queue order in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so ordered queue drift is caught in JSON, human, and Markdown paths.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to pass to operators or local automation while preserving the grouped safety review buckets.
• This remains deterministic and local; it only emits ordering metadata and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 440 — Agent Backlog Execution Queue (unreleased)

design-ai learn --agent-backlog action plans now expose an execution queue that groups safe preview commands before local file-write and local mutation review commands. Operators can see the recommended next command without re-sorting every backlog step manually.

Changed

• Added actionPlan.executionQueue with preview/read-only, file-write review, and mutation-review command groups.
• Added a nextCommand field derived from the safest available queue item.
• Surfaced the execution queue in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so execution queue drift is caught in JSON, human, and Markdown paths.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to execute in a controlled order after reviewing safety summary counts.
• This remains deterministic and local; it only reorganizes emitted action-plan commands and does not run commands, call external APIs, or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 439 — Agent Backlog Safety Summary (unreleased)

design-ai learn --agent-backlog action plans now include a safety summary across all follow-up steps. Operators can see the total count of read-only, local file-writing, and local state-mutating commands before inspecting each step.

Changed

• Added actionPlan.safetySummary with total, read-only, local file-write, local mutation, clean-workspace, and mutation-review counts.
• Surfaced the safety summary in human learn --agent-backlog output and Markdown reports.
• Strengthened unit tests and package-smoke self-test assertions so safety summary drift is caught in JSON, human, and Markdown paths.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent backlog handoff is easier to triage before running generated commands.
• This remains deterministic and local; it only summarizes emitted commands and does not call external APIs or mutate profiles, skill files, usage sidecars, eval files, or target repositories.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 438 — Agent Backlog Command Safety Classification (unreleased)

design-ai learn --agent-backlog action plans now classify each follow-up command before an operator runs it. Steps distinguish read-only preview/report commands from local output-file writes and apply/fix mutations, making the local AI/agent backlog safer to execute without adding external APIs or dependencies.

Changed

• Added commandSafety metadata to each actionPlan.steps[] item with level, local file-write state, local mutation state, detected flags, and a short safety reason.
• Updated action-plan verification guidance so read-only commands ask for preview review, while file-writing or mutating commands ask for a clean working tree or disposable workspace.
• Surfaced command safety in human and Markdown learn --agent-backlog output.
• Strengthened unit tests and package-smoke self-test assertions so action-plan safety metadata cannot silently disappear.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent development follow-up commands are easier to triage before execution.
• The agent backlog report remains deterministic, local, and non-mutating; the new metadata only describes the safety profile of emitted follow-up commands.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 437 — Agent Backlog Action Plan Export (unreleased)

design-ai learn --agent-backlog now turns the focused local AI/agent backlog into an execution-ready action plan. JSON and Markdown reports preserve ordered steps, verification commands, and mutation-review flags while keeping report generation deterministic, local, and read-only.

Changed

• Added an actionPlan object to focused agent backlog JSON output with ordered steps, the next step, verification commands, and read-only report boundaries.
• Added a Markdown “Action Plan” section to learn --agent-backlog --report output.
• Added a concise human output “Action plan” preview for the first execution steps.
• Strengthened unit tests and package-smoke self-test assertions for action plan JSON, human output, and Markdown report coverage.
• Updated usage docs, changelog, roadmap, and session history.

Impact

• Internal AI/agent development has a cleaner handoff from backlog diagnosis to controlled local execution.
• The report remains non-mutating and does not call external AI APIs; individual suggested commands still mark whether they require review before mutation.

Verified

• node --check cli/lib/signals.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke

What's still ahead

• Continue deeper AI/agent learning development or prepare the branch for push when ready.

Phase 436 — Agent Backlog Release Metadata Guard (unreleased)

Release metadata now protects the packed-tarball focused agent backlog smoke wording across release-facing policy docs. README, Korean README, Release Checklist, and Distribution guidance cannot silently drop the Markdown report, JSON --out, or strict gate coverage for design-ai learn --agent-backlog.

Changed

• Added release metadata phrase guards for design-ai learn --agent-backlog --report --out agent-backlog.md, agent backlog JSON --out file-write confirmations, and design-ai learn --agent-backlog --strict --json.
• Added release metadata self-test drift fixtures for agent backlog Markdown, JSON --out, and strict gate package smoke wording.
• Updated README, Korean README, and Distribution docs so packed-tarball smoke guidance explicitly preserves focused agent backlog artifacts and strict gates.
• Updated changelog, roadmap, and session history with the guard hardening.

Impact

• The Phase 435 focused agent backlog CLI surface now has release-facing documentation guards matching its package smoke coverage.
• This is release metadata and documentation hardening only: no CLI runtime behavior, package smoke runner behavior, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 435 — Focused Agent Backlog Reports (unreleased)

design-ai learn --agent-backlog now exposes the deterministic local AI/agent development backlog as its own read-only CLI surface. Operators can inspect the next-action queue without reading the full learn --signals registry, save a Markdown backlog artifact, or use --strict --json as a focused local gate.

Changed

• Added learn --agent-backlog parsing, help output, human output, JSON output, Markdown report rendering, --out support, and strict exit handling.
• Reused the existing learningSignalRegistry().agentDevelopment data so the new surface remains deterministic, local, dependency-free, and non-mutating.
• Added unit tests for parser behavior, focused report shaping/rendering, runtime JSON/human/Markdown output, output-file persistence, non-mutation, and strict warning exits.
• Added packed-tarball smoke and package-smoke self-test coverage for installed-bin and one-shot npm exec --package <tarball> paths.
• Updated usage docs, README, Korean README, Product Readiness, Release Checklist, changelog, roadmap, and session history.

Impact

• Internal AI/agent development can now archive or gate just the actionable backlog before deeper skill proposal review or release prep.
• This does not add external AI APIs, embeddings, fine-tuning, backend storage, target repo mutation, skill-file mutation, or new dependencies.

Verified

• node --check cli/commands/help.mjs cli/commands/learn.mjs cli/lib/learn.mjs cli/lib/signals.mjs
• node --test cli/lib/help-command.test.mjs cli/lib/learn.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run package:check
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke

What's still ahead

• Continue the next AI learning surface after reviewing whether release metadata phrase guards should cover focused agent backlog artifacts explicitly.

Phase 434 — Full Release Check Evidence After Learning Guard Hardening (unreleased)

The full npm run release:check gate now passes after the learning signal and skill proposal package smoke release metadata guard phases. This records that the latest local AI/agent learning artifact guards still work together through tests, audits, package checks, release metadata, release self-tests, and packed-tarball smoke.

Changed

• Ran the full release check after Phase 429-433 learning signal and skill proposal package smoke guard hardening.
• Recorded release evidence so the branch has a single current gate result before push or broader AI/agent feature work.
• Updated changelog, roadmap, and session history with the passing gate.

Impact

• Confirms the recent learn --signals and learn --propose-skills artifact guards do not weaken the release gate.
• This is release evidence documentation only: no CLI runtime behavior, package smoke runner behavior, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• npm run release:check
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 433 — Learning Signals JSON Out Release Guard (unreleased)

Release metadata now protects the packed-tarball learn signals JSON --out file-write confirmation smoke phrase across release-facing policy docs. This closes the remaining learning signal package artifact gap so README, Distribution, and Release Checklist guidance cannot silently drop JSON output-file persistence coverage.

Changed

• Added a release metadata phrase guard for learn signals JSON --out file-write confirmation package smoke wording.
• Added a release metadata --self-test drift fixture that fails when a policy doc drops the learning signal JSON output-file wording while retaining Markdown report and strict gate wording.
• Updated README, Korean README, Distribution docs, Release Checklist, changelog, roadmap, and session history with the guarded phrase.

Impact

• Release-facing docs now preserve every packaged learning signal artifact path: JSON --out, Markdown signal report, and strict signal readiness gating.
• This is release guard and documentation coverage only: no CLI runtime behavior, package smoke runner behavior, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 432 — Skill Proposal JSON Out Release Guard (unreleased)

Release metadata now protects the packed-tarball learn skill proposals JSON --out file-write confirmation smoke phrase across release-facing policy docs. This closes the remaining skill proposal package artifact gap so README, Distribution, and Release Checklist guidance cannot silently drop JSON output-file persistence coverage.

Changed

• Added a release metadata phrase guard for learn skill proposals JSON --out file-write confirmation package smoke wording.
• Added a release metadata --self-test drift fixture that fails when a policy doc drops the skill proposal JSON output-file wording while retaining other skill proposal smoke wording.
• Updated README, Korean README, changelog, roadmap, and session history with the guarded phrase.

Impact

• Release-facing docs now preserve every packaged skill proposal artifact path: JSON --out, Markdown report, read-only review-file decisions, JSON review template, unified diff patch, threshold skipping, and strict proposal readiness gating.
• This is release guard and documentation coverage only: no CLI runtime behavior, package smoke runner behavior, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 498 — Skill Proposal Apply-Plan Workflow (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan now converts accepted proposal decisions into a read-only manual apply plan. This bridges the gap between review acceptance and actual skill-file editing without introducing auto-mutation, external AI calls, embeddings, or dependency changes.

Changed

• Added --apply-plan parsing for learn --propose-skills, requiring --review-file and rejecting --patch, --review-template, and --review-check combinations.
• Added human, JSON, and Markdown apply-plan output with accepted proposal tasks, proposed instruction deltas, manual steps, verification commands, evidence, follow-up review-check commands, and explicit read-only privacy boundaries.
• Added unit, help, package-smoke, and release metadata guard coverage for design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json and --apply-plan --report --out skill-proposal-apply-plan.md.

Impact

• Accepted proposals are easier to apply manually and consistently, but design-ai still does not edit learning.json, review files, skill files, target repos, or external systems.
• The strict proposal gate still clears only after the operator marks reviewed decisions as applied or rejected.

Verification Plan

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue broader AI/agent learning development after the apply-plan workflow has package and release guard coverage.

Phase 497 — Skill Proposal Review-Check Markdown Package Smoke Coverage (unreleased)

Packed-tarball smoke now executes design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md through installed-bin and one-shot npm exec --package <tarball> paths. This closes the human-review artifact side of Phase 496 so the review-check readiness gate is protected in both JSON and Markdown report forms.

Changed

• Added package smoke execution for read-only skill proposal review-check Markdown reports with --out file-write confirmation.
• Added package smoke self-test drift coverage for the review-check Markdown report privacy and readiness sections.
• Added release metadata phrase guards and self-test drift fixtures for the release-facing review-check Markdown report smoke wording.
• Updated README, Korean README, Distribution docs, Release checklist, changelog, and session history with the new packaged report contract.

Impact

• The review-check Markdown report remains read-only: it does not mutate learning.json, review files, skill files, target repos, or external systems.
• Release-facing docs now protect both --review-check --json and --review-check --report --out paths for local AI/agent skill proposal reviews.

Verification Plan

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

Phase 496 — Skill Proposal Review-Check Gate (unreleased)

design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check now verifies that the current skill proposal set is covered by read-only review-file decisions. This gives local AI/agent skill evolution a deterministic post-review gate before any manual skill edit is considered complete.

Changed

• Added --review-check parsing for learn --propose-skills, requiring --review-file and rejecting --patch / --review-template combinations.
• Added human, JSON, and Markdown review-check outputs with pass/warn/fail checks for review-file configuration, existence, validity, current proposal clearance, and stale decisions.
• Added unit, help, package-smoke, and release metadata guard coverage for design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --json.

Impact

• Review-check is read-only: it does not mutate learning.json, review files, skill files, target repos, or external systems.
• --strict can now gate the review-check status itself, so stale or pending review files fail local readiness without conflating that check with broader signal readiness warnings.

Verification Plan

• node --check cli/lib/learn.mjs cli/lib/skill-proposals.mjs cli/commands/learn.mjs cli/commands/help.mjs
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• git diff --check

What's still ahead

• Continue from read-only readiness checks toward a reviewed manual apply workflow for accepted skill deltas.

Phase 431 — Skill Proposal Review-File Release Guard (unreleased)

Release metadata now protects the packed-tarball design-ai learn --propose-skills --review-file skill-proposals.review.json --json read-only review decision join smoke phrase across release-facing policy docs. This closes the Phase 427/428 follow-up so README, Distribution, and Release Checklist guidance cannot silently drop packaged review-file decision coverage.

Changed

• Added a release metadata phrase guard for the learn --propose-skills --review-file skill-proposals.review.json --json read-only review decision join package smoke phrase.
• Added a release metadata --self-test drift fixture that fails when a policy doc drops the review-file decision wording while retaining other skill proposal smoke wording.
• Updated changelog, roadmap, and session history with the guarded phrase.

Impact

• Release-facing docs now preserve the full skill proposal package smoke contract: Markdown report, read-only review-file decisions, JSON review template, unified diff patch, threshold skipping, and strict proposal readiness gating.
• This is release guard and documentation coverage only: no CLI runtime behavior, package smoke runner behavior, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 430 — Learning Signal Markdown Release Guard (unreleased)

Release metadata now protects the packed-tarball design-ai learn --signals --report --out learning-signals.md Markdown signal report smoke phrase across release-facing policy docs. This closes the Phase 429 follow-up so README, Distribution, and Release Checklist guidance cannot silently drop packaged Markdown signal report coverage.

Changed

• Added a release metadata phrase guard for the learn --signals --report --out learning-signals.md Markdown signal report package smoke phrase.
• Added a release metadata --self-test drift fixture that fails when a policy doc drops the Markdown signal report wording while retaining the strict signal gate wording.
• Updated README, Korean README, Korean Distribution docs, Release Checklist, changelog, roadmap, and session history with the guarded phrase.

Impact

• Release-facing docs now preserve both learning signal package smoke contracts: Markdown signal report persistence and strict signal readiness gating.
• This is release guard and documentation coverage only: no CLI runtime behavior, package smoke runner behavior, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 429 — Learning Signal Markdown Handoff Reports (unreleased)

design-ai learn --signals --report --out learning-signals.md now writes a durable Markdown handoff for the local AI/agent signal registry. This turns the existing read-only JSON/human signal surface into a shareable artifact covering learning audit state, usage sidecar counts, eval signal files, check captures, workspace readiness, deterministic agent development backlog actions, recommendations, and privacy boundaries.

Changed

• Added --report support for learn --signals and kept it mutually exclusive with JSON and other proposal-only output modes.
• Added a Markdown signal report renderer with sections for profile audit, usage signals, eval signals, check-capture entries, workspace readiness, agent development backlog, recommendations, and privacy boundaries.
• Wired report output through safe --out file writes without mutating learning profiles, usage sidecars, eval files, skill files, or target repositories.
• Updated command help, shared smoke assertions, package smoke, AI learning docs, Product Readiness, README, Distribution docs, Release checklist, changelog, roadmap, and session history.
• Added packed-tarball smoke execution for learn --signals --report --out learning-signals.md through installed-bin and one-shot npm exec --package <tarball> paths.

Impact

• Operators can archive or share the local AI/agent development backlog before running evals, applying skill proposal decisions, or preparing a push.
• The report is deterministic, local, and read-only: no learning.json mutation, usage sidecar mutation, eval file mutation, skill file mutation, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• node --check cli/lib/signals.mjs && node --check cli/lib/learn.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:check
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 428 — Skill Proposal Review Template Handoffs (unreleased)

design-ai learn --propose-skills --review-template --out skill-proposals.review.json now emits a JSON review-file scaffold for unresolved skill proposals. This closes the operator workflow gap after Phase 427: users no longer need to copy proposal ids by hand before recording manual applied, rejected, accepted, or deferred decisions.

Changed

• Added --review-template parsing for learn --propose-skills and rejected the option for unrelated learn actions.
• Added a JSON review template renderer with review policy metadata, source file paths, summary counts, and one decision scaffold per unresolved proposal.
• Defaulted generated decisions to deferred so the strict proposal gate stays pending until an operator deliberately changes a proposal to applied or rejected.
• Excluded proposals already cleared by applied or rejected review-file decisions from generated templates.
• Updated command help, shared smoke assertions, package smoke, AI learning docs, Product Readiness, README, Korean README, Distribution docs, Release checklist, changelog, roadmap, and session history.
• Added packed-tarball smoke execution for --review-template --out skill-proposals.review.json through installed-bin and one-shot npm exec --package <tarball> paths.

Impact

• Operators get a safe review ledger starting point for local AI/agent skill evolution decisions without mutating learning.json, skill files, or an existing review file.
• The feature remains deterministic, local, and non-mutating except for explicit --out artifact writes: no skill file mutation, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• node --check cli/lib/skill-proposals.mjs && node --check cli/lib/learn.mjs && node --check cli/commands/learn.mjs && node --check cli/commands/help.mjs
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:check
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 427 — Skill Proposal Review State (unreleased)

design-ai learn --propose-skills now accepts --review-file skill-proposals.review.json to join manual proposal decisions without mutating the learning profile, skill files, or the review file. This gives local AI/agent skill-evolution work a deterministic way to distinguish unresolved proposals from proposals that were manually applied or rejected.

Changed

• Added --review-file path parsing for learn --propose-skills and rejected the option for unrelated learn actions.
• Added read-only review file loading for decisions or reviews arrays with accepted, rejected, applied, and deferred statuses.
• Marked proposal payloads with reviewStatus, reviewDecision, reviewClearsStrict, review summary counts, stale decision counts, and pending review counts.
• Kept applied and rejected as strict-clearing statuses; accepted and deferred remain pending because follow-up work is still unresolved.
• Updated JSON, human, Markdown report, patch preview, command help, shared smoke assertions, AI learning docs, Product Readiness, README, Korean README, Distribution docs, Release checklist, changelog, roadmap, and session history.
• Added packed-tarball smoke execution for the read-only review decision join through installed-bin and one-shot npm exec --package <tarball> paths.

Impact

• Operators can keep a portable review ledger for skill proposals and clear the proposal-review gate only after manual apply or rejection decisions.
• Patch previews exclude proposals already marked applied or rejected, while unresolved proposals still appear in the diff handoff.
• The feature remains deterministic, local, read-only, and non-mutating: no learning.json mutation, skill file mutation, review file mutation, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• node --check cli/lib/skill-proposals.mjs && node --check cli/lib/learn.mjs && node --check cli/commands/learn.mjs
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run audit:strict
• npm run package:smoke
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 426 — Skill Proposal Patch Package Smoke Coverage (unreleased)

Packed-tarball smoke now executes design-ai learn --propose-skills --patch --out skill-proposals.patch through installed-bin and one-shot npm exec --package <tarball> paths. This turns the Phase 425 unified diff handoff into a package-level local AI/agent learning contract.

Changed

• Added package smoke execution for learn --propose-skills --patch --out skill-proposals.patch.
• Added package smoke assertions for patch headers, candidate skill diff paths, proposal metadata, verification commands, and preview-only non-mutation behavior.
• Added release metadata guard coverage so release-facing docs cannot drop the patch package smoke phrase.
• Updated README, Korean README, Distribution docs, Release checklist, changelog, roadmap, and session history.

Impact

• Packaged internal/company builds now verify the diff-style manual-review handoff, not only console, JSON, Markdown, threshold, and strict proposal paths.
• The smoke remains deterministic, local, preview-only, and non-mutating: no learning.json mutation, skill file mutation, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run package:smoke
• npm test
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 425 — Skill Proposal Patch Handoffs (unreleased)

design-ai learn --propose-skills --patch now emits preview-only unified diff handoffs for repeated check-capture skill proposals. This gives an operator a concrete manual-review artifact before editing skills/*/SKILL.md, while keeping the command non-mutating.

Changed

• Added --patch parsing for learn --propose-skills and rejected conflicting --json / --report output modes.
• Added a patch renderer that groups proposals by candidate skill file and appends local learning proposal notes in unified diff format.
• Wired patch output through stdout and safe --out file writes without changing learning profiles or skill files.
• Updated help output, smoke help assertions, AI learning docs, agent development notes, Product Readiness, README, Korean README, Distribution docs, changelog, roadmap, and session history.

Impact

• Operators can review or save a concrete diff-style handoff before manually applying accepted skill instruction changes.
• The command remains deterministic, local, preview-only, and non-mutating: no learning.json mutation, skill file mutation, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• node --check cli/lib/skill-proposals.mjs && node --check cli/lib/learn.mjs && node --check cli/commands/learn.mjs && node --check cli/commands/help.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke
• git diff --check

What's still ahead

• Closed by Phase 426.

Phase 423 — Skill Proposal Minimum Evidence Threshold (unreleased)

design-ai learn --propose-skills now accepts --min-evidence N so local AI/agent development reviews can tune how much repeated check-capture evidence is required before a candidate skill delta appears.

Changed

• Added --min-evidence N parsing and validation for learn --propose-skills.
• Passed the threshold into the preview-only skill proposal builder and exposed the effective threshold in JSON, human output, and Markdown reports.
• Updated help output, CLI help catalog, smoke assertion expectations, AI learning docs, usage docs, distribution docs, README, Korean README, changelog, roadmap, and session history.
• Added unit coverage for parser validation, threshold-driven skipped groups, help output, and report threshold visibility.

Impact

• Operators can keep the default threshold of 2, raise it for stricter internal skill review, or lower it for early dogfood review without editing learning.json or skill files.
• The command remains deterministic, local, preview-only, and non-mutating: no external AI API, embeddings, fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• node --check cli/commands/learn.mjs && node --check cli/lib/learn.mjs && node --check cli/lib/skill-proposals.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py
• Manual CLI smoke: design-ai learn --propose-skills --min-evidence 3 --json reports minEvidenceCount: 3, proposalCount: 0, and skippedCount: 1 for a two-entry repeated check-capture profile.

What's still ahead

• Closed by Phase 424.

Phase 424 — Skill Proposal Minimum Evidence Package Smoke Coverage (unreleased)

Packed-tarball smoke now executes design-ai learn --propose-skills --min-evidence 3 --json through installed-bin and one-shot npm exec --package <tarball> paths. This turns the Phase 423 threshold option into a package-level contract.

Changed

• Added package smoke execution for learn --propose-skills --min-evidence 3 --json.
• Added package smoke assertions for effective minEvidenceCount, threshold-driven skipped groups, preview-only boundaries, and read-only privacy metadata.
• Updated release-facing docs so packed-tarball smoke guidance names the min-evidence threshold path.
• Updated changelog, roadmap, and session history.

Impact

• Packaged internal/company builds now verify that a two-entry repeated check-capture group is skipped when the proposal threshold is raised to 3.
• The smoke remains deterministic, local, preview-only, and non-mutating: no learning.json mutation, skill file mutation, external AI API call, embeddings/fine-tuning, backend storage, target repo mutation, or dependency change.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run package:smoke

What's still ahead

• Continue broader AI/agent learning development or prepare the current branch for push when ready.

Phase 422 — Local Portfolio Artifact Release Gate Isolation (unreleased)

Release gates now tolerate local portfolio/evidence output artifacts without deleting or editing those artifacts. The link audit and package contents checks distinguish repository release assets from local portfolio exports so npm run release:check can run in the same working tree used for portfolio evidence collection.

Changed

• Skipped evidence/ and _portfolio_export/ in the internal link audit because those directories contain local output artifacts with links outside the package/docs release surface.
• Excluded local portfolio docs under docs/ from npm package contents so untracked portfolio pages do not introduce broken package links to non-packaged screenshots.
• Updated the package contents self-test helper so exact and directory-style files negation patterns are handled consistently.
• Updated changelog, roadmap, and session history.

Impact

• npm run release:check can pass in a workspace that also contains local portfolio/evidence exports.
• No portfolio files were deleted or modified.
• CLI runtime behavior, package command behavior, learning profiles, skill files, external AI/API boundaries, target repo boundaries, and dependency surface remain unchanged.

Verified

• python3 -m py_compile tools/audit/link-check.py tools/audit/package-contents.py
• python3 -B tools/audit/link-check.py
• npm run audit:strict
• python3 -B tools/audit/package-contents.py --self-test
• npm run package:check
• npm run release:check

What's still ahead

• Continue product/AI learning development or prepare the current branch for push when ready.

Phase 421 — Skill Proposal Markdown Release Metadata Guard (unreleased)

Release metadata now protects the packed-tarball design-ai learn --propose-skills --report --out skill-proposals.md Markdown review artifact smoke phrase across release-facing policy docs. This closes the Phase 420 follow-up so README, Distribution, and Release Checklist guidance cannot silently drop packaged Markdown report coverage.

Changed

• Added a table-driven release metadata phrase guard for the skill proposal Markdown report package smoke phrase.
• Added a release metadata self-test drift fixture that fails when a policy doc drops the Markdown --report --out review artifact wording while keeping the strict proposal gate wording.
• Updated changelog, roadmap, and session history.

Impact

• Release-facing docs now preserve both skill proposal package smoke contracts: Markdown review artifact persistence and strict expected-failure readiness.
• Existing CLI behavior, package smoke execution, learning profile storage, skill files, external AI/API boundaries, target repo boundaries, and dependency surface remain unchanged.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:self-test
• npm run release:metadata

What's still ahead

• Continue broader release hardening or move back to product/AI learning feature development.

Phase 420 — Skill Proposal Markdown Package Smoke Coverage (unreleased)

Packed-tarball smoke now executes design-ai learn --propose-skills --report --out skill-proposals.md through installed-bin and one-shot npm exec --package <tarball> paths. This closes the gap between the Phase 419 Markdown review artifact and packaged CLI verification.

Changed

• Added package smoke assertions for skill proposal Markdown report content, including profile/usage paths, candidate skill, verification command, privacy boundaries, and preview-only next steps.
• Added installed-bin and one-shot package smoke execution for learn --propose-skills --report --out.
• Added package smoke self-test drift coverage for the Markdown report privacy boundary.
• Updated changelog, roadmap, and session history.

Impact

• Packaged internal/company builds now verify the reviewer-friendly skill proposal Markdown artifact, not only human console, JSON, JSON --out, and strict JSON paths.
• The smoke remains local and non-mutating: no learning.json mutation, skill file mutation, external AI API call, embedding/fine-tuning, backend storage, target repo mutation, or new dependency.

Verified

• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run release:metadata
• git diff --check
• npm run package:smoke

What's still ahead

• Closed by Phase 421.

Phase 419 — Skill Proposal Markdown Review Reports (unreleased)

design-ai learn --propose-skills can now emit a Markdown review artifact with --report --out skill-proposals.md. This gives the local AI/agent learning loop a durable human-review handoff before any skill file is edited manually.

Changed

• Added a Markdown renderer for skill evolution proposal payloads, including proposal summary, evidence, verification commands, skipped groups, privacy boundaries, and next steps.
• Wired learn --propose-skills --report into the CLI while keeping JSON output and strict gating behavior intact.
• Updated help smoke assertions, usage docs, distribution docs, Product Readiness, changelog, roadmap, and session history.

Impact

• Operators can archive/review skill proposal evidence without mutating learning.json, editing skills/*/SKILL.md, calling external AI APIs, adding embeddings/fine-tuning, adding backend storage, touching target repos, or adding dependencies.
• The proposal gate remains preview-only: --strict can still fail pending review, but --report only writes the requested Markdown artifact.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• node --check cli/lib/skill-proposals.mjs && node --check cli/lib/learn.mjs && node --check cli/commands/learn.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Package smoke can be extended later to execute the Markdown --report --out path through packed tarballs if release evidence needs to cover that exact artifact mode.

Phase 418 — Skill Proposal Strict Guard Release Self-Test Evidence (unreleased)

The full npm run release:self-test chain now passes after the strict skill proposal package smoke metadata guard. This records that the release assertion fixtures, package smoke self-tests, registry smoke self-tests, release metadata self-tests, local CI self-tests, and token extractor self-tests all still agree after the Phase 417 guard.

Changed

• Ran the full release assertion self-test chain after adding the strict skill proposal package smoke metadata guard.
• Recorded the passing evidence in changelog, roadmap, and session history.

Impact

• Release evidence now confirms the new design-ai learn --propose-skills --strict --json smoke phrase guard does not weaken existing assertion fixtures.
• This is evidence/documentation only: no CLI runtime behavior, JSON contract, package smoke execution path, learning schema, skill files, external AI call, embedding/fine-tuning, backend storage, target repo mutation, or dependency changed.

Verified

• npm run release:self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Public registry smoke can add the same strict proposal path after publish if post-publish AI/agent readiness evidence becomes required.

Phase 417 — Skill Proposal Strict Package Smoke Metadata Guard (unreleased)

Release metadata now guards the packed-tarball design-ai learn --propose-skills --strict --json expected-failure smoke phrase in release-facing docs. This keeps the Phase 416 package evidence visible in README, Distribution, and Release checklist guidance.

Changed

• Added a release metadata phrase guard for packed strict skill proposal smoke coverage.
• Added release metadata self-test drift coverage that fails when README drops the strict skill proposal package smoke phrase.
• Tightened Release checklist wording so it names the exact design-ai learn --propose-skills --strict --json expected-failure gate.
• Updated changelog, roadmap, and session history.

Impact

• Release docs now preserve the installed-bin and one-shot package strict skill proposal readiness gate alongside package smoke coverage.
• This remains docs/metadata only: no runtime CLI behavior change, learning schema change, skill file mutation, external AI call, embedding/fine-tuning, backend storage, target repo mutation, or new dependency.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/release-metadata.py
• npm run release:metadata
• git diff --check

What's still ahead

• Public registry smoke can add the same strict proposal path after publish if post-publish AI/agent readiness evidence becomes required.

Phase 416 — Skill Proposal Strict Package Smoke Coverage (unreleased)

Packed-tarball smoke now executes design-ai learn --propose-skills --strict --json through installed-bin and one-shot npm exec --package <tarball> paths as an expected-failure gate when pending proposal review remains.

Changed

• Added strict skill proposal expected-failure smoke execution to package smoke's installed-bin and one-shot package paths.
• Tightened package smoke proposal assertions so JSON status and human status output remain visible.
• Added package smoke self-test drift coverage for proposal status and strict exit-code behavior.
• Updated changelog, roadmap, session history, and distribution guidance.

Impact

• Packaged internal/company builds now verify the strict skill proposal readiness gate, not only source-tree unit tests.
• This remains preview-only and local: no learning.json mutation, skill file mutation, external AI API call, embedding/fine-tuning, backend storage, target repo mutation, or new dependency.

Verified

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py
• npm run release:metadata
• git diff --check

What's still ahead

• Public registry smoke can add the same strict proposal path after publish if post-publish AI/agent readiness evidence becomes required.

Phase 415 — Skill Proposal Strict Readiness Gate (unreleased)

design-ai learn --propose-skills --strict now turns preview-only skill evolution proposals into a local readiness gate. Pending proposal review or upstream learning signal warnings exit non-zero, but the command still does not edit learning.json, does not edit skill files, and does not call external AI APIs.

Changed

• Added status to skill proposal JSON payloads, derived from upstream signal readiness and pending proposal count.
• Allowed --strict with learn --propose-skills and set exit code 1 when proposal status is not pass.
• Updated learn help, README command lists, usage docs, distribution docs, and help smoke assertions for the new strict proposal surface.
• Added unit coverage for parser support, JSON payload status, human status output, non-mutating strict exit behavior, and non-strict success behavior.

Impact

• Internal AI/agent development can now fail a local gate when repeated check-capture signals have generated skill deltas that still require manual review.
• This remains preview-only and local: no learning.json mutation, skill file mutation, external AI API call, embedding/fine-tuning, backend storage, target repo mutation, or new dependency.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py
• npm run release:metadata
• git diff --check

What's still ahead

• A future apply path for accepted skill deltas still requires explicit approval and a separate archive/review design.

Phase 414 — Learning Signals Strict Package Smoke Metadata Guard (unreleased)

Release metadata now guards the packed-tarball design-ai learn --signals --strict --json smoke phrase in release-facing docs. This keeps the Phase 413 package evidence visible in README, Distribution, and Release checklist guidance instead of allowing the strict local AI/agent readiness gate to drift out silently.

Changed

• Added a release metadata phrase guard for packed strict learning signal smoke coverage.
• Added release metadata self-test drift coverage that fails when README drops the strict signal package smoke phrase.
• Tightened Release checklist wording so it names the exact design-ai learn --signals --strict --json command.
• Updated changelog, roadmap, and session history.

Impact

• Release docs now preserve the installed-bin and one-shot package strict AI/agent readiness gate alongside package smoke coverage.
• This remains docs/metadata only: no runtime CLI behavior change, learning schema change, external AI call, embedding/fine-tuning, backend storage, target repo mutation, or new dependency.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/release-metadata.py
• npm run release:metadata
• git diff --check

What's still ahead

• Public registry smoke can add the same strict path after publish if post-publish AI/agent readiness evidence becomes required.

Phase 413 — Learning Signals Strict Package Smoke Coverage (unreleased)

Packed-tarball smoke now executes design-ai learn --signals --strict --json through installed-bin and one-shot npm exec --package <tarball> paths. This closes the Phase 412 hardening follow-up by proving the local signal registry and deterministic agentDevelopment backlog strict gate still passes after packaging.

Changed

• Added strict learning signal registry JSON smoke execution to package smoke's installed-bin and one-shot package paths.
• Tightened shared package smoke assertions so agentDevelopment.status must remain pass in the good signal fixture.
• Added package smoke self-test drift coverage for non-passing agentDevelopment status.
• Updated changelog, roadmap, and session history.

Impact

• Packaged internal/company builds now verify the strict AI/agent readiness gate, not only source-tree unit tests.
• This remains read-only and local: no learning.json mutation, skill file mutation, external AI API call, embedding/fine-tuning, backend storage, target repo mutation, or new dependency.

Verified

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py
• npm run release:metadata
• git diff --check

What's still ahead

• Public registry smoke can add the same strict path after the next publish if we decide this gate should be post-publish required evidence.

Phase 412 — Learning Signals Strict Agent Gate (unreleased)

design-ai learn --signals --strict now exits non-zero when the signal registry or deterministic agentDevelopment backlog is not pass. This turns the Phase 411 backlog into a local gate for AI/agent development readiness while keeping the command read-only, local, and dependency-free.

Changed

• Allowed --strict with learn --signals in addition to learn --eval.
• Applied strict exit handling after JSON or human learn --signals output is emitted.
• Updated learn help, README command lists, usage docs, and agent development docs with the strict signal gate.
• Added unit coverage for parser support and non-zero strict exit behavior.

Impact

• Local scripts can now fail on warning/failing learning signal registry or agent backlog status without running external AI APIs or mutating learning.json.
• This does not add embeddings, fine-tuning, online model calls, telemetry, backend storage, auth, multi-user sync, target website repo mutation, or new dependencies.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/smoke_assertions.py
• npm run release:metadata
• git diff --check

What's still ahead

• Public registry smoke can add a direct learn --signals --strict path after publish if this gate becomes part of the post-publish release checklist.

Phase 411 — Learning Signals Agent Development Backlog (unreleased)

design-ai learn --signals now turns the existing local learning, usage sidecar, eval checkpoint, check-capture, and workspace readiness summaries into a deterministic agentDevelopment backlog. The backlog ranks profile audit, usage recording, eval harness replay, check-capture skill evolution, and workspace readiness actions without adding dependencies, changing learning.json, editing skill files, or calling external AI APIs.

Changed

• Added agentDevelopment to the learning signal registry JSON payload with ranked p0/p1/p2/p3 actions, commands, evidence, and local privacy boundaries.
• Added an Agent development backlog section to human design-ai learn --signals output.
• Extended unit and package smoke assertions so the new backlog shape and local/preview-only privacy boundary cannot drift silently.
• Updated changelog, roadmap, and session history.

Impact

• Local AI/agent development can now move from raw signal summaries to an ordered next-action queue that fits the Hermes/Harness-style eval loop while staying deterministic and local.
• This does not add embeddings, fine-tuning, online model calls, telemetry, backend storage, auth, multi-user sync, target website repo mutation, or new dependencies.

Verified

• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py
• npm run release:metadata
• git diff --check

What's still ahead

• Add a future apply path only after explicit approval; v1 stays preview-only and local.

Phase 410 — Post-Release Scope Decision Boundary (unreleased)

After the Phase 409 full npm run release:check evidence, the next work is no longer another release hardening pass. The roadmap now separates three paths: push/Real-CI/public launch evidence, deeper AI learning work with explicit data boundaries, and broader product-surface expansion for Website Console automation, VS Code Webview reuse, Figma/plugin surfaces, or agent SDK workflows.

Changed

• Recorded the post-release hardening scope boundary in the roadmap.
• Kept push/Real-CI/public launch as external-system work that requires explicit approval.
• Kept embeddings, fine-tuning, backend storage, auth, and multi-user sync outside shipped scope until a dedicated phase defines privacy and data boundaries.
• Updated changelog, roadmap, and session history.

Impact

• Future development can choose a concrete product path instead of continuing redundant release evidence loops.
• This is planning documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:metadata
• git diff --check

What's still ahead

• Choose one path explicitly: push/Real-CI launch, deeper AI learning architecture, or broader product-surface work.

Phase 409 — Release Policy Product Readiness Full Gate Evidence (unreleased)

The full npm run release:check gate now passes after the release-facing docs Product Readiness release policy full gate evidence guard. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after Phase 408 made the release-facing docs evidence guard durable.

Changed

• Ran npm run release:check after Phase 408.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the release-facing docs Product Readiness full gate evidence guard is covered by the complete pre-push release gate.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 408 — Release Policy Product Readiness Full Gate Evidence Guard (unreleased)

Release metadata now guards release-facing docs against dropping the Product Readiness release policy full gate evidence npm run release:check phrase. README, Korean README, Distribution docs, Korean Distribution docs, and the release checklist now preserve the same unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke wording recorded in Phase 407.

Changed

• Added a release policy phrase group for Product Readiness release policy full gate evidence release:check coverage.
• Added a release metadata --self-test drift fixture that fails if release-facing docs drop that evidence phrase.
• Updated README, Korean README, Distribution docs, Korean Distribution docs, release checklist, changelog, roadmap, and session history.

Impact

• Release-facing docs now keep Phase 407 full release gate evidence aligned with Product Readiness.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 407 — Product Readiness Release Policy Full Gate Evidence (unreleased)

The full npm run release:check gate now passes after the Product Readiness release policy full gate evidence guard. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after Phase 406 made the Product Readiness evidence guard durable.

Changed

• Ran npm run release:check after Phase 406.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the Product Readiness release policy full gate evidence guard is covered by the complete pre-push release gate.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 406 — Product Readiness Release Policy Full Gate Evidence Guard (unreleased)

Release metadata now guards Product Readiness against dropping the full npm run release:check evidence after the release-facing policy docs Product Readiness release policy full gate evidence guard. Product Readiness now keeps the Phase 405 evidence tied to unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.

Changed

• Added a Product Readiness phrase group for release-facing policy docs Product Readiness release policy full gate release:check evidence.
• Added a release metadata --self-test drift fixture that fails if Product Readiness drops that full release gate evidence.
• Updated Product Readiness, changelog, roadmap, and session history.

Impact

• Product Readiness now has deterministic guard coverage for the Phase 405 full release gate evidence.
• This is Product Readiness and release metadata hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 405 — Release Policy Product Readiness Full Gate Evidence (unreleased)

The full npm run release:check gate now passes after the release-facing policy docs Product Readiness release policy full gate evidence guard. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after Phase 404 made the release-facing policy docs guard durable.

Changed

• Ran npm run release:check after Phase 404.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the release-facing policy docs Product Readiness full gate evidence guard is covered by the complete pre-push release gate.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 404 — Release Policy Product Readiness Full Gate Evidence Guard (unreleased)

Release metadata now guards release-facing docs against dropping the Product Readiness release policy full gate npm run release:check evidence phrase for Website Console bundle boundary metadata full release:check evidence. README, Korean README, Distribution docs, Korean Distribution docs, and the release checklist now preserve the same unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke wording recorded in Phase 403.

Changed

• Added a release policy phrase group for Product Readiness release policy full gate release:check evidence.
• Added a release metadata --self-test drift fixture that fails if release-facing docs drop that evidence phrase.
• Updated README, Korean README, Distribution docs, Korean Distribution docs, release checklist, changelog, roadmap, and session history.

Impact

• Release-facing docs now keep Phase 403 full release gate evidence aligned with Product Readiness.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 403 — Product Readiness Release Policy Full Gate Evidence (unreleased)

The full npm run release:check gate now passes after the Product Readiness guard for release-facing policy docs Website Console bundle boundary metadata full release:check evidence. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after Phase 402 made the readiness evidence durable.

Changed

• Ran npm run release:check after Phase 402.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the Product Readiness release policy full gate guard is covered by the complete pre-push release gate.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 402 — Product Readiness Bundle Boundary Release Policy Full Gate Guard (unreleased)

Release metadata now guards Product Readiness against dropping the full npm run release:check evidence recorded after the release-facing policy docs guard for Website Console bundle boundary metadata full release:check evidence. Product Readiness now keeps that Phase 401 evidence tied to unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.

Changed

• Added a Product Readiness phrase group for release-facing policy docs full bundle boundary release:check evidence.
• Added a release metadata --self-test drift fixture that fails if Product Readiness drops that evidence phrase.
• Updated Product Readiness, changelog, roadmap, and session history.

Impact

• Product Readiness now has deterministic guard coverage for the Phase 401 full release gate evidence, not only the earlier Product Readiness/release-facing policy docs bundle boundary guard evidence.
• This is Product Readiness and release metadata hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 401 — Release Policy Bundle Boundary Full Release Gate Evidence (unreleased)

The full npm run release:check gate now passes after the release-facing policy docs guard for Website Console bundle boundary metadata full release:check evidence. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after Phase 400 aligned README, Korean README, Distribution docs, Korean Distribution docs, and the release checklist with Product Readiness.

Changed

• Ran npm run release:check after Phase 400.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the release-facing policy docs guard for Website Console bundle boundary metadata full release:check evidence is covered by the complete pre-push release gate.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 400 — Release Policy Bundle Boundary Full Release Gate Guard (unreleased)

Release metadata now guards release-facing docs against dropping the full npm run release:check evidence for Website Console bundle boundary metadata guard phases after full release:self-test evidence recording. README, Korean README, Distribution docs, Korean Distribution docs, and the release checklist now keep the same unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke wording that Product Readiness protects.

Changed

• Extended the release policy phrase group for Website Console bundle boundary metadata full release:check evidence.
• Updated README, Korean README, Distribution docs, Korean Distribution docs, and the release checklist with the full gate evidence wording.
• Updated changelog, roadmap, and session history.

Impact

• Release-facing docs now keep Phase 398 full release gate evidence aligned with Product Readiness, including full release:self-test evidence recording and the full pre-push gate components.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 399 — Product Readiness Bundle Boundary Full Release Gate Guard (unreleased)

Release metadata now guards Product Readiness against dropping the full npm run release:check evidence recorded after Website Console bundle boundary metadata release:check guards and their full release:self-test evidence recording. Product Readiness now explicitly keeps unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke tied to that full release gate evidence.

Changed

• Added a Product Readiness phrase group for bundle boundary metadata full release:check coverage after release:self-test evidence recording.
• Added a release metadata --self-test drift fixture that fails if Product Readiness drops that full release gate evidence.
• Updated Product Readiness, changelog, roadmap, and session history.

Impact

• Product Readiness now has deterministic guard coverage for the Phase 398 full release gate evidence, not only the earlier bundle boundary release:check and release:self-test evidence phrases.
• This is Product Readiness and release metadata hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 398 — Bundle Boundary Release Gate Guard Full Release Evidence (unreleased)

The full npm run release:check gate now passes after the Product Readiness and release-facing policy docs guards for Website Console bundle boundary metadata release:check evidence plus their full release:self-test evidence recording. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after the bundle boundary release gate guard phases.

Changed

• Ran npm run release:check after Phase 397.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the bundle boundary metadata release:check evidence guard chain is covered by the full pre-push release gate, not only targeted metadata checks or release:self-test.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 397 — Bundle Boundary Release Gate Guard Self-Test Evidence (unreleased)

The full npm run release:self-test chain now passes after the Product Readiness and release-facing policy docs guards for Website Console bundle boundary metadata release:check evidence. This confirms the new Product Readiness phrase guard, release policy phrase guard, and their drift fixtures run together with shared smoke assertions, package smoke self-tests, registry smoke self-tests, release metadata self-tests, local CI self-tests, and token extractor self-tests.

Changed

• Ran npm run release:self-test after Phases 395-396.
• Updated changelog, roadmap, and session history with the release self-test chain result.

Impact

• Release evidence now shows the bundle boundary metadata release:check evidence guards are covered by the full release self-test chain.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 396 — Release Policy Bundle Boundary Release Gate Guard (unreleased)

Release metadata now guards release-facing policy docs against dropping the full npm run release:check evidence for Website Console bundle boundary metadata guard phases. README, Korean README, Distribution docs, Korean Distribution docs, and the release checklist now keep the same bundle-check JSON/human and bundle-handoff JSON/prompt release gate evidence that Product Readiness protects.

Changed

• Added bundle boundary metadata release:check wording to release-facing docs.
• Added a release policy phrase guard for Website Console bundle boundary metadata release gate evidence.
• Added a release metadata --self-test drift fixture that fails if README drops the phrase.
• Updated changelog, roadmap, and session history.

Impact

• Release-facing docs now keep npm run release:check, package contents, release self-tests, and packed-tarball smoke tied to Website Console bundle boundary metadata guard phases.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 395 — Product Readiness Bundle Boundary Release Gate Guard (unreleased)

Release metadata now guards Product Readiness against dropping the full npm run release:check evidence for Website Console bundle boundary metadata guard phases. Phase 394 recorded the full release gate result; this phase makes the Product Readiness evidence durable when readiness docs are edited later.

Changed

• Added a Product Readiness phrase group for npm run release:check coverage after Website Console bundle boundary metadata guard phases.
• Added a release metadata --self-test drift fixture that fails if Product Readiness drops that full release gate evidence.
• Updated Product Readiness, changelog, roadmap, and session history.

Impact

• Product Readiness now has deterministic guard coverage for the bundle boundary metadata full release gate evidence, matching the existing mcp-probes saved-payload release gate evidence guard.
• This is Product Readiness and release metadata hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 394 — Bundle Boundary Metadata Guard Full Release Evidence (unreleased)

The full npm run release:check gate now passes after the Product Readiness and release-facing policy docs guards for Website Console bundle boundary metadata. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after the bundle-check JSON/human and bundle-handoff JSON/prompt boundary wording guards.

Changed

• Ran npm run release:check after Phases 390-393.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the bundle boundary metadata wording is covered by the full pre-push release gate, not only targeted metadata checks or release:self-test.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 393 — Release Policy Bundle Boundary Metadata Guard (unreleased)

Release metadata now guards release-facing policy docs against dropping Website Console bundle boundary metadata wording. README, Korean README, Distribution docs, Korean Distribution docs, and the release checklist now preserve the same bundle-check JSON/human and bundle-handoff JSON/prompt boundary contract already protected in Product Readiness.

Changed

• Added bundle boundary metadata wording to release-facing docs that summarize public registry Website Console coverage.
• Added a release policy phrase guard for Website Console bundle-check and bundle-handoff boundary metadata.
• Added a release metadata --self-test drift fixture that fails if README regresses to generic bundle boundary wording.
• Updated changelog, roadmap, and session history.

Impact

• Release-facing docs now keep deterministic-local, no-external-call, and no-target-repo-mutation handoff boundary wording visible next to public registry Website Console smoke coverage.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 392 — Product Readiness Bundle Boundary Metadata Guard (unreleased)

Release metadata now guards Product Readiness against dropping the Website Console bundle boundary metadata wording added across bundle-check and bundle-handoff. This keeps the release-facing readiness summary explicit that handoff validation exposes deterministic-local, no-external-call, and no-target-repo-mutation boundaries in bundle-check JSON/human output and bundle-handoff JSON/prompt output.

Changed

• Added a Product Readiness phrase guard for Website Console bundle-check and bundle-handoff boundary metadata.
• Added a release metadata --self-test drift fixture that fails if Product Readiness regresses to generic handoff boundary wording.
• Updated changelog, roadmap, and session history.

Impact

• Release metadata now protects the boundary contract introduced in Phases 390 and 391 at the product readiness layer.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 391 — Bundle Handoff Boundary Metadata (unreleased)

design-ai site <bundle-dir> --bundle-handoff [--json] now exposes handoff generation boundary metadata directly in the target-repo handoff output. JSON reports include top-level and bundle-level boundaries, externalCalls: false, and targetRepoMutation: false; the generated handoff prompt includes boundary flags and the boundary list so operators can distinguish local handoff generation from later target-repo implementation work.

Changed

• Added bundle-handoff boundary metadata to buildSiteBundleHandoffReport.
• Added boundary flags and boundary list context to the generated target-repo handoff prompt.
• Extended CLI unit coverage and package smoke assertions for bundle-handoff boundary flags and boundary list preservation.
• Updated changelog, Product Readiness, roadmap, and session history.

Impact

• Target-repo handoff reviews can now confirm that handoff prompt generation is deterministic, local, non-mutating, and free of external MCP calls without opening the originating bundle-check output.
• This does not change bundle generation, checksums, generated contract verification, MCP probe payloads, external MCP behavior, target repo mutation behavior, backend storage, or dependencies.

Verified

• node --check cli/lib/site.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• npm run release:metadata
• npm test
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 390 — Bundle Check Boundary Metadata (unreleased)

design-ai site <bundle-dir> --bundle-check [--json] now exposes handoff bundle boundary metadata directly in bundle-check output. JSON reports include boundaries, externalCalls: false, and targetRepoMutation: false; human reports include boundary flags and the recorded bundle boundary list so operators can confirm the check is deterministic, local, non-mutating, and not a real MCP/Lighthouse/axe execution before handing work to a target website repo.

Changed

• Added bundle-check boundary metadata to buildSiteBundleCheckReport.
• Added human bundle-check output for boundary flags and bundle boundary lines.
• Extended CLI unit coverage and package smoke assertions for bundle-check boundary flags and boundary list preservation.
• Updated changelog, Product Readiness, roadmap, and session history.

Impact

• Target-repo handoff reviews no longer require opening summary.json just to confirm bundle-check safety boundaries.
• This does not change bundle generation, checksums, generated contract verification, MCP probe payloads, external MCP behavior, target repo mutation behavior, backend storage, or dependencies.

Verified

• node --check cli/lib/site.mjs
• python3 -m py_compile tools/audit/package-smoke.py
• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 389 — MCP Probe Release Gate Guard Full Release Evidence (unreleased)

The full npm run release:check gate now passes after the Product Readiness and release-facing policy docs guards for Website Console bundle mcp-probes.json saved-payload release:check evidence. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after the saved-payload release gate phrase guards.

Changed

• Ran npm run release:check after Phases 386-388.
• Updated changelog, roadmap, and session history with the full release gate result.

Impact

• Release evidence now shows the saved-payload release:check wording is covered by the full pre-push release gate, not only targeted metadata checks or release:self-test.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 388 — MCP Probe Release Gate Guard Self-Test Evidence (unreleased)

The full npm run release:self-test chain now passes after the Product Readiness and release-facing policy docs guards for Website Console bundle mcp-probes.json saved-payload release:check evidence. This confirms the new Product Readiness phrase guard, release policy phrase guard, and their drift fixtures run together with shared smoke assertions, package smoke self-tests, registry smoke self-tests, release metadata self-tests, local CI self-tests, and token extractor self-tests.

Changed

• Ran npm run release:self-test after Phases 386-387.
• Updated changelog, roadmap, and session history with the release self-test chain result.

Impact

• Release evidence now shows the saved-payload release:check wording is covered by the full release self-test chain, not only by direct release-metadata.py --self-test.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 387 — Release Policy MCP Probe Release Gate Guard (unreleased)

Release metadata now guards release-facing policy docs against dropping the npm run release:check evidence that ties Website Console bundle mcp-probes.json saved-payload guard phases to package contents, release self-tests, and packed-tarball smoke. Phase 386 guarded Product Readiness; this phase extends the same release gate evidence to README, Korean README, Distribution docs, and the release checklist.

Changed

• Added a release policy phrase group for Website Console bundle mcp-probes.json saved-payload release:check evidence.
• Added short release-facing doc guidance in README, Korean README, English/Korean Distribution docs, and the release checklist.
• Added a release metadata --self-test drift fixture that fails if README drops the saved-payload release gate evidence phrase.
• Updated changelog, roadmap, and session history.

Impact

• Release-facing docs now preserve the link between the saved-payload boundary and the full local release gate, not only the standalone release:check command or standalone bundle payload assertion.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 386 — Product Readiness MCP Probe Release Gate Guard (unreleased)

Release metadata now guards Product Readiness against dropping the full npm run release:check evidence for the Website Console bundle mcp-probes.json saved-payload guard phases. Phase 385 recorded the full release gate result; this phase makes the Product Readiness evidence less likely to drift when release-facing docs are edited later.

Changed

• Added a Product Readiness phrase group for npm run release:check coverage after Website Console bundle mcp-probes.json saved-payload guard phases.
• Added a release metadata --self-test drift fixture that fails if Product Readiness drops that full release gate evidence.
• Updated changelog, roadmap, and session history.

Impact

• Product Readiness now has a deterministic guard for the saved-payload full release gate evidence, matching the existing payload-boundary and self-test coverage guards.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 385 — Bundle MCP Probe Evidence Full Release Gate Evidence (unreleased)

The full npm run release:check gate now passes after the Website Console bundle mcp-probes.json saved-payload guard phases. This confirms unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke still run together after the saved-payload assertion fix and docs/Product Readiness guards.

Changed

• Ran npm run release:check after Phases 381-384.
• Updated Product Readiness release confidence to name the full release gate after the Website Console bundle mcp-probes.json saved-payload guard phases.
• Updated changelog, roadmap, and session history.

Impact

• Release evidence now shows the saved-payload boundary is covered by the full pre-push release gate, not only targeted checks or release:self-test.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:check
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 384 — Bundle MCP Probe Evidence Release Self-Test Chain Evidence (unreleased)

The full release self-test chain now passes after the Website Console bundle mcp-probes.json saved-payload guard phases. This confirms that shared smoke assertions, package smoke self-tests, registry smoke self-tests, release metadata self-tests, local CI self-tests, and token extractor self-tests still run together after the package smoke assertion fix, release-facing docs guard, and Product Readiness guard.

Changed

• Ran npm run release:self-test after Phases 381-383.
• Updated Product Readiness release confidence to name the Website Console bundle mcp-probes.json saved-payload guard phases.
• Updated changelog, roadmap, and session history with the release self-test chain result.

Impact

• Release evidence now shows the saved-payload boundary is covered by the top-level release self-test command, not only by isolated package smoke and release metadata checks.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 383 — Product Readiness Bundle MCP Probe Evidence Guard (unreleased)

Product Readiness now carries the same Website Console bundle probe evidence boundary as release-facing docs. Bundled mcp-probes.json is explicitly documented as a saved probe evidence payload, not the full site --mcp-check --probes --json response, and release metadata now guards that readiness wording.

Changed

• Added a Product Readiness phrase group for bundled Website Console mcp-probes.json saved probe evidence payload wording.
• Added a release metadata --self-test drift fixture that fails if Product Readiness drops the saved-payload boundary.
• Updated Product Readiness, changelog, roadmap, and session history.

Impact

• Product Readiness now matches the Phase 381 package smoke assertion boundary and the Phase 382 release-facing docs guard.
• This is Product Readiness and release metadata hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 382 — Website Console Bundle MCP Probe Evidence Release Guard (unreleased)

Release metadata now protects the release-facing wording that clarifies bundled Website Console mcp-probes.json is a saved probe evidence payload, not the full site --mcp-check --probes --json response. Phase 381 fixed the package smoke assertion boundary; this phase prevents README, distribution, and release checklist docs from drifting back to the wrong payload contract.

Changed

• Added a release metadata phrase group for bundled mcp-probes.json saved probe evidence payload wording.
• Added a release metadata --self-test drift fixture that fails if README drops the saved-payload assertion phrase.
• Updated README, Korean README, distribution docs, release checklist, changelog, roadmap, and session history.

Impact

• Release-facing docs now preserve the Website Console bundle probe evidence boundary alongside bundle mcpProbeCounts telemetry and bundle probe count self-test coverage.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 381 — Website Console Bundle MCP Probe Evidence Smoke Assertion Fix (unreleased)

Package smoke now checks bundled Website Console mcp-probes.json with the correct payload contract. The bundle file stores the probe evidence object saved inside handoff bundles, not the full design-ai site --mcp-check --probes --json CLI response, so this phase adds a bundle-specific assertion and self-test drift fixture.

Changed

• Added bundle-specific mcp-probes.json expected key and probe item assertions in tools/audit/package-smoke.py.
• Updated Website Console bundle smoke to validate the saved probe evidence payload instead of reusing the full MCP check probe JSON assertion.
• Added a package smoke --self-test fixture that mutates a bundled probe item status and expects the bundle assertion to fail.

Impact

• npm run package:smoke now matches the actual handoff bundle file shape while still guarding read-only mode, external-call boundaries, pass/warn/fail counts, item order, evidence, and action arrays.
• This is package smoke assertion hardening only: no CLI runtime behavior, JSON contract, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run package:smoke
• npm run release:check
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 380 — MCP Probe Count Guard Release Self-Test Chain Evidence (unreleased)

The full release self-test chain now passes after the Website Console MCP probe count self-test and release metadata guard phases. This confirms that shared smoke assertions, package smoke self-tests, registry smoke self-tests, release metadata self-tests, local CI self-tests, and token extractor self-tests still run together through npm run release:self-test.

Changed

• Recorded full npm run release:self-test evidence after the Website Console MCP probe count guard phases.
• Updated changelog, Product Readiness, roadmap, and session history with the release self-test chain result.

Impact

• Release evidence now shows the MCP probe count assertion hardening is covered by the top-level release self-test command, not only by isolated targeted commands.
• This is release evidence documentation only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• npm run release:self-test

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 379 — Product Readiness MCP Probe Count Self-Test Coverage Guard (unreleased)

Product Readiness now reflects the MCP probe count self-test coverage that was added across Website Console next-actions and bundle smoke assertions. Release metadata also guards that Product Readiness wording so the readiness summary cannot drift back to generic MCP probe coverage.

Changed

• Added Product Readiness phrase checks for Website Console MCP probe count self-test coverage.
• Added a release metadata --self-test drift fixture that fails if Product Readiness drops the MCP probe count self-test coverage wording.
• Updated Product Readiness to mention MCP probe count telemetry with package/shared smoke self-test coverage for Website Console MCP probe counts.
• Updated changelog, roadmap, and session history.

Impact

• Product Readiness now matches the recently hardened next-actions and bundle mcpProbeCounts smoke assertion surface.
• This is Product Readiness and release metadata hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 378 — Website Console Bundle MCP Probe Count Self-Test Release Guard (unreleased)

Release metadata now protects the release-facing wording for package smoke self-test coverage around Website Console bundle MCP probe counts. Phases 374 and 375 completed the bundle count drift fixtures; this phase makes the public release docs keep mentioning that package smoke self-test protection.

Changed

• Added a release metadata phrase group for package smoke self-test coverage of Website Console bundle MCP probe counts.
• Added the phrase to release policy labels and checks.
• Added a release metadata --self-test drift fixture that fails if release docs drop the bundle probe count self-test wording.
• Updated README, Korean README, distribution docs, release checklist, changelog, roadmap, and session history.

Impact

• Release-facing docs now preserve both the bundle-check/compare/handoff mcpProbeCounts public smoke contract and the package smoke self-test coverage that guards the assertion surface.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 377 — Website Console Next-Actions MCP Probe Count Self-Test Release Guard (unreleased)

Release metadata now protects the release-facing wording for shared smoke assertion self-test coverage around Website Console next-actions MCP probe counts. Phase 376 added the direct drift fixture; this phase makes the public release docs keep mentioning that protection.

Changed

• Added a release metadata phrase group for shared smoke assertion self-test coverage of Website Console next-actions MCP probe counts.
• Added the phrase to release policy labels and checks.
• Added a release metadata --self-test drift fixture that fails if release docs drop the self-test coverage wording.
• Updated README, Korean README, distribution docs, release checklist, changelog, roadmap, and session history.

Impact

• Release-facing docs now preserve both the mcpProbeCounts public smoke contract and the self-test coverage that guards the assertion.
• This is release metadata and documentation hardening only: no CLI runtime behavior, JSON contract, package smoke runner, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 376 — Website Console Next-Actions MCP Probe Count Smoke Self-Test (unreleased)

Shared smoke assertion self-tests now protect the Website Console next-actions MCP probe count contract. The next-actions JSON smoke already checked mcpProbeCounts; this phase adds a direct drift fixture so that assertion cannot silently weaken.

Changed

• Added a shared expected MCP probe count constant in tools/audit/smoke_assertions.py.
• Reused the constant in the next-actions JSON smoke assertion.
• Added a --self-test drift fixture that mutates next-actions mcpProbeCounts and expects the assertion to fail.
• Updated changelog, roadmap, and session history.

Impact

• Packed-tarball and public-registry next-actions smoke coverage now has self-test protection for probe count drift before package smoke runs.
• This is smoke assertion hardening only: no CLI runtime behavior, JSON contract, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 375 — Website Console Bundle MCP Probe Count Smoke Surface Completion (unreleased)

Package smoke self-tests now cover every bundle MCP probe count surface asserted by packed smoke. Phase 374 added shared count fixtures for bundle-check summary, bundle-compare left side, and bundle-handoff; this phase adds the remaining bundle-check top-level and bundle-compare right-side drift fixtures.

Changed

• Added package smoke self-test drift coverage for the top-level bundle-check mcpProbeCounts payload.
• Added package smoke self-test drift coverage for the right-side bundle-compare mcpProbeCounts payload.
• Updated changelog, roadmap, and session history.

Impact

• tools/audit/package-smoke.py --self-test now exercises all bundle mcpProbeCounts assertion labels used by bundle-check, bundle-compare, and bundle-handoff smoke checks.
• This is smoke assertion coverage only: no CLI runtime behavior, JSON contract, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 374 — Website Console Bundle MCP Probe Count Smoke Self-Test (unreleased)

Package smoke self-tests now protect the Website Console bundle MCP probe count assertions. The packed-tarball smoke already checked bundle-check, bundle-compare, and bundle-handoff mcpProbeCounts; this phase adds direct self-test drift fixtures so those assertions cannot silently weaken.

Changed

• Added a shared package-smoke helper for the expected Website Console MCP probe count payload.
• Reused the helper in bundle-check, bundle-compare, and bundle-handoff package smoke assertions.
• Added package smoke self-test drift fixtures for bundle-check summary, bundle-compare left side, and bundle-handoff MCP probe counts.
• Updated changelog, roadmap, and session history.

Impact

• Packed-tarball smoke assertion drift around bundle mcpProbeCounts is now caught by tools/audit/package-smoke.py --self-test before release smoke runs.
• This is smoke assertion hardening only: no CLI runtime behavior, JSON contract, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 373 — Website Console Bundle Compare Human CLI Coverage (unreleased)

Website Console bundle comparison now has end-to-end CLI coverage for the human MCP probe count summary. Phase 372 added the formatter line; this phase verifies the actual runSite human --bundle-compare path prints the same left/right probe coverage.

Changed

• Added runSite test coverage for non-JSON design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> output.
• Verified the emitted human output includes the left/right MCP probe pass/warn/fail count summary.
• Updated changelog, roadmap, and session history.

Impact

• Future changes cannot keep the formatter unit passing while accidentally breaking the real CLI human output path.
• This is CLI test coverage and release history only: no runtime behavior, external MCP call, target website repo mutation, package smoke runner behavior, backend storage, or dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 372 — Website Console Bundle Compare Human Probe Counts (unreleased)

Website Console bundle comparison now keeps MCP probe coverage visible in the human report. Bundle compare JSON already carried left/right mcpProbeCounts; this phase exposes the same pass/warn/fail count summary in the Markdown-style CLI output.

Changed

• Added a left/right MCP probe count summary line to design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> human output.
• Added CLI unit coverage so identical bundle comparisons keep the human probe count summary.
• Updated changelog, roadmap, and session history.

Impact

• Operators can inspect bundle comparison readiness from the default human report without switching to --json.
• This is deterministic local CLI formatting and unit coverage only: no external MCP call, target website repo mutation, package smoke runner behavior, backend storage, or dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 371 — Website Console Bundle MCP Probe Count Release Guard (unreleased)

Release metadata now protects the Website Console bundle-check/compare/handoff MCP probe count telemetry wording. Phase 368 exposed mcpProbeCounts in bundle consumers; this phase makes release-facing docs keep that public smoke contract visible.

Changed

• Added a release metadata phrase guard for Website Console bundle-check/compare/handoff mcpProbeCounts probe count telemetry.
• Added a release metadata self-test drift fixture that removes only the bundle mcpProbeCounts phrase and expects the guard to fail.
• Updated README, Korean README, Release Checklist, English/Korean Distribution docs, changelog, roadmap, and session history with the guarded phrase.

Impact

• Release-facing docs can no longer silently regress to generic bundle-check/compare/handoff smoke wording while omitting the probe count telemetry contract.
• This is release guard and documentation coverage only: no CLI runtime behavior, package/registry smoke runner behavior, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 370 — Website Console Next-Actions MCP Probe Count Release Guard (unreleased)

Release metadata now protects the Website Console next-actions MCP probe count telemetry wording. Phase 369 added mcpProbeCounts to next-actions JSON/human output; this phase makes release-facing docs keep documenting that public smoke contract.

Changed

• Added a release metadata phrase guard for mcpProbeCounts probe count telemetry in Website Console next-actions guidance.
• Added a release metadata self-test drift fixture that removes only the mcpProbeCounts phrase and expects the guard to fail.
• Updated README, Korean README, Release Checklist, English/Korean Distribution docs, changelog, roadmap, and session history with the guarded phrase.

Impact

• Release-facing docs can no longer silently regress to a generic next-actions smoke phrase while omitting the probe count telemetry contract.
• This is release guard and documentation coverage only: no CLI runtime behavior, package/registry smoke runner behavior, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 369 — Website Console Next-Actions MCP Probe Count Telemetry (unreleased)

Website Console next-actions now exposes read-only MCP probe counts before operators export a bundle. Phase 368 made bundle consumers carry mcpProbeCounts; this phase puts the same count/pass/warn/fail telemetry into the first operator checklist so malformed repo/Figma/Browser/deploy references are visible without opening a separate probe report.

Changed

• Added mcpProbeCounts to design-ai site --next-actions --json.
• Added an MCP probe count summary line to human next-actions output.
• Extended next-actions unit coverage for pass and probe-gap states.
• Updated shared smoke assertion fixtures so packed/public next-actions smoke requires the new probe count contract.
• Updated Website Improvement docs, Product Readiness, changelog, roadmap, and session history.

Impact

• Operators can see both probe status and probe volume directly in the prioritized local checklist before target-repo handoff.
• This remains deterministic and local: no external MCP calls, target website repo mutation, Lighthouse/axe execution, screenshot capture, backend storage, or dependency changes.

Verified

• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py
• npm test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 368 — Website Console Bundle MCP Probe Count Contract (unreleased)

Website Console bundle consumers now expose and validate read-only MCP probe counts, not only probe status. Phase 367 preserved mcp-probes.json inside the bundle; this phase makes the downstream JSON reports carry the same count/pass/warn/fail telemetry through bundle-check, bundle-compare, and target-repo handoff.

Changed

• Added normalized mcpProbeCounts to Website Console bundle-check reports.
• Added mcpProbeCounts to bundle-compare left/right summaries and metadata drift detection.
• Added mcpProbeCounts to bundle-handoff JSON and target-repo handoff prompt context.
• Extended bundle-check validation so summary.json mcp.probeCounts must match mcp-probes.json.
• Updated CLI unit coverage, packed-tarball package smoke assertions, Website Improvement docs, Product Readiness, changelog, roadmap, and session history.

Impact

• Operators and downstream automation can verify whether a passing or warning handoff bundle actually checked all expected read-only MCP probe references.
• This remains deterministic and local: no external MCP calls, target website repo mutation, Lighthouse/axe execution, screenshot capture, backend storage, or dependency changes.

Verified

• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 367 — Website Console Handoff Bundle MCP Probe Evidence (unreleased)

Website Console handoff bundles now preserve read-only MCP probe evidence beside the base MCP readiness gate. Phase 366 made next-actions probe-aware; this phase carries the same local probe evidence into the portable bundle so target-repo handoff packages retain the repo/Figma/Browser/deploy reference checks used before implementation.

Changed

• Added mcp-probes.json to the Website Console handoff bundle manifest.
• Recorded MCP probe status and probe counts in summary.json under the existing mcp summary block.
• Included mcp-probes.json in bundle checksums, generated contract verification, repair preview/apply, compare summaries, and target-repo handoff context.
• Extended bundle-check validation so mcp-probes.json must match the recomputed read-only MCP probe report.
• Updated CLI unit coverage, package smoke bundle assertions, Website Improvement docs, Product Readiness, changelog, roadmap, and session history.

Impact

• Operators can archive or hand off one bundle that contains both MCP readiness evidence and stricter read-only probe evidence.
• This remains deterministic and local: no external MCP calls, target website repo mutation, Lighthouse/axe execution, screenshot capture, backend storage, or dependency changes.

Verified

• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 366 — Website Console Next-Actions MCP Probe Readiness (unreleased)

Website Console next-actions now includes read-only MCP probe readiness before target-repo handoff. This closes a practical operator gap where base MCP readiness could pass because a field was present, while the stricter local probe check could still detect an invalid GitHub URL, Figma URL, Browser smoke target, or deployment reference.

Changed

• Added mcpProbeStatus and counts.probeGaps to design-ai site --next-actions --json.
• Added probe follow-up commands to the next-actions commands block: mcpCheckProbes and mcpPlanProbes.
• Ranked failing/warning MCP probe gaps as blocking or warning next-actions before implementation and bundle handoff steps.
• Updated next-actions human output with MCP probe status and the read-only probe boundary.
• Updated CLI unit coverage, shared smoke assertion fixtures, Website Improvement docs, changelog, roadmap, and session history.

Impact

• Operators can catch malformed local handoff references directly from the prioritized next-actions report, without running a separate probe command first.
• This remains deterministic and local: no external MCP calls, target website repo mutation, Lighthouse/axe execution, screenshot capture, backend storage, or dependency changes.

Verified

• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -m py_compile tools/audit/smoke_assertions.py
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 365 — Product Readiness JSON Release Policy Guard (unreleased)

Release metadata now guards release-facing docs against dropping the Product Readiness JSON summary phrase. Phase 364 exposed product_readiness_checked: true; this phase makes README, release checklist, and distribution docs keep documenting that machine-readable guard signal.

Changed

• Added a release policy phrase group for release metadata JSON product_readiness_checked: true Product Readiness guard coverage.
• Updated English/Korean README and Distribution docs plus Release Checklist guidance with the new JSON field phrase.
• Added a release metadata self-test drift fixture that removes the phrase and expects the release policy guard to fail.
• Updated changelog, roadmap, and session history.

Impact

• Release-facing docs now stay aligned with the release metadata JSON shape added in Phase 364.
• This is release guard and documentation coverage only: no CLI runtime behavior, package/registry smoke runner behavior, Product Readiness guard logic, JSON field value, external MCP call, target website repo mutation, backend storage, or dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 364 — Product Readiness Release Metadata JSON Visibility (unreleased)

Release metadata JSON now exposes whether Product Readiness guard coverage ran. Phase 363 made Product Readiness part of the release metadata check; this phase makes the machine-readable summary show that state through product_readiness_checked: true.

Changed

• Added product_readiness_checked to the release metadata summary key order.
• Set the field to true when Product Readiness text is provided to the release metadata summary.
• Updated release metadata self-test coverage for the new JSON field and key order.
• Updated changelog, roadmap, and session history.

Impact

• Operators and automation can now confirm that Product Readiness guard coverage ran without parsing release metadata errors.
• This changes release metadata JSON shape only. It does not change CLI runtime behavior, package/registry smoke runner behavior, release policy doc set, external MCP calls, target website repo mutation, backend storage, or dependencies.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py --json
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 363 — Product Readiness Warning Strict Release Metadata Guard (unreleased)

Release metadata now checks Product Readiness for the warning-state Website Console bundle-compare strict coverage wording. Phases 361-362 corrected the human-readable readiness summary; this phase makes that correction durable by failing release metadata when Product Readiness drops the warning-state compare contract.

Changed

• Added docs/PRODUCT-READINESS.md as a release metadata text input.
• Added a Product Readiness-specific warning strict compare phrase guard.
• Added a self-test drift fixture that removes warning-state bundle-compare strict coverage wording and expects release metadata to fail.
• Updated changelog, roadmap, and session history.

Impact

• Release metadata now catches Product Readiness regressions where Website Console compare coverage falls back to generic bundle comparison wording.
• This is release guard coverage only: no CLI runtime behavior, package/registry smoke runner behavior, release policy doc set, JSON schema, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 362 — Product Readiness Public Registry Warning Strict Compare Accuracy (unreleased)

Product readiness public-registry summaries now name the warning-state Website Console bundle-compare strict smoke path. Phase 361 fixed the local release-confidence wording; this phase aligns the post-publish registry-smoke summary so it does not hide the warning-state compare contract inside generic bundle-check/compare/handoff/repair coverage.

Changed

• Updated Product Readiness public-registry Website Console coverage wording.
• Made the published-package path explicitly include warning-state bundle-compare strict smoke coverage.
• Updated changelog, roadmap, and session history for the public-registry readiness wording.

Impact

• Product readiness now describes both packed-tarball and public-registry compare coverage with the same warning-state strict contract.
• This is documentation accuracy only: no CLI runtime behavior, package/registry smoke runner behavior, release metadata table, JSON schema, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 361 — Product Readiness Warning Strict Compare Accuracy (unreleased)

Product readiness now reflects the warning-state Website Console bundle-compare strict smoke coverage added in Phases 357-360. The readiness summary previously mentioned bundle digest comparison, but it did not explicitly say that warning-state identical bundles keep sameBundle: true while still exiting non-zero under --strict.

Changed

• Updated Product Readiness release confidence wording for Website Console bundle compare.
• Made the verified compare path include warning-state strict smoke coverage, identical warning bundles, sameBundle: true, and strict non-zero exits.
• Updated changelog, roadmap, and session history so completion status stays aligned with the current smoke contract.

Impact

• Product readiness no longer implies that only pass-state bundle comparison is covered.
• This is documentation accuracy only: no CLI runtime behavior, package smoke runner behavior, release metadata table, JSON schema, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 360 — Website Console Bundle Compare Warning Strict Release Metadata Guard (unreleased)

Release metadata now guards the warning-state Website Console bundle-compare strict smoke phrase across release-facing docs. Phase 359 added the packed-tarball and public-registry smoke execution; this phase makes sure release guidance cannot silently regress to only mentioning pass-state bundle comparison.

Changed

• Added a dedicated release metadata term group for warning-state Website Console bundle-compare strict failures.
• Required release policy docs to mention packed-tarball and public-registry smoke, identical warning bundles, sameBundle: true, and non-zero strict exits.
• Added a release metadata self-test drift fixture that removes the warning strict phrase and expects the guard to fail.
• Updated English/Korean release-facing docs, changelog, roadmap, and session history.

Impact

• Release metadata self-tests now catch docs drift where warning-state bundle-compare strict smoke coverage is dropped while the generic bundle-compare phrase remains.
• This is documentation and release guard coverage only: no CLI runtime behavior, package smoke runner behavior, JSON schema, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• python3 -m py_compile tools/audit/release-metadata.py
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 359 — Website Console Bundle Compare Warning Strict Smoke Coverage (unreleased)

Packed-tarball and public-registry smoke now verify warning-state Website Console bundle-compare strict failures. This extends the Phase 357 runtime/unit contract into distribution checks: identical warning bundles should keep sameBundle: true and digestMatch: true, but --bundle-compare --strict --json should still exit non-zero because optional MCP readiness warnings remain.

Changed

• Added a warning-only Website Console bundle fixture for smoke runners by omitting optional Sentry evidence while keeping the workspace structurally valid.
• Added a shared smoke assertion for warning-state bundle-compare strict JSON, checking exit code 1, status: "warn", valid: true, unchanged bundle identity, left/right warning states, and left/right compare warning issues.
• Wired the warning-state compare smoke through packed-tarball installed-bin, packed-tarball one-shot npm exec --package <tarball>, and public-registry npm exec --package @design-ai/cli@<version> paths.
• Updated changelog and session history beside the Phase 357-358 Website Console strict warning coverage.

Impact

• Distribution smoke now catches regressions where published or packed package paths silently drop warning-state strict failures for identical Website Console handoff bundles.
• This is smoke assertion and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/smoke_assertions.py
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 358 — Website Console Bundle Repair Warning Strict Exit Unit Coverage (unreleased)

Website Console bundle repair unit coverage now verifies warning-only strict exits on apply. Regenerating a bundle cannot clear optional MCP readiness warnings by itself, so --bundle-repair --yes --strict --json should remain non-zero when the repaired bundle still checks as warning-state.

Changed

• Reused the warning-only handoff bundle generated from the Website Console fixture where siteProfile.sentryProject is empty.
• Added CLI coverage for design-ai site <bundle-dir> --bundle-repair --yes --strict --json.
• Verified the repair applies, preserves before.status: "warn" and after.status: "warn", reports bundle-repair-verify-fail, and exits with code 1.
• Updated changelog and session history beside the Phase 330-357 Website Console strict/next-actions hardening work.

Impact

• Local tests now catch regressions where bundle repair apply falsely reports strict success even though regenerated bundle readiness warnings remain.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 357 — Website Console Bundle Compare Warning Strict Exit Coverage (unreleased)

Website Console bundle compare now preserves warning-state bundle-check results. Identical bundles with optional MCP readiness warnings should still compare as the same bundle, but --bundle-compare --strict --json should return non-zero because the compared artifacts are not strict-ready for target-repo handoff.

Changed

• Updated buildSiteBundleCompareReport to add left/right warning issues when either bundle-check report has status: "warn".
• Kept sameBundle tied to digest, changed-file, and metadata equality instead of overall compare status, so identical warning-state bundles still report sameBundle: true.
• Added CLI coverage for design-ai site <bundle-dir> --bundle-compare <same-bundle-dir> --strict --json using a warning-only Website Console handoff bundle.
• Updated changelog and session history beside the Phase 330-356 Website Console strict/next-actions hardening work.

Impact

• Operators can distinguish "the two bundles are identical" from "the identical bundle is strict-ready"; warning-state bundles now fail strict compare without losing identity information.
• This changes Website Console bundle-compare warning propagation only. It does not add external MCP calls, target website repo mutation, backend storage, dependencies, or schema fields.

Verified

• node --test cli/lib/site.test.mjs
• npm test
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 356 — Website Console Bundle Handoff Warning Strict Exit Unit Coverage (unreleased)

Website Console bundle handoff unit coverage now verifies warning-only strict exits. Target-repo handoff prompts generated from structurally valid but warning-state bundles should preserve the bundle warning context and fail --bundle-handoff --strict --json before implementation handoff.

Changed

• Reused the warning-only handoff bundle generated from the Website Console fixture where siteProfile.sentryProject is empty.
• Verified design-ai site <bundle-dir> --bundle-handoff --strict --json emits status: "warn" and exits with code 1.
• Verified the handoff payload remains valid: true, preserves bundle.mcpStatus: "warn", reports bundle-readiness-warn, and includes the local bundle-check warning in the target-repo prompt.
• Updated changelog and session history beside the Phase 330-355 Website Console strict/next-actions hardening work.

Impact

• Local tests now catch regressions where bundle handoff prompt generation treats warning-only bundles as strict-pass implementation inputs.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 355 — Website Console Bundle Check Warning Strict Exit Unit Coverage (unreleased)

Website Console handoff bundle check unit coverage now verifies warning-only strict exits. A generated bundle with optional MCP readiness warnings should remain structurally valid, but --bundle-check --strict --json should return non-zero and surface the readiness warning before target-repo handoff.

Changed

• Reused the warning-only handoff bundle generated from the Website Console fixture where siteProfile.sentryProject is empty.
• Verified design-ai site <bundle-dir> --bundle-check --strict --json emits status: "warn" and exits with code 1.
• Verified the bundle remains valid: true, preserves summary.status: "warn" and mcpStatus: "warn", and reports the bundle-readiness-warn issue.
• Updated changelog and session history beside the Phase 330-354 Website Console strict/next-actions hardening work.

Impact

• Local tests now catch regressions where bundle verification treats warning-only handoff bundles as strict-pass artifacts before target-repo handoff.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 354 — Website Console Bundle Warning Strict Exit Unit Coverage (unreleased)

Website Console handoff bundle unit coverage now verifies warning-only strict exits. Bundle generation should still write the local artifact, preserve MCP readiness warning status inside the bundle, and return non-zero under --strict when optional readiness gaps remain.

Changed

• Reused the warning-only Website Console fixture where siteProfile.sentryProject is empty while required MCP readiness remains satisfied.
• Verified design-ai site <workspace.json> --bundle --out <dir> --strict writes the handoff bundle and exits with code 1.
• Verified generated summary.json and mcp-check.json both preserve status: "warn" for the optional Sentry readiness gap.
• Updated changelog and session history beside the Phase 330-353 Website Console strict/next-actions hardening work.

Impact

• Local tests now catch regressions where bundle generation hides warning-only MCP gaps or returns success under strict mode.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 353 — Website Console Workflow Graph Warning Strict Exit Unit Coverage (unreleased)

Website Console workflow graph unit coverage now verifies warning-only strict exits. Portable graph exports should preserve MCP readiness warnings and fail --graph --strict --json when optional readiness gaps remain.

Changed

• Reused the warning-only Website Console fixture where siteProfile.sentryProject is empty while required MCP readiness remains satisfied.
• Verified design-ai site <workspace.json> --graph --strict --json emits status: "warn" and exits with code 1.
• Verified the graph keeps workspaceStatus: "pass" while propagating mcpStatus: "warn" into the top-level graph and summary payload.
• Updated changelog and session history beside the Phase 330-352 Website Console strict/next-actions hardening work.

Impact

• Local tests now catch regressions where portable workflow graph exports drop MCP warning status or bypass strict mode.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 352 — Website Console MCP Check Warning Strict Exit Unit Coverage (unreleased)

Website Console MCP readiness unit coverage now verifies warning-only strict exits at the source gate. Optional MCP readiness warnings should fail --mcp-check --strict --json before action plans or next-actions consume the same readiness state.

Changed

• Reused the warning-only Website Console fixture where siteProfile.sentryProject is empty while required MCP readiness remains satisfied.
• Verified design-ai site <workspace.json> --mcp-check --strict --json emits status: "warn" and exits with code 1.
• Verified the Sentry readiness item remains optional, missing, and warn, with exactly one missing readiness item in the report.
• Updated changelog and session history beside the Phase 330-351 Website Console strict/next-actions hardening work.

Impact

• Local tests now catch regressions where the MCP readiness source gate allows optional warning-only gaps through strict mode.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 351 — Website Console MCP Plan Warning Strict Exit Unit Coverage (unreleased)

Website Console MCP action-plan unit coverage now verifies warning-only strict exits. Optional MCP readiness warnings should fail --mcp-plan --strict --json the same way they fail summary and next-actions strict gates, so planning gaps do not pass through CI or operator checks unnoticed.

Changed

• Reused the warning-only Website Console fixture where siteProfile.sentryProject is empty while required MCP readiness remains satisfied.
• Verified design-ai site <workspace.json> --mcp-plan --strict --json emits status: "warn" with zero blocking items.
• Verified the action-plan warning list includes the optional Sentry readiness gap and still exposes the strict MCP check follow-up command.
• Updated changelog and session history beside the Phase 330-350 Website Console strict/next-actions hardening work.

Impact

• Local tests now catch regressions where MCP action-plan strict mode exits cleanly for warning-only readiness gaps.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 350 — Website Console Next Actions Warning Strict Exit Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies warning-only strict exits. Optional MCP readiness warnings should still fail --strict so operators resolve readiness planning before target-repo implementation.

Changed

• Added a runSite warning-only fixture where siteProfile.sentryProject is empty while required MCP readiness remains satisfied.
• Verified design-ai site <workspace.json> --next-actions --strict --json emits status: "warn" with zero blocking actions.
• Verified the first action is the optional Sentry readiness warning and strict mode exits with code 1.
• Updated changelog and session history beside the Phase 330-349 next-actions hardening work.

Impact

• Local tests now catch regressions where --next-actions --strict only fails hard blockers and accidentally allows warning-only MCP planning gaps through.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 349 — Website Console Next Actions Rank Sequence Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies action rank sequencing after severity sorting. Human checklist numbering and JSON rank fields should always start at 1 and remain gapless across pass, warning, and blocking paths.

Changed

• Added pass-state rank assertions for the default implementation, evidence, and bundle actions.
• Added warning-state rank assertions for optional MCP readiness guidance.
• Added blocking-state rank assertions to ensure severity sorting still renumbers the final action list from 1.
• Updated changelog and session history beside the Phase 330-348 next-actions hardening work.

Impact

• Local tests now catch regressions where sorted next-actions keep stale rank numbers or produce gaps in operator checklists.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 348 — Website Console Next Actions Top-Task Cap Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies the top-task cap. The payload should report the total task count while exposing only the three highest-priority tasks for operator focus.

Changed

• Extended the multi-task next-actions scenario to include a fourth P3 refactor task.
• Verified counts.tasks preserves the full task count.
• Verified topTasks remains capped at three entries and excludes the lower-priority P3 task.
• Updated changelog and session history beside the Phase 330-347 next-actions hardening work.

Impact

• Local tests now catch regressions where next-actions payloads become too noisy or lose the total task count when more than three refactor tasks exist.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 347 — Website Console Next Actions Priority Selection Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies multi-task priority selection. When a workspace has P0/P1/P2 refactor tasks, the operator checklist should surface the P0 task first for Codex implementation.

Changed

• Added a multi-task buildSiteNextActionsReport scenario with P0, P1, and P2 refactor tasks.
• Verified topTasks are sorted in P0/P1/P2 order.
• Verified the first implementation action targets the P0 task and keeps the highest-priority rationale.
• Updated changelog and session history beside the Phase 330-346 next-actions hardening work.

Impact

• Local tests now catch regressions where Website Console next-actions selects a lower-priority implementation task before a P0 task.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 346 — Website Console Next Actions Stdin Command Target Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies stdin command targets. When the workspace source is stdin, the JSON follow-up commands should use the portable <workspace.json> placeholder instead of leaking a filesystem path.

Changed

• Added buildSiteNextActionsReport assertions for a summary with filePath: "stdin".
• Verified the full stdin commands block uses <workspace.json> for summary, MCP check, MCP plan, task generation, implementation prompt, handoff report, and handoff bundle commands.
• Verified formatted next-actions JSON preserves the same stdin command object as the in-memory report.
• Updated changelog and session history beside the Phase 330-345 next-actions hardening work.

Impact

• Local tests now catch regressions where stdin-based next-actions payloads emit unusable or environment-specific follow-up commands.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 345 — Website Console Next Actions Command Set Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies the full JSON commands block. This complements package/public smoke checks that inspect selected commands by ensuring the local unit suite catches drift in every follow-up command emitted by the operator checklist.

Changed

• Added buildSiteNextActionsReport assertions for the full command set: summary, MCP check, MCP plan, task generation, implementation prompt, handoff report, and handoff bundle.
• Verified the formatted next-actions JSON preserves the same command object as the in-memory report.
• Updated changelog and session history beside the Phase 330-344 next-actions hardening work.

Impact

• Local tests now catch regressions where a follow-up command disappears or changes in the next-actions JSON payload before package/public smoke runs.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 344 — Website Console Next Actions Warning Path Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies warning-state MCP guidance. Optional MCP readiness gaps and task/MCP status mismatches should warn operators and route them to the MCP action plan before target-repo implementation starts.

Changed

• Added a missing optional Sentry readiness scenario where siteProfile.sentryProject is empty while mcpReadiness.sentry remains optional.
• Verified the optional MCP warning ranks first, explains the missing evidence, and points to design-ai site <workspace.json> --mcp-plan --out mcp-action-plan.md.
• Added a task/MCP gap scenario where a refactor task recommends Figma while mcpReadiness.figma is marked unused.
• Verified the task gap warning preserves task/MCP references and uses the same MCP action-plan command.
• Updated changelog and session history beside the Phase 330-343 next-actions hardening work.

Impact

• Local tests now catch regressions where warning-state Website Console workspaces skip MCP planning and jump straight to implementation guidance.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 343 — Website Console Next Actions Evidence Trail Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies the implementation evidence handoff reminder. The operator checklist should ask for website-handoff.md evidence when executed work or verification results are empty, and skip that reminder once both are recorded.

Changed

• Added assertions for the Create implementation evidence trail next-actions item in the default sample workspace.
• Verified the evidence reminder command points to design-ai site <workspace.json> --report --out website-handoff.md in JSON-backed actions and human Markdown.
• Added an evidence-ready workspace scenario with executed work and verification results populated, verifying the handoff reminder is not emitted.
• Updated changelog and session history beside the Phase 330-342 next-actions hardening work.

Impact

• Local tests now catch regressions where operators lose the handoff evidence reminder or keep seeing it after evidence is already recorded.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 342 — Website Console Next Actions Setup Path Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies the no-task setup path. When a workspace has no refactorTasks, the operator checklist must recommend generating starter tasks before preparing implementation prompts.

Changed

• Added buildSiteNextActionsReport assertions for an empty refactorTasks workspace.
• Verified the next-actions report stays pass, reports zero tasks, has no top tasks, and ranks Generate starter refactor tasks as the first setup action.
• Verified the generated command and human Markdown output point to design-ai site <workspace.json> --tasks --out website-workspace.tasks.json.
• Updated changelog and session history beside the Phase 330-341 next-actions hardening work.

Impact

• Local tests now catch regressions where no-task workspaces skip task generation and jump directly to implementation or handoff guidance.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 341 — Website Console Next Actions Strict Failure Unit Coverage (unreleased)

Website Console next-actions unit coverage now verifies the fail-state path where required MCP readiness is missing. This keeps the operator checklist honest when it should block target-repo implementation instead of only covering the pass and saved-file paths.

Changed

• Extended buildSiteNextActionsReport assertions for a missing GitHub readiness scenario.
• Verified fail-state JSON and human next-actions output rank the required MCP readiness blocker first.
• Added runSite([workspace, "--next-actions", "--strict", "--json"]) coverage to ensure strict mode exits non-zero for fail-state next-actions output.
• Updated changelog and session history beside the Phase 330-340 next-actions hardening work.

Impact

• Local tests now catch regressions where next-actions keeps rendering but stops enforcing blocking MCP readiness through strict exit behavior.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 340 — Website Console Next Actions Help Usage Unit Coverage (unreleased)

Website Console help unit coverage now verifies the design-ai site <workspace.json> --next-actions [--json] [--out file] [--force] Usage line directly. This keeps command discovery aligned with the JSON and human Markdown next-actions output-file workflows added and hardened in Phases 330-339.

Changed

• Added a runSite(["--help"]) assertion for the next-actions Usage line.
• Updated changelog and session history so the help coverage sits beside the existing next-actions output-file smoke, help example, release guard, and unit persistence work.

Impact

• Local tests now catch a stale site --help Usage block that drops the --next-actions output-file workflow while the runtime still supports it.
• This is CLI help test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 339 — Website Console Next Actions Markdown Output-File Unit Coverage (unreleased)

Website Console unit coverage now verifies the human Markdown design-ai site --next-actions --out file --force path directly in cli/lib/site.test.mjs. This complements the existing packed/public smoke coverage with a faster local regression check for the operator-facing next-actions runbook artifact.

Changed

• Added a direct runSite unit assertion for saving human next-actions Markdown to an output file.
• Verified forced overwrite replacement by seeding stale output before running --force.
• Checked the saved Markdown for prioritized command text, local/operator boundary text, and absence of JSON payload shape.
• Updated changelog and session history so the coverage intent remains visible beside the Phase 336-338 smoke/help/release guard work.

Impact

• Local test runs now catch regressions where --next-actions --out stops writing human Markdown correctly even if JSON output still works.
• This is unit test and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/site.test.mjs
• npm run release:metadata
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 338 — Website Console Next Actions Help Example Release Guard (unreleased)

Release metadata now guards the design-ai site website-workspace.json --next-actions --out website-next-actions.md help example across release-facing docs. This keeps Phase 337's human Markdown next-actions runbook example visible in the release ritual, not only in CLI help smoke assertions.

Changed

• Added a release metadata term group for the Website Console next-actions Markdown help example.
• Added the term group to required release policy phrase labels and checks.
• Added a release metadata self-test drift fixture that fails when README guidance drops the concrete help example.
• Updated README, Korean README, Release Checklist, and English/Korean Distribution docs to mention the next-actions Markdown help example beside shared site help topic smoke assertions.

Impact

• Release-facing docs cannot silently drop the human next-actions Markdown help example while retaining generic site help topic smoke wording.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, output formatter, smoke command execution, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 337 — Website Console Next Actions Help Example Coverage (unreleased)

Website Console help now shows the human Markdown next-actions output-file workflow directly in design-ai site --help. This keeps the operator-facing runbook checkpoint discoverable without requiring users to infer it from the generic --out file option.

Changed

• Added design-ai site website-workspace.json --next-actions --out website-next-actions.md to the site command help examples.
• Added CLI help unit coverage for the new next-actions Markdown output-file example.
• Added shared package/public-registry smoke assertion coverage so design-ai help site must retain the human next-actions output-file example.
• Updated English and Korean Website Improvement docs to show and explain the Markdown next-actions checkpoint alongside JSON next-actions output.

Impact

• Operators can discover both machine-readable next-actions JSON and human-readable next-actions Markdown from command help and docs.
• This is help/documentation/smoke assertion coverage only: no CLI runtime behavior, JSON schema, output formatter, external MCP call, target website repo mutation, backend storage, or new dependency changed.

Verified

• node --test cli/lib/help-command.test.mjs
• node cli/bin/design-ai.mjs help site | rg -n "next-actions|website-next-actions"
• python3 -m py_compile tools/audit/smoke_assertions.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 336 — Website Console Next Actions Human Output-File Smoke Coverage (unreleased)

Packed-tarball and public-registry smoke now verify design-ai site --stdin --next-actions --out file --force human Markdown output-file persistence. This complements the Phase 334 JSON saved-file smoke by checking the operator-facing report that humans copy into local runbooks.

Changed

• Added shared smoke assertions for Website Console next-actions human output files.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> next-actions Markdown output files.
• Added public-registry smoke coverage for published-package npm exec --package @design-ai/cli@<version> next-actions Markdown output files.
• Added package, registry, and shared assertion self-test fixtures for Markdown output-file persistence and boundary drift.
• Added release metadata guard coverage and release-facing docs guidance for the human output-file smoke phrase.

Impact

• Release smoke now checks both machine-readable JSON and human-readable Markdown saved-file next-action reports, including forced overwrite replacement and local/read-only boundary text.
• This is smoke/assertion/documentation coverage only: no CLI runtime behavior, JSON schema, command semantics, external MCP call, target website repo mutation, backend storage, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 335 — Website Console Next Actions Output-File Release Guard (unreleased)

Release metadata now guards the design-ai site --stdin --next-actions --json --out file --force next-action output-file smoke phrase across release-facing docs. This keeps Phase 334's installed-bin, one-shot, and public-registry output-file coverage visible in the release ritual.

Changed

• Added a release metadata term group for Website Console next-actions output-file smoke coverage.
• Added the term group to the required release policy phrase labels and checks.
• Added a self-test drift fixture that fails when README guidance drops the next-actions output-file phrase.
• Updated README, Korean README, Release Checklist, and English/Korean Distribution docs to mention the installed-bin, one-shot, and public-registry output-file smoke contract.

Impact

• Release-facing docs cannot silently drop the saved-file next-action smoke guidance while retaining stdout next-action smoke coverage.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, smoke command execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 334 — Website Console Next Actions Output-File Smoke Coverage (unreleased)

Packed-tarball and public-registry smoke now verify design-ai site --stdin --next-actions --json --out file --force output-file persistence. This closes the remaining release-smoke gap after Phase 331 and Phase 332 covered stdout JSON execution for the next-action operator checklist.

Changed

• Added a shared assert_site_next_actions_json_file_output helper that validates write confirmation plus the saved next-action JSON contract.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> next-action JSON output files.
• Added public-registry smoke coverage for published-package npm exec --package @design-ai/cli@<version> next-action JSON output files.
• Added package, registry, and shared assertion self-test fixtures for next-action JSON file-output persistence.

Impact

• Release smoke now checks both stdout and saved-file next-action reports, including forced overwrite replacement and local/read-only boundary fields.
• This is smoke/runtime coverage only: no CLI schema, command semantics, external MCP call, target website repo mutation, backend storage, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/smoke_assertions.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 333 — Website Console Next Actions Registry Smoke Release Guard (unreleased)

Release metadata now guards the public registry design-ai site --stdin --next-actions --json next-action operator checklist smoke phrase across release-facing docs. This keeps Phase 332's post-publish registry coverage visible beside the broader Website Console public registry smoke guidance.

Changed

• Added a release metadata term group for public registry Website Console next-actions smoke coverage.
• Added the term group to the required release policy phrase labels and checks.
• Added a self-test drift fixture that fails when README guidance drops the public registry next-actions phrase.
• Updated README, Korean README, Release Checklist, and English/Korean Distribution docs to mention the public registry next-actions operator checklist contract.

Impact

• Release-facing docs cannot silently keep generic Website Console registry smoke wording while dropping the specific next-actions JSON smoke contract.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, smoke command execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 332 — Website Console Next Actions Public Registry Smoke Coverage (unreleased)

Public-registry smoke now directly executes design-ai site --stdin --next-actions --json through the published-package npm exec --package @design-ai/cli@<version> path. This aligns next-action release verification with the Website Console smoke pattern used for MCP probe outputs and handoff bundle checks after publish.

Changed

• Added assert_site_next_actions_json to the registry smoke assertion imports and self-test path.
• Added a registry smoke helper that feeds the shared Website Console sample workspace through stdin and verifies the next-action JSON contract.
• Added the published-package npm exec smoke call immediately after the baseline site --stdin --json registry check.

Impact

• Post-publish smoke now catches registry-only regressions in the next-action operator checklist, including boundary flags, ranked actions, top task selection, and follow-up commands.
• This remains deterministic and local: no external MCP call, target website repo mutation, backend storage, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/smoke_assertions.py
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 331 — Website Console Next Actions Package Smoke Coverage (unreleased)

Packed-tarball smoke now directly executes design-ai site --stdin --next-actions --json through both installed-bin and one-shot npm exec --package <tarball> paths. This closes the gap between Phase 330's unit coverage and release-package runtime coverage for the next-action operator checklist.

Changed

• Added shared assert_site_next_actions_json smoke assertions for the website-improvement-next-actions JSON contract.
• Added negative self-test fixtures for ANSI output, boundary flag drift, missing ranked actions, and implementation prompt command drift.
• Added installed-bin and one-shot npm exec package smoke calls for site --stdin --next-actions --json.

Impact

• Release smoke now verifies that packed artifacts can execute the next-action checklist, not only advertise it through help text.
• This remains deterministic and local: no external MCP call, target website repo mutation, backend storage, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• npm run release:metadata
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 330 — Website Console Next Actions CLI (unreleased)

design-ai site --next-actions [--json] now turns a Website Improvement workspace into a prioritized local operator checklist. The report helps decide whether to fix validation/MCP blockers, generate tasks, prepare the selected Codex implementation prompt, preserve handoff evidence, or export a bundle before touching the target website repo.

Changed

• Added --next-actions as a read-only design-ai site output mode with human and JSON formats.
• Built the next-action payload from existing workspace validation, MCP readiness, task/MCP gap, refactor task, implementation evidence, and bundle command data.
• Updated command-specific help, top-level help catalog expectations, README command lists, Website Improvement docs, Distribution docs, and Product Readiness notes.
• Added unit coverage for argument parsing, invalid mode combinations, payload shape, human formatting, and --out file persistence.

Impact

• Operators can ask the CLI "what should I do next?" without opening the static console or manually reading the MCP action plan.
• This remains deterministic and local: no external MCP call, target website repo mutation, backend storage, new dependency, or --yes apply behavior changed.

Verified

• node --check cli/lib/site.mjs && node --check cli/commands/site.mjs && node --check cli/commands/help.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm test
• npm run audit:strict
• npm run package:check
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 329 — MCP Action Plan Command Mapping Self-Test Release Guard (unreleased)

Release metadata now guards the shared MCP action plan command mapping self-test coverage phrase across release-facing docs. The guard keeps Phase 328's shared smoke_assertions.py --self-test parity coverage visible beside the action-plan emitted human report, check JSON, and self-archive command smoke guidance.

Changed

• Added a release metadata term group for shared MCP action plan command mapping self-test coverage.
• Added a release policy label/check for the shared command mapping self-test phrase.
• Updated README, Korean README, distribution docs, and release checklist guidance to mention shared MCP action plan command mapping self-test coverage.
• Added a self-test drift fixture that fails when README guidance drops the shared command mapping self-test phrase.
• Updated CHANGELOG and SESSION-LOG entries for the release guard.

Impact

• Release-facing docs must now preserve that action-plan emitted JSON command mapping is guarded by shared self-tests, not only by package/public-registry runtime smoke.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, smoke command execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 328 — MCP Action Plan Embedded Command Self-Test Parity (unreleased)

Shared smoke assertion self-tests now map the action-plan emitted mcpCheckProbesJsonOut and mcpPlanProbesJsonOut commands back to executable design-ai site --stdin ... --out file --force argv. This keeps the common assertion layer aligned with the packed-tarball and public-registry smoke paths that already execute those action-plan emitted commands.

Changed

• Added action-plan payload self-test coverage for the emitted MCP readiness probe JSON archive command.
• Added action-plan payload self-test coverage for the emitted MCP action-plan self-archive JSON command.
• Added a negative drift fixture for action-plan emitted mcpPlanProbesJsonOut command shape changes.
• Updated CHANGELOG and SESSION-LOG entries for the shared self-test parity coverage.

Impact

• Local smoke_assertions.py --self-test now catches action-plan emitted JSON command mapping drift before package or public registry smoke executes the commands.
• This changes shared test coverage only: no CLI runtime behavior, JSON schema, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 327 — MCP Action Plan Check JSON Release Guard (unreleased)

Release metadata now guards the MCP action plan emitted check JSON command smoke coverage phrase across release-facing docs. The guard keeps Phase 323's action-plan emitted mcpCheckProbesJsonOut execution visible beside the existing human report and self-archive action-plan command smoke guidance.

Changed

• Added a release metadata term group for MCP action plan emitted check JSON command smoke coverage.
• Added a release policy label/check for the check JSON command smoke phrase.
• Updated README, Korean README, distribution docs, and release checklist guidance to mention action-plan emitted check JSON command smoke coverage.
• Added a self-test drift fixture that fails when README guidance drops the check JSON smoke phrase.
• Updated CHANGELOG and SESSION-LOG entries for the release guard.

Impact

• Release-facing docs must now preserve that action-plan emitted mcpCheckProbesJsonOut is smoke-executed, not only present as schema guidance.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, smoke command execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 326 — MCP Action Plan Emitted JSON Drift Fixtures (unreleased)

Package and registry smoke self-tests now include negative drift fixtures for action-plan emitted JSON outputs. The local self-test path fails if the action-plan emitted mcpCheckProbesJsonOut report claims external calls or if the action-plan emitted mcpPlanProbesJsonOut self-archive report claims target-repo mutation.

Changed

• Added a package smoke negative self-test fixture for action-plan emitted MCP check probe JSON output.
• Added a package smoke negative self-test fixture for action-plan emitted MCP action-plan self-archive JSON output.
• Added the same registry smoke negative self-test fixtures for the published-package smoke assertion path.
• Updated CHANGELOG and SESSION-LOG entries for the emitted JSON drift fixture coverage.

Impact

• The action-plan emitted JSON output self-tests now guard both command mapping and local/read-only boundary drift.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 325 — MCP Action Plan Self-Archive Release Guard (unreleased)

Release metadata now guards the MCP action plan emitted self-archive command smoke coverage phrase across release-facing docs. The guard keeps Phase 324's mcpPlanProbesJsonOut action-plan payload execution visible beside the existing action-plan human report command smoke guidance.

Changed

• Added a release metadata term group for MCP action plan emitted self-archive command smoke coverage.
• Added a release policy label/check for the self-archive command smoke phrase.
• Updated README, Korean README, distribution docs, and release checklist guidance to mention action-plan emitted self-archive command smoke coverage.
• Added a self-test drift fixture that fails when README guidance drops the self-archive smoke phrase.
• Updated CHANGELOG and SESSION-LOG entries for the release guard.

Impact

• Release-facing docs must now preserve that action-plan emitted mcpPlanProbesJsonOut is smoke-executed, not only present as schema guidance.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, smoke command execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 324 — MCP Action Plan Self-Archive Command Smoke Execution (unreleased)

Packed-tarball and public-registry smoke now execute the mcpPlanProbesJsonOut command emitted by design-ai site --mcp-plan --probes --json action-plan payloads themselves. This closes the last action-plan emitted command parity gap: the payload can now prove its own JSON archive command works, not only the human readiness report and MCP check probe JSON archive commands.

Changed

• Added package smoke execution for action-plan emitted mcpPlanProbesJsonOut in installed-bin and one-shot npm exec --package <tarball> paths.
• Added public-registry smoke execution for the same action-plan self-archive command.
• Added package and registry smoke self-test fixtures that replay the action-plan emitted plan JSON command through shared JSON file-output assertions.
• Updated CHANGELOG and SESSION-LOG entries for the self-archive command execution coverage.

Impact

• Action-plan payload command smoke coverage now covers all emitted output-preservation commands from the action-plan payload itself.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 323 — MCP Action Plan Check JSON Command Smoke Execution (unreleased)

Packed-tarball and public-registry smoke now execute the mcpCheckProbesJsonOut command emitted by design-ai site --mcp-plan --probes --json. This closes the remaining action-plan command execution gap: a structured action-plan payload can now preserve both the human readiness probe report and the machine-readable MCP readiness probe JSON without requiring operators to open the original MCP check payload.

Changed

• Added package smoke execution for action-plan emitted mcpCheckProbesJsonOut in installed-bin and one-shot npm exec --package <tarball> paths.
• Added public-registry smoke execution for the same action-plan emitted readiness probe JSON preservation command.
• Added package and registry smoke self-test fixtures that replay the action-plan emitted check JSON command through shared JSON file-output assertions.
• Updated CHANGELOG and SESSION-LOG entries for the command execution coverage.

Impact

• Action-plan payload command smoke coverage now includes human report output, MCP check probe JSON output, action-plan JSON output, and direct action-plan JSON generation.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 322 — MCP Action Plan Human Report Drift Fixtures (unreleased)

Package and registry smoke self-tests now include negative fixtures for the human readiness report generated from action-plan emitted mcpCheckProbesHumanOut commands. The local self-test path fails if the saved report loses the Probe commands guidance, matching the distribution smoke assertion that operators rely on for copy/paste follow-up commands.

Changed

• Added a package smoke negative self-test fixture for action-plan emitted human readiness report output.
• Added the same registry smoke negative self-test fixture for the public-package smoke assertion path.
• Updated CHANGELOG and SESSION-LOG entries for the drift fixture coverage.

Impact

• The action-plan emitted human report self-test now guards both command mapping and content drift.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 321 — MCP Action Plan Human Command Self-Test Hardening (unreleased)

Package and registry smoke self-tests now replay the mcpCheckProbesHumanOut command emitted by design-ai site --mcp-plan --probes --json through the same human readiness report file-output assertion used by distribution smoke. This keeps the local --self-test path aligned with the installed-bin, one-shot npm exec, and public-registry command execution coverage added in Phase 320.

Changed

• Added a package smoke self-test fixture that maps the action-plan JSON command to --stdin, --out, and --force, then validates the saved human MCP readiness probe report.
• Added the same registry smoke self-test fixture for the published-package smoke assertion path.
• Updated CHANGELOG and SESSION-LOG entries for the self-test hardening.

Impact

• Distribution smoke command execution is now backed by local runner-level self-tests, not only by shared assertion self-tests.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 320 — MCP Action Plan Human Command Smoke Execution (unreleased)

Packed-tarball and public-registry smoke now execute the mcpCheckProbesHumanOut command emitted by design-ai site --mcp-plan --probes --json. This closes the gap between action-plan JSON command parity and distribution verification: the action-plan payload must now produce a preserved human readiness probe report in installed-bin, one-shot npm exec, and published-package paths.

Changed

• Updated package smoke and registry smoke helpers so MCP action plan probe JSON smoke returns the parsed payload.
• Executed the action-plan emitted mcpCheckProbesHumanOut command in packed-tarball installed-bin smoke.
• Executed the same action-plan emitted command in one-shot npm exec --package <tarball> smoke.
• Executed the same action-plan emitted command in public-registry smoke.
• Added shared smoke assertion self-test coverage for mapping the action-plan payload's human report command to --stdin, --out, and --force.
• Added release metadata guard coverage and release-facing docs wording for MCP action plan emitted human report command smoke coverage.
• Updated CHANGELOG and SESSION-LOG entries for the smoke execution.

Impact

• Action-plan JSON command parity is now executable smoke coverage, not only schema guidance.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 319 — MCP Action Plan Human Command Release Guard (unreleased)

Release metadata now guards the MCP action plan human report output command parity phrase across release-facing docs. The guard keeps Phase 318's mcpCheckProbesHumanOut action-plan JSON parity visible beside the existing MCP probe action plan JSON output-file command guidance.

Changed

• Added a release metadata term group for MCP action plan human report output command parity.
• Added a release policy label/check for the action-plan human output command parity phrase.
• Updated README, Korean README, distribution docs, and release checklist guidance to mention the action-plan human report output command parity.
• Added a self-test drift fixture that fails when README guidance drops the action-plan parity phrase.
• Updated CHANGELOG and SESSION-LOG entries for the release guard.

Impact

• Release-facing docs must now preserve that MCP action plan JSON exposes the human readiness report preservation command.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, smoke command execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 318 — MCP Action Plan Human Report Command Parity (unreleased)

design-ai site --mcp-plan --probes --json now carries commands.mcpCheckProbesHumanOut alongside the existing probe JSON preservation commands. Operators can use a single MCP action-plan payload to discover both the human readiness report archive command and the machine-readable probe JSON archive command.

Changed

• Added mcpCheckProbesHumanOut to the structured MCP action plan JSON command map.
• Updated MCP action plan Markdown output indirectly through the shared command map so the human report archive command appears in the command list.
• Updated site unit tests for action-plan data, Markdown output, and runSite --mcp-plan --probes --json.
• Updated shared smoke assertion schema, fixture payload, command validation, and self-test drift coverage for the action-plan human report output command.
• Updated CHANGELOG and SESSION-LOG entries for the command parity change.

Impact

• MCP check probe JSON and MCP action plan JSON now both expose the human readiness report preservation command.
• This is deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 317 — MCP Check Human Output Command Release Guard (unreleased)

Release metadata now guards the embedded MCP check probe human report output command phrase across release-facing docs. The guard keeps the mcpCheckProbesHumanOut command contract visible beside human MCP check probe command guidance and output-file smoke coverage.

Changed

• Added a release metadata term group for embedded MCP check probe human report output commands.
• Added a release policy label/check for the human report output command phrase.
• Added a self-test drift fixture that fails when README guidance drops the embedded human report output command phrase.
• Updated README, Korean README, distribution docs, and release checklist guidance to mention the embedded human report output command.
• Updated CHANGELOG and SESSION-LOG entries for the release guard.

Impact

• Release-facing docs must now preserve the mcpCheckProbesHumanOut contract independently from the broader human command guidance phrase.
• This is release metadata and documentation coverage only: no CLI runtime behavior, JSON schema, smoke command execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 316 — MCP Check Probe Embedded Human Report Command (unreleased)

design-ai site --mcp-check --probes --json now embeds commands.mcpCheckProbesHumanOut alongside the existing probe JSON and action-plan commands. Human probe output also shows a matching Save readiness probe report command, and package/public-registry smoke executes the embedded command to verify that it writes a preserved human report with the Probe commands section intact.

Changed

• Added mcpCheckProbesHumanOut to buildSiteMcpProbeCommandSet.
• Added Save readiness probe report to the Probe commands section in MCP check probe human output.
• Updated site unit tests to verify the new JSON command field and human output command line.
• Extended shared smoke assertions and embedded command parsing to support mcpCheckProbesHumanOut.
• Wired packed-tarball installed-bin, one-shot npm exec --package <tarball>, and public-registry smoke to execute the embedded human report output command.
• Updated CHANGELOG and SESSION-LOG entries for the embedded human report command.

Impact

• Machine-readable MCP readiness probe payloads now expose both human report and JSON report preservation commands.
• Existing non-probe MCP check JSON remains unchanged; this only expands probe-enabled commands.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 315 — MCP Check Probe Human Output Persistence Smoke (unreleased)

design-ai site --stdin --mcp-check --probes --out file is now covered by unit and distribution smoke tests. The persisted human report must retain the readiness summary, read-only probe section, and Probe commands guidance so operators can archive the exact human handoff output alongside JSON probe evidence.

Changed

• Added site unit coverage for writing the probe-enabled MCP check human report to --out file.
• Added assert_site_mcp_check_probes_human_file_output to shared smoke assertions.
• Wired packed-tarball installed-bin and one-shot npm exec --package <tarball> smoke to verify human probe report --out file persistence.
• Wired public-registry smoke to verify the same human probe report persistence from the published package path.
• Updated release metadata phrase guards and release-facing docs to name human MCP check probe command guidance and output-file smoke coverage.

Impact

• Human MCP readiness probe reports are now preservation-tested like the existing JSON probe payloads.
• This is verification coverage only: no CLI runtime behavior, JSON schema, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 314 — MCP Check Probe Human Smoke Coverage (unreleased)

Packed-tarball and public-registry smoke now verify design-ai site --stdin --mcp-check --probes human output. The shared smoke assertion checks the readiness summary, read-only probe section, and the Probe commands copy/paste guidance that points operators to readiness JSON preservation and structured MCP action plan JSON generation.

Changed

• Added passing_site_mcp_check_probes_human and assert_site_mcp_check_probes_human to tools/audit/smoke_assertions.py.
• Added self-test drift coverage for losing the Probe commands section from MCP check probe human output.
• Wired packed-tarball installed-bin and one-shot npm exec --package <tarball> smoke to run site --stdin --mcp-check --probes without --json.
• Wired public-registry smoke to run the same human output check through npm exec --package @design-ai/cli@<version>.
• Updated release-facing smoke guidance and project history docs for the human probe command guidance smoke coverage.

Impact

• The Phase 313 human output guidance is now protected at the same distribution boundaries as the existing JSON probe command contract.
• This is smoke coverage only: no CLI runtime behavior, JSON schema, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 313 — MCP Check Probe Human Command Guidance (unreleased)

design-ai site --mcp-check --probes now shows the same probe follow-up commands in human output that probe-enabled JSON already carries. Operators can save the readiness probe JSON, generate the structured probe action plan JSON, and save that action plan from the visible report without switching to --json. The default --mcp-check human output remains unchanged.

Changed

• Added a Probe commands section to formatSiteMcpCheckHuman when the report includes read-only probe commands.
• Kept the default non-probe MCP readiness human output free of probe command guidance.
• Added site unit tests for formatted probe reports and runSite human output to verify the command section and default-output boundary.
• Updated CHANGELOG and SESSION-LOG entries for the human command guidance.

Impact

• Human operators get the same copy/paste next-step path as JSON consumers when they run MCP readiness probes.
• This is presentation-only CLI behavior: no external MCP call, target website repo mutation, smoke runner behavior, release metadata policy, new dependency, or --yes apply behavior changed.

Verified

• node --test cli/lib/site.test.mjs
• node cli/bin/design-ai.mjs site --sample | node cli/bin/design-ai.mjs site --stdin --mcp-check --probes
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 312 — MCP Check Executable Embedded Command Release Guard (unreleased)

Release metadata now protects the release-facing documentation phrase for executable embedded MCP check probe command smoke coverage. The guard ties Phase 311's package/public-registry smoke execution of mcpCheckProbesJsonOut, mcpPlanProbesJson, and mcpPlanProbesJsonOut to README, Release Checklist, and Distribution guidance, so docs cannot describe static embedded command guidance while omitting that the emitted commands are executed by smoke.

Changed

• Added RELEASE_SITE_MCP_CHECK_EXECUTABLE_COMMANDS_TERM_GROUPS to tools/audit/release-metadata.py.
• Added site MCP check executable embedded command smoke phrase to release policy phrase labels and checks.
• Updated README, README.ko, Distribution docs, and Release Checklist release smoke guidance to name executable embedded MCP check probe command smoke coverage.
• Added a release metadata self-test drift fixture that fails when README guidance drops the executable embedded command smoke phrase.
• Updated CHANGELOG and SESSION-LOG entries for the release-policy guard.

Impact

• Release-facing docs now fail npm run release:metadata if they describe MCP readiness probe JSON --out plus embedded command guidance but omit executable embedded command smoke coverage.
• This is release-policy hardening only: no CLI runtime behavior, package smoke execution path, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 311 — MCP Check Probe Embedded Command Smoke Execution (unreleased)

Packed-tarball and public-registry smoke now execute the embedded commands emitted by design-ai site --mcp-check --probes --json. Instead of only checking that the commands payload shape is present, the smoke runners rewrite the <workspace.json> placeholder to --stdin, map the command onto the active installed-bin / one-shot npm exec / published-package runner, and verify the emitted readiness probe --out, action-plan JSON, and action-plan JSON --out commands.

Changed

• Added site_mcp_probe_embedded_command to tools/audit/smoke_assertions.py.
• Added self-test coverage that verifies embedded MCP probe commands map to stdin and forced output paths, and fail when the command body drifts.
• Updated package smoke and registry smoke helpers so assert_site_mcp_check_probes_json_smoke returns the parsed payload after validation.
• Updated packed-tarball installed-bin, packed-tarball one-shot npm exec, and public-registry smoke flows to execute mcpCheckProbesJsonOut, mcpPlanProbesJson, and mcpPlanProbesJsonOut from the emitted payload.
• Updated CHANGELOG and SESSION-LOG entries for the executable embedded command smoke coverage.

Impact

• The commands object in MCP readiness probe JSON is now verified as executable guidance, not just a static JSON shape.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• node --test cli/lib/site.test.mjs
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 310 — MCP Check Probe Embedded Command Release Guard (unreleased)

Release metadata now protects the release-facing documentation phrase for embedded MCP check probe next-step commands. The guard ties Phase 309's design-ai site --mcp-check --probes --json commands payload to README, Release Checklist, and Distribution guidance, so docs cannot describe MCP readiness probe JSON --out persistence while omitting the embedded mcpCheckProbesJsonOut / mcpPlanProbesJson / mcpPlanProbesJsonOut command contract.

Changed

• Added RELEASE_SITE_MCP_CHECK_COMMANDS_TERM_GROUPS to tools/audit/release-metadata.py.
• Added site MCP check embedded command phrase to release policy phrase labels and checks.
• Updated README, README.ko, Distribution docs, and Release Checklist release smoke guidance to name embedded MCP check probe next-step commands.
• Added a release metadata self-test drift fixture that fails when README guidance drops the embedded MCP check command phrase.
• Updated CHANGELOG and SESSION-LOG entries for the release-policy guard.

Impact

• Release-facing docs now fail npm run release:metadata if they keep MCP readiness probe JSON --out coverage but drop the embedded probe payload command contract.
• This is release-policy hardening only: no CLI runtime behavior, package smoke execution path, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 309 — MCP Check Probe Output Commands (unreleased)

design-ai site --mcp-check --probes --json now embeds the preservation and next-step command hints directly in the probe payload. The default non-probe MCP check JSON shape stays unchanged, while probe-enabled reports include mcpCheckProbesJsonOut, mcpPlanProbesJson, and mcpPlanProbesJsonOut so operators can save readiness evidence and continue into the structured MCP action plan from the same machine-readable output.

Changed

• Added shared Website Console MCP command target helpers in cli/lib/site.mjs.
• Added a commands object only to probe-enabled MCP check JSON reports.
• Reused the same probe output command builder for structured MCP action plan JSON output-file commands without expanding the action-plan command key set.
• Updated site unit tests to verify the default MCP check JSON remains stable and the probe JSON exposes the embedded command hints.
• Updated shared package/public-registry smoke assertion fixtures, validators, and self-test drift coverage for the probe report command contract.
• Updated CHANGELOG and SESSION-LOG entries for the MCP check probe command payload.

Impact

• Machine-readable MCP readiness probe reports now carry copy/paste preservation and next-step commands alongside probe evidence.
• Existing consumers of design-ai site --mcp-check --json without --probes keep the same top-level JSON contract.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• node cli/bin/design-ai.mjs site --sample | node cli/bin/design-ai.mjs site --stdin --mcp-check --probes --json
• npm run release:metadata
• npm run audit:strict
• npm test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 308 — MCP Action Plan Embedded Command Release Guard (unreleased)

Release metadata now protects the release-facing documentation phrase for embedded MCP action plan probe output-file commands. The guard ties Phase 307's structured JSON command fields to README, Release Checklist, and Distribution guidance, so docs cannot describe MCP probe action plan JSON --out persistence while omitting the embedded mcpCheckProbesJsonOut / mcpPlanProbesJsonOut command contract.

Changed

• Added RELEASE_SITE_MCP_ACTION_PLAN_COMMANDS_TERM_GROUPS to tools/audit/release-metadata.py.
• Added site MCP action plan embedded command phrase to release policy phrase labels and checks.
• Updated README, README.ko, Distribution docs, and Release Checklist release smoke guidance to name embedded MCP action plan probe output-file commands.
• Added a release metadata self-test drift fixture that fails when README guidance drops the embedded command phrase.
• Updated CHANGELOG and SESSION-LOG entries for the release-policy guard.

Impact

• Release-facing docs now fail npm run release:metadata if they keep MCP probe action plan JSON --out coverage but drop the embedded command contract.
• This is release-policy hardening only: no CLI runtime behavior, package smoke execution path, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 307 — MCP Action Plan Probe Output Commands (unreleased)

Structured Website Console MCP action plan JSON now carries the MCP probe JSON output-file commands directly in its commands object. Operators and automation can read one action-plan payload and discover both preservation paths without opening help text: mcpCheckProbesJsonOut for readiness probe JSON and mcpPlanProbesJsonOut for probe action-plan JSON.

Changed

• Added commands.mcpCheckProbesJsonOut and commands.mcpPlanProbesJsonOut to buildSiteMcpActionPlanData.
• Updated site unit tests so Markdown and JSON MCP action plans must include the probe --out commands.
• Updated shared package/public-registry smoke assertion fixtures and validators for the expanded action-plan commands contract.
• Added a smoke assertion self-test fixture that fails when the MCP readiness probe output command drops the --out target.
• Updated CHANGELOG and SESSION-LOG entries for the structured JSON command improvement.

Impact

• Machine-readable Website Console MCP action plans now expose the same saved-probe workflows that design-ai site --help documents.
• This remains deterministic and local: no external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• node --test cli/lib/site.test.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• node cli/bin/design-ai.mjs site --sample | node cli/bin/design-ai.mjs site --stdin --mcp-plan --probes --json
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 306 — Site Help Topic Example Release Guard (unreleased)

Release metadata now protects the shared Website Console site help topic example smoke assertion phrase that Phase 305 added to package and registry smoke assertions. Release-facing docs must mention the command-specific design-ai help site example guard alongside help topic smoke coverage, so docs cannot describe generic help topic validation while dropping the MCP probe JSON --out example contract.

Changed

• Added RELEASE_SITE_HELP_TOPIC_EXAMPLE_TERM_GROUPS to tools/audit/release-metadata.py.
• Added site help topic example phrase to the release policy phrase labels and checks.
• Updated README, README.ko, Distribution docs, and Release Checklist release smoke guidance to name shared Website Console site help topic example smoke assertions.
• Added a release metadata self-test drift fixture that fails when README guidance drops the shared site help topic example phrase.

Impact

• Release-facing docs now fail npm run release:metadata if help topic smoke guidance omits the Website Console site help example guard.
• This is release-policy hardening only: no CLI runtime behavior, package smoke execution path, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 305 — Site Help Topic Probe Output Smoke Assertions (unreleased)

Shared package/public-registry smoke assertions now protect the command-specific Website Console site help examples for MCP probe JSON output files. The site help topic fixture must include copy/paste commands for --mcp-check --probes --json --out mcp-check-probes.json and --mcp-plan --probes --json --out mcp-action-plan-probes.json, so package and registry smoke catch drift where top-level help still advertises probes but the detailed topic loses the save-to-file workflow.

Changed

• Added Website Console MCP probe JSON output-file example fragments to EXPECTED_HELP_TOPIC_FRAGMENTS["site"] in tools/audit/smoke_assertions.py.
• Added a positive self-test assertion for the site help topic fixture.
• Added a drift fixture that fails when the MCP readiness probe example drops the --out mcp-check-probes.json save target.
• Updated CHANGELOG and SESSION-LOG entries for the shared help-topic smoke assertion hardening.

Impact

• Packed-tarball and public-registry smoke now validate the command-specific Website Console help topic examples through the shared helper path, not only the help JSON usage line and top-level help summary.
• This is smoke assertion hardening only: no CLI runtime behavior, package smoke execution path, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 304 — Probe-Capable Site Help Release Guard (unreleased)

Release metadata now protects the probe-capable Website Console site help usage that package and registry smoke assertions validate. Release-facing docs must mention the design-ai help --json topic catalog together with probe-capable Website Console site help usage, so the docs cannot keep generic help catalog wording while dropping the --mcp-check [--probes] / --mcp-plan [--probes] [--json] discovery contract.

Changed

• Added RELEASE_SITE_HELP_USAGE_TERM_GROUPS to tools/audit/release-metadata.py.
• Added site help usage phrase to the release policy phrase labels and checks.
• Updated README, README.ko, Distribution docs, and Release Checklist release smoke guidance to name probe-capable Website Console site help usage next to help JSON catalog coverage.
• Added a release metadata self-test drift fixture that fails when README guidance drops the probe-capable site help usage phrase.

Impact

• Release-facing docs now fail npm run release:metadata if help JSON catalog guidance omits the Website Console site probe usage contract.
• This is release-policy hardening only: no CLI runtime behavior, package smoke execution path, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 303 — Probe-Capable Site Help Smoke Assertions (unreleased)

Shared package/public-registry smoke assertions now require the same probe-capable Website Console site usage that top-level help exposes. The help JSON contract and main help output fixtures now include --mcp-check [--probes] and --mcp-plan [--probes] [--json], and the self-test fails if the site usage drifts back to the older probe-less shape.

Changed

• Updated tools/audit/smoke_assertions.py expected help topic usage for the site command.
• Updated main help fixture fragments so packed-tarball and public-registry smoke validate probe-capable site usage.
• Added a smoke assertion self-test fixture that fails when help JSON reports stale probe-less site usage.

Impact

• Package and registry smoke now catch drift where top-level help/catalog loses Website Console probe discovery while command-specific help still passes.
• This is smoke assertion hardening only: no CLI runtime behavior, package smoke execution path, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 302 — Site Probe Usage in Top-Level Help (unreleased)

Top-level design-ai help and machine-readable design-ai help --json now expose the Website Console probe-capable site modes. The site usage line names --mcp-check [--probes] and --mcp-plan [--probes] [--json], so operators and tool wrappers can discover probe support before opening command-specific help.

Changed

• Updated the site entry in HELP_COMMANDS to include probe-capable MCP readiness and action-plan modes.
• Updated help catalog tests for human and JSON output so top-level usage cannot silently fall back to the older probe-less shape.
• Updated CHANGELOG and SESSION-LOG entries for the top-level help/catalog improvement.

Impact

• This is help/catalog hardening only: no CLI runtime behavior, package smoke execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• node cli/bin/design-ai.mjs help
• node cli/bin/design-ai.mjs help --json
• node --test cli/lib/help-command.test.mjs
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 301 — MCP Probe Output-File Help Examples (unreleased)

design-ai site --help now surfaces the MCP probe JSON output-file workflows directly in the examples list. Operators can copy the exact --mcp-check --probes --json --out mcp-check-probes.json and --mcp-plan --probes --json --out mcp-action-plan-probes.json commands without reconstructing them from release smoke guidance.

Changed

• Added explicit Website Console MCP readiness probe JSON and MCP probe action plan JSON --out examples to the site command help.
• Added help-command and site command unit assertions so the examples cannot silently disappear.
• Updated CHANGELOG and SESSION-LOG entries for the operator-facing help improvement.

Impact

• This is help/documentation hardening only: no CLI runtime behavior, package smoke execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• node cli/bin/design-ai.mjs help site
• node --test cli/lib/help-command.test.mjs cli/lib/site.test.mjs
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 300 — Shared MCP Probe Output-File Release Guard (unreleased)

Release metadata now treats the shared Website Console MCP probe output-file smoke assertion contract as release-facing policy. The guard requires release docs to mention shared MCP probe output-file smoke assertions next to MCP readiness probe JSON --out coverage, and the self-test fails if that helper phrase disappears from README release guidance.

Changed

• Added RELEASE_SITE_MCP_SHARED_OUTPUT_ASSERTION_TERM_GROUPS to tools/audit/release-metadata.py.
• Updated README, README.ko, Distribution docs, and Release Checklist release-gate guidance to name the shared MCP probe output-file smoke assertion coverage.
• Added a release metadata self-test drift fixture that fails when the shared MCP probe output-file smoke assertion phrase is removed from README release policy text.

Impact

• Release-facing docs now fail npm run release:metadata if they document MCP probe output-file smoke without preserving the shared assertion helper contract.
• This is release-policy hardening only: no CLI runtime behavior, package smoke execution, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 299 — Shared MCP Probe Output-File Smoke Assertions (unreleased)

Website Console MCP probe output-file smoke now uses shared assertion helpers. The packed-tarball and public-registry smoke runners still execute their own installed-bin, one-shot npm exec, and published-package commands, but smoke_assertions.py now owns the write-confirmation plus saved JSON payload contract for both MCP readiness probe JSON and MCP probe action plan JSON.

Changed

• Added shared assert_site_mcp_check_probes_json_file_output and assert_site_mcp_plan_probes_json_file_output helpers to tools/audit/smoke_assertions.py.
• Refactored package and registry smoke helpers/self-tests to use the shared output-file assertion contract after runner-specific command execution.
• Added smoke assertion self-test fixtures for successful output-file validation, missing write confirmation, and saved payload drift.

Impact

• Package and registry smoke can no longer drift apart on MCP probe output-file semantics while still keeping their separate runner setup and command execution paths.
• This is smoke assertion hardening only: no CLI runtime behavior, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 298 — MCP Readiness Probe JSON Output Persistence Smoke (unreleased)

Website Console MCP readiness probe JSON now has output-file persistence smoke coverage. The installed-bin, one-shot npm exec --package <tarball>, and public-registry smoke paths verify that design-ai site --stdin --mcp-check --probes --json --out file --force writes a file and that the saved file still matches the read-only MCP probe contract.

Changed

• Added package smoke and registry smoke helpers that run the MCP readiness probe JSON command with --out file --force, confirm the write message, and validate the saved JSON payload.
• Added package/registry self-test fixtures for MCP readiness probe JSON output-file persistence and read-only boundary drift.
• Extended release metadata policy guards and release-facing docs so the output-file smoke phrase cannot be dropped from packed-tarball or public-registry release guidance.

Impact

• Release smoke now catches regressions where MCP readiness probe JSON works on stdout but fails to persist, writes artifact text to stdout instead of a confirmation, or saves a payload that drifts from the read-only probe contract.
• This is smoke/release-policy hardening only: no CLI runtime behavior, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 297 — MCP Action Plan JSON Output Persistence Smoke (unreleased)

Website Console MCP probe action plan JSON now has output-file persistence smoke coverage. The installed-bin, one-shot npm exec --package <tarball>, and public-registry smoke paths verify that design-ai site --stdin --mcp-plan --probes --json --out file --force writes a file and that the saved file still matches the structured website-improvement-mcp-action-plan contract.

Changed

• Added package smoke and registry smoke helpers that run the MCP probe action plan JSON command with --out file --force, confirm the write message, and validate the saved JSON payload.
• Added package/registry self-test fixtures for MCP probe action plan JSON output-file persistence and boundary drift.
• Extended release metadata policy guards and release-facing docs so the output-file smoke phrase cannot be dropped from packed-tarball or public-registry release guidance.

Impact

• Release smoke now catches regressions where the JSON action plan works on stdout but fails to persist, writes artifact text to stdout instead of a confirmation, or saves a payload that drifts from the action-plan contract.
• This is smoke/release-policy hardening only: no CLI runtime behavior, external MCP call, target website repo mutation, new dependency, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 296 — MCP Action Plan JSON Export (unreleased)

Website Console MCP action plans now support a structured JSON output for agent and CI handoff workflows. design-ai site --mcp-plan [--probes] --json emits the same deterministic readiness/action-plan data as Markdown, including optional read-only probes, without calling external MCPs or mutating target repos.

Changed

• Added buildSiteMcpActionPlanData and formatSiteMcpActionPlanJson so Markdown and JSON action plans share one deterministic data contract.
• Updated design-ai site --mcp-plan to accept --json, including the --probes --json path for read-only probe action plans.
• Added site unit tests, shared smoke assertion helpers, package smoke, and public registry smoke coverage for structured MCP probe action plan JSON.
• Updated Website Improvement docs, README/Distribution/Release Checklist guidance, and release metadata guard fixtures for the new JSON smoke phrase.

Impact

• Agent runners, CI smoke, and handoff scripts can consume MCP action plans without parsing Markdown.
• Existing Markdown --mcp-plan output remains unchanged for operators.
• This is deterministic and local: no external MCP calls, target website repo mutation, Lighthouse/axe/browser automation, new dependencies, or --yes apply behavior changed.

Verified

• node --check cli/lib/site.mjs && node --check cli/commands/site.mjs
• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• node cli/bin/design-ai.mjs site --sample | node cli/bin/design-ai.mjs site --stdin --mcp-plan --probes --json
• npm test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 295 — Public Registry MCP Probe Action Plan Release Guard (unreleased)

Release metadata now protects the post-publish public registry Website Console guidance for MCP probe action plans. The public registry smoke already runs design-ai site --stdin --mcp-plan --probes; release-facing docs now have to say that explicitly instead of only mentioning MCP readiness probes and the base MCP action plan.

Changed

• Extended the public registry Website Console release metadata term group to require MCP probe action plan next to MCP readiness probes and MCP action plan coverage.
• Updated README, Korean README, Distribution docs, and Release Checklist post-publish registry smoke guidance with the new phrase.
• Added a release metadata self-test drift fixture that fails when the public registry MCP probe action plan phrase is removed.

Impact

• Release docs now stay aligned with the actual registry-smoke.py coverage for design-ai site --stdin --mcp-plan --probes.
• This is a release metadata/docs guard only: no CLI runtime behavior, package output, target website repo mutation, external MCP calls, dependency graph, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 294 — MCP Plan Probe Smoke Parity (unreleased)

Packed-tarball and public-registry smoke now verify the Website Console read-only MCP probe section in Markdown action plans. The installed-bin, one-shot npm exec --package <tarball>, and public npm exec --package @design-ai/cli@<version> paths now run design-ai site --stdin --mcp-plan --probes and validate the shared Markdown probe contract.

Changed

• Added shared smoke assertions for design-ai site --stdin --mcp-plan --probes Markdown output, including the read-only probe heading, status, mode, no-external-call boundary, table header, and expected probe rows.
• Added packed-tarball smoke coverage for MCP probe action plan output in both installed-bin and one-shot package paths.
• Added public registry smoke coverage and registry self-test coverage for MCP probe action plan output.
• Extended release metadata policy guards so release-facing docs must retain the MCP probe action plan smoke phrase.

Impact

• Smoke now catches drift where --mcp-plan --probes loses probe rows or read-only boundary text while the JSON --mcp-check --probes path still passes.
• This is a smoke/release-policy parity change only: no CLI runtime behavior, package output format outside the opt-in command, target website repo mutation, external MCP calls, dependency graph, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 293 — Public Registry MCP Probe Smoke Parity (unreleased)

Public registry smoke now verifies the same Website Console read-only MCP probe JSON contract as packed-tarball smoke. The post-publish npm exec --package @design-ai/cli@<version> path now runs design-ai site --stdin --mcp-check --probes --json and checks the shared probe payload assertion contract.

Changed

• Added a registry smoke wrapper for Website Console MCP probe JSON output using the existing shared smoke assertion helper.
• Added the public registry MCP probe smoke command to the npm exec --package @design-ai/cli@<version> Website Console smoke sequence.
• Extended registry smoke self-test and release metadata drift fixtures so public registry Website Console guidance must retain MCP readiness probe coverage.

Impact

• Published-package smoke now catches drift in Website Console MCP probe payload shape, read-only mode, external-call boundary, probe count, and probe item order.
• This is a smoke/release-policy parity change only: no CLI runtime behavior, package output, target website repo mutation, external MCP calls, dependency graph, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run registry:smoke:self-test
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 292 — Shared Repair Report Release Metadata Guard (unreleased)

Release metadata now treats the shared Website Console repair report assertion helper contract as release-facing policy. The guard requires release docs to mention shared repair report assertion helpers alongside bundle repair preview/apply, repair report --out file persistence, and shared repair guidance smoke helpers.

Changed

• Added a shared repair report assertion helper term group to the existing site bundle-repair package smoke release metadata guard.
• Updated README, README.ko, Distribution docs, and Release Checklist release-gate guidance to name the shared repair report assertion helper coverage.
• Added a release metadata self-test fixture that fails when the shared repair report assertion helper phrase is removed from README release policy text.

Impact

• Release-facing docs now fail npm run release:metadata if they document shared bundle repair guidance without preserving the shared repair report assertion helper contract.
• This is a release metadata/docs guard only: no CLI runtime behavior, package output, target website repo mutation, external MCP calls, dependency graph, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 291 — Shared Repair Report Smoke Assertions (unreleased)

Website Console repair report smoke now shares the detailed assertion contract for report guidance commands. Package and registry smoke still execute their own installed-bin / npm exec paths, but smoke_assertions.py owns the command shape, output path, preview payload, and applied payload checks.

Changed

• Added shared smoke assertion helpers for repair guidance report command shape, expected repair-preview.json / repair-applied.json output paths, preview report payloads, and applied repair report payloads.
• Updated tools/audit/package-smoke.py and tools/audit/registry-smoke.py to call the shared helpers instead of duplicating the same report command and payload assertions.
• Added smoke assertion self-test fixtures for the shared repair report helpers, including invalid preview command and generated drift failure cases.

Impact

• Package and registry smoke now fail consistently if repair report command shape, output path, or payload semantics drift.
• This is a test architecture cleanup only: no CLI runtime behavior, package output, target website repo mutation, external MCP calls, dependency graph, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 290 — Shared Repair Guidance Release Metadata Guard (unreleased)

Release metadata now treats the shared Website Console repair guidance smoke helper contract as release-facing policy. The guard requires release docs to mention shared repair guidance smoke helpers alongside the bundle repair preview/apply and repair report --out file smoke coverage, and the self-test includes a drift fixture that removes that phrase from README guidance.

Changed

• Added a shared repair guidance helper term group to the existing site bundle-repair package smoke release metadata guard.
• Updated README, README.ko, Distribution docs, and Release Checklist release-gate guidance to name the shared repair guidance smoke helper coverage.
• Added a release metadata self-test fixture that fails when the shared helper phrase is removed from README release policy text.

Impact

• Release-facing docs now fail npm run release:metadata if they document bundle repair smoke without preserving the shared helper contract.
• This is a release metadata/docs guard only: no CLI runtime behavior, package output, target website repo mutation, external MCP calls, dependency graph, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/release-metadata.py
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run audit:strict
• npm run release:self-test
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 289 — Shared Repair Guidance Smoke Helpers (unreleased)

Website Console repair guidance smoke now has a single helper contract for parsing copy/paste commands. The packed-tarball and public-registry smoke runners both use smoke_assertions.py helpers for repairGuidance command parsing and --out path extraction, reducing duplicated release-gate logic after Phase 288 made the guidance executable.

Changed

• Moved site_guidance_command and guidance_out_path into tools/audit/smoke_assertions.py.
• Added smoke assertion self-test fixtures for quoted report paths, invalid non-site guidance, missing site runner prefixes, missing --out, and dangling --out.
• Updated tools/audit/package-smoke.py and tools/audit/registry-smoke.py to import the shared helpers instead of maintaining duplicate local copies.

Impact

• Package and registry smoke now fail consistently if repair guidance command parsing drifts.
• This is a test architecture cleanup only: no CLI runtime behavior, dependencies, external MCP calls, target website repo mutation, or --yes apply behavior changed.

Verified

• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:check
• npm run package:smoke
• git diff --check

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 288 — Website Console Executable Repair Guidance Smoke (unreleased)

Website Console repair report guidance is now smoke-tested as an executable operator instruction. Instead of only checking that previewReportCommand and applyReportCommand strings contain --out, package and registry smoke parse the emitted guidance commands, map them onto the active installed-bin or npm exec --package runner, execute them, and verify the written preview/applied report payloads.

Changed

• Added shared smoke helpers that parse design-ai site ... repair guidance with shlex.split and preserve the smoke runner prefix.
• Updated packed-tarball smoke so the installed-bin and one-shot npm exec --package <tarball> repair report checks execute the emitted guidance commands directly.
• Updated public-registry smoke so post-publish verification catches broken repair guidance quoting, path generation, or missing --out behavior.
• Kept report paths beside the handoff bundle and asserted those paths before execution.

Impact

• Copy/paste repair guidance is now covered as a real executable contract, not just a documented string shape.
• This remains local and deterministic: no new dependencies, no external MCP calls, no target website repo mutation, and no change to the explicit --yes apply requirement.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• git diff --check
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run package:check
• npm run package:smoke

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 287 — Website Console Bundle Repair Report Command Guidance (unreleased)

Website Console repair guidance now tells operators how to preserve repair evidence as files. Bundle-check, bundle-handoff, and bundle-repair outputs include preview/apply report commands with --out file, using paths outside the handoff bundle directory so saved reports do not create unexpected bundle files.

Changed

• Added previewReportCommand and applyReportCommand to Website Console bundle repairGuidance JSON metadata.
• Added Preview report and Apply report lines to human repair guidance and the generated target-repo handoff prompt.
• Extended site unit coverage so bundle-check, bundle-handoff, and bundle-repair JSON/human/prompt outputs assert the report command contract.
• Extended packed-tarball and public-registry smoke assertions so repair guidance drift is caught in installed-bin, one-shot npm exec --package <tarball>, and public registry paths.

Impact

• Operators can copy deterministic evidence-preservation commands directly from the guidance instead of manually appending --out.
• Report output paths are generated beside the handoff bundle, not inside it, avoiding unexpected bundle-file drift.
• The change does not add dependencies, call external MCPs, mutate target website repos, or change the explicit --yes requirement for applying repairs.

Verified

• node --check cli/lib/site.mjs.
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py.
• node --test cli/lib/site.test.mjs.
• python3 -B tools/audit/package-smoke.py --self-test.
• python3 -B tools/audit/registry-smoke.py --self-test.
• git diff --check.
• npm test.
• npm run audit:strict.
• npm run release:metadata.
• npm run package:check.
• npm run package:smoke.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 286 — Website Console Bundle Repair Report Output Persistence (unreleased)

Website Console bundle repair reports now match the other bundle evidence commands: operators can save preview and apply reports with --out file, while repair preview stays read-only and confirmed apply remains scoped to the local handoff bundle directory.

Changed

• Added design-ai site <bundle-dir> --bundle-repair [--yes] [--json] --out file [--force] support.
• Reused the existing safe file-write path so repair reports print Wrote <path> and respect overwrite protection unless --force is provided.
• Extended site unit coverage so repair preview --out does not mutate a drifted bundle and repair apply --out records the fail-to-pass transition.
• Extended packed-tarball and public-registry smoke assertions so installed-bin, one-shot npm exec --package <tarball>, and public registry paths verify repair report output-file persistence.
• Extended help, README, Distribution docs, release checklist, and release metadata guards to document and enforce the new --out contract.

Impact

• Operators can archive deterministic repair evidence without shell redirection, which makes handoff and release evidence easier to preserve.
• The change does not add dependencies, call external MCPs, mutate target website repos, or change the explicit --yes requirement for applying repairs.

Verified

• node --check cli/lib/site.mjs.
• node --check cli/commands/site.mjs.
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py.
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs.
• python3 -B tools/audit/package-smoke.py --self-test.
• python3 -B tools/audit/registry-smoke.py --self-test.
• python3 -B tools/audit/release-metadata.py --self-test.
• python3 -B tools/audit/smoke_assertions.py --self-test.
• npm run release:metadata.
• npm test.
• npm run audit:strict.
• npm run release:self-test.
• npm run package:check.
• npm run package:smoke.
• git diff --check.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 285 — Website Console Bundle Repair Preview/Apply (unreleased)

Website Console handoff bundle repair guidance is now a first-class local CLI flow. Operators can preview a repair plan without changing files, then explicitly apply the repair to regenerate only the handoff bundle directory from its embedded website-workspace.tasks.json.

Changed

• Added design-ai site <bundle-dir> --bundle-repair [--json] as a read-only repair preview mode.
• Added design-ai site <bundle-dir> --bundle-repair --yes [--json] to rewrite the local handoff bundle directory and immediately re-run bundle-check verification.
• Added previewCommand and applyCommand to bundle repairGuidance metadata.
• Extended site unit coverage so drifted generated artifacts show a fail-to-pass repair transition and preview mode does not mutate files.
• Extended packed-tarball and public-registry smoke assertions so installed-bin, one-shot npm exec --package <tarball>, and public registry paths verify bundle repair preview/apply behavior.

Impact

• Operators no longer have to copy the regeneration command manually after bundle drift; the CLI can perform the local repair after explicit --yes.
• Repair remains scoped to the handoff bundle directory. It does not mutate the target website repo, call external MCPs, crawl pages, run Lighthouse/axe, add dependencies, or modify learning profiles.

Verified

• node --check cli/lib/site.mjs.
• node --check cli/commands/site.mjs.
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/smoke_assertions.py.
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 284 — Website Console Bundle Repair Guidance (unreleased)

Verified Website Console handoff bundle checks now include deterministic repair guidance. When generated contract drift is found, operators can see the exact local command to regenerate the bundle from its embedded website-workspace.tasks.json, plus the follow-up strict verification command.

Changed

• Added top-level repairGuidance metadata to design-ai site <bundle-dir> --bundle-check --json.
• Added repair guidance to bundle-check human output, including regenerate command, verify command, mutation scope, target-repo mutation flag, and external-call flag.
• Added repair guidance to design-ai site <bundle-dir> --bundle-handoff --json bundle metadata and the generated target-repo handoff prompt.
• Extended unit coverage so passing bundles and coherent generated-contract drift both expose a regeneration command.
• Extended packed-tarball smoke assertions so installed-bin and one-shot npm exec --package <tarball> bundle-check/handoff paths verify repair guidance.

Impact

• Website Improvement operators now get an actionable next step after drift detection instead of only a failing issue and digest comparison.
• Repair remains explicit and local: the command rewrites only the handoff bundle directory with --force, does not mutate the target website repo, does not call external MCPs, and does not add dependencies.

Verified

• node --check cli/lib/site.mjs.
• python3 -m py_compile tools/audit/package-smoke.py.
• node --test cli/lib/site.test.mjs.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 283 — Website Console Bundle Generated Contract Diagnostics (unreleased)

Verified Website Console handoff bundle checks now expose per-file generated contract diagnostics. Operators can see which checksum-managed artifact drifted from the current CLI output contract, including expected and actual SHA-256 digests, without exposing artifact contents.

Changed

• Added a generatedContract JSON block to design-ai site <bundle-dir> --bundle-check --json with availability, source, expected/verified counts, drift file paths, and per-file expected/actual SHA-256 digests.
• Added generated drift file summaries to bundle-check human output, bundle-compare summaries, and target-repo bundle-handoff JSON/prompt output.
• Extended the coherent tamper regression test so website-handoff.md drift verifies both the mismatch path and digest diagnostics.
• Extended packed-tarball smoke assertions so installed-bin and one-shot npm exec --package <tarball> bundle-check/compare/handoff paths verify generated contract diagnostics and empty drift lists.

Impact

• Website Improvement operators can distinguish checksum mismatch, coherent manual bundle edits, and current CLI contract drift without inspecting every bundle artifact manually.
• Diagnostics remain deterministic and local: they expose digests and file paths only, not generated Markdown contents, and do not mutate target repos, call external MCPs, crawl pages, or add dependencies.

Verified

• node --check cli/lib/site.mjs.
• python3 -m py_compile tools/audit/package-smoke.py.
• node --test cli/lib/site.test.mjs.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 282 — Website Console Bundle Generated Contract Guard (unreleased)

Verified Website Console handoff bundle checks now confirm that the generated bundle artifacts still match the current CLI output contract. This protects target-repo handoff against coherent manual edits where a bundle file and summary.json checksums are changed together.

Changed

• Added generated contract verification to design-ai site <bundle-dir> --bundle-check --json for the seven checksum-managed bundle artifacts.
• Added expectedGeneratedFiles, verifiedGeneratedFiles, and generatedFailures counts to bundle-check JSON.
• Added generated contract metadata to bundle-compare summaries and target-repo bundle-handoff JSON/prompt output.
• Added a coherent tamper regression test where website-handoff.md is edited and summary.json checksums are recomputed; bundle-check now fails on bundle-generated-website-handoff.md.
• Extended packed-tarball smoke assertions so installed-bin and one-shot npm exec --package <tarball> bundle-check/compare/handoff JSON verify the generated bundle contract counts.
• Extended release metadata guidance so release-facing docs keep generated bundle contract verification visible.

Impact

• Website Improvement operators can trust that a verified handoff bundle is not only checksum-consistent, but also reproducible from website-workspace.tasks.json under the current CLI.
• summary.json remains validated through manifest, checksum, digest, evidence count, and workspace drift checks; exact regeneration is applied to the seven checksum-managed artifacts where the task-generation summary does not depend on original pre-generation state.
• The feature remains deterministic and local: it does not mutate target repos, call external MCPs, validate real target-repo claims automatically, crawl pages, run Lighthouse/axe, or add dependencies.

Verified

• node --check cli/lib/site.mjs.
• python3 -m py_compile tools/audit/package-smoke.py.
• node --test cli/lib/site.test.mjs.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 281 — Website Console Verified Bundle Evidence Metadata (unreleased)

Verified Website Console handoff bundle flows now keep implementation evidence counts visible after bundle verification. This closes the gap between evidence-preserving bundle export and the later --bundle-check, --bundle-compare, and --bundle-handoff JSON summaries used before target-repo implementation.

Changed

• Added normalized implementationEvidence count metadata to design-ai site <bundle-dir> --bundle-check --json summaries.
• Added evidence count metadata to both sides of design-ai site <bundle-dir> --bundle-compare other-bundle-dir --json.
• Added evidence count metadata to design-ai site <bundle-dir> --bundle-handoff --json and the generated target-repo handoff prompt.
• Added bundle-check validation that fails when summary.json.implementationEvidence counts drift from website-workspace.tasks.json.
• Extended packed-tarball smoke so installed-bin and one-shot npm exec --package <tarball> paths verify non-empty evidence counts through evidence bundle check, compare, and handoff JSON.

Impact

• Website Improvement operators can confirm recorded target-repo evidence survives the whole handoff chain: browser workspace export, CLI report/tasks/bundle generation, bundle verification, bundle comparison, and target-repo handoff prompt generation.
• The feature remains deterministic and local: it does not mutate target repos, call external MCPs, validate real target-repo claims automatically, crawl pages, run Lighthouse/axe, or add dependencies.

Verified

• node --check cli/lib/site.mjs.
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py.
• node --test cli/lib/site.test.mjs.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 280 — Website Console Evidence Package Smoke Expansion (unreleased)

Packed-tarball smoke now verifies that non-empty Website Console handoff evidence survives the release distribution paths. This protects the Phase 278/279 evidence workflow after packaging, install shims, and one-shot npm exec --package <tarball> execution.

Changed

• Added a non-empty implementationEvidence smoke fixture for executed work, verification results, remaining risks, and next actions.
• Added installed-bin smoke coverage for design-ai site --stdin --report, design-ai site --stdin --tasks, and design-ai site --stdin --bundle --out <dir> using the evidence fixture.
• Added one-shot npm exec --package <tarball> smoke coverage for the same report, tasks, and bundle evidence preservation paths.
• Added package smoke self-test drift fixtures for evidence payload and Markdown fragment assertions.

Impact

• Website Improvement evidence capture is now protected across browser export, CLI report generation, generated task workspaces, handoff bundles, local package install shims, and one-shot tarball execution.
• The smoke remains deterministic and local: it does not mutate target repos, call external MCPs, validate real target-repo claims, crawl pages, or add dependencies.

Verified

• python3 -m py_compile tools/audit/package-smoke.py.
• python3 -B tools/audit/package-smoke.py --self-test.
• npm run package:smoke.
• npm test.
• npm run audit:strict.
• npm run release:metadata.
• python3 -B tools/audit/local-ci.py --docs-only.
• npm run release:self-test.
• git diff --check.

What's still ahead

• Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 279 — Website Console CLI Handoff Evidence Export (unreleased)

design-ai site now preserves Website Console handoff evidence when operators move from the browser workspace to file-first CLI reports and bundles. Evidence recorded in the static app can now survive --tasks, appear in --report, and be archived in --bundle artifacts.

Changed

• Added implementationEvidence normalization to cli/lib/site.mjs with executed work, verification results, remaining risks, and next actions.
• Added optional evidence-shape validation so malformed evidence arrays fail workspace analysis while older workspaces without the block remain compatible.
• Added evidence counts to design-ai site --json summaries.
• Updated CLI-generated handoff reports to render evidence-backed Executed work, Verification results, Remaining risks, and Next actions sections.
• Preserved evidence through design-ai site --tasks and design-ai site --bundle, including website-workspace.tasks.json, website-handoff.md, and summary.json.
• Added unit and smoke assertion coverage for sample schema, evidence preservation, bundle summary counts, and assertion drift.

Impact

• Website Improvement operators can now use the static console for local evidence capture and the CLI for durable report/bundle export without losing implementation proof.
• The CLI remains deterministic and local: it does not mutate target repos, call external MCPs, verify evidence claims automatically, add dependencies, run crawling, or run Lighthouse/axe.

Verified

• node --check cli/lib/site.mjs.
• node --test cli/lib/site.test.mjs.
• python3 -B tools/audit/smoke_assertions.py --self-test.
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py.

What's still ahead

• Evidence-specific package smoke expansion is covered in Phase 280. Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 278 — Website Console Handoff Evidence Tracking (unreleased)

The static Website Improvement Console now lets operators record target-repo implementation evidence before exporting a final handoff report. This closes the gap between planning prompts and the local Markdown report without letting this repo edit the target website source.

Changed

• Added an implementationEvidence localStorage workspace block for executed work, verification results, remaining risks, and next actions.
• Added editable Handoff Report evidence fields plus compact count metrics in docs/website-console/.
• Updated generated Markdown handoff reports so copied/exported reports include operator-entered implementation evidence instead of fixed placeholder text.
• Preserved existing JSON import/export compatibility by normalizing older workspaces that do not include the new evidence block.
• Kept the static console dependency-free, browser-local, and target-repo safe.

Impact

• Website Improvement operators can now keep planning, implementation proof, verification results, risks, and next actions in one browser workspace.
• The console still does not call external MCPs, mutate target repos, run crawling/Lighthouse/axe automation, add backend sync, or add dependencies.

Verified

• node --check docs/website-console/app.js.
• Browser smoke confirmed Handoff Report evidence inputs, live Markdown preview, JSON import restore, mobile overflow safety, and zero console errors.

What's still ahead

• CLI evidence export is covered in Phase 279, and packed-tarball evidence smoke coverage is covered in Phase 280. Real MCP connection checks, Playwright/Lighthouse/axe automation, and VS Code Webview reuse remain future Website Console automation work.

Phase 277 — Website Console Workflow Graph Rendering (unreleased)

The static Website Improvement Console now renders the portable workflow graph directly in the browser. Operators can inspect the same local workflow shape before exporting graph JSON or moving implementation prompts into the target website repo.

Changed

• Added a Workflow Graph tab to docs/website-console/.
• Added deterministic in-browser graph generation for workspace intake, site profile, audit categories, MCP readiness, refactor tasks, prompt templates, handoff report, handoff bundle, and target repo boundary.
• Added lane-based graph rendering, summary metrics, boundary markers, and a complete edge table.
• Added browser-side copy/export actions for website-workflow-graph.json.
• Kept the static console dependency-free and local/read-only.

Impact

• Website Improvement operators can now review graph structure visually before saving the portable JSON artifact.
• The static console can render the graph without a workflow runtime dependency, external MCP calls, target-repo mutation, crawling, Lighthouse/axe automation, or backend sync.

Verified

• node --check docs/website-console/app.js.
• Browser smoke at http://127.0.0.1:8765/ confirmed 35 graph nodes, 67 edge rows, 6 lanes, boundary markers, and zero console errors.

What's still ahead

• Target-repo implementation tracking is covered in Phase 278. Real MCP connection checks, Playwright/Lighthouse/axe automation, CLI evidence export, and VS Code Webview reuse remain future Website Console automation work.

Phase 276 — Website Console Workflow Graph Export (unreleased)

design-ai site --graph [--json] now exports Website Improvement workspaces and agent plans as portable workflow graphs. The graph can be stored as JSON and, as of Phase 277, rendered by the static console without adding a visual workflow runtime dependency.

Changed

• Added design-ai site <workspace.json|--stdin> --graph [--json] [--out file] [--force].
• Added deterministic graph nodes for workspace intake, site profile, audit categories, MCP readiness, generated and retained refactor tasks, prompt templates, handoff report, handoff bundle, and target website repo boundary.
• Added deterministic graph edges for profile context, audit finding to task conversion, MCP support, task-selected Codex implementation prompts, handoff report inputs, prompt-to-target workflow, and bundle handoff.
• Added JSON and Markdown graph formatters while keeping the export local/read-only.
• Added unit coverage, smoke assertion fixtures, and packed-tarball smoke coverage for installed-bin and one-shot npm exec --package <tarball> graph JSON paths.

Impact

• Website Improvement operators can preserve a machine-readable workflow map alongside MCP readiness, prompts, and handoff artifacts.
• The graph exports the useful part of visual workflow tools without adding dependencies, external MCP calls, target-repo mutation, crawling, Lighthouse/axe automation, or hidden background state.

Verified

• Targeted site and help unit tests.
• Package smoke assertion self-tests.

What's still ahead

• Static console graph rendering is covered by Phase 277; real MCP connection checks remain future Website Console automation work.

Phase 275 — Website Console MCP Probes (unreleased)

design-ai site --mcp-check --probes and design-ai site --mcp-plan --probes now add read-only local probe results to the Website Improvement MCP readiness workflow. The default --mcp-check JSON shape remains unchanged unless --probes is explicitly requested.

Changed

• Added --probes for design-ai site --mcp-check and design-ai site --mcp-plan.
• Added a separate probes JSON block with mode, external call policy, pass/warn/fail counts, and itemized probe evidence.
• Added deterministic probes for GitHub repo references, Figma URLs, Browser smoke targets, and deployment provider references.
• Added human and Markdown action-plan probe sections when probe mode is enabled.
• Added unit coverage, smoke assertion fixtures, and packed-tarball smoke coverage for installed-bin and one-shot npm exec --package <tarball> probe JSON paths.

Impact

• Website Improvement operators can verify handoff readiness beyond declared MCP statuses while preserving the stable local readiness contract.
• Probes are read-only and deterministic: they do not call external MCPs, write to external systems, crawl target sites, run Lighthouse/axe, mutate target repos, add dependencies, or use external AI APIs.

Verified

• Targeted site and help unit tests.
• Package smoke assertion self-tests.

What's still ahead

• Workflow graph export is covered by Phase 276; real MCP connection checks remain future Website Console automation work.

Phase 274 — Skill Evolution Proposals (unreleased)

design-ai learn --propose-skills now converts repeated check-capture learning signals into preview-only skill instruction delta proposals. It uses the active local learning profile, optional usage sidecar path, and optional eval signal file/directory to keep the same operator context as learn --signals.

Changed

• Added design-ai learn --propose-skills [--from-file signal-file-or-dir] [--usage-file path] [--json] [--out file] [--force].
• Added deterministic grouping from source: check:* learning entries to candidate skill paths through route skills or category fallback.
• Added proposal JSON fields for candidate skill, evidence sources, proposed instruction delta, verification command, risk level, skipped single-entry groups, and privacy metadata.
• Added human output for quick review of candidate skill deltas and evidence previews.
• Added package-smoke coverage for installed-bin and one-shot npm exec --package <tarball> skill proposal JSON/human/--out paths.
• Added help, unit, smoke assertion, and docs coverage for the new preview-only proposal flow.

Impact

• Repeated local QA feedback can now be reviewed as concrete skill improvement candidates before any skill file is edited.
• The command is deterministic and preview-only; it rejects --yes, does not mutate learning.json, does not edit skills/*/SKILL.md, does not call external AI APIs, and does not add dependencies.

Verified

• Targeted learn and help unit tests.
• Package smoke assertion self-tests.

What's still ahead

• Workflow graph export remains a future phase.

Phase 273 — Learning Signal Registry (unreleased)

design-ai learn --signals now reports a joined, read-only local signal registry for AI/agent development. It combines learning profile audit state, learning usage sidecar activity, eval signal files, check learning capture entries, and workspace readiness without changing the active learning profile.

Changed

• Added design-ai learn --signals [--from-file signal-file-or-dir] [--usage-file path] [--json] [--out file] [--force].
• Added signal-file discovery for route, prompt, pack, and learning eval reports/templates.
• Added registry JSON fields for learning health, usage sidecar status, eval signal summary, check capture summaries, workspace readiness, recommendations, and privacy metadata.
• Added human output for quick review of eval signals, recent check captures, workspace readiness, and recommended next actions.
• Added package-smoke coverage for installed-bin and one-shot npm exec --package <tarball> learning signal registry JSON/human/--out paths.
• Added help, unit, smoke assertion, and docs coverage for the new read-only registry flow.

Impact

• Local learning and agent eval drift can be reviewed from one command before deeper skill evolution, MCP probe, or Website Console automation work.
• The registry is deterministic and read-only; it does not mutate learning.json, call external AI APIs, add dependencies, or store raw brief text.

Verified

• Targeted learn and help unit tests.
• Package smoke assertion self-tests.

What's still ahead

• Optional MCP probes and workflow graph export remain future phases.

Phase 272 — Agent Prompt and Pack Eval Harness (unreleased)

design-ai prompt and design-ai pack now have deterministic eval surfaces for prompt plans and context bundles. This extends the Phase 271 route eval pattern into the actual agent handoff payloads used by design-ai.

Changed

• Added design-ai prompt --eval-template [--json] to generate runnable prompt-plan checkpoint JSON.
• Added design-ai prompt --eval --from-file prompt-eval.json [--strict] [--json] and stdin support for local prompt-plan conformance checks.
• Added prompt eval assertions for expected route id, required files to read, required checklist items, required prompt fragments, and optional learning context.
• Added design-ai pack --eval-template [--json] to generate runnable prompt-pack checkpoint JSON.
• Added design-ai pack --eval --from-file pack-eval.json [--strict] [--json] and stdin support for local context-bundle conformance checks.
• Added pack eval assertions for expected route id, planned files, included context files, context status, and optional learning context.
• Kept pack eval JSON readable by returning context file metadata and markdown byte counts instead of embedding full context file bodies.
• Added packed-tarball smoke coverage for route eval, prompt eval, and pack eval checkpoints in installed-bin and one-shot npm exec --package <tarball> paths.
• Added release metadata guard coverage for the route/prompt/pack eval smoke phrase in release policy docs.
• Added help and unit coverage for eval argument parsing, template generation, passing checkpoints, strict failure fixtures, invalid combinations, and machine-readable help catalog drift.

Impact

• Agent prompt generation and context bundling can now be checked after route selection but before deeper learning or Website Console automation depends on them.
• The eval harness is deterministic and read-only; it does not add dependencies, external AI calls, background telemetry, or learning-profile mutation.

Verified

• node --test cli/lib/pack.test.mjs cli/lib/prompt.test.mjs cli/lib/help-command.test.mjs
• design-ai prompt --eval-template --json | design-ai prompt --eval --stdin --strict --json
• design-ai pack --eval-template --json | design-ai pack --eval --stdin --strict --json
• Package smoke and release metadata self-tests.

What's still ahead

• Preview-only skill evolution proposals, optional MCP probes, and workflow graph export remain future phases.

Phase 271 — Agent Route Eval Harness (unreleased)

design-ai route now has a deterministic eval surface for agent routing. This is the first AI/agent development step after reviewing Hermes, Harness, Strands, Superpowers, ECC, OpenCode, Langflow, Dify, Anthropic Skills, LangChain, Gemini CLI, CC Switch, TradingAgents, and related reference repos.

Changed

• Added design-ai route --eval-template [--json] to generate a runnable route-selection checkpoint JSON file.
• Added design-ai route --eval --from-file route-eval.json [--strict] [--json] and stdin support for local conformance checks.
• Added route eval JSON reports with status, summary counts, expected route, top route, confidence, score, matched keywords, and full candidate routes.
• Added unit coverage for eval argument parsing, template generation, passing checkpoints, mismatched checkpoints, invalid route ids, and invalid payloads.
• Added docs/AGENT-DEVELOPMENT.md with reference-repo analysis and the phased plan for future prompt/learning/skill evolution work.

Impact

• Agent routing can now be checked before prompt generation, learning capture, or Website Console workflows depend on a route.
• The eval harness is deterministic and read-only; it does not add dependencies, external AI calls, background telemetry, or learning-profile mutation.

What's still ahead

• Prompt/pack evals, joined learning signal registry, preview-only skill evolution proposals, optional MCP probes, and workflow graph export remain future phases.

Phase 270 — Public Registry Website Console Smoke Coverage (v4.55.0) ✓ shipped

npm run registry:smoke now verifies the published-package Website Improvement Console CLI surface. The public npm exec --package @design-ai/cli@<version> smoke runs design-ai site sample, JSON validation, prompt template listing, MCP readiness, MCP action plan, handoff bundle, bundle-check/compare/handoff/repair, generated tasks, and task-selected prompt flows.

Changed

• Added public registry smoke coverage for design-ai site --stdin --json, design-ai site --sample, and design-ai site --prompt-list --json.
• Added public registry smoke coverage for design-ai site --stdin --mcp-check --json and design-ai site --stdin --mcp-plan.
• Added public registry smoke coverage for design-ai site --stdin --bundle --out <dir>, --bundle-check --strict --json, --bundle-compare <dir> --strict --json, and --bundle-handoff --strict --json.
• Added public registry smoke coverage for design-ai site --stdin --tasks and design-ai site --stdin --prompt codex-implementation --task task-homepage-cta.
• Added registry-smoke self-test coverage for Website Console assertion drift.
• Added release metadata guard phrases for public registry Website Console smoke coverage.
• Updated README, Korean README, Product Readiness, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.55.0.

Impact

• Local packed-tarball smoke and post-publish public registry smoke now protect the same Website Console handoff and prompt-generation contracts.
• Existing Website Console workspace, task, MCP readiness, and bundle schemas remain compatible.

What this enables

• After publish, operators can confirm that the public registry package can generate website improvement handoff artifacts before company rollout or external release checks.

Verified

• All 8 audits pass.
• Registry smoke self-test.
• Release metadata self-test.

Versions

• package.json + .claude-plugin/plugin.json: 4.54.0 → 4.55.0.

What's still ahead

• Real MCP connection probes, Playwright/Lighthouse/axe automation, semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 269 — Public Registry Workspace Restore Backup Readiness Smoke (v4.54.0) ✓ shipped

npm run registry:smoke now verifies the published-package workspace restore-backups readiness path. The public npm exec --package @design-ai/cli@<version> smoke creates a clean workspace fixture, writes sibling restore rollback backups beside the selected learning profile, and checks that design-ai workspace reports learningRestoreBackups inventory plus preview-first prune next actions.

Changed

• Added public registry smoke coverage for design-ai workspace --root <repo> --learning-file <learning.json> --json with sibling restore rollback backup inventory.
• Added registry-smoke fixture generation for six sibling *.restore-backup-*.json rollback files.
• Added registry-smoke assertions for total backup count, limited count, latest restore preview command, readiness prune candidate count, and prune next action.
• Added registry-smoke self-test coverage for workspace restore-backups assertion drift.
• Added release metadata guard phrases for public registry workspace restore-backups readiness coverage.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.54.0.

Impact

• Local packed-tarball smoke and post-publish public registry smoke now protect the same workspace restore-backups readiness contract.
• Existing workspace, learning profile, restore, restore-backups, and prune schemas remain compatible.

What this enables

• After publish, operators can confirm that the public registry package reports rollback backup readiness and cleanup guidance before company rollout or external release checks.

Verified

• All 8 audits pass.
• Registry smoke self-test.
• Release metadata self-test.

Versions

• package.json + .claude-plugin/plugin.json: 4.53.0 → 4.54.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 268 — Workspace Learning Restore Backup Readiness (v4.53.0) ✓ shipped

design-ai workspace now detects sibling learning restore rollback backups beside the selected profile and reports the inventory in local dogfood readiness. The report stays read-only, exposes learningRestoreBackups in JSON, shows the latest rollback backup, and points operators to preview-first prune cleanup when older backups exceed the default keep count.

Changed

• Added workspace auto-detection for sibling *.restore-backup-*.json rollback backups.
• Added learningRestoreBackups JSON output with inventory counts, latest backup metadata, readiness, privacy flags, and error handling.
• Added human workspace output for restore rollback backup inventory and readiness.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> workspace restore-backups readiness.
• Added release metadata guard phrases for workspace learning restore-backups readiness coverage.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.53.0.

Impact

• Workspace readiness now covers rollback backup discoverability and retention cleanup without mutating the active learning profile.
• Existing learning profile, restore, restore-backups, and prune schemas remain compatible.

What this enables

• Operators can decide whether to restore, inspect, or prune local learning rollback backups from the same read-only workspace snapshot used before commits, pushes, and handoffs.

Verified

• All 8 audits pass.
• Targeted workspace/learning unit tests.
• Smoke assertion, package smoke, and release metadata self-tests.

Versions

• package.json + .claude-plugin/plugin.json: 4.52.0 → 4.53.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 267 — Public Registry Learning Restore Smoke (v4.52.0) ✓ shipped

npm run registry:smoke now verifies the published-package learning restore safety path. The public npm exec --package @design-ai/cli@<version> smoke covers restore preview/apply behavior, rollback backup creation with explicit backup paths, restore-backups inventory, and restore-backups prune preview/apply cleanup.

Changed

• Added public registry smoke coverage for design-ai learn --restore preview/apply JSON output.
• Added public registry smoke coverage for learn restore --out, rollback backup verification, and --backup-file path handling.
• Added public registry smoke coverage for design-ai learn --restore-backups inventory and design-ai learn --restore-backups --prune preview/apply pruning.
• Added registry smoke self-test fixtures for restore metadata, restore-backups inventory drift, and prune candidate drift.
• Added release metadata guard phrases for public registry restore, restore-backups, and restore-backups prune coverage.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.52.0.

Impact

• Published package verification now covers the full restore rollback maintenance path, not just packed-tarball pre-release smoke.
• Existing learning profile, restore, restore-backups, and prune schemas remain compatible.

What this enables

• After publish, operators can verify that registry-installed packages preserve the same preview-first restore and backup-pruning safety behavior proven by local package smoke.

Verified

• All 8 audits pass.
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.51.0 → 4.52.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 266 — Learning Restore Backup Prune (v4.51.0) ✓ shipped

design-ai learn --restore-backups --prune now turns rollback backup discovery into a safe retention workflow. It previews older sibling restore rollback backup files by default, keeps the newest backups, and deletes only older backup files after explicit --yes.

Changed

• Added design-ai learn --restore-backups --prune [--keep N] [--dry-run|--yes] [--json] [--out file].
• Added default retention of the 5 newest rollback backups and explicit --keep N retention control.
• Added prune JSON metadata for dry-run/apply state, retained backups, delete candidates, deleted backups, delete failures, and privacy flags.
• Kept the active learning profile unchanged during both preview and confirmed prune.
• Added unit coverage for parser validation, helper preview/apply behavior, command human output, command JSON output, and help text.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> restore-backups prune preview/apply paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.51.0.

Impact

• Solo and company rollout flows can keep rollback backup folders tidy without losing the newest recovery points.
• Existing learning profile, archive, usage sidecar, eval checkpoint, curation, import, diff, restore, and restore-backups inventory schemas remain compatible.

What this enables

• A complete rollback backup maintenance loop: list backups, preview prune candidates, keep the newest recovery points, and delete older backup files only after explicit confirmation.

Verified

• All 8 audits pass.
• node --check cli/lib/learn.mjs
• node --check cli/commands/learn.mjs
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.50.0 → 4.51.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 265 — Learning Restore Backup Inventory (v4.50.0) ✓ shipped

design-ai learn --restore-backups now lists sibling restore rollback backups for the selected learning profile without changing any files. The command audits each backup candidate and prints a restore dry-run preview command so operators can find the right rollback file before applying any restore.

Changed

• Added design-ai learn --restore-backups [--limit N] [--json] [--out file].
• Added sibling learning.restore-backup-*.json scanning beside the active learning profile.
• Added backup metadata output for path, file name, restore-created timestamp, modified time, size, profile updatedAt, entry count, audit summary, issue count, and restore preview command.
• Kept invalid backup JSON visible as a failed backup candidate instead of hiding it.
• Added unit coverage for parser validation, read-only backup scanning, invalid backup audit visibility, command human output, command JSON output, and help text.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> restore-backups human, JSON, and --out paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.50.0.

Impact

• Solo and company rollout flows can now discover automatic rollback backups after restore operations without manually searching the filesystem.
• Existing learning profile, archive, usage sidecar, eval checkpoint, curation, import, diff, and restore schemas remain compatible.

What this enables

• A clearer rollback workflow: list rollback backups, audit the candidate, run the printed restore dry-run command, then add --yes only after the diff is correct.

Verified

• All 8 audits pass.
• node --check cli/lib/learn.mjs
• node --check cli/commands/learn.mjs
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.49.0 → 4.50.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 264 — Learning Restore Rollback Backup (v4.49.0) ✓ shipped

design-ai learn --restore --yes now writes a rollback backup of the active local learning profile before replacing it with a portable restore source. The command still previews by default, still requires --yes for mutation, and now exposes rollback backup metadata in human and JSON output.

Changed

• Added automatic rollback backup creation before confirmed learn --restore --yes profile replacement.
• Added --backup-file path to override the default sibling rollback backup path.
• Added human and JSON restore output for backup file path, creation state, backup entry count, backup updatedAt, and rollback preview command.
• Added path safety checks so rollback backups cannot overwrite the active profile or restore source, and existing explicit backup paths require --force.
• Added unit coverage for parser validation, helper preview/apply output, rollback backup creation, path protection, command JSON output, and help text.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> restore rollback backup paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.49.0.

Impact

• Solo and company rollout flows now have a deterministic rollback file whenever a full-profile restore is applied.
• Existing learning profile, archive, usage sidecar, eval checkpoint, curation, import, diff, and restore schemas remain compatible.

What this enables

• A safer portable learning operations loop: backup/redact, verify, diff, restore with rollback backup, then restore from the rollback file if the replacement needs to be undone.

Verified

• All 8 audits pass.
• node --check cli/lib/learn.mjs
• node --check cli/commands/learn.mjs
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.48.0 → 4.49.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 263 — Learning Profile Restore (v4.48.0) ✓ shipped

design-ai learn --restore now lets operators replace the active local learning profile from a portable backup after backup/redaction/verification/diff review. The command is preview-first by default, requires --yes for mutation, and blocks apply when the source payload audit has failures.

Changed

• Added design-ai learn --restore --from-file learning-backup.json [--dry-run|--yes] [--json] [--out file] and stdin support.
• Added human and JSON restore output with target file, source, restorable state, previous/restored counts, removed/added counts, same-text count, metadata changes, id conflicts, audit summary, diff details, and privacy metadata.
• Kept restore deterministic by normalizing the portable profile and using the existing diff comparison shape for replace decisions.
• Kept source-audit failures visible in preview and blocked confirmed apply with a clear refusal error.
• Added unit coverage for parser validation, helper preview/apply output, stdin restore, no-mutation default behavior, audit-failure blocking, and command JSON output.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> restore JSON/apply paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Release Checklist, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.48.0.

Impact

• Solo and company rollout flows can now recover a complete reviewed learning profile, not only merge entries into the current one.
• Existing learning profile, archive, usage sidecar, eval checkpoint, and curation schemas remain compatible.

What this enables

• A complete portable learning operations loop: backup/redact, verify, diff, then restore the full profile or import only additive entries.

Verified

• All 8 audits pass.
• node --check cli/lib/learn.mjs
• node --check cli/commands/learn.mjs
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.47.0 → 4.48.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 262 — Learning Profile Diff (v4.47.0) ✓ shipped

design-ai learn --diff now compares the active local learning profile against a portable JSON profile without importing or mutating entries. Operators can run it after backup/redaction/verification and before import or restore decisions to see profile-only entries, comparison-only entries, metadata changes, and id conflicts.

Changed

• Added design-ai learn --diff --from-file learning.json [--json] [--out file] and stdin support.
• Added read-only human and JSON diff output with profile counts, comparison counts, audit summaries, same-text counts, profile-only entries, comparison-only entries, metadata changes, id conflicts, recommendations, and privacy metadata.
• Kept the comparison deterministic by matching entries on category + normalized text, while separately flagging id conflicts when the same id points at different learning text.
• Added unit coverage for parser validation, helper output, command JSON output, and no-mutation behavior.
• Added package smoke coverage for installed-bin and one-shot npm exec --package <tarball> diff JSON paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.47.0.

Impact

• Local learning migration, backup review, redaction review, and company rollout preparation can now inspect profile drift before applying imports.
• Existing learning profile, archive, usage sidecar, eval checkpoint, and curation schemas remain compatible.

What this enables

• A safer local learning operations loop: backup/redact, verify, diff, then import only after the expected additions and conflicts are clear.

Verified

• All 8 audits pass.
• node --check cli/lib/learn.mjs
• node --check cli/commands/learn.mjs
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs

Versions

• package.json + .claude-plugin/plugin.json: 4.46.0 → 4.47.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 261 — Workspace Curation Report Next Actions (v4.46.0) ✓ shipped

design-ai workspace now pairs learning curation warnings with a Markdown report artifact command. Operators can keep the existing learn --curate preview path, or first run learn --curate --report --out learning-curation-report.md from the workspace next actions to save a readable audit trail before applying archive-first cleanup.

Changed

• Added workspace next actions that recommend design-ai learn --curate --file <learning.json> --report --out <learning-file-dir>/learning-curation-report.md when the active learning profile audit is not clean.
• Added usage-aware report next actions that preserve --usage-file <learning.usage.json> when learning usage sidecar readiness warns.
• Kept workspace read-only: no profile, sidecar, checkpoint, git, release, report, or archive mutation occurs from the readiness snapshot.
• Reused existing shell-safe path quoting for learning profile, usage sidecar, and report output paths.
• Added unit coverage for profile-warning and usage-warning report next actions, including paths with spaces and apostrophes.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.46.0.

Impact

• Local learning maintenance now has a clearer review sequence: inspect workspace warnings, save a Markdown curation report, then decide whether to apply archive-first cleanup.
• Existing learning profile, archive, usage sidecar, eval checkpoint, workspace readiness, and JSON/Markdown curation schemas remain compatible.

What this enables

• A safer solo-to-company rollout loop where curation evidence can be reviewed or shared as a local Markdown artifact before mutating learning.json.

Verified

• All 8 audits pass.
• node --check cli/lib/workspace.mjs
• node --test cli/lib/workspace.test.mjs

Versions

• package.json + .claude-plugin/plugin.json: 4.45.0 → 4.46.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 260 — Learning Curation Markdown Reports (v4.45.0) ✓ shipped

design-ai learn --curate now has a Markdown report mode for local learning maintenance. Operators can preview curation normally, or run learn --curate --report --out learning-curation-report.md to save a readable audit trail before applying archive-first cleanup.

Changed

• Added --report to design-ai learn --curate.
• Allowed --curate --report --out file to write Markdown without requiring --json.
• Rendered profile file, archive file, before/after audit summaries, archive candidates, manual review candidates, usage sidecar review items, privacy notes, and next steps in the report.
• Kept report mode preview-first: profile mutation still requires --yes.
• Added unit coverage for parser validation, Markdown report rendering, output-file writing, and help text.
• Added package smoke coverage for curation report output in installed-bin and one-shot packed-tarball paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.45.0.

Impact

• Learning curation decisions can be reviewed as a durable Markdown artifact before archive actions are applied.
• Local learning maintenance remains deterministic and privacy-preserving: reports include entry previews and usage ids, but usage review still excludes raw prompt/pack brief text.
• Existing learning profile, archive, usage sidecar, eval checkpoint, workspace readiness, and JSON curation schemas remain compatible.

What this enables

• A stronger company-rollout review loop: generate a local curation report, review archive candidates and usage hints, then apply only confirmed duplicate/sensitive archive candidates.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -m py_compile tools/audit/package-smoke.py

Versions

• package.json + .claude-plugin/plugin.json: 4.44.0 → 4.45.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 259 — Workspace Learning Curation Next Actions (v4.44.0) ✓ shipped

design-ai workspace now routes local learning maintenance warnings into the safer archive-first curation preview. Instead of splitting operators between audit-only and usage-only reports, workspace next actions point to learn --curate --file ... and include --usage-file ... when a usage sidecar is part of readiness.

Changed

• Added workspace next actions that recommend design-ai learn --curate --file <learning.json> when the active learning profile audit is not clean.
• Added workspace next actions that recommend design-ai learn --curate --file <learning.json> --usage-file <learning.usage.json> when learning usage sidecar readiness warns.
• Kept read-only workspace behavior: no profile, sidecar, checkpoint, git, release, or archive mutation occurs from workspace.
• Extended learn --curate usage review with profileFile, profileFileMatches, and a usage-profile-file-mismatch advisory item when a sidecar was recorded for another profile path.
• Preserved usage curation as advisory only through autoArchive: false; --curate --yes still archives only duplicate/sensitive audit candidates.
• Added unit coverage for workspace curation next actions and usage profile mismatch review.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.44.0.

Impact

• Operators can move from workspace --strict warnings directly into the single curation preview that combines profile audit findings with usage evidence.
• Usage sidecar profile mismatch is visible from both workspace readiness and curation review without changing existing learning.usage.json files.
• Existing learning profile, usage sidecar, eval checkpoint, prompt/pack recording, and archive apply schemas remain compatible.

What this enables

• A tighter local dogfood loop before solo use or company rollout: inspect workspace readiness, preview curation with usage evidence, then apply only explicit duplicate/sensitive archive candidates.

Verified

• All 8 audits pass.
• node --test cli/lib/workspace.test.mjs cli/lib/learn.test.mjs

Versions

• package.json + .claude-plugin/plugin.json: 4.43.0 → 4.44.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 258 — Learning Usage Curation Review (v4.43.0) ✓ shipped

design-ai learn --curate now folds local prompt/pack usage sidecar evidence into the archive-first curation preview. The feature keeps curation conservative: duplicate and sensitive profile entries can still be archived after --yes, while usage-derived findings only become manual review hints.

Changed

• Added usage-aware review metadata to learn --curate JSON output.
• Allowed --usage-file path with learn --curate.
• Added stale selected-id usage review items when the sidecar references ids no longer present in the active profile.
• Added unused active-entry review items when recorded prompt/pack usage has not selected entries yet.
• Kept usage review advisory only through autoArchive: false; unused entries are not archived automatically.
• Added human curation output for usage review when a sidecar is available or invalid.
• Added unit coverage for usage-file parsing, usage review JSON shape, stale selected ids, unused entries, and apply behavior that leaves usage-only entries untouched.
• Added package-smoke coverage for usage-aware curation JSON in installed-bin and one-shot packed tarball paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.43.0.

Impact

• Operators can review duplicate/sensitive cleanup and usage-derived stale/unused signals from one command.
• Curation remains archive-first and conservative; prompt/pack usage metadata cannot delete or archive a valid active entry on its own.
• Existing learning.json, learning.usage.json, learn --usage, workspace --learning-usage, and learn --curate --yes archive schemas remain compatible.

What this enables

• Safer learning profile maintenance before relying on personalized prompt context for solo or company dogfood use.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.42.0 → 4.43.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 257 — Workspace Learning Usage Readiness (v4.42.0) ✓ shipped

design-ai workspace now includes privacy-preserving prompt/pack learning usage sidecar readiness. The command can read an explicit --learning-usage path or auto-detect a sibling learning.usage.json beside the selected learning profile, then report whether local learning is actually being exercised and whether the sidecar still matches the active profile.

Changed

• Added --learning-usage path to design-ai workspace.
• Added sibling learning.usage.json auto-detection for the selected learning profile.
• Added learningUsage to workspace JSON with event counts, used/unused entry counts, stale selected id count, latest event metadata, privacy flags, recommendations, and readiness.
• Added human workspace output for learning usage sidecar status.
• Made workspace --strict fail when the usage sidecar points at another profile or references selected entry ids that no longer exist.
• Added next actions for aligned usage sidecars, stale/mismatched sidecars, missing usage telemetry, and usage report inspection.
• Added unit coverage for parsing, explicit usage paths, sibling usage auto-detection, stale selected ids, profile mismatch, human output, JSON output, and strict behavior.
• Added package/registry smoke fixture usage sidecars so workspace learning readiness covers usage metadata in installed-bin, one-shot, and public registry paths.
• Updated README, Korean README, Product Readiness, AI Learning docs, Distribution docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.42.0.

Impact

• Operators can now distinguish "learning profile exists" from "learning profile is being used in prompt/pack runs".
• Usage sidecar readiness remains read-only and privacy-preserving: selected entry ids and short brief hashes only, no raw brief text.
• Existing learning profile schema, usage sidecar event schema, eval checkpoint schema, prompt/pack recording behavior, and workspace eval freshness behavior remain compatible.

What this enables

• Safer curation decisions before archiving or rewriting learning entries.
• A stronger local dogfood gate for solo use first, company rollout later.

Verified

• All 8 audits pass.
• node --test cli/lib/workspace.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.41.0 → 4.42.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 256 — Workspace Learning Eval Freshness Guard (v4.41.0) ✓ shipped

design-ai workspace now checks whether an included learning eval checkpoint still matches the active learning profile metadata. A checkpoint can pass its deterministic cases but still produce a readiness warning when it was generated before the profile was updated, was generated from another profile path, or records a different source entry count.

Changed

• Added privacy-preserving generatedAt and sanitized sourceProfile metadata to learn --eval reports.
• Added learning.updatedAt and learningEval.freshness to workspace JSON.
• Added human workspace output for checkpoint generation time and freshness status.
• Made workspace --strict fail on stale/mismatched learning eval checkpoint freshness warnings through the existing nextActions warning path.
• Added a regenerate next-action command that rewrites the same checkpoint path through design-ai learn --eval-template --force.
• Added unit coverage for stale checkpoint detection and source profile drift.
• Added package-smoke fixture metadata so installed-bin and one-shot workspace strict smoke cover freshness-pass checkpoint metadata.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.41.0.

Impact

• Operators no longer get a clean workspace gate from an old checkpoint after adding or changing local learning entries.
• Existing checkpoint case schema, explicit --learning-eval override, sibling checkpoint auto-detection, prompt/pack learning selection, and profile storage remain compatible.

What this enables

• A more trustworthy local dogfood gate before relying on personalized prompt context for internal use or company rollout.

Verified

• All 8 audits pass.
• node --test cli/lib/workspace.test.mjs cli/lib/learn.test.mjs

Versions

• package.json + .claude-plugin/plugin.json: 4.40.0 → 4.41.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 255 — Workspace Learning Eval Sibling Checkpoint Discovery (v4.40.0) ✓ shipped

design-ai workspace now automatically includes the selected learning profile's sibling learning-eval.json checkpoint when the operator does not pass --learning-eval. The eval-template next action writes to the same sibling checkpoint path, so the suggested bootstrap command and the next workspace readiness run line up without extra flags.

Changed

• Added a deterministic default learning eval checkpoint path beside the selected learning profile.
• Auto-detect that sibling checkpoint when --learning-eval is omitted and the file exists.
• Kept explicit --learning-eval path as the override for alternate checkpoint files.
• Updated the eval-template next-action command to write to the sibling checkpoint path.
• Preserved shell-safe quoting for learning profile and checkpoint paths.
• Added unit coverage for sibling checkpoint auto-detection and the updated next-action output path.
• Added package-smoke coverage for installed-bin and one-shot npm exec --package <tarball> workspace strict runs that rely on sibling checkpoint discovery.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.40.0.

Impact

• Operators can generate a private local learning-eval.json once beside learning.json, then run design-ai workspace --strict without repeatedly passing --learning-eval.
• Existing explicit checkpoint paths, learning profile schema, eval checkpoint schema, workspace JSON key shape, and prompt/pack learning selection behavior remain compatible.

What this enables

• A lower-friction local dogfood loop for personal or company learning profiles while keeping checkpoint files colocated with the private profile by default.

Verified

• All 8 audits pass.
• node --test cli/lib/workspace.test.mjs cli/lib/help-command.test.mjs

Versions

• package.json + .claude-plugin/plugin.json: 4.39.0 → 4.40.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 254 — Workspace Learning Eval Command Path Quoting (v4.39.0) ✓ shipped

design-ai workspace now shell-quotes learning eval next-action command paths. The eval-template bootstrap hint and the checkpoint revalidation command remain copy/paste safe when the selected learning.json or learning-eval.json path includes spaces, apostrophes, or other shell-sensitive characters.

Changed

• Added a dependency-free shell argument quoting helper for workspace next-action commands.
• Applied quoting to design-ai learn --eval-template --file <learning.json> --out learning-eval.json.
• Applied quoting to design-ai learn --eval --from-file <checkpoint.json> --file <learning.json> --strict.
• Added unit coverage for safe args, empty args, spaces, apostrophes, eval-template next actions, and eval checkpoint next actions.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.39.0.

Impact

• Operators can copy/paste workspace learning eval next actions from realistic local project paths without manually escaping file names.
• Existing workspace JSON shape, learning profile schema, eval checkpoint schema, and prompt/pack learning selection behavior remain compatible.

What this enables

• A more reliable local dogfood loop for personal or company paths that include spaces, names, or synced folder labels.

Verified

• All 8 audits pass.
• node --test cli/lib/workspace.test.mjs

Versions

• package.json + .claude-plugin/plugin.json: 4.38.0 → 4.39.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 253 — Workspace Learning Eval Template Hints (v4.38.0) ✓ shipped

design-ai workspace now closes the gap between a populated local learning profile and the checkpoint gate. When the selected learning profile has entries, passes audit, and no --learning-eval checkpoint is supplied, the readiness next actions recommend generating a runnable checkpoint with design-ai learn --eval-template.

Changed

• Added an info-level workspace next action for design-ai learn --eval-template --file <learning.json> --out learning-eval.json.
• Kept the hint read-only and conditional: it is skipped for empty profiles, audit warnings/failures, profile errors, and runs that already include --learning-eval.
• Added unit coverage for the hint and for suppressing it when an eval checkpoint is present.
• Updated README, Korean README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.38.0.

Impact

• Operators can move from captured local learning entries to deterministic checkpoint validation without remembering the eval-template command manually.
• Existing learning.json, usage sidecar, eval checkpoint, workspace readiness, and prompt/pack learning selection schemas remain compatible.

What this enables

• A clearer dogfood loop: capture feedback, generate a checkpoint, run learn --eval --strict, then include the checkpoint in workspace --learning-eval --strict.

Verified

• All 8 audits pass.
• node --test cli/lib/workspace.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/smoke_assertions.py tools/audit/package-smoke.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• npm run release:self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.37.0 → 4.38.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 252 — Public Registry Learning Eval Template Smoke (v4.37.0) ✓ shipped

Post-publish registry smoke now covers the learning eval-template bootstrap path from the public package. tools/audit/registry-smoke.py runs design-ai learn --eval-template against a deterministic learning relevance fixture through npm exec --package @design-ai/cli@<version>, then feeds the generated checkpoint into design-ai learn --eval --strict --json.

Changed

• Extended assert_learning_relevance_smoke so public registry checks cover learn --eval-template --out <file> --force.
• Added registry smoke assertions for eval-template source profile metadata, checkpoint cases, raw-brief privacy disclosure, and generated strict eval pass.
• Added registry smoke self-test drift fixtures for eval-template privacy metadata and generated checkpoint strict validation.
• Added release metadata guard phrases for public registry eval-template smoke.
• Updated README, Distribution docs, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.37.0.

Impact

• Local packed-tarball smoke and post-publish registry smoke now protect the same eval-template bootstrap contract.
• Existing learning.json, usage sidecar, eval checkpoint, workspace readiness, and prompt/pack learning selection schemas remain compatible.

What this enables

• Operators can trust that checkpoint generation works not only from the local repo and packed tarball, but also from the published npm package path before broader internal distribution.

Verified

• All 8 audits pass.
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.36.0 → 4.37.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader product UI surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 251 — Learning Eval Template Generation (v4.36.0) ✓ shipped

Local learning eval checkpoints can now be bootstrapped from the active profile. design-ai learn --eval-template generates runnable checkpoint JSON from current entries, an optional query, category, and limit, so operators can immediately feed the output into design-ai learn --eval --strict.

Changed

• Added --eval-template to design-ai learn.
• Generated valid checkpoint JSON with version, source profile metadata, selection summary, cases, recommendations, and privacy metadata.
• Supported --query, --category, --limit, --json, --out, and --force.
• Kept the active learning.json read-only while allowing --out to write only the checkpoint artifact.
• Added unit tests for parser behavior, generated checkpoint validity, no-mutation behavior, and generated strict eval pass.
• Added package-smoke coverage for installed-bin and one-shot npm exec --package <tarball> paths.
• Updated CLI help assertions, README, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.36.0.

Impact

• Operators no longer need to hand-author every learning eval case before creating a deterministic local checkpoint suite.
• Existing learning.json, usage sidecar, eval checkpoint, workspace readiness, and prompt/pack learning selection schemas remain compatible.

What this enables

• Faster internal dogfood loops for local learning: capture feedback, generate checkpoint, run learn --eval --strict, then include it in workspace --learning-eval --strict.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.35.0 → 4.36.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader public-registry smoke coverage for future learning surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 250 — Public Registry Workspace Learning Eval Smoke (v4.35.0) ✓ shipped

Post-publish registry smoke now covers workspace learning eval readiness from the published package path. tools/audit/registry-smoke.py creates a clean git workspace plus local learning profile/eval checkpoint fixtures, then runs public npm exec --package @design-ai/cli@<version> with design-ai workspace --learning-eval <checkpoint.json> --strict --json.

Changed

• Added registry-smoke fixture generation for a deterministic workspace learning eval checkpoint.
• Extended the public registry workspace strict success smoke to include --learning-eval and validate the resulting learningEval JSON summary.
• Added a registry-smoke self-test fixture for strict workspace success with learning eval metadata.
• Added release metadata guard phrases for public registry workspace learning-eval smoke.
• Updated README, Distribution docs, Product Readiness, AI Learning docs, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.35.0.

Impact

• Local packed-tarball smoke and post-publish public registry smoke now protect the same workspace learning eval readiness contract.
• Existing CLI runtime behavior, learning.json, usage sidecar, and eval checkpoint schemas remain compatible.

What this enables

• External publish verification can catch npm registry path regressions in the dogfood readiness gate before broader company rollout.

Verified

• All 8 audits pass.
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.34.0 → 4.35.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader public-registry smoke coverage for future learning surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 249 — Workspace Learning Eval Readiness (v4.34.0) ✓ shipped

Workspace readiness can now include local learning checkpoint health. design-ai workspace --learning-eval <checkpoint.json> reads the selected --learning-file profile and reports a compact learning eval summary beside git, repository metadata, learning audit state, release scripts, and next actions.

Changed

• Added --learning-eval path to design-ai workspace.
• Added optional learningEval JSON output with source path, profile file, status, case counts, audit summary, privacy flags, and error text.
• Added a human "Learning eval" section when a checkpoint is supplied.
• Extended workspace --strict so learning eval warn/fail states become readiness issues without mutating learning.json.
• Added package-smoke coverage for clean strict workspace runs with learning eval summaries through installed-bin and one-shot npm exec --package <tarball> paths.
• Added unit tests, CLI help tests, smoke assertions, release metadata guard phrases, AI learning docs, README, Product Readiness, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.34.0.

Impact

• Operators can use one local workspace readiness command to inspect repo sync, learning profile audit state, release-script availability, and deterministic learning-selection checkpoint health before dogfood handoff.
• Existing learning.json, usage sidecar, and eval checkpoint schemas remain compatible.

What this enables

• A future composite dogfood gate can promote workspace --learning-eval --strict as the local pre-handoff check before heavier release smoke.

Verified

• All 8 audits pass.
• node --test cli/lib/workspace.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.33.0 → 4.34.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader public-registry smoke coverage for future learning surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 248 — Local Learning Eval Strict Gate (v4.33.0) ✓ shipped

Local learning eval checkpoints can now act as deterministic failure gates. design-ai learn --eval --strict keeps the existing report-first, read-only behavior, then exits non-zero when any checkpoint case warns or fails.

Changed

• Added --strict to design-ai learn --eval.
• Rejected --strict outside eval mode so other learning commands keep their previous exit behavior.
• Preserved JSON/human output and safe --out report writes before applying the strict non-zero exit status.
• Added package-smoke coverage for strict failed checkpoints through installed-bin and one-shot npm exec --package <tarball> paths.
• Added unit tests, CLI help tests, package-smoke assertions, release metadata guard phrases, AI learning docs, README, Product Readiness, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.33.0.

Impact

• Operators can use local learning checkpoint suites in CI or internal release scripts without adding external AI APIs, embeddings, telemetry, fine-tuning, or raw brief storage.
• Existing learning.json schema, usage sidecar schema, eval checkpoint payloads, and prompt/pack learning injection remain compatible.

What this enables

• Future release gates can combine workspace --strict, site --bundle-check --strict, and learn --eval --strict into one local dogfood readiness sequence.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.32.0 → 4.33.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader public-registry smoke coverage for future learning surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 247 — Local Learning Eval Checkpoints (v4.32.0) ✓ shipped

Local learning selection is now checkpointable without mutating the learning profile. design-ai learn --eval reads a JSON checkpoint file or stdin and verifies expected selected ids, avoided selected ids, minimum matched counts, and fallback policy against the same brief-relevance ranking used by prompt --with-learning and pack --with-learning.

Changed

• Added --eval to design-ai learn with --from-file, --stdin, --category, --limit, --json, --out, and --force support.
• Reported per-case status, brief hashes, selected ids, matched counts, fallback state, warnings, failures, and privacy metadata.
• Kept eval reports privacy-preserving by exposing short brief hashes and selected ids, not raw brief / query text or matched tokens.
• Added safe learn --eval --json --out <file> coverage with normal --force overwrite behavior.
• Added unit tests, CLI help tests, package-smoke assertions, release metadata guard phrases, AI learning docs, README, Product Readiness, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.32.0.

Impact

• Operators can validate that learned context still selects intended entries for known briefs before using it as a release or handoff confidence signal.
• Existing learning.json schema, usage sidecar schema, prompt/pack learning injection, and cleanup flows remain compatible.

What this enables

• Future local learning quality gates can combine explicit feedback, check-captured QA issues, usage sidecar activity, and checkpoint results without adding external AI services.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.31.0 → 4.32.0.

What's still ahead

• Semantic embeddings, fine-tuning, hosted sync, and broader public-registry smoke coverage for future learning surfaces remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 246 — Local Learning Usage Report (v4.31.0) ✓ shipped

Local learning usage is now inspectable without mutating the learning profile. design-ai learn --usage reads the active learning.json profile plus a sibling usage sidecar such as learning.usage.json and emits a deterministic report in human or JSON form.

Changed

• Added --usage and --usage-file to design-ai learn.
• Summarized usage sidecar events, command counts, route counts, category counts, audit status counts, selected entry counts, unused active entry ids, stale selected ids, and recent events.
• Kept the report privacy-preserving by exposing selected ids and brief hashes, not raw prompt / brief text.
• Added safe learn --usage --json --out <file> coverage with normal --force overwrite behavior.
• Added unit tests, CLI help tests, package-smoke assertions, release metadata guard phrases, AI learning docs, README, Product Readiness, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.31.0.

Impact

• Operators can see whether local learning entries are actually used by prompt / pack --with-learning.
• Existing learning.json schema, usage sidecar write format, prompt/pack learning injection, and cleanup flows remain compatible.

What this enables

• Future deterministic quality checks can compare explicit feedback, check-captured issues, and actual prompt/pack usage frequency before introducing any heavier learning layer.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.30.0 → 4.31.0.

What's still ahead

• Eval/checkpoint harnesses, semantic embeddings, fine-tuning, hosted sync, and public-registry smoke expansion for usage reports remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 245 — Local Learning Usage Sidecar (v4.30.0) ✓ shipped

Local learning injection now leaves a local, privacy-preserving usage trail outside learning.json. design-ai prompt --with-learning and design-ai pack --with-learning write selection metadata into a sibling usage sidecar such as learning.usage.json.

Changed

• Added local learning usage event helpers for sidecar load/write/normalization.
• Recorded prompt and pack learning usage only when --with-learning is explicitly used.
• Stored selected learning entry ids, command, route id, selection counts, audit status, and a short brief hash instead of raw prompt text.
• Added learningUsage metadata to prompt/pack JSON output.
• Added unit and package-smoke coverage for sidecar events through installed-bin and npm exec --package <tarball> paths.
• Updated package/plugin metadata to 4.30.0.

Impact

• Operators can see which local learning entries are actually injected over time without modifying the learning profile schema.
• The feature remains local-only and does not add external telemetry, embeddings, model calls, or fine-tuning behavior.

What this enables

• Future learning quality reports can identify stale or unused entries from deterministic local usage events.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.29.0 → 4.30.0.

What's still ahead

• Deterministic learning quality reports, eval/checkpoint harnesses, semantic embeddings, fine-tuning, and hosted multi-user sync remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 244 — Local Learning Archive-First Curation (v4.29.0) ✓ shipped

Local learning profiles now have a safer maintenance loop. design-ai learn --curate previews deterministic curation proposals, and design-ai learn --curate --yes moves duplicate and sensitive-content entries into a sibling archive JSON instead of deleting them outright.

Changed

• Added --curate to design-ai learn.
• Added curation plan helpers that classify duplicate learning text and conservative sensitive-content warnings as archive candidates.
• Kept malformed entries, duplicate ids, timestamp gaps, long notes, and profile-level failures in manual-review status.
• Added learning.archive.json-style archive persistence with archivedAt, archiveReason, issueCodes, and originalFile metadata.
• Added CLI help, parser, unit test, package-smoke assertion, AI learning docs, README, Product Readiness, Changelog, Roadmap, and Session Log coverage.
• Updated package/plugin metadata to 4.29.0.

Impact

• Operators can clean a growing local learning profile before prompt / pack --with-learning while preserving removed entries for review and audit history.
• Existing learn --audit, learn --audit --fix, learn --forget, learn --clear, check --learn, and learned-context injection behavior remain compatible.

What this enables

• A later local learning telemetry layer can record usage/selection metadata without changing the profile schema or requiring external AI services.

Verified

• All 8 audits pass.
• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: 4.28.0 → 4.29.0.

What's still ahead

• Deterministic sidecar usage telemetry, eval/checkpoint harnesses, semantic embeddings, fine-tuning, and hosted multi-user sync remain future phases.
• External release remains held until owner review and Real-CI are green.

Phase 1 — Foundation ✓ shipped (v1.0)

Three commits. See git log --oneline.

• Project skeleton, entry docs (README, AGENTS.md, CLAUDE.md)
• Sparse-cloned upstream sources into refs/
• Architecture, contributing, using, Figma-integration, token-sync docs
• 7 idempotent extractors (tools/extractors/)
• 24 knowledge files / 10K+ lines (a11y, colors, components, design-tokens, i18n, icons, layout, motion, patterns, typography)
• 6 skills with playbooks: design-system-builder, component-spec-writer, color-palette, ux-audit, design-critique, handoff-spec
• 4 agent personas: design-critic, a11y-reviewer, token-extractor, component-architect
• 4 slash commands: design-review, palette-from-brand, component-spec, extract-tokens
• 6 worked examples: violet SaaS palette, Button, Input, Modal, Toast, Card
• Dogfood validation: Korean fintech app design system bootstrap end-to-end
• Self-critique published as docs/DOGFOOD-FINDINGS.md

Phase 2 — Depth ✓ shipped (v1.1)

Driven by the dogfood findings. Wrapped in 4 commits (Batch A–D).

Knowledge gaps filled

• knowledge/patterns/money-and-amount.md — currency display, amount input ergonomics, ± color semantics (separate axis from primary/error), Korean stock convention (red=up), tabular numerals, edge cases.
• knowledge/patterns/mobile-navigation.md — bottom tab bar, top app bar, drawer (when NOT), stack, back navigation contract, search patterns, sheets.
• knowledge/patterns/list-and-feed.md — list anatomy, settings/chat/transaction/search patterns, pull-to-refresh, infinite scroll vs Load More, empty/loading/error states, swipe actions, virtualization.
• knowledge/platforms/react-native.md — web↔RN gap matrix, token translation, Pressable, touch targets/hitSlop, safe area, keyboard handling, animations (Reanimated), Pretendard loading, navigation, common pitfalls.
• knowledge/i18n/korean-payments.md — vendor landscape, decision tree by product type, payment selector ordering, subscription disclosure, 청약철회, 본인인증, ESCROW, cost structure.

More component specs (examples/)

• Form (composition pattern with Zod + react-hook-form)
• Table / DataTable (TanStack engine, mobile→card-list)
• Tabs (underline / segmented / card / bottom-bar in one spec)
• DatePicker (single / range / dateTime / quickRange, Korean formats)
• Select / Combobox (single/multi/searchable/creatable/async)
• Pagination (numbered / Load More / simple, URL sync)

Skill upgrades

• color-palette PLAYBOOK — added "mood → hue mapping" section + differentiation check + Korean considerations + verification phase.
• design-system-builder PLAYBOOK — added "starter component set by category" with extension matrix for 8 product categories + verification phase.
• component-spec-writer PLAYBOOK — added verification phase (cite ≥ 2 references, all states, ARIA, keyboard, RN/IME conditional).
• ux-audit PLAYBOOK — verification phase (user goal stated, every issue cited, CRITICAL has WCAG section).
• design-critique PLAYBOOK — verification phase (problem-fit first, hierarchy walk, single recommendation).
• handoff-spec PLAYBOOK — verification phase (every screen, every component referenced or sub-spec'd).

Tooling

• tools/audit/check-coverage.py — coverage report. Outputs to knowledge/COVERAGE.md + console summary.
• CI lint that fails PRs introducing raw hex in examples/ unless the file is an explicit palette/brand/email/chart fixture. (Phase 50)

Phase 243 — Website Improvement Target-Repo Bundle Handoff Prompt (v4.28.0) ✓ shipped

Verified Website Improvement handoff bundles can now be converted into target-repo implementation prompts. design-ai site <bundle-dir> --bundle-handoff [--strict] [--json] reuses bundle-check validation, carries the SHA-256 bundle digest, embeds the top-priority Codex implementation prompt, and adds target-repo operating rules plus final response requirements.

Changed

• Added --bundle-handoff for design-ai site.
• Added human Markdown prompt output and JSON output with status, valid, bundle, prompt, files, and issues.
• Reused bundle-check validation so strict mode fails on bundle warnings or failures before target-repo handoff.
• Added unit/help coverage for parser validation, verified prompt generation, tampered bundle handling, JSON output, and output-file writing.
• Extended packed-tarball smoke coverage for installed-bin and one-shot npm exec --package <tarball> paths.
• Updated release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.28.0.

Impact

• Operators can paste one verified prompt into the target website repo instead of manually stitching together summary.json, website-handoff.md, mcp-action-plan.md, and codex-implementation.md.
• The prompt preserves the design-ai boundary: no external MCP calls and no target repo mutation happen inside design-ai.

What this enables

• Future target-repo automation can consume one handoff JSON contract after bundle approval and before implementation.

Versions

• package.json + .claude-plugin/plugin.json: 4.27.0 → 4.28.0.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• All 8 audits pass.
• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs

Phase 242 — Website Improvement Handoff Bundle Compare (v4.27.0) ✓ shipped

Website improvement handoff bundles can now be compared as deterministic local artifacts. design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> [--strict] [--json] validates both bundles with bundle-check, compares bundle digest identity, lists checksum-level file changes, and reports summary metadata drift before target-repo handoff.

Changed

• Added --bundle-compare <other-bundle-dir> for design-ai site.
• Added human and JSON compare output with sameBundle, digestMatch, changed files, metadata changes, and issue counts.
• Reused local bundle-check validation for both compared directories before comparing fingerprints.
• Added unit and help coverage for parser validation, identical bundle compare, changed bundle compare, command help, and output-file writing.
• Extended packed-tarball smoke coverage for installed-bin and one-shot npm exec --package <tarball> paths.
• Updated release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.27.0.

Impact

• Operators can confirm whether archived or regenerated Website Improvement handoff bundles are identical before implementation.
• When bundles differ, the compare report points at changed generated artifacts instead of requiring manual checksum inspection.

What this enables

• Future hosted, VS Code, or target-repo automation can use one compare JSON contract for bundle approval and archive drift review.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: 4.26.0 → 4.27.0.

Phase 241 — Website Improvement Handoff Bundle Fingerprint Verification (v4.26.0) ✓ shipped

Website improvement handoff bundles now carry a deterministic bundle-level fingerprint. design-ai site --bundle --out <dir> records summary.json.checksums.bundleDigest from the ordered SHA-256 checksum manifest, and design-ai site <bundle-dir> --bundle-check [--strict] [--json] verifies both the manifest digest and the current bundle files before target-repo handoff.

Changed

• Added summary.json.checksums.bundleDigest as a stable SHA-256 digest for the ordered checksum manifest.
• Extended bundle-check validation to fail when the stored bundle digest does not match the checksum manifest or the current generated files.
• Added bundle digest output to the human bundle-check report so operators can compare handoff bundle identity quickly.
• Preserved backward compatibility for v4.25 bundles by warning when bundleDigest is missing instead of treating old checksum manifests as corrupt.
• Added unit coverage for bundle digest shape, human output, and tampered bundle digest failure.
• Extended packed-tarball smoke assertions to verify bundle digest presence in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.26.0.

Impact

• Operators can compare, archive, or attach Website Improvement handoff bundles using a single stable bundle fingerprint.
• File-level checksum diagnostics remain intact for pinpointing which artifact drifted.

What this enables

• Future hosted, VS Code, or target-repo automation can store a compact bundle fingerprint while still relying on the full checksum manifest for detailed validation.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: 4.25.0 → 4.26.0.

Phase 240 — Website Improvement Handoff Bundle Checksum Verification (v4.25.0) ✓ shipped

Website improvement handoff bundles now carry SHA-256 checksums for generated artifacts. design-ai site --bundle --out <dir> records the checksum manifest in summary.json, and design-ai site <bundle-dir> --bundle-check [--strict] [--json] recomputes those checksums before target-repo handoff.

Changed

• Added summary.json.checksums with algorithm: "sha256" and digests for every generated bundle file except summary.json.
• Extended bundle-check JSON/human output with expected checksum file count, verified checksum file count, and checksum failure count.
• Added checksum mismatch failures so edited or partially transferred bundle files fail the local integrity gate.
• Kept the verification deterministic and local: no external MCP calls, target repo mutation, backend storage, crawling, Lighthouse/axe automation, visual diff, embeddings, fine-tuning, or new dependencies were added.
• Added unit coverage for checksum manifest shape, complete checksum verification, and tampered bundle failure.
• Extended packed-tarball smoke assertions to verify the checksum manifest and bundle-check checksum counts in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.25.0.

Impact

• Operators can detect handoff bundle drift after copying, attaching, archiving, or editing generated artifacts.
• Internal pilots get a stronger local integrity gate before using a bundle in a Codex or Claude target-repo implementation session.

What this enables

• Future target-repo automation can trust bundle-check JSON to include both structural validity and artifact integrity.
• Hosted or VS Code consumers can reuse the same checksum contract when bundles move between storage surfaces.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs
• node --test cli/lib/site.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: 4.24.0 → 4.25.0.

Phase 239 — Website Improvement Handoff Bundle Verification (v4.24.0) ✓ shipped

Website improvement handoff bundles can now be checked as portable artifacts. design-ai site <bundle-dir> --bundle-check [--strict] [--json] [--out file] validates the generated bundle directory before it is attached to a target-repo Codex or Claude implementation session.

Changed

• Added --bundle-check for design-ai site as a read-only handoff bundle directory verification mode.
• Added human and JSON bundle-check output with file counts, summary/task/MCP status, unexpected file reporting, and issue details.
• Validates the expected bundle file manifest, JSON parseability, summary.json file list, task count consistency, site name consistency, mcp-check.json status/counts against recomputed local MCP readiness, and required Markdown anchors.
• Kept the check deterministic and local: no external MCP calls, target repo mutation, backend storage, crawling, Lighthouse/axe automation, visual diff, embeddings, fine-tuning, or new dependencies were added.
• Added unit coverage for parser validation, complete bundle verification, missing bundle file failure, command-specific help, and help JSON catalog usage.
• Added packed-tarball smoke coverage for design-ai site <bundle-dir> --bundle-check --strict --json in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.24.0.

Impact

• Operators can verify a handoff bundle after export and before target-repo implementation.
• Internal pilots now have a local integrity gate for bundle portability, manifest drift, and stale MCP readiness evidence.

What this enables

• Future bundle consumers, VS Code webviews, or target-repo automation can depend on the same bundle-check JSON contract.
• Real MCP probes can later replace local readiness evidence while keeping bundle validation stable.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: 4.23.0 → 4.24.0.

Phase 238 — Website Improvement Handoff Bundle Export (v4.23.0) ✓ shipped

Website improvement work can now be packaged as a complete local handoff bundle. design-ai site <workspace.json|--stdin> --bundle --out <dir> [--strict] [--force] writes a portable directory containing generated tasks, MCP readiness, MCP action plan, handoff report, prompt bundle, and a focused Codex implementation prompt.

Changed

• Added --bundle --out <dir> for design-ai site as a directory output mode for workspace/stdin inputs.
• Added bundle artifact generation for README.md, summary.json, website-workspace.tasks.json, mcp-check.json, mcp-action-plan.md, website-handoff.md, website-prompts.md, and codex-implementation.md.
• Reused deterministic local task generation, MCP readiness, action plan, report, and prompt builders; no external MCP calls, target repo mutation, backend storage, crawling, Lighthouse/axe automation, visual diff, embeddings, fine-tuning, or new dependencies were added.
• Added safe directory output writing with collision checks and --force overwrite behavior.
• Added unit coverage for parser validation, bundle file manifest, generated implementation prompt, output directory writing, command-specific help, and help JSON catalog usage.
• Added packed-tarball smoke coverage for design-ai site --stdin --bundle --out <dir> in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.23.0.

Impact

• Operators can move from Website Console JSON to a single handoff directory that includes both machine-readable evidence and human-readable execution docs.
• Solo/internal pilots can attach the bundle to a target-repo Codex session without copying multiple ad hoc artifacts by hand.

What this enables

• Internal pilots can keep --mcp-check --strict --json as the automated gate, --mcp-plan --out mcp-action-plan.md as the operator checklist, and --bundle --out website-handoff-bundle as the portable handoff package.
• Future real MCP connection probes can reuse the same bundle manifest while replacing local readiness evidence with live probe results.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs cli/lib/output.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• npm run package:smoke
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• Manual CLI smoke for design-ai site --bundle --out, design-ai site --stdin --bundle --out, and design-ai help site

Versions

• package.json + .claude-plugin/plugin.json: 4.22.0 → 4.23.0.

Phase 237 — Website Improvement MCP Action Plan Export (v4.22.0) ✓ shipped

Website improvement readiness checks can now become an operator-facing action plan. design-ai site <workspace.json|--stdin> --mcp-plan [--strict] [--out file] exports a Markdown plan that translates MCP readiness evidence, workspace issues, and task/MCP gaps into blocking items, warnings, task alignment, execution sequence, and follow-up commands.

Changed

• Added --mcp-plan for design-ai site as a read-only workspace/stdin mode.
• Added Markdown action plan output with summary, readiness matrix, blocking items, warnings, task/MCP alignment, execution sequence, reusable commands, and local/operator boundaries.
• Reused the same deterministic local readiness engine as --mcp-check; no external MCP calls, target repo mutation, backend storage, crawling, Lighthouse/axe automation, visual diff, embeddings, fine-tuning, or new dependencies were added.
• Added unit coverage for parser validation, action plan content, output-file writing, command-specific help, and help JSON catalog usage.
• Added packed-tarball smoke coverage for design-ai site --stdin --mcp-plan in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.22.0.

Impact

• Operators can include a human-readable readiness remediation plan with Website Improvement handoff packages.
• The strict JSON readiness gate remains machine-readable, while --mcp-plan gives solo/internal pilots a concise execution sequence before handing work to Codex or Claude.

What this enables

• Internal pilots can keep --mcp-check --strict --json as the automated gate and --mcp-plan --out mcp-action-plan.md as the operator checklist.
• Future real MCP connection probes can keep the same action plan output contract while replacing local evidence checks underneath.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• npm run package:smoke
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• Manual CLI smoke for design-ai site --mcp-plan, design-ai site --mcp-plan --out, and design-ai help site

Versions

• package.json + .claude-plugin/plugin.json: 4.21.0 → 4.22.0.

Phase 236 — Website Improvement MCP Readiness Check (v4.21.0) ✓ shipped

Website improvement work now has a local MCP readiness gate. design-ai site <workspace.json|--stdin> --mcp-check [--strict] [--json] checks Site Profile evidence, MCP readiness statuses, workspace validation issues, and refactor task MCP recommendations before operators hand work to Codex, Claude, or a target repo.

Changed

• Added --mcp-check for design-ai site as a read-only workspace/stdin mode.
• Added human and JSON MCP readiness output with item-level state, evidence, actions, counts, task gaps, workspace issues, and next actions.
• Added strict failure behavior when required MCP evidence or unavailable task MCP dependencies are present.
• Kept the command deterministic and local: no external MCP calls, target repo mutation, backend storage, crawling, Lighthouse/axe automation, visual diff, embeddings, fine-tuning, or new dependencies.
• Added unit coverage for parser validation, human/JSON readiness output, stdin/file input, output-file writing, required MCP failures, and task/MCP gap warnings.
• Added packed-tarball smoke coverage for design-ai site --stdin --mcp-check --json in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.21.0.

Impact

• Operators can catch missing GitHub/Figma/browser/deploy/Sentry/CMS/DB/collaboration/research readiness evidence before exporting implementation prompts.
• Website Improvement remains a file-first local control tower while gaining a stricter pre-handoff quality gate.
• Release smoke now verifies MCP readiness JSON output from both installed-bin and one-shot npm exec --package <tarball> paths.

What this enables

• Internal pilots can treat --mcp-check --strict --json as a stable readiness contract before starting target-repo implementation.
• Future phases can replace local evidence checks with real MCP connection probes while preserving the same JSON shape.

What's still ahead

• Real MCP connection probes, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• npm run package:smoke
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• Manual CLI smoke for design-ai site --mcp-check, design-ai site --mcp-check --json, and design-ai help site

Versions

• package.json + .claude-plugin/plugin.json: 4.20.0 → 4.21.0.

Phase 235 — Website Improvement Prompt Template Listing (v4.20.0) ✓ shipped

Website improvement prompt templates can now be discovered directly from the CLI. design-ai site --prompt-list [--json] lists the eight Codex/Claude template ids with agent, output type, description, and task-selection support before operators export a single prompt.

Changed

• Added --prompt-list for design-ai site as a workspace-free, read-only mode.
• Added human and JSON prompt template listing output.
• Added template metadata for id, label, agent, output, description, and taskSelectable.
• Kept --task scoped to codex-implementation, while making that capability visible in the template listing.
• Added unit coverage for parser validation, human/JSON listing output, output-file writing, command-specific help, and release-facing help catalog usage.
• Added packed-tarball smoke coverage for prompt template listing in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.20.0.

Impact

• Operators can choose codex-repo-intake, codex-implementation, claude-design-review, or another Website Improvement template without opening docs or generating the full prompt bundle.
• The command remains local and deterministic: no target repo mutation, no external MCP calls, no backend storage, no embeddings, no fine-tuning, and no new dependencies.
• Packed-tarball smoke now verifies prompt template listing JSON output from both installed-bin and one-shot npm exec --package <tarball> paths.

What this enables

• Internal pilots can keep a terminal-first Website Improvement workflow and discover prompt ids before exporting a single handoff prompt.
• Future phases can add real MCP readiness checks while preserving the same prompt template catalog contract.

What's still ahead

• Real MCP connection checks, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py tools/audit/registry-smoke.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• npm run package:smoke
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• Manual CLI smoke for design-ai site --prompt-list and design-ai site --prompt-list --json

Versions

• package.json + .claude-plugin/plugin.json: 4.19.0 → 4.20.0.

Phase 234 — Website Improvement Prompt Task Selection (v4.19.0) ✓ shipped

Website improvement implementation prompts can now target a specific refactor task. design-ai site --prompt codex-implementation --task <id-or-number> reads Website Improvement workspace JSON and emits a Markdown implementation prompt for that selected task instead of always using the top-priority task.

Changed

• Added --task <id-or-number> for design-ai site --prompt codex-implementation.
• Added deterministic task resolution by id or by 1-based top-task order.
• Added Task ID to generated implementation prompts for clearer handoff traceability.
• Updated the human design-ai site task summary to show task numbers and ids.
• Kept --task scoped to --prompt codex-implementation so report, bundle, JSON, sample, and task-generation modes stay unambiguous.
• Added unit coverage for parser validation, id selection, numeric selection, unknown task handling, output-file writing, and command-specific help.
• Added packed-tarball smoke coverage for task-selected prompt generation in installed-bin and one-shot npm exec --package <tarball> paths.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.19.0.

Impact

• Operators can generate a focused Codex implementation prompt for task-accessibility, task-content-quality, or another selected task from a multi-task workspace.
• The command remains local and deterministic: no target repo mutation, no external MCP calls, no backend storage, no embeddings, no fine-tuning, and no new dependencies.
• Packed-tarball smoke now verifies task-selected prompt Markdown output from both installed-bin and one-shot npm exec --package <tarball> paths.

What this enables

• Internal pilots can keep a single Website Improvement workspace with several tasks and export the exact next prompt without reordering JSON or manually editing the prompt.
• Future phases can add prompt-template listing and real MCP readiness checks on top of the same workspace schema.

What's still ahead

• Real MCP connection checks, target-repo automation, Lighthouse/axe/visual diff, hosted multi-user storage, and public registry smoke expansion remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs cli/commands/help.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• npm run release:self-test
• npm run release:metadata
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• Manual CLI smoke for design-ai site --sample → --tasks → --prompt codex-implementation --task task-accessibility

Versions

• package.json + .claude-plugin/plugin.json: 4.18.0 → 4.19.0.

Phase 233 — Website Improvement Single Prompt CLI Export (v4.18.0) ✓ shipped

Website improvement work can now export one Codex or Claude prompt from the CLI. design-ai site --prompt <template-id> reads a Website Improvement workspace JSON and emits a single Markdown prompt for the next handoff step.

Changed

• Added design-ai site <workspace.json|--stdin> --prompt <template-id> [--out file] [--force] as a single-prompt Markdown mode.
• Added prompt template id validation for the eight Website Improvement templates.
• Kept generated workspace, summary, report, full prompt bundle, and single prompt output modes separate to avoid ambiguous CLI output.
• Added unit coverage for parser validation, selected prompt generation, output-file writing, and command-specific help.
• Added packed-tarball smoke coverage for installed-bin and one-shot npm exec --package <tarball> paths.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.18.0.

Impact

• Operators can use a file-first flow: design-ai site --sample, edit findings, design-ai site workspace.json --tasks, then export only --prompt codex-implementation for the target repo.
• The command remains local and deterministic: no target repo mutation, no external MCP calls, no backend storage, no embeddings, no fine-tuning, and no new dependencies.
• Packed-tarball smoke now verifies single-prompt Markdown output from both installed-bin and one-shot npm exec --package <tarball> paths.

What this enables

• Internal pilots can paste a focused next-step prompt into Codex or Claude without manually cutting a section out of the full prompt bundle.
• Future phases can add task selection, prompt-template listing, and real MCP readiness checks on top of the same workspace schema.

What's still ahead

• Real MCP connection checks, target-repo automation, Lighthouse/axe/visual diff, and hosted multi-user storage remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs docs/website-console/app.js
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• All 8 audits pass.
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: 4.17.0 → 4.18.0.

Phase 232 — Website Improvement Refactor Task CLI Generation (v4.17.0) ✓ shipped

Website improvement work can now generate starter refactor tasks from the CLI. design-ai site --tasks reads a Website Improvement workspace JSON, converts audit findings into deterministic task entries, and emits updated workspace JSON for later validation, prompt generation, or handoff reporting.

Changed

• Added design-ai site <workspace.json|--stdin> --tasks [--out file] [--force] as a generated workspace mode.
• Added shared CLI helpers for category-to-MCP mapping, Codex task prompt generation, and deterministic starter task creation.
• Updated the Web App task generator to skip categories that already have a refactor task, preventing duplicate category-level tasks after repeated generation.
• Added unit coverage for parser validation, duplicate-safe task generation, stdout output, output-file writing, and command-specific help.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.17.0.

Impact

• Operators can use a file-first flow: design-ai site --sample, edit findings, design-ai site workspace.json --tasks, then generate --prompts or --report.
• The command remains local and deterministic: no target repo mutation, no external MCP calls, no backend storage, no embeddings, no fine-tuning, and no new dependencies.
• Packed-tarball smoke now verifies generated task workspace JSON from both installed-bin and one-shot npm exec --package <tarball> paths.

What this enables

• Internal pilots can keep Website Improvement workspace JSON in a repo and still generate an initial implementation backlog without opening the browser console.
• Future phases can add richer task prioritization, selected-template prompt output, and real MCP readiness checks on top of the same workspace schema.

What's still ahead

• Real MCP connection checks, target-repo automation, Lighthouse/axe/visual diff, and hosted multi-user storage remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs docs/website-console/app.js
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• All 8 audits pass.
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: 4.16.0 → 4.17.0.

Phase 231 — Website Improvement Sample Workspace Bootstrap (v4.16.0) ✓ shipped

Website improvement work can now start from the CLI without first opening the static console. design-ai site --sample emits a valid Website Improvement workspace JSON that can be saved, shared, validated, and converted into handoff artifacts.

Changed

• Added design-ai site --sample [--out file] [--force] as a standalone sample workspace mode.
• Updated parseSiteArgs and runSite so sample generation does not require a workspace input and cannot be mixed with validation/report/prompt modes.
• Added unit coverage for sample parsing, invalid combinations, stdout output, output-file writing, and command-specific help.
• Updated help catalog, smoke assertions, package smoke, release metadata phrase guards, README, Distribution docs, Product Readiness, Website Improvement docs, Changelog, Roadmap, and Session Log.
• Updated package/plugin metadata to 4.16.0.

Impact

• Operators can bootstrap a Website Improvement workspace from a terminal, then run design-ai site website-workspace.json --json, --report, or --prompts after editing.
• The command remains local and deterministic: no target repo mutation, no external MCP calls, no backend storage, no embeddings, no fine-tuning, and no new dependencies.
• Packed-tarball smoke now verifies sample workspace JSON from both installed-bin and one-shot npm exec --package <tarball> paths.

What this enables

• File-first internal pilots can keep workspace JSON in a local project folder or internal repo before opening the Web App.
• Future CLI subcommands can reuse the same workspace bootstrap path for schema validation, MCP connection checks, and target-repo handoff automation.

What's still ahead

• Real MCP connection checks, target-repo automation, Lighthouse/axe/visual diff, and hosted multi-user storage remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• All 8 audits pass.
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: 4.15.0 → 4.16.0.

Phase 230 — Website Improvement Workspace CLI (v4.15.0) ✓ shipped

Website Improvement Console exports now have a CLI handoff path. design-ai site validates exported workspace JSON, summarizes readiness, and generates Markdown artifacts without leaving the local/operator boundary.

Changed

• Added design-ai site <workspace.json|--stdin> with --json, --strict, --report, --prompts, --out, and --force.
• Added cli/lib/site.mjs, cli/commands/site.mjs, and unit coverage for parser validation, schema summaries, stdin input, strict warnings, handoff report generation, prompt bundle generation, and output-file writing.
• Added examples/website-improvement-workspace.json as a portable sample export fixture.
• Updated CLI dispatch/help catalog and package smoke so installed-bin and one-shot npm exec --package <tarball> paths verify design-ai site --stdin --json.
• Updated package/plugin metadata to 4.15.0.

Impact

• Operators can move from the static Web App to durable Markdown handoff artifacts without manually copying every prompt/report section.
• The command keeps the MVP boundary intact: no target website repo mutation, no external MCP calls, no backend storage, no embeddings, no fine-tuning, and no new dependencies.
• Future Playwright/Figma/GitHub/Sentry/Vercel connection checks can attach to the same workspace schema.

What this enables

• Website improvement work now has a browser-to-CLI handoff: localStorage workspace → JSON export → validated Markdown report/prompt artifacts.
• Internal company pilots can store reviewable handoff artifacts without introducing hosted storage or changing the target website repo.

What's still ahead

• Real MCP connection checks, target-repo automation, Lighthouse/axe/visual diff, and hosted multi-user storage remain future phases.
• External release remains held until owner review and Real-CI are green.

Verified

• node --check cli/lib/site.mjs cli/commands/site.mjs
• node --test cli/lib/site.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm test
• All 8 audits pass.
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: 4.14.0 → 4.15.0.

Phase 229 — Website Improvement Control Tower Web App (v4.14.0) ✓ shipped

Website improvement is now a first-class design-ai workflow: a local static Web App coordinates Site Profiles, audit checklists, MCP readiness, refactor tasks, prompt generation, and handoff reports without owning or mutating the target website source repo.

Changed

• Added docs/website-console/ as a zero-dependency static Web App with localStorage persistence, JSON export/import, sample Korean SaaS Site Profile data, dense dashboard styling, and keyboard-reachable controls.
• Added docs/WEBSITE-IMPROVEMENT.md / .ko.md plus MkDocs navigation so the control tower is documented alongside the existing product docs.
• Added skills/website-improvement/, commands/website-improvement.md, and examples/website-improvement-report.md.
• Added the website-improvement CLI route, route-aware prompt checklist, and design-ai check --route website-improvement quality requirements.
• Updated package/plugin metadata to 4.14.0 and 20 skills / 17 commands / 4 agents.

Impact

• Solo and internal operators can prepare website improvement work from one local dashboard before handing implementation prompts to Codex in the target website repo.
• Claude remains positioned for design review, copy/UX critique, competitor research, and alternative proposals; MCPs remain readiness/status inputs in MVP rather than external write actions.
• The Web App state schema can later be promoted to API storage or reused in a VS Code Webview without changing the core workspace shape.

What this enables

• Future phases can add design-ai site ... CLI validation/report generation, Browser/Playwright/Figma/GitHub/Sentry/Vercel connection checks, and target-repo handoff automation.

What's still ahead

• Automatic crawling, Lighthouse, axe, visual diff, screenshot capture, backend sync, auth, multi-user collaboration, and real MCP writes remain out of MVP scope.
• External launch remains held until owner review and Real-CI are green.

Verified

• node --check docs/website-console/app.js
• node --test cli/lib/route.test.mjs cli/lib/prompt.test.mjs cli/lib/check.test.mjs
• python3 -m py_compile tools/audit/*.py
• npm test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run release:metadata
• npm run release:self-test
• npm run package:smoke
• Browser smoke for sample load, profile edit, checklist update, MCP status change, task generation, prompt/report generation, export/import roundtrip, and mobile overflow.
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: 4.13.0 → 4.14.0.

Phase 228 — Learning feedback output-file smoke coverage (v4.13.0) ✓ shipped

Learning feedback reports now have explicit output-file persistence coverage in both pre-publish and post-publish smoke paths, while still proving that the feedback entry is saved to the target profile.

Changed

• Added packed-tarball package smoke coverage for design-ai learn --feedback <text> --outcome keep --file <profile> --json --out <file> --force.
• Added public registry smoke coverage for the same learning feedback output-file path.
• Reused the existing feedback JSON assertions against the written output file, so outcome, category, instruction text, source, count, and profile path must survive both stdout and file artifact paths.
• Added release metadata phrase protection so release-facing docs keep both local package and public registry learning feedback --out guidance.

Impact

• Before publish, npm run package:smoke now checks that feedback JSON can be persisted to disk from installed-bin and one-shot npm exec --package <tarball> paths.
• After publish, npm run registry:smoke now checks the same feedback output-file persistence contract from the public npm execution path.
• The smoke fixtures use only temporary learning profiles/output files and do not mutate the real local learning profile, change schema, add dependencies, or call external AI APIs.

What this enables

• A packed tarball or published package can fail verification if learn --feedback --out --force stops confirming the write, stops producing a valid feedback JSON artifact, or writes the artifact without persisting the feedback entry.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• npm run package:smoke:self-test
• npm run registry:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 227 — Learning import output-file smoke coverage (v4.13.0) ✓ shipped

Learning import preview reports now have explicit output-file persistence coverage in both pre-publish and post-publish smoke paths.

Changed

• Added packed-tarball package smoke coverage for design-ai learn --import --from-file <file> --dry-run --file <profile> --json --out <file> --force.
• Added public registry smoke coverage for the same learning import preview output-file path.
• Reused the existing import JSON assertions against the written output file, so added/skipped counts, duplicate-skip metadata, reminted ids, and dry-run/apply flags must survive both stdout and file artifact paths.
• Added release metadata phrase protection so release-facing docs keep both local package and public registry learning import --out guidance.

Impact

• Before publish, npm run package:smoke now checks that import preview JSON can be persisted to disk from installed-bin and one-shot npm exec --package <tarball> paths.
• After publish, npm run registry:smoke now checks the same import output-file persistence contract from the public npm execution path.
• The smoke fixtures use only temporary learning profiles/import payloads/output files and do not mutate the real local learning profile, change schema, add dependencies, or call external AI APIs.

What this enables

• A packed tarball or published package can fail verification if learn --import --out --force stops confirming or writing a valid import preview JSON artifact.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• npm run package:smoke:self-test
• npm run registry:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 226 — Learning audit output-file smoke coverage (v4.13.0) ✓ shipped

Learning audit cleanup reports now have explicit output-file persistence coverage in both pre-publish and post-publish smoke paths.

Changed

• Added packed-tarball package smoke coverage for design-ai learn --audit --file <file> --json --out <file> --force.
• Added public registry smoke coverage for the same learning audit output-file path.
• Reused the existing cleanup suggestion JSON assertions against the written output file, so duplicate/sensitive-entry cleanup guidance must survive both stdout and file artifact paths.
• Added release metadata phrase protection so release-facing docs keep both local package and public registry learning audit --out guidance.

Impact

• Before publish, npm run package:smoke now checks that audit cleanup JSON can be persisted to disk from installed-bin and one-shot npm exec --package <tarball> paths.
• After publish, npm run registry:smoke now checks the same audit output-file persistence contract from the public npm execution path.
• The smoke fixtures use only temporary learning profiles/output files and do not mutate the real local learning profile, change schema, add dependencies, or call external AI APIs.

What this enables

• A packed tarball or published package can fail verification if learn --audit --out --force stops confirming or writing a valid cleanup-suggestion JSON artifact.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• npm run package:smoke:self-test
• npm run registry:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 225 — Public registry learning stats output-file smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves learning stats JSON output-file persistence from the published npm package path.

Changed

• Added public registry smoke coverage for design-ai learn --stats --file <file> --json --out <file> --force.
• Added assertion coverage that the registry smoke command prints a file-write confirmation and that the written file contains the expected profile stats JSON payload.
• Added registry smoke self-test coverage for stats output-file confirmation drift.
• Added release metadata phrase protection so release-facing docs keep the public registry learning stats output-file guidance.

Impact

• After publish, npm run registry:smoke now checks that stats JSON can be persisted to disk from the public npm execution path.
• The smoke fixture writes only temporary profile/output files and does not read or mutate the real learning profile, change schema, add dependencies, or call external AI APIs.

What this enables

• A published package can fail post-publish verification if learn --stats --out --force stops confirming or writing a valid profile summary JSON artifact.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 224 — Packed-tarball learning stats output-file smoke coverage (v4.13.0) ✓ shipped

Packed-tarball package smoke now proves learning stats JSON output-file persistence before publish in both installed-bin and one-shot npm exec paths.

Changed

• Added packed-tarball package smoke coverage for design-ai learn --stats --file <file> --json --out <file> --force.
• Added assertion coverage that the smoke command prints a file-write confirmation and that the written file contains the expected profile stats JSON payload.
• Added package smoke self-test coverage for stats output-file confirmation drift.
• Added release metadata phrase protection so release-facing docs keep the packed-tarball learning stats output-file guidance.

Impact

• Before publish, npm run package:smoke now checks that stats JSON can be persisted to disk from both install paths.
• The smoke fixture writes only temporary profile/output files and does not read or mutate the real learning profile, change schema, add dependencies, or call external AI APIs.

What this enables

• A packed tarball can fail pre-publish verification if learn --stats --out --force stops confirming or writing a valid profile summary JSON artifact.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run package:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:check
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 223 — Packed-tarball learning verify output-file smoke coverage (v4.13.0) ✓ shipped

Packed-tarball package smoke now proves portable learning verify output-file persistence before publish in both installed-bin and one-shot npm exec paths.

Changed

• Added packed-tarball package smoke coverage for design-ai learn --verify --from-file <file> --json --out <file> --force.
• Added assertion coverage that the smoke command prints a file-write confirmation and that the written file contains the expected non-mutating learning verification JSON payload.
• Added package smoke self-test coverage for verify output-file confirmation drift.
• Added release metadata phrase protection so release-facing docs keep the packed-tarball learning verify output-file guidance.

Impact

• Before publish, npm run package:smoke now checks that verify JSON can be persisted to disk from both install paths.
• The smoke fixture writes only temporary source/output files and does not read or mutate the real learning profile, change schema, add dependencies, or call external AI APIs.

What this enables

• A packed tarball can fail pre-publish verification if learn --verify --out --force stops confirming or writing a valid portable verification JSON artifact.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run package:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 222 — Public registry learning verify output-file smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves portable learning verify output-file persistence from the published npm package path.

Changed

• Added public registry smoke coverage for design-ai learn --verify --from-file <file> --json --out <file> --force.
• Added assertion coverage that the registry smoke command prints a file-write confirmation and that the written file contains the expected non-mutating learning verification JSON payload.
• Added registry smoke self-test coverage for verify output-file confirmation drift.
• Added release metadata phrase protection so release-facing docs keep the public registry learning verify output-file guidance.

Impact

• After publish, npm run registry:smoke now checks that verify JSON can be persisted to disk from the public npm execution path, matching the portable learning output-file contracts covered before publish.
• The smoke fixture writes only to temporary source/output files and does not read or mutate the real user learning profile, change the learning schema, add dependencies, or call external AI APIs.

What this enables

• A published package can fail post-publish verification if learn --verify --out --force stops confirming or writing a valid portable verification JSON artifact.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 221 — Public registry learning backup output-file smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves portable learning backup output-file persistence from the published npm package path.

Changed

• Added public registry smoke coverage for design-ai learn --backup --json --out <file> --force.
• Added assertion coverage that the registry smoke command prints a file-write confirmation and that the written file contains a full import-compatible learning backup JSON payload.
• Added registry smoke self-test coverage for backup output-file confirmation drift.
• Added release metadata phrase protection so release-facing docs keep the public registry learning backup output-file guidance.

Impact

• After publish, npm run registry:smoke now checks that backup JSON can be persisted to disk from the public npm execution path, matching the packed-tarball pre-publish smoke contract.
• The smoke fixture writes only to temporary profile/output files and does not read or mutate the real user learning profile, change the learning schema, add dependencies, or call external AI APIs.

What this enables

• A published package can fail post-publish verification if learn --backup --out --force stops confirming or writing a valid portable backup JSON artifact.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 220 — Public registry learning relevance/query smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves query-filtered learning inspection and brief-relevant prompt/pack learned-context selection from the published npm package path.

Changed

• Added public registry smoke coverage for human design-ai learn --list --query --explain output.
• Added public registry smoke coverage for JSON design-ai learn --list --query --explain selection metadata.
• Added public registry smoke coverage for JSON design-ai learn --export --query output without recency fallback.
• Added public registry smoke coverage for prompt --with-learning and pack --with-learning brief-relevance selection.
• Added registry smoke self-test fixtures for query matched-token drift, human explanation drift, export fallback drift, and prompt/pack learned-context selection drift.
• Added release metadata phrase protection so release-facing docs keep the public registry learning relevance/query smoke guidance.

Impact

• After publish, npm run registry:smoke now checks the same query-filtered learning inspection and brief-relevance prompt/pack contracts that packed-tarball smoke already checks before publish.
• The registry smoke fixtures use temporary learning profiles and do not read or mutate the real user learning profile, change the learning schema, add dependencies, or call external AI APIs.

What this enables

• A published package can fail post-publish verification if query scoring, explanation metadata, export fallback behavior, or learned-context prompt/pack ranking drifts in the public npm execution path.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm run release:metadata
• npm run release:self-test
• npm test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 219 — Public registry learning feedback/init smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves explicit learning feedback capture and starter profile bootstrap behavior from the published npm package path.

Changed

• Added public registry smoke coverage for JSON design-ai learn --feedback inline feedback capture.
• Added public registry smoke coverage for JSON design-ai learn --feedback --from-file and design-ai learn --feedback --stdin capture paths.
• Added public registry smoke coverage for JSON design-ai learn --init preview output that does not create a profile.
• Added public registry smoke coverage for confirmed JSON design-ai learn --init --yes apply output, persisted starter entries, and duplicate-skip behavior.
• Added registry smoke self-test fixtures for feedback outcome/category/source/instruction drift and init key/count/category/text/duplicate-skip drift.
• Added release metadata phrase protection so release-facing docs keep the public registry learning feedback/init smoke guidance.

Impact

• After publish, npm run registry:smoke now checks the same explicit feedback and local-dogfood starter bootstrap contracts that packed-tarball smoke already checks before publish.
• The registry smoke fixtures are local to temporary profiles and feedback files; they do not read or mutate the real user learning profile, change the learning schema, add dependencies, or call external AI APIs.

What this enables

• A published package can fail post-publish verification if feedback source normalization, from-file/stdin feedback handling, init preview safety, starter entry creation, or duplicate skipping drifts in the public npm execution path.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 218 — Public registry portable learning import/redact smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves portable learning import and redaction behavior from the published npm package path.

Changed

• Added public registry smoke coverage for JSON design-ai learn --import dry-run output from portable files.
• Added public registry smoke coverage for confirmed JSON design-ai learn --import --stdin --yes application and persisted profile merge behavior.
• Added public registry smoke coverage for JSON design-ai learn --redact from the local profile, --from-file, --stdin, and --out --force file-write paths.
• Added registry smoke self-test fixtures for import counts, duplicate skip metadata, redaction summaries, sensitive entry ids, redaction marker output, and redaction code drift.
• Added release metadata phrase protection so release-facing docs keep the public registry portable learning import/redact smoke guidance.

Impact

• After publish, npm run registry:smoke now checks the same portable learning import and redaction contracts that packed-tarball smoke already checks before publish.
• The registry smoke fixtures are local to temporary profiles and portable JSON files; they do not read or mutate the real user learning profile, change the learning schema, add dependencies, or call external AI APIs.

What this enables

• A published package can fail post-publish verification if learning import dry-run/apply behavior, duplicate skipping, redaction safety, stdin handling, or redacted output-file writing drifts in the public npm execution path.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 217 — Public registry learning audit cleanup smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves the safe learning audit cleanup loop from the published npm package path.

Changed

• Added public registry smoke coverage for human and JSON design-ai learn --audit cleanup suggestions.
• Added public registry smoke coverage for design-ai learn --audit --fix --dry-run --json cleanup previews.
• Added public registry smoke coverage for confirmed design-ai learn --audit --fix --yes --json cleanup application and persisted profile cleanup.
• Added registry smoke self-test fixtures for audit suggestions, cleanup metadata, human cleanup output, dry-run drift, and apply drift.
• Added release metadata phrase protection so release-facing docs keep the public registry learning audit cleanup smoke guidance.

Impact

• After publish, npm run registry:smoke now checks the same safe learning audit cleanup contract that packed-tarball smoke already checks before publish.
• The registry smoke fixture is local to a temp profile; it does not read or mutate the real user learning profile, change the learning schema, add dependencies, or call external AI APIs.

What this enables

• A published package can fail post-publish verification if learning audit cleanup suggestions, dry-run behavior, or confirmed cleanup persistence drift in the public npm execution path.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 216 — Public registry workspace strict smoke coverage (v4.13.0) ✓ shipped

Post-publish registry smoke now proves the strict workspace readiness gate from the published npm package path.

Changed

• Added public registry smoke coverage for design-ai workspace --json.
• Added public registry smoke coverage for design-ai workspace --strict --json failure behavior in a non-git temporary project.
• Added a clean temporary git fixture with canonical origin/main tracking so registry smoke also verifies strict success behavior with no readiness warnings or failures.
• Added registry smoke self-test fixtures for workspace JSON, strict failure, and strict clean-success assertion drift.
• Added release metadata phrase protection so release-facing docs keep the public registry workspace strict smoke guidance.

Impact

• After publish, npm run registry:smoke now checks the same workspace strict readiness contract that packed-tarball smoke already checks before publish.
• The registry smoke fixture is local to a temp directory; it does not fetch, push, mutate the real repo, change learning schemas, or add dependencies.

What this enables

• A published package can fail post-publish verification if workspace strict readiness behavior drifts in the public npm execution path.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run registry:smoke:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 215 — Workspace strict package smoke metadata guard (v4.13.0) ✓ shipped

Release metadata now protects the workspace strict package smoke guidance added in Phase 214.

Changed

• Added a release metadata phrase guard for design-ai workspace --strict --json package smoke guidance.
• Required release-facing docs to keep the workspace strict failure/success readiness language alongside installed-bin and one-shot packed-tarball smoke paths.
• Added a release metadata self-test drift fixture that fails when the workspace strict package smoke phrase disappears from a release policy doc.

Impact

• README, Korean README, Release checklist, and English/Korean Distribution docs cannot silently drop the workspace strict package smoke contract while keeping generic package smoke wording.
• Existing CLI runtime behavior, workspace command behavior, package smoke execution, registry smoke execution, package allowlist, and learning schema remain unchanged.

What this enables

• Future edits to release docs will preserve the fact that packed tarballs verify strict readiness failure and clean-success behavior before internal/company sharing.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 214 — Workspace strict package smoke coverage (v4.13.0) ✓ shipped

Packed-tarball smoke now proves the strict workspace readiness gate in the same install paths users exercise.

Changed

• Added package smoke assertions for design-ai workspace --strict --json failure behavior when the command runs in a non-git temp project.
• Added clean temporary git fixtures with canonical origin/main tracking so package smoke also verifies strict success behavior with no readiness warnings or failures.
• Covered both packed-tarball installed-bin and one-shot npm exec --package <tarball> execution paths.
• Added smoke assertion self-test fixtures for strict success/failure exit codes and readiness issue drift.

Impact

• Internal/company dogfood builds now verify the workspace --strict gate after packaging, not only through unit tests and source-tree execution.
• The new git fixtures are local temp repositories only; they do not fetch, push, mutate the real repo, change learning schemas, or add dependencies.

What this enables

• A shared packed tarball can fail fast if strict readiness JSON behavior drifts before the tool reaches another developer's machine.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm run package:smoke
• npm run release:metadata
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 213 — Workspace strict readiness gate (v4.13.0) ✓ shipped

design-ai workspace can now act as a blocking local readiness gate, not only a read-only status view.

Changed

• Added design-ai workspace --strict, which exits non-zero when workspace next actions include warn or fail readiness items.
• Kept normal and JSON workspace output unchanged so humans and automation see the same diagnostics before the exit code is applied.
• Added a fail-level next action when required release scripts are missing from package.json.
• Updated workspace help, top-level help, README command lists, distribution docs, AI learning docs, product readiness docs, smoke assertions, and session logs for the strict gate.
• Added unit coverage for strict parsing, warn/fail readiness detection, strict success on info-only readiness, and strict failure on dirty git readiness.

Impact

• Internal dogfood handoff can now run design-ai workspace --strict before commit/push/package sharing and fail on dirty state, repository drift, learning profile warnings, or missing release scripts.
• The command remains read-only: it does not edit files, mutate learning profiles, run release scripts, commit, or push.

What this enables

• Local automation can use the same readiness model shown to humans instead of re-implementing git/repository/learning checks.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• node --test cli/lib/workspace.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/smoke_assertions.py
• npm run release:check
• git diff --check
• Full release gate passed: unit tests, strict audit, package contents, release metadata, release self-tests, and package smoke.
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 212 — Workspace repository alignment diagnostics (v4.13.0) ✓ shipped

design-ai workspace now makes canonical repository readiness visible before internal dogfood users commit, push, package, or share a local build.

Changed

• Added a repository section to workspace JSON and human output with canonical slug, canonical URL, expected remote URL, package repository/homepage/bugs metadata, plugin homepage/repository metadata, remote slug, metadata alignment, remote alignment, and drift issues.
• Added next-action warnings for package/plugin repository metadata drift and git remote mismatch.
• Added workspace unit coverage for canonical metadata, remote normalization, stale metadata drift, and stable JSON key order.
• Added packed-tarball smoke coverage for design-ai workspace --json from both installed-bin and one-shot npm exec --package <tarball> paths.
• Updated README, Korean README, distribution docs, product readiness docs, and AI learning docs to describe repository alignment as part of the internal dogfood readiness snapshot.

Impact

• Solo/internal dogfood now catches wrong remotes or stale repository metadata before push or shared install testing.
• Package smoke now verifies the workspace JSON contract in the same install paths users will exercise.
• No learning schema, route behavior, artifact checker behavior, package allowlist, or external API behavior changes.

What this enables

• Repository ownership drift can be caught from the user-facing workspace command, not only from release metadata checks.
• Internal company rollout preparation has one more local preflight signal before sharing a build.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• node --test cli/lib/workspace.test.mjs cli/lib/help-command.test.mjs
• NO_COLOR=1 node cli/bin/design-ai.mjs workspace
• node cli/bin/design-ai.mjs workspace --json
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• npm run release:metadata
• npm run release:self-test
• npm run package:check
• npm run package:smoke
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 211 — Canonical repository metadata alignment (v4.13.0) ✓ shipped

Public-facing repository references now point to the actual GitHub repository, sungjin9288/design-ai, before broader internal or external distribution.

Changed

• Updated package.json, .claude-plugin/plugin.json, CLI help, README files, distribution docs, quickstarts, integration docs, launch drafts, MkDocs config, Homebrew examples, and VS Code extension metadata from the stale owner slug to sungjin9288/design-ai.
• Added release metadata validation for package repository URL, homepage, bugs URL, plugin homepage, plugin repository, and stale release-policy repository slugs.
• Added release metadata self-test coverage for stale package, plugin, and release-policy doc repository references.

Impact

• npm package metadata, plugin metadata, generated docs links, CLI help, and install instructions now agree with the repository users actually access.
• Release checks fail if the old repository owner slug returns in critical package or release-facing docs.
• No CLI command behavior, learning profile schema, package file allowlist, or design corpus content changes.

What this enables

• Internal dogfood and future external launch paths no longer send users to stale GitHub URLs.
• Repository ownership drift becomes an automated release metadata failure instead of a manual launch review issue.

What's still ahead

• External launch remains held until owner review.
• Homebrew publishing still needs a real release tag and checksum update when an external release is approved.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• npm run release:self-test
• npm run package:check
• npm run package:smoke
• python3 -B tools/audit/local-ci.py --docs-only
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 210 — Retire temporary Node 24 workflow opt-in (v4.13.0) ✓ shipped

The temporary GitHub Actions runtime opt-in is removed now that repository workflows use official action major refs that already target Node 24-compatible runtimes.

Changed

• Removed FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 from audit, docs, publish, and release workflows.
• Removed the dedicated local CI opt-in parser, failure path, and self-test fixtures.
• Kept the action-ref drift guard introduced in Phase 209 as the source of truth for workflow runtime compatibility.

Impact

• CI policy now checks the actual workflow dependency pins instead of a temporary environment override.
• Workflow files are simpler and no longer depend on a platform migration escape hatch.
• No CLI runtime, npm package contents, learning profile schema, docs corpus, or user-facing command behavior changes.

What this enables

• Future workflow runtime maintenance can focus on explicit action refs and Real-CI evidence.
• The local CI parity gate remains strict without carrying redundant opt-in state.

What's still ahead

• Monitor Real-CI after push to confirm the opt-in removal stays annotation-free.
• External launch remains held until owner review.

Verified

• python3 -B tools/audit/local-ci.py --self-test
• python3 -B tools/audit/local-ci.py --docs-only
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/local-ci.py
• npm run audit:strict
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 209 — GitHub Actions Node 24 action refs (v4.13.0) ✓ shipped

Official GitHub Actions refs now target Node 24-compatible major versions where available, reducing hosted-runner deprecation noise while keeping the explicit runtime opt-in guard.

Changed

• Upgraded workflow refs for actions/checkout, actions/setup-node, actions/setup-python, actions/cache, actions/upload-pages-artifact, actions/deploy-pages, and softprops/action-gh-release.
• Added a local CI action-ref drift guard so stale major refs fail before push.
• Added self-test fixtures for expected action refs, stale action refs, and missing required action refs.

Impact

• Audit, docs, publish, and release workflows now exercise the same Node 24-compatible action generation used by current official action releases.
• The temporary FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 guard was kept in this phase, then retired in Phase 210 after Real-CI returned zero annotations.
• No CLI runtime, npm package contents, learning profile schema, docs corpus, or user-facing command behavior changes.

What this enables

• Future workflow edits cannot silently reintroduce older official action major refs.
• Real-CI annotations should now focus on remaining platform issues instead of repository-owned action pin drift.

What's still ahead

• Monitor Real-CI after push because action major updates can surface workflow-only compatibility issues.
• External launch remains held until owner review.

Verified

• python3 -B tools/audit/local-ci.py --self-test
• python3 -B tools/audit/local-ci.py --docs-only
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/local-ci.py
• npm run audit:strict
• npm run release:self-test
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 208 — GitHub Actions Node 24 opt-in (v4.13.0) ✓ shipped

All GitHub workflows now opt into the upcoming Node 24 JavaScript action runtime before GitHub changes the default.

Changed

• Added FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" to audit, docs, publish, and release workflows.
• Added a local CI guard that checks every repository workflow keeps the Node 24 opt-in.
• Added self-test fixtures for present and missing Node 24 workflow opt-in behavior.

Impact

• GitHub Actions warnings about Node.js 20 action runtime deprecation are converted into an explicit compatibility check before the platform default changes.
• Release and publish workflows get the same opt-in as normal audit/docs pushes, even though they run less often.
• No CLI runtime, npm package contents, learning profile schema, docs corpus, or user-facing command behavior changes.

What this enables

• Real-CI now exercises the near-future GitHub Actions JavaScript runtime behavior instead of waiting for the hosted runner default to change.
• Future workflow edits cannot silently drop the Node 24 opt-in without failing the local CI self-test.

What's still ahead

• Monitor GitHub-hosted action version support when the platform fully switches defaults.
• External launch remains held until owner review.

Verified

• python3 -B tools/audit/local-ci.py --self-test
• python3 -B tools/audit/release-metadata.py
• python3 -m py_compile tools/audit/local-ci.py
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 207 — Pages-disabled docs workflow guard (v4.13.0) ✓ shipped

The docs workflow now keeps MkDocs build verification green when GitHub Pages has not been enabled yet.

Changed

• Added a GitHub Pages availability check to .github/workflows/docs.yml.
• The workflow now calls the GitHub Pages API after the MkDocs warning-policy build.
• When Pages is enabled, the Pages artifact upload and deploy job still run.
• When Pages is disabled, artifact upload and deployment are skipped with a clear log message instead of failing the workflow.

Impact

• Internal dogfood and pre-launch pushes can keep docs build verification active without forcing a public Pages deployment setting.
• This preserves the local/CI MkDocs warning-policy gate while avoiding a false-negative deploy failure caused by repository settings.
• No source content, CLI runtime behavior, package output, or learning profile behavior changes.

What this enables

• The repo can stay private-to-internal in behavior until the owner deliberately enables GitHub Pages for external docs.
• CI can distinguish a real docs build failure from a disabled deployment target.

What's still ahead

• Enable GitHub Pages only when the owner is ready for public docs deployment.
• External launch remains held until owner review.

Verified

• python3 -B tools/audit/local-ci.py --self-test
• python3 -B tools/audit/local-ci.py --docs-only
• python3 -B tools/audit/release-metadata.py
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 206 — Public registry check learning capture smoke (v4.13.0) ✓ shipped

Post-publish registry smoke now verifies design-ai check --learn --yes --json from the published npm package path.

Changed

• Added a registry-smoke artifact fixture that intentionally produces warning-level artifact QA findings without failures.
• Added JSON assertions for learningCapture, including file path, applied/dry-run flags, source, candidate/add/skip counts, category mapping, entry schema, and captured text shape.
• Verified that the selected learning profile file is actually written with the captured entries.
• Wired the smoke into the public npm exec --package @design-ai/cli@<version> registry path.
• Added registry-smoke self-test drift fixtures for capture count and metadata regressions.

Impact

• The public post-publish gate now matches the release-facing docs that already promised check learning capture coverage.
• This closes the Phase 203 follow-up for public registry smoke coverage without changing CLI runtime behavior, learning schema, package smoke, or local profile defaults.
• check remains read-only unless users explicitly pass --learn --yes.

What this enables

• Post-publish verification now covers the same local QA-to-learning feedback loop that packed-tarball smoke already checks before release.
• Registry-only regressions in check learning capture JSON shape, category mapping, or persisted profile writes will fail before launch confidence is claimed.

What's still ahead

• External launch remains held until owner review.
• Future AI learning beyond deterministic local profile entries, such as embeddings or fine-tuning, remains a separate product decision.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -m py_compile tools/audit/registry-smoke.py
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 205 — Starter learning profile bootstrap (v4.13.0) ✓ shipped

design-ai learn --init gives solo/internal dogfood users a safe way to start with useful local learning preferences instead of an empty profile.

Changed

• Added design-ai learn --init as a preview-first starter learning bootstrap.
• Added design-ai learn --init --yes to write starter entries through the existing local learning profile schema.
• Starter entries cover recommendation style, implementation workflow, accessibility, Korean UX, brand language, and local data boundaries.
• Reuses the existing duplicate detection behavior: matching category + normalized text entries are skipped and reported.
• Added JSON/human output, command help, top-level help catalog, CLI unit tests, smoke assertion help guards, README command references, AI learning docs, product-readiness docs, quickstart, distribution docs, changelog, roadmap, and session log coverage.

Impact

• First dogfood runs can immediately include explicit local preference context without manually writing six separate learn --remember commands.
• The command does not train a model, call external AI APIs, add embeddings, change the learning schema, or mutate the profile unless --yes is present.

What this enables

• Solo and internal users can bootstrap a consistent baseline profile before using prompt --with-learning, pack --with-learning, or check --learn.
• Company onboarding can start from deterministic local preferences while still allowing each user to add or remove personal/team-specific entries.

What's still ahead

• Dogfood the starter entries through real design-tool sessions and adjust wording only if repeated outputs show drift.
• Team-wide shared profile templates, hosted sync, embeddings, or fine-tuning remain separate future product decisions.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 204 — Internal dogfood workspace mode (v4.13.0) ✓ shipped

design-ai workspace gives solo/internal users a read-only readiness snapshot before committing, pushing, or sharing local dogfood builds.

Changed

• Added design-ai workspace [--root path] [--learning-file path] [--json].
• Reports git branch, cleanliness, upstream sync, remote, and last commit without changing repository state.
• Reports local learning profile path, entry count, category counts, latest entry, and audit status through the existing local learning profile schema.
• Reports available release scripts so dogfood users can see the relevant npm test, npm run audit:strict, and package smoke gates.
• Adds deterministic next-action hints for dirty worktrees, missing upstream branches, behind/ahead branches, learning audit warnings, and release verification commands.
• Added help catalog, command alias (ws), CLI unit tests, smoke assertion topic guards, README command references, AI learning docs, product-readiness docs, distribution docs, changelog, roadmap, and session log coverage.

Impact

• Local dogfood flow now has a single read-only command for deciding whether to keep developing, run verification, capture learning feedback, or prepare a push.
• This does not create git commits, push branches, modify learning profiles, run release scripts, call external services, or add dependencies.

What this enables

• Solo and internal dogfood runs can start with one deterministic readiness check instead of manually checking git, learning profile health, and release-script availability.
• Future web UI, VS Code, Figma, or SDK surfaces can reuse the same report shape as an internal status panel.

What's still ahead

• Dogfood the command through normal solo development sessions and tune next-action wording based on repeated use.
• Public launch, registry smoke, and any hosted/productized workspace dashboard remain separate follow-up decisions.

Verified

• node --test cli/lib/workspace.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• node --test cli/lib/*.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py tools/audit/smoke_assertions.py
• npm test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

Phase 203 — Auto feedback capture for local AI learning (v4.13.0) ✓ shipped

design-ai check can now turn local artifact QA warnings and failures into explicit learning entries after user confirmation.

Changed

• Added design-ai check <artifact.md|--stdin> --learn as a read-only learning capture preview for non-pass check results.
• Added --learn --yes and --learning-file path so warning/failure results can be written to the selected local learning.json profile.
• Mapped check results to existing learning categories without changing the learning schema: accessibility checks become accessibility, Korean-context checks become korean, and remaining artifact/route checks become workflow.
• Added duplicate detection by category + normalized text, with skipped entries reported in both human and JSON output.
• Added learningCapture to check JSON reports while preserving pass-only reports with zero candidates.
• Extended package smoke to verify check learning capture output and persisted profile entries in both installed-bin and one-shot npm exec --package <tarball> paths.
• Added release metadata wording protection for check learning capture output.
• Updated check help, README command references, AI learning docs, product-readiness docs, distribution docs, release checklist, changelog, roadmap, and session log.

Impact

• Local AI learning now has a deterministic feedback loop from artifact QA to future prompt guidance.
• The feature remains opt-in and local: check stays read-only unless --learn --yes is present.
• This does not add external AI APIs, embeddings, fine-tuning export, telemetry, new dependencies, or a learning profile schema change.

Verified

• node --test cli/lib/check.test.mjs cli/lib/learn.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• npm test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Design QA findings can now become durable local learning guidance without leaving the machine or changing the explicit prompt/pack learning boundary.

What's still ahead (4.x — incremental only)

• External launch (held).
• Decide whether future AI learning should expand into embeddings or model fine-tuning.

Resolved follow-up

• Public registry smoke coverage for check learning capture was completed in Phase 206.

Phase 202 — Public registry learning verify smoke (v4.13.0) ✓ shipped

Post-publish registry smoke now verifies learn --verify --json portable profile validation from the published npm package path.

Changed

• Added a registry-smoke portable learning verification fixture with duplicate-entry warning metadata.
• Added JSON assertions for learn --verify, including source path/stdin identity, importable flag, count, warning audit summary, duplicate-id issue metadata, normalized import sources, and entry summaries.
• Wired the verify smoke into the public npm exec --package @design-ai/cli@<version> registry path for both --from-file and --stdin.
• Expanded registry-smoke self-test fixtures for importable flag drift and duplicate warning drift.
• Added release metadata wording protection for public registry JSON design-ai learn --verify output.
• Updated release-facing docs, changelog, roadmap, and session log for the new registry smoke coverage.

Impact

• The post-publish smoke now catches registry-only regressions where the published package can run but cannot validate portable learning-profile JSON before import.
• This does not change CLI runtime behavior, local learning profile storage, import mutation behavior, package smoke commands, or prompt/pack learned-context injection.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Public registry verification now covers portable learning-profile validation before backup/export workflows are trusted after publish.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 201 — Public registry learning backup smoke (v4.13.0) ✓ shipped

Post-publish registry smoke now verifies learn --backup --json portable profile output from the published npm package path.

Changed

• Added a registry-smoke learning backup fixture with deterministic local learning entries.
• Added JSON assertions for learn --backup, including profile path, version, updated timestamp, exported timestamp presence, count, audit status, entry list shape, and full-text preservation.
• Wired the backup smoke into the public npm exec --package @design-ai/cli@<version> registry path.
• Expanded registry-smoke self-test fixtures for backup entry drift and missing full-text preservation.
• Added release metadata wording protection for public registry JSON design-ai learn --backup output.
• Updated release-facing docs, changelog, roadmap, and session log for the new registry smoke coverage.

Impact

• The post-publish smoke now catches registry-only regressions where the published package can run but cannot export a portable learning-profile backup from an explicit profile file.
• This does not change CLI runtime behavior, local learning profile storage, package smoke commands, or prompt/pack learned-context injection.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Public registry verification now covers both learning profile overview health (learn --stats) and portable backup export (learn --backup --json).

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 200 — Public registry learning stats smoke (v4.13.0) ✓ shipped

Post-publish registry smoke now verifies learn --stats human and JSON output from the published npm package path.

Changed

• Added a registry-smoke learning stats fixture with category/source distribution and deterministic recency metadata.
• Added human and JSON assertions for learn --stats, including profile count, category counts, source counts, audit status, latest entry, and oldest entry summaries.
• Wired the stats smoke into the public npm exec --package @design-ai/cli@<version> registry path.
• Expanded registry-smoke self-test fixtures for stats JSON and human output drift.
• Added release metadata wording protection for public registry human / JSON design-ai learn --stats profile summary output.
• Updated release-facing docs, changelog, roadmap, and session log for the new registry smoke coverage.

Impact

• The post-publish smoke now catches registry-only packaging/runtime regressions in learn --stats, not only version/help/catalog/audit/install lifecycle regressions.
• This does not change CLI runtime behavior, local learning profile storage, audit logic, package smoke commands, or prompt/pack learned-context injection.

Verified

• python3 -B tools/audit/registry-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/registry-smoke.py tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local learning overview health checks now have both packed-tarball and public-registry release confidence before external launch.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 199 — Learning stats package smoke (v4.13.0) ✓ shipped

Packed-tarball package smoke now verifies learn --stats human and JSON output through both tarball execution paths.

Changed

• Added a package-smoke learning stats fixture with category/source distribution and parseable recency metadata.
• Added human and JSON assertions for learn --stats, including profile count, category counts, source counts, audit status, latest entry, and oldest entry summaries.
• Wired the stats smoke into both installed-bin and one-shot npm exec --package <tarball> learning smoke paths.
• Expanded package-smoke self-test fixtures for stats JSON and human output drift.
• Added release metadata wording protection for human / JSON design-ai learn --stats profile summary output.
• Updated release-facing docs, changelog, roadmap, and session log for the new stats smoke coverage.

Impact

• The release smoke now catches packaging/runtime regressions in learn --stats, which previously had CLI and docs coverage but no dedicated packed-tarball smoke assertion.
• This does not change CLI runtime behavior, local learning profile storage, audit logic, or prompt/pack learned-context injection.

Verified

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local learning overview health checks now have the same package-level release confidence as feedback, backup, redact, verify, import, query inspection, audit cleanup, and prompt/pack learning selection flows.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 198 — Human learning query explanation package smoke (v4.13.0) ✓ shipped

Packed-tarball package smoke now verifies the human learn --list --query --explain output, not only the JSON selection metadata.

Changed

• Added a package-smoke assertion for human query-filtered learn list explanation output.
• The new assertion checks the explanation header, filtered entry count, query/limit display, matched tokens, brief-match reason, and exclusion of unrelated learning entries.
• Wired the human list check into both installed-bin and one-shot npm exec --package <tarball> learning relevance smoke paths.
• Expanded package-smoke self-test fixtures for the new human assertion.
• Updated release-facing docs wording so the smoke scope now names human learn list explanation output alongside export JSON output.
• Updated changelog, roadmap, and session log for the new package smoke hardening.

Impact

• The release smoke now catches regressions in the user-facing learn --list --query --explain output, not just machine-readable JSON.
• This does not change CLI runtime behavior, local learning profile storage, prompt/pack learned-context injection, or learning selection scoring.

Verified

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• npm run package:smoke
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Human and JSON learning inspection paths now have matching packed-tarball smoke coverage before Real-CI.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 197 — Learning query explanation release guard (v4.13.0) ✓ shipped

Release metadata now guards the query-filtered learn list explanation/export smoke guidance added around local learning inspection.

Changed

• Added a dedicated learn query explain smoke phrase guard to tools/audit/release-metadata.py.
• Required release-facing docs to keep the query-filtered learn list explanation/export JSON smoke wording independently from the prompt/pack learning relevance guard.
• Expanded release metadata self-test fixtures so phrase-table label drift and missing query explanation/export wording fail before tagging.
• Updated changelog, roadmap, and session log for the new release guard.

Impact

• Release-facing docs cannot silently drop the learn --list --query --explain --json and learn --export --query --json smoke scope while package smoke still verifies it.
• This does not change CLI runtime behavior, local learning profile storage, prompt/pack learned-context injection, or package smoke commands.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Query-filtered learning inspection stays represented in the same release metadata gate that protects the rest of the public CLI smoke surface.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 196 — Explainable learning list inspection (v4.13.0) ✓ shipped

design-ai learn --list can now explain why query-filtered local learning entries matched.

Changed

• Added --explain to design-ai learn --list.
• Reused the same learning selection metadata shape already used by prompt/pack and export JSON.
• Human list output can now show score, matched tokens, and selection reason for each selected entry.
• JSON list output includes selection only when --explain is requested, preserving compact default list JSON output.
• Packed-tarball smoke now verifies query-filtered learn --list --explain --json metadata through installed-bin and one-shot npm exec paths.
• Updated help, unit tests, package smoke, AI learning docs, quickstart docs, product readiness, release docs, changelog, roadmap, and session log.

Impact

• Users can inspect why a local preference matched before exporting it or injecting it into prompt/pack learned context.
• This remains local and read-only; it does not add telemetry, embeddings, model training, automatic feedback capture, or profile schema changes.
• Existing learn --list, learn --export, prompt/pack learning injection, and learning profile storage remain compatible.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check
• npm run package:smoke
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local learning inspection now has the same explainability surface as learned-context injection.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 195 — Query-filtered learning inspection (v4.13.0) ✓ shipped

design-ai learn --list and learn --export can now inspect local learning entries by query without recency fallback.

Changed

• Added --query text to design-ai learn --list and design-ai learn --export.
• Reused the existing lightweight learning relevance scorer so query-filtered inspection ranks matching entries by category/text relevance.
• Disabled recency fallback for query-filtered list/export so profile inspection only returns entries that actually match the query.
• Kept prompt/pack --with-learning behavior unchanged: prompt injection still ranks by brief relevance and can use recency fallback when the learning limit has room.
• Updated help, unit tests, package smoke, AI learning docs, quickstart docs, product readiness, changelog, roadmap, and session log for the new query-filtered learning inspection path.

Impact

• Users can search a growing local learning profile before deciding whether to export, clean up, or inject preferences into a prompt.
• The feature remains local and read-only for list/export; it does not add telemetry, embeddings, model training, or automatic feedback capture.
• Existing category/limit filters, prompt/pack learning injection, and learning profile storage remain compatible.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check
• npm run package:smoke
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local learning remains explicit and inspectable as profiles grow beyond a handful of entries.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 194 — Explainable learning selection metadata (v4.13.0) ✓ shipped

prompt/pack --with-learning --json now explain why each selected learning entry was included.

Changed

• Added per-selected-entry learning selection metadata: id, category, relevance score, matchedTokens, and reason.
• Added selectedCount, fallbackCount, and queryTokenCount to the learning selection summary.
• Kept the existing ranking behavior and Markdown output compact; the expanded explanation is available in JSON output.
• Expanded unit tests and packed-tarball smoke assertions to verify score, matched-token, and brief-match/fallback metadata.
• Updated AI learning, product readiness, README, changelog, roadmap, and session docs for the explainable selection shape.

Impact

• Users and maintainers can see whether a learned preference was selected because it matched the current brief or because recency fallback filled the remaining learning limit.
• This does not add telemetry, embeddings, model training, or automatic feedback capture.
• Existing selectLearningEntries() consumers still receive the same entry array shape.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/prompt.test.mjs cli/lib/pack.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check
• npm run package:smoke
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Learning context remains opt-in while becoming inspectable enough for release smoke, debugging, and future UI surfaces.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 193 — Learning relevance release metadata guard (v4.13.0) ✓ shipped

Release metadata now guards release-facing docs against dropping the brief-relevant prompt/pack learning selection smoke guidance added for --with-learning.

Changed

• Added a learn relevance smoke phrase guard to tools/audit/release-metadata.py.
• Expanded release metadata self-test fixtures with a drift case that fails when brief-relevant prompt/pack learning selection language disappears.
• Updated release checklist and English/Korean distribution docs so the packed-tarball smoke scope explicitly includes brief-relevant prompt/pack learning selection.
• Updated changelog, roadmap, and session log for the new release guard.

Impact

• README, Korean README, release checklist, and English/Korean distribution docs cannot silently drop the learning relevance smoke guidance while the package smoke still depends on it.
• This does not change CLI runtime behavior; it only hardens release policy verification and documentation drift detection.

Verified

• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/release-metadata.py
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• git diff --check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The Phase 192 learning relevance behavior remains represented in release-facing docs and is protected by the automated release metadata gate.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 192 — Brief-relevant learning injection (v4.13.0) ✓ shipped

design-ai prompt --with-learning and design-ai pack --with-learning now rank saved local learning entries against the current task brief before applying the existing limit, then fall back to recency for ties or unmatched entries.

Changed

• Added lightweight local relevance scoring for learned entries using the current prompt/pack brief, without embeddings, telemetry, or model training.
• Kept the existing explicit --with-learning privacy boundary and the existing --learning-category / --learning-limit controls.
• Added learning selection metadata (mode, query, candidate count, matched count) to prompt/pack JSON output and a compact selection note in the learned-context Markdown block.
• Expanded unit coverage and packed-tarball smoke so both installed-bin and one-shot npm exec --package <tarball> paths verify brief-relevant prompt/pack learning selection.
• Updated AI learning, quickstart, product readiness, README, changelog, and session docs for the new selection behavior.

Impact

• Limited learned context now favors entries that match the current design task, such as Button accessibility preferences for a Button spec, instead of blindly taking the newest saved note.
• Existing learn --export, profile storage, backup/redact/verify/import/audit, and non-learning prompt/pack behavior remain unchanged.
• When no entry matches the brief, recency remains the fallback so users still get predictable opt-in context.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/prompt.test.mjs cli/lib/pack.test.mjs
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py
• npm test
• npm run audit:strict
• npm run release:metadata
• git diff --check
• npm run package:smoke
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local learning becomes more useful for mixed profiles because prompt/pack can keep the opt-in boundary while selecting the most task-relevant preference subset.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 191 — Learning output file support (v4.13.0) ✓ shipped

design-ai learn can now write JSON result artifacts, and learn --export Markdown, through --out file with --force overwrite control.

Changed

• Added --out file / --force parsing to design-ai learn, reusing the shared output-file semantics already used by prompt and pack.
• Allows JSON-producing learn actions to write their payload to a file, while keeping learn --export --out available for Markdown learned-context blocks.
• Requires --json for --out on non-export learn actions so human summaries are not silently captured as machine artifacts.
• Expanded help, unit tests, package smoke, release metadata guards, and release-facing docs for the new output path.

Impact

• Users can save learn --backup, learn --redact, learn --verify, learn --audit, learn --stats, import dry-run/apply, and feedback result JSON without shell redirection.
• Existing stdout behavior remains unchanged when --out is omitted.
• Existing profile mutation, confirmation, privacy, and redaction boundaries remain unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs cli/lib/output.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• node cli/bin/design-ai.mjs learn --backup --json --out <tmp>/backup.json plus overwrite refusal without --force
• node cli/bin/design-ai.mjs learn --export --out <tmp>/context.md
• npm test
• npm run audit:strict
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Learning backup, redaction, verification, audit, stats, import, and feedback result artifacts can be saved with the same safe output-file UX as prompt and pack.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 190 — Portable learning redaction input sources (v4.13.0) ✓ shipped

design-ai learn --redact can now redact an existing portable learning JSON artifact from --from-file or --stdin, not only the local profile file.

Changed

• Extended design-ai learn --redact [--json] so it keeps the existing local-profile behavior when no input source is supplied, and reads portable learning JSON from --from-file or --stdin when provided.
• Reused the same redaction and audit pipeline for local profiles and portable input payloads, preserving import-compatible entries, redactions, sourceAuditSummary, and post-redaction auditSummary.
• Updated help, unit tests, package smoke, release metadata phrase guards, README, quickstart, distribution, product-readiness, and AI learning docs for the new source modes.

Impact

• Users can redact a learn --backup --json artifact after it has already been created, without pointing the command at or mutating the active local profile.
• --redact --stdin --json supports shell pipelines and support handoff workflows where writing the unredacted artifact to another path is undesirable.
• Existing local --redact, backup, verify, import, audit, stats, remember/feedback, and prompt/pack learning injection behavior remains unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• node cli/bin/design-ai.mjs learn --redact --stdin --json with a portable JSON payload
• npm test
• npm run audit:strict
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Teams can create a full backup once and then generate redacted shareable copies later from a file or pipeline without touching their active local learning profile.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 189 — Redacted portable learning backup (v4.13.0) ✓ shipped

design-ai learn can now produce an importable portable profile with sensitive-looking entry text redacted before sharing.

Changed

• Added design-ai learn --redact [--json] as a read-only export path for shareable learning-profile backups.
• Reused the learning audit sensitive-content patterns so private key blocks, secret-like assignments, OpenAI-style keys, email addresses, and Korean mobile phone numbers are replaced with [REDACTED:<code>] markers in exported entries.
• Added redaction metadata: redacted, redactedCount, sourceAuditSummary, post-redaction auditSummary, and per-entry redactions.
• Expanded help, unit tests, package smoke, release metadata policy guards, README, quickstart, distribution, and AI learning docs for the redacted export path.

Impact

• Users can create a safer portable profile for support, team review, or repository handoff without mutating the source local profile.
• Redacted output keeps the same entries shape as backup/import payloads, so it can be verified with learn --verify before import.
• Existing remember, feedback, list/export/backup/verify/import, audit/fix, stats, forget/clear, and prompt/pack learning injection behavior remains unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Teams can share learning profiles with a first-pass privacy guard before manual review and import verification.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 188 — Portable learning import verification (v4.13.0) ✓ shipped

design-ai learn can now validate portable learning JSON before import without touching the local profile.

Changed

• Added design-ai learn --verify --from-file learning.json [--json] and cat learning.json | design-ai learn --verify --stdin [--json].
• Reused the import parser so verification checks the same JSON entries payload shape that learn --import accepts.
• Added normalized-entry audit output so duplicate ids, duplicate notes, long notes, and sensitive-looking text stay visible before import.
• Expanded top-level help, command-specific help, unit tests, smoke assertions, package smoke, release metadata policy guards, and adopter docs for the verification path.
• Hardened package smoke so transient one-shot npm exec cache ENOENT failures retry once with a fresh npm cache while real CLI assertion failures still fail the gate.

Impact

• Users can test a backup or imported profile artifact before --dry-run or confirmed import, while preserving the current local learning profile.
• Verification is intentionally read-only and does not use --yes, --dry-run, or the target --file profile for mutation.
• Existing remember, feedback, list/export/backup/import, audit/fix, stats, forget/clear, and prompt/pack learning injection behavior remains unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check
• All 8 audits pass.

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Teams can validate portable learning artifacts as a separate review step before merging local design preferences.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 187 — Portable learning profile backup (v4.13.0) ✓ shipped

design-ai learn can now emit a full portable JSON backup before cleanup or migration.

Changed

• Added design-ai learn --backup --json for full learning-profile backups that include all normalized entries, profile metadata, an export timestamp, and audit summary.
• Added human design-ai learn --backup summary output that points users to the JSON backup command.
• Expanded top-level help, command-specific help, unit tests, smoke assertions, package smoke, release metadata policy guards, and adopter docs for the backup path.
• Verified packed-tarball installed-bin and one-shot npm exec --package <tarball> paths for backup JSON output.

Impact

• Users can create a complete local learning-profile backup before safe cleanup, machine migration, or import review.
• Backup differs from learn --export: it is not limited to the default prompt-context subset and keeps the import-compatible entries array.
• Existing remember, feedback, list/export/import, audit/fix, stats, forget/clear, and prompt/pack learning injection behavior remains unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Teams can now back up explicit local design preferences before moving, merging, or cleaning them up.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 186 — Portable learning profile import (v4.13.0) ✓ shipped

design-ai learn can now import portable learning JSON with preview-first safety.

Changed

• Added design-ai learn --import for JSON objects that contain an entries array, including full local profiles and learn --export --json payloads.
• Added design-ai learn --import --from-file learning.json --dry-run for non-mutating previews.
• Added cat learning.json | design-ai learn --import --stdin --yes for confirmed imports from piped JSON.
• Deduplicated imported entries by category+text, preserved valid imported timestamps, marked imported sources with import:, and reminted ids only when an imported id conflicts with an existing entry.
• Expanded unit tests, help discovery assertions, smoke assertions, package smoke, release metadata policy guards, and adopter docs for the import path.

Impact

• Local learning preferences can now be backed up, reviewed, and moved between machines without manual JSON editing.
• Confirmed import remains explicit local memory only; no sync, telemetry, embeddings, model training, or fine-tuning was added.
• Existing remember, feedback, audit, safe cleanup, stats, forget/clear, and prompt/pack learning injection behavior remains unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Teams can move explicit local learning preferences across dev machines or agents while preserving the same auditable, opt-in prompt injection boundary.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 185 — Feedback input source smoke coverage (v4.13.0) ✓ shipped

design-ai learn --feedback now has covered input-source parity for inline, file, and stdin feedback.

Changed

• Expanded design-ai learn --feedback help to show dedicated --from-file and --stdin usage for feedback capture.
• Added command-level coverage for feedback --stdin parsing and --from-file command execution.
• Expanded package smoke so both packed-tarball installed-bin and one-shot npm exec paths record inline, --from-file, and --stdin feedback entries into the same profile.
• Tightened feedback JSON smoke assertions to verify exact keep/improve/avoid instruction text, category, source, profile path, and count.
• Updated AI learning and quickstart docs with file/stdin feedback examples.

Impact

• Users can paste or pipe longer feedback without relying on shell-quoted inline strings.
• The feedback loop remains explicit local memory only; no telemetry, background capture, embeddings, or model training were added.
• Existing remember, audit, safe cleanup, stats, forget/clear, and prompt/pack learning injection flows remain unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The local feedback-learning loop now has the same source-input ergonomics as other long-form CLI workflows.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 184 — Explicit feedback learning loop (v4.13.0) ✓ shipped

design-ai learn can now turn explicit reviewed-output feedback into durable local learning entries.

Changed

• Added design-ai learn --feedback text for recording outcome feedback without model training, automatic telemetry, or background collection.
• Added --outcome keep|improve|avoid, converting feedback into repeat / improve / avoid instructions before it enters prompt personalization.
• Defaulted feedback entries to the workflow category while keeping --category overrides for scoped feedback.
• Added machine-readable feedback payloads with outcome, category, generated instruction text, persisted entry metadata, source, and count.
• Updated CLI help discovery, smoke assertions, package smoke, README command references, quickstart guidance, product readiness docs, AI learning docs, changelog, roadmap, and session log for the feedback loop.
• Expanded package smoke coverage so packed-tarball installed-bin and one-shot npm exec paths verify learn-feedback JSON behavior.

Impact

• Users can capture “keep this”, “improve this”, and “avoid this” guidance as explicit local memory that remains opt-in through prompt / pack --with-learning.
• The feature keeps the current privacy boundary: no embeddings, no automatic recommendation tracking, no model fine-tuning, and no provider upload.
• Existing learn --remember, audit cleanup, stats, forget/clear, and scoped prompt/pack learning injection remain unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py tools/audit/release-metadata.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local personalization now has a user-controlled feedback capture loop before any future retrieval-memory or fine-tuning scope is considered.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, automatic feedback capture, or model fine-tuning.

Phase 183 — Learning audit safe fix loop (v4.13.0) ✓ shipped

design-ai learn --audit can now turn safe cleanup suggestions into a dry-run plan or confirmed profile cleanup.

Changed

• Added design-ai learn --audit --fix --dry-run to preview automatically fixable cleanup suggestions without mutating the learning profile.
• Added design-ai learn --audit --fix --yes to remove only safe, unambiguous entries targeted by audit suggestions.
• Added machine-readable cleanup payloads with before/after audit summaries, skipped manual-review suggestions, removed entry previews, and stable cleanup command metadata.
• Updated CLI help discovery, smoke assertions, README command references, quickstart guidance, product readiness docs, AI learning docs, changelog, and session log for the safe fix loop.
• Expanded package smoke coverage so packed-tarball installed-bin and one-shot npm exec paths verify learn-audit fix dry-run and confirmed apply JSON behavior.

Impact

• Users can move from audit warnings to safe cleanup without manually copying each suggested --forget command.
• Ambiguous or unsafe cases still stay manual: invalid JSON, malformed entries, duplicate ids, and warnings without stable ids are skipped instead of auto-deleted.
• Existing read-only learn --audit, confirmed learn --forget / learn --clear, prompt/pack learning injection, repository audits, package contents checks, and registry smoke remain unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/help-command.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -m py_compile tools/audit/package-smoke.py tools/audit/smoke_assertions.py
• npm test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run package:smoke
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The local learning workflow now has a closed inspect-preview-apply loop while preserving explicit confirmation for mutations.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 182 — Learning audit package smoke coverage (v4.13.0) ✓ shipped

Packed-tarball smoke now verifies the learn --audit cleanup guidance through both installed-bin and one-shot npm exec --package <tarball> execution paths.

Changed

• Added a package-smoke learning profile fixture with duplicate-entry and sensitive-content warnings.
• Added JSON assertions for learn --audit --json status, issue codes, suggestion actions, and safe --forget ... --yes command args.
• Added human-output assertions for the Suggested cleanup section and cleanup command strings.
• Wired the learned-audit cleanup smoke into both installed-bin and npm exec tarball paths.
• Added package-smoke self-test fixtures for the new JSON and human-output assertions.
• Added a release metadata phrase guard so release-facing docs keep mentioning the learn-audit cleanup smoke surface.

Impact

• The local release gate now catches packaging/runtime regressions in learning audit cleanup suggestions before publish or push.
• Existing learn --audit behavior, profile storage, confirmed deletion controls, repository audits, package contents checks, and registry smoke remain unchanged.

Verified

• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• npm run package:smoke
• npm test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The cleanup guidance shipped in Phase 181 is now exercised in the same packed-tarball surfaces adopters will use.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 181 — Learning audit cleanup suggestions (v4.13.0) ✓ shipped

design-ai learn --audit now turns learning profile warnings into explicit cleanup guidance without mutating the local profile.

Changed

• Added suggestions metadata to learning profile audit payloads, mapping each issue to a recommended cleanup action.
• Added safe design-ai learn --file ... --forget ... --yes command suggestions for duplicate, sensitive-content, long-note, and metadata warnings when id-based deletion is unambiguous.
• Added manual repair suggestions for ambiguous duplicate ids, missing ids, and profile-level failures where automatic deletion guidance would be unsafe.
• Added a Suggested cleanup section to human learn --audit output.
• Updated AI learning docs, quickstart guidance, product readiness docs, README status copy, changelog, and session log for audit cleanup suggestions.
• Expanded learning tests for audit suggestion metadata and human cleanup output.

Impact

• Users can move from audit warnings to concrete cleanup decisions faster while keeping learn --audit read-only.
• Existing profile storage, learn --forget confirmation, learn --clear confirmation, prompt/pack learning injection, and audit issue reporting remain unchanged.

Verified

• node --test cli/lib/learn.test.mjs
• node --test cli/lib/help-command.test.mjs
• Learning audit cleanup suggestion smoke passed with temporary profile files.
• npm test
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local personalization profiles now have a safer inspect-and-clean loop before learned context enters generated prompts or packs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 180 — Learned-context audit summaries (v4.13.0) ✓ shipped

design-ai learn --export, design-ai prompt --with-learning, and design-ai pack --with-learning now carry learning profile audit status with the learned context they produce.

Changed

• Added auditSummary metadata to learned context payloads returned by export, prompt, and pack flows.
• Added a compact learned-context Markdown notice when the local profile audit status is warn, pointing users back to design-ai learn --audit before relying on the context.
• Kept passing profiles compact by omitting the notice when audit status is pass.
• Updated AI learning docs, quickstart guidance, product readiness docs, README status copy, changelog, and session log for the audit-summary surface.
• Expanded learning unit coverage for warning-aware learned-context Markdown and prompt/pack learning payload metadata.

Impact

• Downstream agents and users can see whether injected local preferences came from a clean or warning-bearing profile.
• Existing opt-in --with-learning, category/limit scoping, read-only learn --audit / learn --stats, and deletion confirmation behavior remain unchanged.

Verified

• node --test cli/lib/learn.test.mjs cli/lib/prompt.test.mjs cli/lib/pack.test.mjs
• Learned-context audit summary smoke passed with temporary profile files.
• npm test
• npm run audit:strict
• All 8 audits pass.
• git diff --check
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local personalization can remain opt-in while making profile quality warnings visible at the exact point where preferences enter generated prompts or packs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 179 — Learning profile stats summary (v4.13.0) ✓ shipped

design-ai learn now includes a read-only stats mode for quickly checking local learning profile size, distribution, recency, and audit status.

Changed

• Added design-ai learn --stats and design-ai learn --stats --json.
• Summarized profile existence, entry count, category counts, source counts, oldest/latest parseable entries, and audit summary without mutating the profile.
• Kept stats resilient for missing or invalid profiles by reporting audit status instead of writing or normalizing files.
• Updated CLI help discovery, smoke assertions, README command references, quickstart guidance, product readiness docs, and AI learning docs for the stats surface.
• Expanded learning unit coverage for stats parsing, normal profile summaries, missing profile summaries, and invalid JSON handling.

Impact

• Users can decide whether to filter, audit, clean up, or inject local preferences before using --with-learning.
• Existing learn --audit, list/export filtering, forget/clear controls, scoped prompt/pack injection, and non-learning prompt/pack behavior remain unchanged.

Verified

• npm test
• python3 -B tools/audit/smoke_assertions.py --self-test
• Learning stats smoke passed with temporary profile files.
• npm run audit:strict
• All 8 audits pass.
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local personalization memory is easier to inspect at a glance before it influences generated agent prompts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 178 — Scoped learning prompt injection (v4.13.0) ✓ shipped

design-ai prompt and design-ai pack now let users scope opt-in local learning context by category and entry count before injecting it into generated agent context.

Changed

• Added --learning-category and --learning-limit to design-ai prompt --with-learning.
• Added the same scoped learning controls to design-ai pack --with-learning, passing filters into the embedded prompt plan.
• Kept scoped learning flags behind the existing --with-learning privacy boundary.
• Updated CLI help discovery, smoke assertions, README command references, quickstart guidance, product readiness docs, and AI learning docs for scoped prompt injection.
• Expanded prompt and pack unit coverage for parser contracts, invalid filter handling, and category/limit propagation.

Impact

• Prompt personalization can now include only the relevant local learning category and a bounded number of entries.
• Existing unfiltered prompt/pack --with-learning, local learning profile management, audit controls, and non-learning prompt/pack behavior remain unchanged.

Verified

• npm test
• python3 -B tools/audit/smoke_assertions.py --self-test
• Scoped learning prompt/pack smoke passed with a temporary profile file.
• npm run audit:strict
• All 8 audits pass.
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Users can apply saved local preferences more safely to focused tasks without exposing unrelated profile entries to generated prompts or packs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 177 — Learning profile audit controls (v4.13.0) ✓ shipped

design-ai learn now includes a non-mutating audit mode for local learning profiles before they are exported or injected into prompts.

Changed

• Added design-ai learn --audit and design-ai learn --audit --json to inspect local profile existence, entry counts, category counts, schema issues, duplicate notes, timestamp gaps, long notes, and conservative sensitive-content patterns.
• Kept audit mode advisory and read-only so users can inspect a profile before deciding whether to use --with-learning, --forget, or --clear.
• Updated CLI help discovery, smoke assertions, README command references, quickstart guidance, product readiness docs, and AI learning docs for the audit surface.
• Expanded learning unit coverage for audit parsing, missing-profile pass state, invalid JSON failure reporting, duplicate detection, timestamp warnings, and sensitive-content warnings.

Impact

• Local learning now has a safer inspection step before prompt personalization without adding telemetry, embeddings, model training, or background collection.
• Existing learn --remember, list/export filtering, forget/clear retention controls, and prompt/pack --with-learning behavior remain unchanged.

Verified

• npm test
• python3 -B tools/audit/smoke_assertions.py --self-test
• Learning audit smoke passed with temporary profile files.
• npm run audit:strict
• All 8 audits pass.
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Users can inspect local personalization memory for quality and possible sensitive content before including it in generated agent context.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 176 — Learning profile management controls (v4.13.0) ✓ shipped

design-ai learn now supports local profile management with category/limit filters plus confirmed --forget and --clear deletion controls.

Changed

• Added design-ai learn --forget id-or-number --yes and design-ai learn --clear --yes so users can remove local learning entries without editing the JSON profile by hand.
• Added --category and --limit filtering for learn --list and learn --export, keeping prompt personalization context easier to inspect before use.
• Updated CLI help discovery, smoke assertions, README command references, and AI learning docs for the expanded management surface.
• Expanded learning unit coverage for parsing, category/limit filtering, single-entry deletion, full-profile clearing, and filtered Markdown export.

Impact

• Local learning remains explicit and privacy-safe, but now has user-controlled retention and narrower inspection/export controls.
• Existing learn --remember, default list output, prompt/pack --with-learning, and package manifest counts remain unchanged.

Verified

• npm test
• python3 -B tools/audit/smoke_assertions.py --self-test
• Learning management smoke passed with a temporary profile file.
• npm run audit:strict
• All 8 audits pass.
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Users can inspect, export, forget, or clear local learning preferences from the CLI before allowing those preferences into generated prompt and pack context.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 175 — Local learning profile MVP (v4.13.0) ✓ shipped

design-ai learn now stores local learning preferences and prompt/pack --with-learning can inject them into generated agent context without model training.

Changed

• Added design-ai learn for explicit local preference memory with --remember, --list, --export, --from-file, --stdin, --category, --file, and --json support.
• Added opt-in --with-learning support to design-ai prompt and design-ai pack, injecting the learned-context block only when requested.
• Added docs/AI-LEARNING.md, updated product readiness docs, README command references, MkDocs navigation, and CLI help discovery for the new learning surface.
• Wrapped long top-level help rows so prompt, pack, and learn usage stays readable after adding learning options.
• Expanded unit and smoke assertion coverage for learning profile parsing, persistence, prompt/pack injection, help topic discovery, and unknown-option suggestion behavior.

Impact

• design-ai now ships a privacy-safe local personalization layer while keeping model training, fine-tuning, embeddings, and feedback learning outside the shipped scope.
• Existing route selection, prompt/pack output without --with-learning, slash-command inventory, install lifecycle, and package manifest counts remain unchanged.

Verified

• npm test
• python3 -B tools/audit/smoke_assertions.py --self-test
• All 8 audits pass.
• Learning profile prompt/pack smoke passed with a temporary profile file.
• npm run release:metadata
• npm run release:check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Users can make design-ai remember project or taste constraints locally, then explicitly include that context in prompt and pack generation.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning should expand into embeddings, feedback learning, or model fine-tuning.

Phase 174 — Product readiness scope boundary documented (v4.13.0) ✓ shipped

Product readiness docs now clarify that core design consulting workflows are locally release-ready while AI model training is outside shipped scope.

Changed

• docs/PRODUCT-READINESS.md now separates shipped design consulting capability, local release confidence, conversational AI design coverage, and non-shipped AI learning/model-training scope.
• README status sections now link to the readiness boundary and clarify that design-ai is a corpus/routing/prompt-pack/QA layer rather than a model or fine-tune.
• MkDocs navigation now exposes the readiness page under Reference so launch reviewers can find the current completion matrix.
• CHANGELOG and SESSION-LOG now record the Phase 174 readiness boundary.

Impact

• Product status is now explicit: core design consulting workflows are locally release-ready for v4.13, while Real-CI, external launch, registry smoke, and any future personalization/model-learning work remain separate decisions.
• Existing CLI runtime behavior, package contents, release smoke assertions, knowledge corpus files, examples, and command coverage remain unchanged.

Verified

• All 8 audits pass.
• npm run release:metadata

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The team can answer completion questions without conflating the shipped design consulting system with future AI learning or personalization products.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.
• Decide whether future AI learning means embeddings, feedback learning, or model fine-tuning.

Phase 173 — Lifecycle JSON context path assertion hardening (v4.13.0) ✓ shipped

Lifecycle JSON smoke assertions now verify source/target context separation across install, update dry-run, status, and uninstall reports.

Changed

• tools/audit/smoke_assertions.py now validates lifecycle JSON context paths through a shared source/target guard for design-ai install --json, design-ai update --dry-run --json, design-ai status --json, and design-ai uninstall --json.
• Lifecycle JSON assertions now reject sourceRoot and claudeHome when they are identical or nested inside each other, while preserving the existing key-order, prefix, count, plan, and install-state checks.
• The smoke assertion self-test now covers install context equality, update source-inside-target drift, status target-inside-source drift, and uninstall target-inside-source drift fixtures.
• CHANGELOG and SESSION-LOG now record the Phase 173 hardening.

Impact

• Package and registry smoke checks now fail when lifecycle JSON remains parseable and counts still match, but the reported source and Claude Code target roots no longer describe separate lifecycle contexts.
• Existing CLI runtime behavior, lifecycle JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now validates lifecycle source/target separation before relying on lifecycle counts, update plan summaries, or status target directories.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 172 — Status JSON install-state target assertion hardening (v4.13.0) ✓ shipped

Status JSON smoke assertions now verify exact install-state section labels and Claude-home target directory contracts.

Changed

• tools/audit/smoke_assertions.py now verifies design-ai status --json section labels and target directories against the install-state contract used by package and registry smoke.
• Status JSON assertions now require each section to keep the exact Skills, Agents, and Slash commands labels, keep target directories under claudeHome, and end each target path with the matching skills, agents, or commands directory.
• The smoke assertion self-test now covers section label drift, target directory escaping claudeHome, and target directory basename drift fixtures.
• CHANGELOG and SESSION-LOG now record the Phase 172 hardening.

Impact

• Package and registry smoke checks now fail when status JSON remains parseable and has the right symlink entries, but no longer describes the same user-facing install-state sections or Claude Code target directories.
• Existing CLI runtime behavior, status JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects the status install-state JSON as a stable human-readable and machine-readable map of installed symlink sections and their Claude Code target directories.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 171 — Update dry-run JSON smoke plan assertion hardening (v4.13.0) ✓ shipped

Update dry-run JSON smoke assertions now verify exact git/install plan key order, boolean contracts, command arrays, and readiness reasons.

Changed

• tools/audit/smoke_assertions.py now verifies design-ai update --dry-run --json with stricter update-plan guards for top-level key order, nested plan key order, git-pull boolean fields, git command arrays, and git/install readiness reasons.
• Update dry-run JSON assertions now reject bool-as-int drift for gitPull.wouldRun, stale git clone reasons, missing git pull commands for clone sources, missing install reason keys, and install reason wording drift.
• The smoke assertion self-test now covers top-level reorder, plan reorder, boolean type drift, clone command drift, git reason drift, install key drift, and install reason drift fixtures.
• CHANGELOG and SESSION-LOG now record the Phase 171 hardening.

Impact

• Package and registry smoke checks now fail when update preview JSON remains parseable but no longer describes the same non-mutating git/install plan contract used before install lifecycle checks.
• Existing CLI runtime behavior, update dry-run JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects the update preview plan as a stable non-mutating lifecycle contract before install, status, doctor, and uninstall smoke checks run.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 170 — Help/list/version JSON smoke schema assertion hardening (v4.13.0) ✓ shipped

Help, list, and version JSON smoke assertions now verify command-discovery key shape, alias/topic order, catalog item contracts, and version metadata keys.

Changed

• tools/audit/smoke_assertions.py now verifies design-ai help --json, design-ai list --json, and design-ai version --json with stable top-level, topic, alias, catalog section, catalog item, context, and version key guards.
• Help JSON assertions now require exact topic usage strings, stable topic entry key order, exact alias order, and per-topic alias lists aligned with the canonical alias map.
• List JSON assertions now reject non-object payloads, top-level key-order drift, bool-as-int section counts, and catalog item shape drift.
• Version JSON assertions now reject non-object payloads, top-level key-order drift, missing context keys, and version metadata key-order drift.
• CHANGELOG and SESSION-LOG now record the Phase 170 hardening.

Impact

• Package and registry smoke checks now fail when command discovery or version metadata JSON remains parseable but drifts from the machine-readable contracts used by automation and downstream agents.
• Existing CLI runtime behavior, help/list/version JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects command discovery, catalog listing, and version metadata JSON as stable machine-readable contracts, not only as parseable JSON containing expected fragments.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 169 — Check JSON smoke schema assertion hardening (v4.13.0) ✓ shipped

Check JSON smoke assertions now verify artifact/stdin/example report key shape, exact result order, count consistency, and example metadata contracts.

Changed

• tools/audit/smoke_assertions.py now verifies design-ai check --json, design-ai check --stdin --json, and design-ai check --examples --json with stable report, result, example-entry, and example-metadata key guards.
• Artifact and stdin check assertions now require stable report keys, exact component-spec result order, non-boolean integer count fields, exact score formatting, required result title/message fields, and content-depth evidence shape.
• Check examples JSON assertions now require stable top-level key order, exact example entry shape, positive non-boolean example scores, non-empty previews, nested report schema checks, and summary counts aligned with nested example reports.
• CHANGELOG and SESSION-LOG now record the Phase 169 hardening.

Impact

• Package and registry smoke checks now fail when design-ai check JSON remains parseable but drifts from the artifact QA contract used by release automation and downstream agents.
• Existing CLI runtime behavior, check JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects design-ai check artifact/stdin/examples JSON as stable machine-readable QA contracts, not only as passing reports that contain expected result ids.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 168 — Route/prompt/pack JSON smoke schema assertion hardening (v4.13.0) ✓ shipped

Route, prompt, and pack JSON smoke assertions now verify recommendation/prompt-bundle key shape, exact numeric fields, reference coverage consistency, and context file order.

Changed

• tools/audit/smoke_assertions.py now verifies design-ai route --json, design-ai routes --json, design-ai prompt --json, and design-ai pack --json with stable top-level, route-entry, explanation, reference, prompt-plan, summary, and file-entry key guards.
• Route JSON assertions now require exact route result counts for --limit 1, stable recommendation key shape, exact non-boolean integer scores, keyword lists, reference entry shape, score breakdown shape, and full reference coverage consistency.
• Prompt JSON assertions now require stable forced-route plan shape, exact filesToRead order, reference example previews/scores, route coverage consistency, and prompt bundle content.
• Pack JSON assertions now require stable bundle and summary key shape, exact budget/count fields, ordered context files aligned with the prompt plan, included file-entry contracts, string warnings, and explicit context budget exhaustion.
• CHANGELOG and SESSION-LOG now record the Phase 168 hardening.

Impact

• Package and registry smoke checks now fail when route selection, prompt generation, or context packing JSON remains parseable but drifts from the machine-readable contracts used by automation and downstream agents.
• Existing CLI runtime behavior, route/prompt/pack JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm run release:self-test
• npm run audit:strict
• npm run package:check
• npm test
• npm run package:smoke
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects route selection, prompt-plan, and context-pack JSON as stable machine-readable contracts, not only as valid JSON containing expected route fragments.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 167 — Corpus discovery JSON smoke schema assertion hardening (v4.13.0) ✓ shipped

Corpus discovery JSON smoke assertions now verify search/show/examples key shape, file paths, exact integer fields, and limit-bound result counts.

Changed

• tools/audit/smoke_assertions.py now verifies design-ai search --json, design-ai show --json, design-ai show --lines --json, and design-ai examples --json with corpus-specific object/key guards.
• Search JSON assertions now require stable hit keys, non-empty absolute file paths ending in the expected corpus path, exact positive integer line numbers, and the single result promised by --limit 1.
• Show JSON assertions now require stable top-level and line-entry keys, exact positive integer range fields, valid totalLines, and file paths aligned with the reported relPath.
• Examples JSON assertions now require stable route-biased payload keys, exact positive integer scores, non-empty previews, and the single result promised by --limit 1.
• CHANGELOG and SESSION-LOG now record the Phase 167 hardening.

Impact

• Package and registry smoke checks now fail when corpus discovery JSON remains parseable but drifts from the machine-readable search/show/examples contract that prompt-building and automation depend on.
• Existing CLI runtime behavior, corpus JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm run release:self-test
• npm run audit:strict
• npm run package:check
• npm test
• npm run package:smoke
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects corpus discovery JSON as stable machine-readable search/show/examples contracts, not only as parseable JSON containing expected text fragments.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 166 — Lifecycle JSON smoke schema assertion hardening (v4.13.0) ✓ shipped

Lifecycle JSON smoke assertions now verify payload type, nested key shape, exact integer counts, and install/status/uninstall summary consistency.

Changed

• tools/audit/smoke_assertions.py now verifies lifecycle JSON payloads for design-ai install --json, design-ai status --json, design-ai uninstall --json, and design-ai update --dry-run --json with shared object/key guards.
• Install JSON assertions now reject non-object top-level payloads, bool-as-int count drift, and installed total values that do not equal the section counts.
• Status JSON assertions now reject unexpected section counts, bool-as-int section/summary counts, and non-object top-level payloads before comparing installed entries.
• Uninstall and update dry-run JSON assertions now reject non-object top-level payloads, and uninstall JSON rejects bool-as-int removed counts.
• CHANGELOG and SESSION-LOG now record the Phase 166 hardening.

Impact

• Package and registry smoke checks now fail when lifecycle JSON remains parseable but drifts from the machine-readable install/status/uninstall/update contract that automation consumes.
• Existing CLI runtime behavior, lifecycle JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm run release:self-test
• npm run audit:strict
• npm run package:check
• npm test
• npm run package:smoke
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects lifecycle JSON as stable machine-readable install-state and lifecycle-result contracts, not only as valid JSON with expected command labels.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 165 — Audit JSON smoke schema assertion hardening (v4.13.0) ✓ shipped

Audit JSON smoke assertions now verify payload type, entry schema, numeric contracts, and summary/count consistency.

Changed

• tools/audit/smoke_assertions.py now verifies the full design-ai audit --strict --quiet --json report contract: top-level payload type, context shape, audit entry keys, boolean/integer/numeric field contracts, strict args shape, and summary/count consistency.
• Audit JSON smoke assertion self-tests now include fixtures for array top-level payloads, missing audit-entry keys, boolean numeric drift, non-boolean pass flags, and mismatched summary counts.
• CHANGELOG and SESSION-LOG now record the Phase 165 hardening.

Impact

• Package and registry smoke checks now fail when audit JSON remains parseable but drifts from the machine-readable repository-audit schema that automation consumes.
• Existing CLI runtime behavior, audit JSON formatter output, audit runner execution, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/run-all.py --self-test
• npm run release:self-test
• npm run audit:strict
• npm run package:check
• npm test
• npm run package:smoke
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects audit JSON as a stable machine-readable repository-audit contract, not only as valid JSON with passing audit names.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 164 — Doctor JSON smoke schema assertion hardening (v4.13.0) ✓ shipped

Doctor JSON smoke assertions now verify schema shape, key order, and summary/count consistency.

Changed

• tools/audit/doctor_assertions.py now verifies the full design-ai doctor --json report contract: top-level key order, context shape, expected inventory counts, check entry keys, summary keys, fix keys, and summary/count consistency.
• Doctor assertion self-tests now include fixtures for missing fix, mismatched summary counts, and changed check-entry shape.
• Shared package/registry smoke doctor JSON fixtures now match the production context, checks, summary, and fix payload shape.
• CHANGELOG and SESSION-LOG now record the Phase 164 hardening.

Impact

• Package and registry smoke checks now fail when doctor JSON remains parseable but drifts from the machine-readable diagnostics schema that automation consumes.
• Existing CLI runtime behavior, doctor JSON formatter output, package smoke command coverage, registry smoke command coverage, release metadata execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/doctor_assertions.py --self-test
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run package:smoke
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke automation now protects doctor JSON as a stable machine-readable contract, not only as valid JSON with passing labels.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 163 — Doctor JSON diagnostics guard split (v4.13.0) ✓ shipped

Release metadata now reports doctor JSON command and machine-readable diagnostics output drift separately.

Changed

• tools/audit/release-metadata.py now adds separate release policy phrase labels for the exact design-ai doctor --json command and machine-readable diagnostics output.
• release-metadata.py --self-test now has drift fixtures for dropping the doctor JSON command while keeping output wording, and for dropping machine-readable diagnostics output wording while keeping the exact command.
• README, Korean README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out design-ai doctor --json machine-readable diagnostics output in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 163 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the doctor JSON command or machine-readable diagnostics output coverage.
• Existing CLI, doctor JSON formatter, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve doctor smoke guidance as independently reported human strict, JSON command, and machine-readable diagnostics output contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 162 — Doctor human diagnostics output guard split (v4.13.0) ✓ shipped

Release metadata now reports human doctor strict diagnostics output drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad doctor human diagnostics guard and adds a separate human doctor strict diagnostics output release policy phrase label.
• release-metadata.py --self-test now has a drift fixture for dropping human diagnostics output from design-ai doctor --strict while the generic human diagnostics wording remains present.
• README, Korean README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out human diagnostics output from design-ai doctor --strict in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 162 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with a separate metadata error when they lose human doctor strict diagnostics output coverage.
• Existing CLI, doctor execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve doctor strict smoke guidance as independently reported command, generic human diagnostics, and human diagnostics output contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 161 — Human update dry-run output guard split (v4.13.0) ✓ shipped

Release metadata now reports human update dry-run output drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad update --dry-run lifecycle guard and adds a separate human update dry-run output release policy phrase label.
• release-metadata.py --self-test now has a drift fixture for dropping human design-ai update --dry-run output wording while JSON dry-run command and update plan wording remain present.
• docs/RELEASE-CHECKLIST.md now names human update dry-run output separately from the exact command and machine-readable update plan in the metadata guard explanation.
• CHANGELOG and SESSION-LOG now record the Phase 161 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with a separate metadata error when they lose human update dry-run output coverage.
• Existing CLI, update dry-run output, update dry-run JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve update dry-run smoke guidance as independently reported human output, command, JSON command, and machine-readable plan contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 160 — Human audit output guard split (v4.13.0) ✓ shipped

Release metadata now reports human audit strict-quiet output drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad audit --strict --quiet smoke guard and adds a separate human audit output release policy phrase label.
• release-metadata.py --self-test now has a drift fixture for dropping human design-ai audit --strict --quiet output wording while JSON audit wording remains present.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out human audit output separately from JSON repository-audit output.
• CHANGELOG and SESSION-LOG now record the Phase 160 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with a separate metadata error when they lose human audit output coverage.
• Existing CLI, audit execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve audit smoke guidance as independently reported human and machine-readable output contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 159 — Human lifecycle output guard split (v4.13.0) ✓ shipped

Release metadata now reports human install, human status, and human uninstall output drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad human install/status/uninstall lifecycle guards and adds separate human install output, human status output, and human uninstall output release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping each human lifecycle output wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out human install, status, and uninstall output as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 159 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose human install, status, or uninstall output coverage.
• Existing CLI, install execution, status execution, uninstall execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve human lifecycle smoke guidance as three independently reported output contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 158 — Check output guard split (v4.13.0) ✓ shipped

Release metadata now reports check examples, check artifact, check stdin, and check all-routes output drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad check examples/artifact/stdin/all-routes guard and adds separate check examples output, check artifact output, check stdin output, and check all-routes output release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping each design-ai check smoke-surface wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out the four check output surfaces as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 158 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose check examples, artifact, stdin, or all-routes output coverage.
• Existing CLI, check execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve design-ai check smoke guidance as four independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 157 — Prompt/pack output-file guard split (v4.13.0) ✓ shipped

Release metadata now reports prompt/pack forced output-file and prompt/pack file-write confirmation drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad prompt/pack output-file guard and adds separate prompt/pack forced output-file and prompt/pack file-write confirmation release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping forced --out wording and file-write confirmation wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out prompt/pack forced output-file coverage and prompt/pack file-write confirmations as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 157 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose prompt/pack forced output-file coverage or prompt/pack file-write confirmation coverage.
• Existing CLI, prompt execution, pack execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve prompt/pack output-file smoke guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 156 — Prompt/pack mode guard split (v4.13.0) ✓ shipped

Release metadata now reports prompt JSON output, prompt markdown output, prompt from-file output, prompt stdin output, pack JSON output, pack markdown output, pack from-file output, and pack stdin output drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad prompt/pack mode guard and adds separate prompt JSON output, prompt markdown output, prompt from-file output, prompt stdin output, pack JSON output, pack markdown output, pack from-file output, and pack stdin output release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping each prompt/pack mode output wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out the eight prompt/pack mode smoke surfaces as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 156 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose prompt JSON, prompt markdown, prompt from-file, prompt stdin, pack JSON, pack markdown, pack from-file, or pack stdin coverage.
• Existing CLI, prompt execution, pack execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve prompt/pack mode smoke guidance as eight independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 155 — Suggestion failure guard split (v4.13.0) ✓ shipped

Release metadata now reports route-id suggestion, option suggestion, value suggestion, and numeric range failure drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad suggestion/range failure guard and adds separate route-id suggestion, option suggestion, value suggestion, and numeric range failure release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping unknown route-id suggestion wording, unknown option suggestion wording, unknown value suggestion wording, and numeric range failure wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out the four suggestion/range smoke surfaces as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 155 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose route-id suggestion, option suggestion, value suggestion, or numeric range failure coverage.
• Existing CLI, unknown route-id suggestion execution, unknown option suggestion execution, unknown value suggestion execution, numeric range failure execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve route-id suggestion, option suggestion, value suggestion, and numeric range failure smoke guidance as four independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 154 — Unknown failure guard split (v4.13.0) ✓ shipped

Release metadata now reports unknown command, help-topic, list-domain, and search-dir failure drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad unknown command/help/list/search-dir failure guard and adds separate unknown command, help-topic, list-domain, and search-dir failure release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping unknown command failure wording, unknown help-topic failure wording, unknown list-domain failure wording, and unknown search-dir failure wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out the four unknown failure smoke surfaces as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 154 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose unknown command, help-topic, list-domain, or search-dir failure coverage.
• Existing CLI, unknown command failure execution, unknown help-topic failure execution, unknown list-domain failure execution, unknown search-dir failure execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve unknown command, help-topic, list-domain, and search-dir failure smoke guidance as four independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 153 — Explicit output guard split (v4.13.0) ✓ shipped

Release metadata now reports show-lines output drift separately from route-explain output drift.

Changed

• tools/audit/release-metadata.py now keeps the broad explicit output guard and adds separate show-lines output and route-explain output release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping show --lines output wording and dropping route --explain output wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out show --lines output and route --explain output as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 153 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose explicit line-range output coverage or route explanation output coverage.
• Existing CLI, show --lines output, route --explain output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve explicit line-range output and route explanation output as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 152 — Route smoke guard split (v4.13.0) ✓ shipped

Release metadata now reports route JSON output, route catalog output, and route stdin input drift separately.

Changed

• tools/audit/release-metadata.py now keeps the broad route JSON/catalog/stdin guard and adds separate route JSON output, route catalog output, and route stdin input release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping route JSON output wording, route catalog output wording, and route stdin input wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now spell out route JSON output, route catalog output, and route stdin input as separate protected release smoke surfaces.
• CHANGELOG and SESSION-LOG now record the Phase 152 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose route recommendation JSON output, route catalog output, or route stdin input coverage.
• Existing CLI, route JSON output, route catalog output, route stdin input execution, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve route JSON output, route catalog output, and route stdin input as three independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 151 — List catalog guard split (v4.13.0) ✓ shipped

Release metadata now reports list JSON mode drift separately from list catalog domain drift.

Changed

• tools/audit/release-metadata.py now keeps the broad list JSON catalog guard and adds separate list JSON mode and list catalog domains release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping list JSON mode wording and dropping all-three list catalog domain wording.
• docs/RELEASE-CHECKLIST.md now describes list JSON mode and list catalog domains as separate protected release metadata phrases.
• CHANGELOG and SESSION-LOG now record the Phase 151 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose list JSON mode guidance versus skills/commands/agents catalog domain coverage.
• Existing CLI, list JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve list JSON mode guidance and list catalog domain coverage as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 150 — Alias smoke guard split (v4.13.0) ✓ shipped

Release metadata now reports command alias smoke drift separately from functional alias smoke drift.

Changed

• tools/audit/release-metadata.py now keeps the broad alias smoke guard and adds separate command alias smoke and functional alias smoke release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping command alias wording and dropping functional alias wording.
• docs/RELEASE-CHECKLIST.md now describes command alias smoke and functional alias smoke as separate protected release metadata phrases.
• CHANGELOG and SESSION-LOG now record the Phase 150 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose command alias help guidance versus functional alias output guidance.
• Existing CLI, help alias output, functional alias output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve command alias help guidance and functional alias output guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 149 — Update dry-run JSON command guard split (v4.13.0) ✓ shipped

Release metadata now reports update dry-run command, JSON command, and machine-readable update plan drift separately.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai update --dry-run and design-ai update --dry-run --json commands with their own release policy phrase labels.
• release-metadata.py --self-test now has separate drift fixtures for dropping the human dry-run command, dropping the JSON dry-run command, and dropping machine-readable update plan wording.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now document all three protected update dry-run phrases in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 149 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the update dry-run command, the JSON dry-run command, or the machine-readable update plan behavior it validates.
• Existing CLI, update dry-run output, update dry-run JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the update dry-run human command, JSON command, and machine-readable update plan guidance as three independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 148 — Doctor strict command guard split (v4.13.0) ✓ shipped

Release metadata now reports design-ai doctor --strict command drift separately from human diagnostics wording drift.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai doctor --strict command with its own release policy phrase label.
• release-metadata.py --self-test now has separate drift fixtures for dropping the design-ai doctor --strict command and dropping human diagnostics wording.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now document both protected phrases in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 148 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the doctor strict command versus the human diagnostics behavior it validates.
• Existing CLI, doctor strict diagnostics output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• npm run release:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the design-ai doctor --strict command and human diagnostics guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 147 — Audit JSON command guard split (v4.13.0) ✓ shipped

Release metadata now reports design-ai audit --strict --quiet --json command drift separately from machine-readable repository-audit output drift.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai audit --strict --quiet --json command with its own release policy phrase label.
• release-metadata.py --self-test now has separate drift fixtures for dropping the design-ai audit --strict --quiet --json command and dropping machine-readable repository-audit output wording.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now document both protected phrases in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 147 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the audit JSON command versus the repository-audit output behavior it validates.
• Existing CLI, audit JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the design-ai audit --strict --quiet --json command and machine-readable repository-audit output guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 146 — Status JSON command guard split (v4.13.0) ✓ shipped

Release metadata now reports design-ai status --json command drift separately from machine-readable install-state output drift.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai status --json command with its own release policy phrase label.
• release-metadata.py --self-test now has separate drift fixtures for dropping the design-ai status --json command and dropping machine-readable install-state output wording.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now document both protected phrases in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 146 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the status JSON command versus the install-state output behavior it validates.
• Existing CLI, status JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the design-ai status --json command and machine-readable install-state output guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 145 — Uninstall JSON command guard split (v4.13.0) ✓ shipped

Release metadata now reports design-ai uninstall --json command drift separately from machine-readable uninstall lifecycle output drift.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai uninstall --json command with its own release policy phrase label.
• release-metadata.py --self-test now has separate drift fixtures for dropping the design-ai uninstall --json command and dropping machine-readable uninstall lifecycle output wording.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now document both protected phrases in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 145 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the uninstall JSON command versus the uninstall lifecycle output behavior it validates.
• Existing CLI, uninstall JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the design-ai uninstall --json command and machine-readable uninstall lifecycle output guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 144 — Install JSON command guard split (v4.13.0) ✓ shipped

Release metadata now reports design-ai install --json command drift separately from machine-readable install lifecycle output drift.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai install --json command with its own release policy phrase label.
• release-metadata.py --self-test now has separate drift fixtures for dropping the design-ai install --json command and dropping machine-readable install lifecycle output wording.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now document both protected phrases in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 144 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the install JSON command versus the install lifecycle output behavior it validates.
• Existing CLI, install JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the design-ai install --json command and machine-readable install lifecycle output guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 143 — Version JSON command guard split (v4.13.0) ✓ shipped

Release metadata now reports design-ai version --json command drift separately from machine-readable version metadata drift.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai version --json command with its own release policy phrase label.
• release-metadata.py --self-test now has separate drift fixtures for dropping the design-ai version --json command and dropping machine-readable version metadata wording.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now document both protected phrases in release smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 143 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the version JSON command versus the version metadata behavior it validates.
• Existing CLI, version JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the design-ai version --json command and machine-readable version metadata guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 142 — Help JSON command guard split (v4.13.0) ✓ shipped

Release metadata now reports design-ai help --json command drift separately from help JSON topic catalog drift.

Changed

• tools/audit/release-metadata.py now checks the exact design-ai help --json command with its own release policy phrase label.
• release-metadata.py --self-test now has separate drift fixtures for dropping the design-ai help --json command and dropping help JSON topic catalog wording.
• docs/RELEASE-CHECKLIST.md now documents both protected phrases in the release metadata guard list.
• CHANGELOG and SESSION-LOG now record the Phase 142 split.

Impact

• README, Release checklist, and English/Korean Distribution docs now fail with separate metadata errors when they lose the help JSON command versus the topic catalog behavior it validates.
• Existing CLI, help JSON output, package smoke execution, registry smoke execution, release metadata execution, release self-test execution, package contents check execution, repository audit execution, local CI execution, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the design-ai help --json command and help JSON topic catalog guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 141 — Top-level help command guard added (v4.13.0) ✓ shipped

Release metadata now protects the local design-ai help command that package and registry smoke use to validate top-level help output.

Changed

• tools/audit/release-metadata.py now checks release policy docs for design-ai help top-level help command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the design-ai help command.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now identify design-ai help as the top-level help command.
• CHANGELOG and SESSION-LOG now record the Phase 141 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep top-level help wording while dropping the design-ai help command that package and registry smoke validate.
• Existing CLI, help command execution, local CI execution, repository audits, CLI unit test execution, whitespace check execution, release self-test execution, release metadata execution, package contents check, package smoke, registry smoke, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the top-level help command and top-level help smoke guidance as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 140 — Local CI command guard split (v4.13.0) ✓ shipped

Release metadata now reports local CI command drift separately from MkDocs warning-policy drift.

Changed

• tools/audit/release-metadata.py now checks npm run ci:local with a dedicated local CI command phrase label.
• release-metadata.py --self-test now has a drift fixture that fails with the exact local CI command phrase error when a release-facing policy doc drops the npm run ci:local command.
• docs/RELEASE-CHECKLIST.md now documents npm run ci:local command guidance separately from MkDocs warning-policy baseline guidance.
• CHANGELOG and SESSION-LOG now record the Phase 140 split.

Impact

• Release metadata failures now distinguish the local CI command handoff from MkDocs warning-policy baseline prose, so maintainers can see whether a doc dropped the command to run, the warning policy itself, or both.
• Existing CLI, local CI execution, repository audits, CLI unit test execution, whitespace check execution, release self-test execution, release metadata execution, package contents check, package smoke, registry smoke, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve local CI command guidance and MkDocs warning-policy guidance as two independently reported contracts.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 139 — Repository audit command guard added (v4.13.0) ✓ shipped

Release metadata now protects the local npm run audit:strict command that runs all eight repository audits before whitespace, package, and smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run audit:strict repository audit command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the npm run audit:strict command.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now identify npm run audit:strict as the all-eight repository audit command.
• CHANGELOG and SESSION-LOG now record the Phase 139 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep all-eight repository audit wording while dropping the npm run audit:strict command that runs before whitespace, package, and smoke checks.
• Existing CLI, repository audit execution, CLI unit test execution, whitespace check execution, release self-test execution, release metadata execution, package contents check, package smoke, registry smoke, and release check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the repository audit command and all-eight repository audit guidance as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 138 — CLI unit test command guard added (v4.13.0) ✓ shipped

Release metadata now protects the local npm test command that runs CLI unit tests before repository audits and package checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm test CLI unit test command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the npm test command.
• README, Korean README, English/Korean Distribution, and docs/RELEASE-CHECKLIST.md now identify npm test as the CLI unit test command.
• CHANGELOG and SESSION-LOG now record the Phase 138 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep CLI unit test wording while dropping the npm test command that runs before repository audits and package checks.
• Existing CLI, CLI unit test execution, whitespace check execution, release self-test execution, release metadata execution, package contents check, package smoke, registry smoke, release check, and repository audits behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the CLI unit test command and CLI unit test guidance as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 137 — Whitespace check command guard added (v4.13.0) ✓ shipped

Release metadata now protects the local git diff --check command that runs whitespace checks before package contents and smoke gates.

Changed

• tools/audit/release-metadata.py now checks release policy docs for git diff --check command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the git diff --check command.
• README, Korean README, Korean Distribution, and docs/RELEASE-CHECKLIST.md now identify git diff --check as the whitespace check command.
• CHANGELOG and SESSION-LOG now record the Phase 137 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep whitespace check wording while dropping the git diff --check command that runs before package contents and smoke checks.
• Existing CLI, whitespace check execution, release self-test execution, release metadata execution, package contents check, package smoke, registry smoke, release check, repository audits, and unit tests behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the whitespace command and whitespace check guidance as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 136 — Release self-test command guard added (v4.13.0) ✓ shipped

Release metadata now protects the local release:self-test command that runs release assertion fixtures before package smoke.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run release:self-test command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the release:self-test command.
• README, Korean README, and docs/RELEASE-CHECKLIST.md now identify release:self-test as the release assertion fixture command before package smoke.
• CHANGELOG and SESSION-LOG now record the Phase 136 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep release self-test wording while dropping the release:self-test command that runs assertion fixtures before package smoke.
• Existing CLI, release self-test execution, release metadata execution, package contents check, package smoke, registry smoke, release check, whitespace check execution, repository audits, and unit tests behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the release self-test command and release self-test guidance as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 135 — Release metadata command guard added (v4.13.0) ✓ shipped

Release metadata now protects the local release:metadata command that runs release metadata checks before tagging.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run release:metadata command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the release:metadata command.
• README, Korean README, and docs/RELEASE-CHECKLIST.md now identify release:metadata as the release metadata command before listing downstream release gates.
• CHANGELOG and SESSION-LOG now record the Phase 135 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep release metadata check wording while dropping the release:metadata command that runs the guard before tagging.
• Existing CLI, release metadata execution, package contents check, package smoke, registry smoke, release check, release self-test execution, whitespace check execution, repository audits, and unit tests behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the release metadata command and release metadata check wording as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 134 — Package contents command metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the local package:check command that verifies tarball package contents before smoke tests.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run package:check package contents command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the package:check command.
• README, Korean README, and docs/RELEASE-CHECKLIST.md now identify package:check as the package contents command before listing downstream smoke checks.
• CHANGELOG and SESSION-LOG now record the Phase 134 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep package contents wording while dropping the package:check command that verifies tarball contents.
• Existing CLI, package contents check, package smoke, registry smoke, release check, release metadata execution, release self-test execution, whitespace check execution, repository audits, and unit tests behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the package contents command and package contents check wording as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 133 — Package smoke command metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the local package:smoke command that runs packed-tarball installed-bin and one-shot npm exec checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run package:smoke packed-tarball command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the package:smoke command.
• README, Korean README, and docs/RELEASE-CHECKLIST.md now identify package:smoke as the packed-tarball smoke command before listing its execution paths.
• CHANGELOG and SESSION-LOG now record the Phase 133 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep packed-tarball smoke path details while dropping the package:smoke command that verifies them.
• Existing CLI, package smoke, registry smoke, release check, release metadata execution, release self-test execution, whitespace check execution, repository audits, unit tests, and package contents check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the local package smoke command and the packed-tarball execution paths as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 132 — Registry smoke command metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the post-publish registry:smoke command that verifies the public npm install path.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run registry:smoke post-publish command guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the registry:smoke command.
• docs/RELEASE-CHECKLIST.md now names registry:smoke inside the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 132 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep the public registry npm exec path while dropping the post-publish command that verifies it.
• Existing CLI, registry smoke, release check, package smoke, release metadata execution, release self-test execution, whitespace check execution, repository audits, unit tests, and package contents check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the post-publish registry smoke command and the public registry install path as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 131 — Release check command metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the top-level release:check core gate command that maintainers run before release PRs or tags.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run release:check core gate guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the release:check command.
• README, Korean README, and docs/RELEASE-CHECKLIST.md now identify release:check as the core gate before listing its downstream checks.
• CHANGELOG and SESSION-LOG now record the Phase 131 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep downstream gate details while dropping the release:check command that runs them.
• Existing CLI, release check execution, package smoke, registry smoke, release metadata execution, release self-test execution, whitespace check execution, repository audits, unit tests, and package contents check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release-facing docs now preserve the top-level local release command and the checks it orchestrates as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 130 — Packed tarball smoke metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the packed-tarball smoke gate that wraps the installed-bin and one-shot npm exec package checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for packed-tarball smoke gate guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops packed-tarball smoke wording.
• README, Korean README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now identify packed-tarball smoke as the package smoke gate for installed-bin and one-shot npm exec paths.
• CHANGELOG and SESSION-LOG now record the Phase 130 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently keep the individual package smoke paths while dropping the packed-tarball smoke gate that runs them.
• Existing CLI, package smoke, registry smoke, release metadata execution, release self-test execution, whitespace check execution, repository audits, unit tests, and package contents check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release-facing docs now preserve the package smoke gate and the local packed-tarball execution paths as one contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 129 — Release metadata check guidance guard added (v4.13.0) ✓ shipped

Release metadata now protects the release metadata check guidance already covered by npm run release:metadata in the release gate.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run release:metadata / release metadata check guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops release metadata check wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now list release metadata check guidance in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 129 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the release metadata check gate while keeping package, self-test, and smoke guidance.
• Existing CLI, release metadata execution, package smoke, registry smoke, release self-test execution, whitespace check execution, repository audits, unit tests, and package contents check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata check guidance now has an end-to-end drift guard from release:check to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 128 — Packed tarball installed-bin metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the packed-tarball installed-bin guidance already covered by package smoke.

Changed

• tools/audit/release-metadata.py now checks release policy docs for packed-tarball installed-bin smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops installed-bin wording.
• English/Korean Distribution docs and docs/RELEASE-CHECKLIST.md now list installed-bin guidance in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 128 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the installed-bin package smoke path while keeping one-shot npm exec, registry, and lifecycle smoke guidance.
• Existing CLI, package smoke, registry smoke, release self-test execution, whitespace check execution, repository audits, unit tests, and package contents check behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local package smoke guidance now preserves both packed-tarball execution paths: installed-bin and one-shot npm exec.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 127 — Release self-test metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects release self-test guidance already covered by npm run release:self-test in the release gate.

Changed

• tools/audit/release-metadata.py now checks release policy docs for npm run release:self-test guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops release self-test wording.
• English Distribution docs and docs/RELEASE-CHECKLIST.md now list release self-test guidance in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 127 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the release assertion self-test gate while keeping downstream package smoke and registry smoke guidance.
• Existing CLI, release self-test execution, whitespace check execution, repository audits, unit tests, package contents check, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release self-test guidance now has an end-to-end drift guard from release:check to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 126 — Whitespace check release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects whitespace check guidance already covered by git diff --check in the release gate.

Changed

• tools/audit/release-metadata.py now checks release policy docs for whitespace check guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops whitespace check wording.
• English Distribution docs and docs/RELEASE-CHECKLIST.md now list whitespace check guidance in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 126 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the whitespace gate while keeping downstream package contents, package smoke, and registry smoke guidance.
• Existing CLI, whitespace check execution, repository audits, unit tests, package contents check, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Whitespace check guidance now has an end-to-end drift guard from release:check to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 125 — Repository audit gate release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects all-eight repository audit guidance already covered by npm run audit:strict in the release gate.

Changed

• tools/audit/release-metadata.py now checks release policy docs for all-eight repository audit guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops repository audit gate wording.
• docs/RELEASE-CHECKLIST.md now lists all-eight repository audit guidance in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 125 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the repository audit gate while keeping downstream package contents, package smoke, and registry smoke guidance.
• Existing CLI, repository audits, unit tests, package contents check, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Repository audit gate guidance now has an end-to-end drift guard from run-all.py --strict to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 124 — CLI unit test release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects CLI unit test guidance already covered by npm test in the release gate.

Changed

• tools/audit/release-metadata.py now checks release policy docs for CLI unit test guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops CLI unit test wording.
• docs/RELEASE-CHECKLIST.md now lists CLI unit test guidance in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 124 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the first release gate while keeping downstream package contents, package smoke, and registry smoke guidance.
• Existing CLI, unit tests, package contents check, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• CLI unit test guidance now has an end-to-end drift guard from the release gate script to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 123 — Package contents release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects package contents check guidance already covered by npm run package:check in the release gate.

Changed

• tools/audit/release-metadata.py now checks release policy docs for package contents check guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops package contents wording.
• docs/RELEASE-CHECKLIST.md now lists package contents check guidance in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 123 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the package contents gate while keeping downstream package and registry smoke guidance.
• Existing CLI, package contents check, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Package contents guidance now has an end-to-end drift guard from the package allowlist audit to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 122 — Public registry npm exec release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the post-publish public registry npm exec --package @design-ai/cli@<version> guidance already covered by registry smoke.

Changed

• tools/audit/release-metadata.py now checks release policy docs for public registry npm exec smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops public registry npm exec --package @design-ai/cli@<version> wording.
• docs/RELEASE-CHECKLIST.md now lists the public registry npm exec path in the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 122 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the post-publish package execution path while keeping local packed-tarball smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Registry smoke guidance now has an end-to-end drift guard from post-publish npm exec verification to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 121 — Packed tarball npm exec release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the one-shot packed-tarball npm exec --package <tarball> guidance already covered by package smoke.

Changed

• tools/audit/release-metadata.py now checks release policy docs for packed-tarball npm exec smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops one-shot npm exec --package <tarball> wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now distinguish the local packed-tarball installed-bin and npm exec paths from public registry npm exec smoke.
• CHANGELOG and SESSION-LOG now record the Phase 121 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the package smoke contract for one-shot packed-tarball execution.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local tarball smoke guidance now has an end-to-end drift guard from package-smoke implementation to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 120 — Unknown command failure release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects unknown command/help/list/search-dir failure guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for unknown command/help/list/search-dir failure smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops unknown command/help/list/search-dir wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now describe unknown command/help/list/search-dir failure coverage in package and registry smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 120 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently narrow failure-path smoke guidance to route-id/option/value and numeric range checks.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Unknown command/help/list/search-dir failure guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 119 — Human lifecycle release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects human install, human+JSON status, and human uninstall lifecycle guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for human install/status/uninstall lifecycle smoke guidance.
• release-metadata.py --self-test now has drift fixtures that fail when a release-facing policy doc drops human lifecycle wording while retaining JSON lifecycle wording.
• docs/RELEASE-CHECKLIST.md now describes the human lifecycle phrases inside the release metadata protected phrase set.
• CHANGELOG and SESSION-LOG now record the Phase 119 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently collapse lifecycle smoke guidance down to JSON-only install/status/uninstall checks.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Human lifecycle smoke guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 118 — Prompt/pack mode release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the prompt/pack JSON/markdown/from-file/stdin guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for prompt/pack JSON/markdown/from-file/stdin smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops prompt/pack mode wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now describe prompt/pack JSON/markdown/from-file/stdin coverage in package and registry smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 118 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop prompt/pack mode smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Prompt/pack JSON/markdown/from-file/stdin guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 117 — Route JSON release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the route JSON/catalog/stdin guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for route JSON/catalog/stdin smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops route JSON/catalog/stdin wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now describe route JSON/catalog/stdin coverage in package and registry smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 117 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop route JSON/catalog/stdin smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Route JSON/catalog/stdin guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 116 — Check command release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the design-ai check guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for check examples/artifact/stdin/all-routes smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops check command wording.
• README, English/Korean Distribution docs, and docs/RELEASE-CHECKLIST.md now describe check command coverage in package and registry smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 116 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop check command smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Check command guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 115 — Human version release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the human version guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for human version smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops human version wording.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for human version guidance.
• CHANGELOG and SESSION-LOG now record the Phase 115 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop human version smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Human version guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 114 — Top-level help release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the top-level help guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for top-level help smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops top-level help wording.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for top-level help guidance.
• CHANGELOG and SESSION-LOG now record the Phase 114 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop top-level help smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Top-level help guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 113 — Help topic release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the command-specific help topic guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for command-specific help topic smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops command-specific help topic wording.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for help topic output guidance.
• CHANGELOG and SESSION-LOG now record the Phase 113 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop command-specific help topic smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Command-specific help topic guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 112 — Alias smoke release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the command alias and functional alias guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for command alias help and functional alias smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops functional alias wording.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for alias smoke guidance.
• CHANGELOG and SESSION-LOG now record the Phase 112 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop command alias and functional alias smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Alias smoke guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 111 — Prompt and pack output-file release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the prompt/pack forced output-file confirmation guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for prompt/pack forced output-file confirmation guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops file-write confirmation wording.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for prompt/pack output-file confirmations.
• CHANGELOG and SESSION-LOG now record the Phase 111 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop prompt/pack output-file confirmation smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Prompt and pack output-file confirmation guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 110 — Suggestion and numeric range release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the unknown suggestion and numeric range failure guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for unknown route-id/option/value suggestion and numeric range failure smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops numeric range failure wording.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for suggestion/range failure guidance.
• CHANGELOG and SESSION-LOG now record the Phase 110 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop suggestion and numeric range failure smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Suggestion and numeric range failure smoke guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 109 — Show lines and route explain release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the explicit show --lines and route --explain guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for both show --lines and route --explain smoke guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the route explanation phrase.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for explicit show --lines / route --explain guidance.
• CHANGELOG and SESSION-LOG now record the Phase 109 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop explicit line-range and route explanation smoke guidance.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Explicit output smoke guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 108 — Corpus discovery release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the human/JSON corpus discovery guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for human/JSON corpus discovery guidance covering search, show, and examples.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the corpus discovery JSON phrase.
• English and Korean README release guidance now names human/JSON corpus discovery smoke coverage explicitly.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for corpus discovery JSON guidance.
• CHANGELOG and SESSION-LOG now record the Phase 108 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the corpus discovery JSON smoke contract.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Corpus discovery automation guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 107 — List JSON release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the list JSON catalog guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for list --json or human/JSON list catalog guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the list JSON catalog phrase.
• English and Korean README release guidance now names human/JSON list catalog smoke coverage explicitly.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for release smoke guidance, including list --json.
• CHANGELOG and SESSION-LOG now record the Phase 107 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the list catalog JSON smoke contract.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• List catalog automation guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 106 — Release metadata phrase table self-test added (v4.13.0) ✓ shipped

Release metadata now self-tests the shared phrase guard table before validating release policy docs.

Changed

• tools/audit/release-metadata.py now keeps expected release policy phrase labels in RELEASE_POLICY_PHRASE_LABELS.
• release_policy_phrase_table_errors() validates label order, label uniqueness, non-empty term groups, and non-empty string terms.
• release-metadata.py --self-test now includes fixtures for dropped phrase labels, duplicate labels, and invalid empty terms.
• CHANGELOG and SESSION-LOG now record the Phase 106 table-shape guard.

Impact

• Future release smoke phrase coverage cannot silently drift because a table entry was removed, duplicated, or malformed.
• Existing CLI behavior, metadata output shape, policy-doc requirements, and release docs remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The table-driven release phrase guard can keep scaling without depending on reviewer memory to notice schema drift.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 105 — Release metadata phrase guard table refactor (v4.13.0) ✓ shipped

Release metadata phrase validation now uses one table-driven guard list.

Changed

• tools/audit/release-metadata.py now routes all release policy-doc smoke phrase checks through RELEASE_POLICY_PHRASE_CHECKS.
• release_policy_phrase_doc_errors() now produces the same structured phrase-drift errors that the individual helper functions previously produced.
• Existing self-test drift fixtures now validate the shared phrase-check path.
• CHANGELOG and SESSION-LOG now record the Phase 105 refactor.

Impact

• Future release smoke phrase guards can be added with less code churn and less risk of forgetting the validation loop.
• Existing CLI behavior, metadata output shape, policy-doc requirements, and release docs remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata can keep expanding smoke-contract coverage without accumulating phrase-specific helper boilerplate.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 104 — Help JSON release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the help JSON topic catalog guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for help --json topic catalog guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the help JSON topic catalog phrase.
• English and Korean README release guidance now names the design-ai help --json topic catalog explicitly.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for release smoke guidance, including help --json.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the help JSON topic catalog smoke contract.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Help topic catalog guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 103 — Status JSON release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the status JSON install-state guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for status --json or human+JSON status guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the status JSON install-state phrase.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for release smoke guidance, including status --json.
• CHANGELOG and SESSION-LOG now record the Phase 103 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the status JSON install-state smoke contract.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Install-state guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 102 — Doctor strict release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the doctor strict diagnostics guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for doctor --strict guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the doctor strict smoke phrase.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for release smoke guidance, including doctor --strict.
• CHANGELOG and SESSION-LOG now record the Phase 102 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the doctor strict diagnostics smoke contract.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release diagnostics guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 101 — Audit strict-quiet release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the audit strict-quiet smoke guidance already covered by package and registry smoke checks.

Changed

• tools/audit/release-metadata.py now checks release policy docs for audit --strict --quiet guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the audit strict-quiet smoke phrase.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for release smoke guidance, including audit --strict --quiet.
• CHANGELOG and SESSION-LOG now record the Phase 101 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the audit strict-quiet smoke contract.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release smoke guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 100 — Update dry-run release metadata guard added (v4.13.0) ✓ shipped

Release metadata now protects the update dry-run smoke guidance added in Phase 99.

Changed

• tools/audit/release-metadata.py now checks release policy docs for update --dry-run guidance.
• release-metadata.py --self-test now has a drift fixture that fails when a release-facing policy doc drops the update dry-run lifecycle phrase.
• docs/RELEASE-CHECKLIST.md now describes release metadata coverage for lifecycle smoke guidance, including update --dry-run.
• CHANGELOG and SESSION-LOG now record the Phase 100 guard.

Impact

• README, Release checklist, and English/Korean Distribution docs cannot silently drop the update dry-run smoke contract.
• Existing CLI, package smoke, and registry smoke behavior remains unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• python3 -B tools/audit/release-metadata.py --json
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Lifecycle smoke guidance now has an end-to-end drift guard from implementation, to packaged smoke, to release-facing docs.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 99 — Update command dry-run preview added (v4.13.0) ✓ shipped

design-ai update --dry-run now previews source update and reinstall actions without mutating the repo or Claude home.

Changed

• cli/commands/update.mjs now accepts --dry-run for human preview output and --dry-run --json for machine-readable update plans.
• The dry-run JSON report includes stable context, plan, and result sections with git pull intent, install script readiness, exact command arrays, and mutating: false.
• cli/lib/update-command.test.mjs now covers dry-run parser behavior, JSON-only rejection, key order, command arrays, localized paths, and readiness flags.
• Help output, README, Distribution, and Release checklist docs now list design-ai update [--dry-run] [--json].
• Package smoke and registry smoke now validate both human and JSON update dry-run output before install lifecycle checks.

Impact

• Contributors can preview update effects before any git pull or install.sh work starts.
• Release automation can verify update readiness from a deterministic JSON plan.
• Existing mutating design-ai update, upgrade, u, and help behavior remain compatible.

Verified

• All 8 audits pass.
• node --test cli/lib/update-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• NO_COLOR=1 node cli/bin/design-ai.mjs update --dry-run
• NO_COLOR=1 node cli/bin/design-ai.mjs update --dry-run --json
• NO_COLOR=1 node cli/bin/design-ai.mjs update --json
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run release:metadata
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Update lifecycle smoke can now assert non-mutating preview behavior before packaged or registry install checks proceed.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 98 — Update command option guard added (v4.13.0) ✓ shipped

design-ai update now rejects unsupported arguments before it can pull source changes or rerun install.sh.

Changed

• cli/commands/update.mjs now has a dedicated parser for help flags, unknown options, and unexpected positional arguments.
• cli/lib/update-command.test.mjs covers help aliases, empty argument parsing, typo suggestions, and positional-argument rejection.
• Shared smoke assertions now include design-ai update --hlep so package and registry smoke tests verify the same fail-closed update contract.

Impact

• Update command typos fail fast with Did you mean \--help`?` instead of continuing into git/install work.
• Existing design-ai update, upgrade, u, and help output remain compatible.

Verified

• All 8 audits pass.
• node --test cli/lib/update-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• NO_COLOR=1 node cli/bin/design-ai.mjs update --hlep
• python3 -B tools/audit/smoke_assertions.py --self-test
• npm test
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Lifecycle CLI smoke coverage now catches update option typos before release packaging.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 97 — Install command JSON lifecycle output added (v4.13.0) ✓ shipped

design-ai install now emits machine-readable lifecycle output for package and registry smoke automation.

Changed

• cli/commands/install.mjs now supports --json while keeping the existing human install output.
• The install JSON report includes source root, Claude home, symlink prefix, and installed skill/agent/command counts.
• cli/lib/install-command.test.mjs covers parser behavior, unknown-option suggestions, installed-count parsing, JSON key order, and readable localized paths.
• Package smoke and registry smoke now verify both human install output and JSON install --json lifecycle output.
• Release metadata now guards policy docs against dropping install --json lifecycle smoke guidance.

Impact

• Release automation can validate install lifecycle completion without scraping human terminal output.
• Existing install, status, doctor, and uninstall flows remain unchanged.

Verified

• All 8 audits pass.
• node --test cli/lib/install-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• npm test
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• CLAUDE_HOME=<tmp>/claude DESIGN_AI_PREFIX=smoke-design- NO_COLOR=1 node cli/bin/design-ai.mjs install --json

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Install lifecycle smoke now has machine-readable entry and exit checks.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 96 — Uninstall command JSON lifecycle output added (v4.13.0) ✓ shipped

design-ai uninstall now emits machine-readable lifecycle output for package and registry smoke automation.

Changed

• cli/commands/uninstall.mjs now supports --json while keeping the existing human uninstall output.
• The uninstall JSON report includes source root, Claude home, symlink prefix, and removed symlink count.
• cli/lib/uninstall-command.test.mjs covers parser behavior, unknown-option suggestions, removed-count parsing, JSON key order, and readable localized paths.
• Package smoke and registry smoke now verify both human uninstall output and JSON uninstall --json lifecycle output.
• Release metadata now guards policy docs against dropping uninstall --json lifecycle smoke guidance.

Impact

• Release automation can validate uninstall lifecycle completion without scraping human terminal output.
• Existing install, status, doctor, and human uninstall flows remain unchanged.

Verified

• All 8 audits pass.
• node --test cli/lib/uninstall-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• python3 -B tools/audit/smoke_assertions.py --self-test
• python3 -B tools/audit/release-metadata.py --self-test
• python3 -B tools/audit/package-smoke.py --self-test
• python3 -B tools/audit/registry-smoke.py --self-test
• CLAUDE_HOME=<tmp>/claude DESIGN_AI_PREFIX=smoke-design- NO_COLOR=1 node cli/bin/design-ai.mjs uninstall --json

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Install lifecycle smoke now has machine-readable entry and exit checks.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 95 — README release-smoke version JSON guidance guarded (v4.13.0) ✓ shipped

Release-facing README guidance now stays aligned with the design-ai version --json smoke contract.

Changed

• README.md and README.ko.md now list the current machine-readable CLI surfaces for status, list, audit, and version commands.
• README release guidance now describes human/JSON version metadata, human/JSON audit output, and human+JSON status lifecycle smoke checks for package and registry verification.
• tools/audit/release-metadata.py now checks every release policy doc for version --json guidance in addition to the MkDocs warning-policy phrases.
• release-metadata.py --self-test now includes a fixture that fails when release-facing docs drop the version JSON smoke phrase.

Impact

• Contributor-facing release docs cannot silently drift away from the current package/registry smoke coverage.
• Existing CLI behavior and smoke command execution remain unchanged.

Verified

• All 8 audits pass.
• python3 -B tools/audit/release-metadata.py --self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release docs and metadata checks now preserve the version JSON smoke contract through future README edits.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 94 — Version command JSON metadata output added (v4.13.0) ✓ shipped

design-ai version now emits a self-tested JSON metadata report for CLI/plugin version alignment.

Changed

• cli/commands/version.mjs now supports --json while keeping the existing human version output.
• cli/commands/version.mjs now uses parseVersionArgs(), collectVersionReport(), and formatVersionJson() for machine-readable version metadata.
• cli/lib/version-command.test.mjs now checks argument parsing, unknown-option suggestions, top-level JSON key order, context key order, version key order, aligned/mismatched states, and readable localized paths.
• tools/audit/smoke_assertions.py, tools/audit/package-smoke.py, and tools/audit/registry-smoke.py now cover version JSON output for installed package and registry lifecycle paths.

Impact

• Automation that uses design-ai version --json can verify CLI/plugin version alignment without parsing human terminal output.
• Existing human design-ai version, design-ai --version, and design-ai -v workflows remain unchanged.

Verified

• All 8 audits pass.
• node --test cli/lib/version-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• npm run smoke:assertions:self-test
• node cli/bin/design-ai.mjs version --json
• npm test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Version alignment becomes a stable automation-facing contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 93 — Audit command JSON repository gate output added (v4.13.0) ✓ shipped

design-ai audit now emits a self-tested JSON report for the shared eight-audit repository gate.

Changed

• tools/audit/run-all.py now supports --json while keeping the existing human summary output.
• tools/audit/run-all.py now uses build_json_report() and format_json_report() for machine-readable audit results.
• cli/commands/audit.mjs now supports --json and keeps wrapper headers out of JSON mode.
• cli/lib/audit-command.test.mjs now checks argument parsing, runner argument forwarding, help output, and unknown-option suggestions.
• tools/audit/smoke_assertions.py, tools/audit/package-smoke.py, and tools/audit/registry-smoke.py now cover audit JSON output for the installed package and registry lifecycle paths.

Impact

• Automation that uses design-ai audit --strict --quiet --json can verify the repository gate without parsing terminal text.
• Existing human design-ai audit, design-ai a, --strict, and --quiet workflows remain unchanged.

Verified

• All 8 audits pass.
• python3 tools/audit/run-all.py --self-test
• node --test cli/lib/audit-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• npm run smoke:assertions:self-test
• node cli/bin/design-ai.mjs audit --strict --quiet --json
• npm test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The final pre-push repository quality gate becomes a stable automation-facing contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 92 — Status command JSON install-state output added (v4.13.0) ✓ shipped

design-ai status now emits a self-tested JSON report for installed design-ai symlinks.

Changed

• cli/commands/status.mjs now supports --json while keeping the existing human status output.
• cli/commands/status.mjs now uses collectStatusReport() and formatStatusJson() for machine-readable install-state output.
• cli/lib/status-command.test.mjs now checks argument parsing, unknown-option suggestions, top-level status key order, context key order, section key order, sorted symlink entry output, missing-section output, and readable localized paths.
• tools/audit/smoke_assertions.py, tools/audit/package-smoke.py, and tools/audit/registry-smoke.py now cover status JSON output after install and before uninstall.

Impact

• Automation that uses design-ai status --json can verify installed skills, agents, and slash commands without parsing terminal text.
• Existing human design-ai status, design-ai s, and VERBOSE=1 workflows remain unchanged.

Verified

• All 8 audits pass.
• node --test cli/lib/status-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• npm run smoke:assertions:self-test
• npm test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Install lifecycle state becomes a stable automation-facing contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 91 — List command JSON catalog output added (v4.13.0) ✓ shipped

design-ai list now emits a self-tested JSON catalog for shipped skills, slash commands, and agents.

Changed

• cli/commands/list.mjs now supports --json for all catalog sections and filtered skills, commands, or agents sections.
• cli/commands/list.mjs now uses buildListCatalog() and formatListJson() for machine-readable manifest catalog output.
• cli/lib/list-command.test.mjs now checks argument parsing, top-level catalog key order, section key order, manifest item key order, filtered catalog output, and readable localized catalog text.
• tools/audit/smoke_assertions.py, tools/audit/package-smoke.py, and tools/audit/registry-smoke.py now cover list catalog JSON output for all catalog domains.

Impact

• Automation that uses design-ai list --json can enumerate skills, slash commands, and agents without parsing human terminal output.
• Existing human design-ai list and design-ai ls output remains unchanged.

Verified

• All 8 audits pass.
• node --test cli/lib/list-command.test.mjs cli/lib/help-command.test.mjs cli/lib/dispatch.test.mjs
• npm run smoke:assertions:self-test
• npm test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Manifest catalog enumeration becomes a stable automation-facing contract.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 90 — Doctor command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai doctor now self-tests its JSON output contract for install-health context, diagnostic checks, summary counts, and fix metadata.

Changed

• cli/lib/doctor.mjs now uses formatDoctorJson() as the shared formatter for doctor diagnostics JSON output.
• cli/commands/doctor.mjs now sends --json output through that formatter.
• cli/lib/doctor.test.mjs now checks JSON round-trip behavior, top-level diagnostic key order, context/expected/check/summary/fix key order, and readable localized diagnostic text.

Impact

• Automation that uses design-ai doctor --json can rely on stable install-health payload order.
• Localized diagnostic labels, details, actions, and fix reasons stay readable instead of being escaped in machine-readable diagnostics output.

Verified

• All 8 audits pass.
• node --test cli/lib/doctor.test.mjs
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai doctor keeps machine-readable install-health diagnostics refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 89 — Help command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai help now self-tests its JSON output contract for top-level command discovery, topic entries, and alias maps.

Changed

• cli/commands/help.mjs now uses formatHelpJson() as the shared formatter for help-topic catalog JSON output.
• cli/commands/help.mjs now sends --json output through that formatter.
• cli/lib/help-command.test.mjs now checks JSON round-trip behavior, top-level catalog key order, topic-entry key order, alias map order, and readable localized help text.

Impact

• Automation that uses design-ai help --json can rely on stable usage, topics, and aliases payload order.
• Localized help text stays readable instead of being escaped in machine-readable help catalog output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai help keeps machine-readable command discovery refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 88 — Show command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai show now self-tests its JSON output contract for corpus file metadata, context windows, and explicit line ranges.

Changed

• cli/lib/show.mjs now uses formatShowJson() as the shared formatter for corpus file JSON output.
• cli/commands/show.mjs now sends --json output through that formatter.
• cli/lib/show.test.mjs now checks JSON round-trip behavior, top-level file payload key order, line-entry key order, explicit line-range payload order, and readable Korean file text.

Impact

• Automation that chains design-ai search --json into design-ai show --json can rely on stable file metadata and lines entry order.
• Korean corpus file content stays readable instead of being escaped in machine-readable file display output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai show keeps machine-readable corpus file display refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 87 — Search command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai search now self-tests its JSON output contract for corpus search hits and empty result payloads.

Changed

• cli/lib/search.mjs now uses formatSearchJson() as the shared formatter for corpus search JSON output.
• cli/commands/search.mjs now sends --json output through that formatter.
• cli/lib/search.test.mjs now checks JSON round-trip behavior, top-level payload key order, hit-entry key order, empty-result payload order, and readable Korean previews.

Impact

• Automation that uses design-ai search --json can rely on stable query and hits payload order.
• Korean search previews stay readable instead of being escaped in corpus search JSON output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai search keeps machine-readable corpus discovery refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 86 — Examples command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai examples now self-tests its JSON output contract for query-driven and route-biased worked-example discovery.

Changed

• cli/lib/examples.mjs now uses formatExamplesJson() as the shared formatter for worked-example discovery JSON output.
• cli/commands/examples.mjs now sends --json output through that formatter.
• cli/lib/examples.test.mjs now checks JSON round-trip behavior, top-level payload key order, example-entry key order, route-biased payload order, and readable Korean example text.

Impact

• Automation that uses design-ai examples --json can rely on stable query, routeId, effectiveQuery, and examples payload order.
• Korean example titles and previews stay readable instead of being escaped in worked-example discovery JSON output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai examples keeps machine-readable worked-example lookup refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 85 — Pack command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai pack now self-tests its JSON output contract for complete and partial prompt-context bundles.

Changed

• cli/lib/pack.mjs now uses formatPackJson() as the shared formatter for prompt-context bundle JSON output.
• cli/commands/pack.mjs now sends both stdout and --out JSON bundles through that formatter.
• cli/lib/pack.test.mjs now checks JSON round-trip behavior, prompt-pack key order, context summary key order, nested prompt-plan key order, file-entry key order, forced-route partial-context payload order, and readable Korean briefs.

Impact

• Automation that consumes generated context bundles can rely on the same top-level report order for complete and partial packs.
• Korean briefs stay readable instead of being escaped in prompt-context bundle JSON output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai pack keeps machine-readable prompt-context bundles refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 84 — Prompt command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai prompt now self-tests its JSON output contract for inferred and forced route prompt plans.

Changed

• cli/lib/prompt.mjs now uses formatPromptJson() as the shared formatter for prompt-plan JSON output.
• cli/commands/prompt.mjs now sends both stdout and --out JSON prompt plans through that formatter.
• cli/lib/prompt.test.mjs now checks JSON round-trip behavior, prompt plan key order, nested route key order, forced-route payload order, and readable Korean briefs.

Impact

• Automation that consumes generated prompt plans can rely on the same top-level report order for inferred and forced route workflows.
• Korean briefs stay readable instead of being escaped in prompt-plan JSON output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai prompt keeps machine-readable agent handoff plans refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 83 — Route command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai route now self-tests its JSON output contract for recommendation and catalog reports.

Changed

• cli/lib/route.mjs now uses formatRouteJson() as the shared formatter for route JSON output.
• cli/commands/route.mjs now sends scored route recommendations and route catalog --json output through that formatter.
• cli/lib/route.test.mjs now checks JSON round-trip behavior, recommendation/catalog key order, and readable Korean route keywords.

Impact

• Automation that consumes route recommendations can rely on the same top-level report order.
• Korean route keywords stay readable instead of being escaped in JSON output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• python3 -B tools/audit/local-ci.py --docs-only
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai route keeps machine-readable recommendation and catalog reports refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 82 — Check command JSON output formatter guard added (v4.13.0) ✓ shipped

design-ai check now self-tests its JSON output contract for artifact and examples reports.

Changed

• cli/lib/check.mjs now uses formatCheckJson() as the shared formatter for check reports.
• cli/commands/check.mjs now sends artifact and examples --json output through that formatter.
• cli/lib/check.test.mjs now checks JSON round-trip behavior, artifact/examples key order, and readable Korean messages.

Impact

• Automation that consumes design-ai check --json can rely on the same top-level report order.
• Future localized diagnostics can include Korean text without Unicode-escaped output.

Verified

• All 8 audits pass.
• npm test
• npm run smoke:assertions:self-test
• npm run release:metadata
• npm run release:self-test
• npm run audit:strict
• npm run package:check
• npm run package:smoke
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• design-ai check keeps machine-readable artifact quality reports refactor-safe.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 81 — Release metadata JSON output formatter guard added (v4.13.0) ✓ shipped

Release metadata now self-tests its JSON output contract.

Changed

• tools/audit/release-metadata.py now uses format_json_summary() for --json output.
• npm run release:metadata:self-test now checks JSON round-trip behavior, summary key order, checked-doc indentation/order, and Korean error readability.
• docs/RELEASE-CHECKLIST.md now documents the stable JSON summary contract.

Impact

• JSON release metadata output can be refactored without losing top-level key order or checked-doc order.
• Korean structured errors remain readable instead of being escaped into Unicode sequences.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata keeps tested contracts for both automation-facing JSON and maintainer-facing terminal output.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 80 — Release metadata human output formatter guard added (v4.13.0) ✓ shipped

Release metadata now self-tests its non-JSON output contract.

Changed

• tools/audit/release-metadata.py now uses format_human_summary() for human pass/fail output.
• npm run release:metadata:self-test now checks the passing summary string and failed bullet output.
• docs/RELEASE-CHECKLIST.md now describes structured bullet errors for metadata failures.

Impact

• Human release metadata output can be refactored without losing the failed-output header or structured bullet lines.
• JSON output remains unchanged, while reviewer-facing terminal output now has explicit regression coverage.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata keeps a tested contract for both automation output and maintainer terminal output.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 79 — Release metadata audit-count loader guard added (v4.13.0) ✓ shipped

Release metadata now reports audit-count source failures as structured errors.

Changed

• tools/audit/release-metadata.py now returns (audit_count, errors) from load_audit_count() instead of raising SystemExit.
• npm run release:metadata:self-test now covers missing AUDITS tuple, missing audit script entries, and missing run-all.py path fixtures.
• docs/RELEASE-CHECKLIST.md now states that audit-count source failures produce release metadata errors instead of tracebacks or early exits.

Impact

• A broken audit runner shape no longer prevents release metadata from producing JSON/human error output.
• CHANGELOG and ROADMAP audit-count checks avoid cascading mismatch noise when the expected audit count cannot be loaded.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata remains actionable even when its audit-count source drifts or disappears.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 78 — Release metadata core input loader guard added (v4.13.0) ✓ shipped

Release metadata now reports core input loading failures as structured errors.

Changed

• tools/audit/release-metadata.py now uses structured loaders for package.json, .claude-plugin/plugin.json, CHANGELOG.md, and docs/ROADMAP.md.
• npm run release:metadata:self-test now covers missing JSON, invalid JSON, missing text, and valid fixture input paths.
• docs/RELEASE-CHECKLIST.md now states that core input loading failures produce release metadata errors instead of tracebacks.

Impact

• Broken core release inputs now produce actionable metadata errors instead of Python exceptions.
• The release metadata command keeps a consistent JSON/human error surface for manifests, release docs, and policy docs.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata remains useful and machine-readable even when required manifests or release docs are damaged.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 77 — Release policy docs loader error guard added (v4.13.0) ✓ shipped

Release metadata now reports policy-doc filesystem failures as structured errors.

Changed

• tools/audit/release-metadata.py now uses load_release_policy_docs() to read the required release policy docs.
• npm run release:metadata:self-test now covers a missing-on-disk policy doc fixture.
• docs/RELEASE-CHECKLIST.md now states that missing required policy docs produce release metadata errors instead of tracebacks.

Impact

• Deleted or unreadable release policy docs now produce actionable release metadata failures.
• The exact coverage contract applies to both the loaded filesystem path and the pure metadata summary path.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata remains useful when docs coverage fails because a required file disappeared.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 76 — Release policy docs deterministic order guard added (v4.13.0) ✓ shipped

Release metadata now guards the policy-doc coverage order as well as membership.

Changed

• tools/audit/release-metadata.py now fails when release policy docs contain the required labels in a different order.
• npm run release:metadata:self-test now covers a reordered policy-doc fixture.
• docs/RELEASE-CHECKLIST.md now documents the exact required release policy docs order.

Impact

• release_policy_docs_checked stays stable for release JSON output and reviewer comparisons.
• Required docs, unexpected docs, and order drift now each have explicit release metadata failure modes.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata remains deterministic even when the checked docs set is maintained by future edits.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 75 — Release policy docs exact set guard added (v4.13.0) ✓ shipped

Release metadata now guards the policy-doc coverage set as an exact set.

Changed

• tools/audit/release-metadata.py now rejects release policy doc labels outside REQUIRED_RELEASE_POLICY_DOC_LABELS.
• npm run release:metadata:self-test now covers an unexpected docs/UNTRACKED.md policy-doc entry.
• docs/DOGFOOD-V4-NPM-FINDINGS.md now records that metadata checks exact policy-doc membership as well as policy wording.

Impact

• A required policy doc cannot silently disappear from release metadata coverage.
• An unexpected or mistyped policy-doc label cannot silently enter release metadata coverage.
• The Phase 72/73 release-facing docs guard now fails closed for exact coverage membership and command/policy content.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata remains reliable even as the list of release-facing docs evolves.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 74 — Release policy docs coverage set guard added (v4.13.0) ✓ shipped

Release metadata now guards the required policy-doc coverage set itself.

Changed

• tools/audit/release-metadata.py now stores the required release policy docs in REQUIRED_RELEASE_POLICY_DOC_LABELS.
• RELEASE_POLICY_DOC_PATHS is derived from that required set.
• npm run release:metadata:self-test now covers a missing-doc failure when README.ko.md is removed from the policy docs map.
• docs/DOGFOOD-V4-NPM-FINDINGS.md now records that metadata checks policy-doc membership as well as policy wording.

Impact

• A required policy doc cannot silently disappear from release metadata coverage.
• The Phase 72/73 release-facing docs guard now fails closed for both coverage membership and command/policy content.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release metadata remains reliable even as the list of release-facing docs evolves.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 73 — Release policy docs ci:local command guard added (v4.13.0) ✓ shipped

Release metadata now guards the executable command in release-facing policy docs.

Changed

• tools/audit/release-metadata.py now requires release-facing MkDocs warning-policy docs to mention ci:local.
• npm run release:metadata:self-test now includes a README command-drift fixture where npm run ci:local is replaced by npm run release:check.
• docs/DOGFOOD-V4-NPM-FINDINGS.md now records that release metadata covers both warning-policy baseline drift and command-reference drift.

Impact

• Docs cannot keep the warning-policy words while losing the actual pre-push command maintainers need before Real-CI.
• README, release checklist, and Distribution docs stay aligned on both command and policy.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release-facing docs keep command-level pre-push guidance intact.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 72 — Release policy docs metadata coverage expanded (v4.13.0) ✓ shipped

Release metadata now checks every release-facing docs page that carries the MkDocs warning-policy baseline.

Changed

• tools/audit/release-metadata.py now checks README.md, README.ko.md, docs/RELEASE-CHECKLIST.md, docs/DISTRIBUTION.md, and docs/DISTRIBUTION.ko.md for the warning-policy phrase groups.
• npm run release:metadata -- --json now reports that full release_policy_docs_checked set.
• docs/RELEASE-CHECKLIST.md and docs/DOGFOOD-V4-NPM-FINDINGS.md now describe the expanded release policy docs coverage.

Impact

• Entry docs, the release checklist, and Distribution docs now stay aligned on the ci:local MkDocs warning-policy baseline.
• Maintainers get one metadata gate for the release-facing docs they read before Real-CI verification.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata -- --json
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Release guidance remains consistent across README, checklist, and distribution surfaces.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 71 — Release metadata bilingual phrase guard hardened (v4.13.0) ✓ shipped

The release metadata distribution policy guard now accepts Korean equivalents.

Changed

• tools/audit/release-metadata.py now accepts English and Korean phrase alternatives for MkDocs warning policy, refs-only warning, non-refs/ warning, and accepted baseline checks.
• npm run release:metadata:self-test now includes a Korean MkDocs 경고 정책 / 기준선 passing fixture.
• docs/DOGFOOD-V4-NPM-FINDINGS.md now records that release metadata covers bilingual distribution warning-policy drift.

Impact

• Korean docs can use natural Korean policy language without causing false release metadata failures.
• The guard still fails when the required warning-policy meaning disappears from either distribution guide.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Bilingual release guidance remains idiomatic while staying under automated metadata validation.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 70 — Bilingual distribution policy metadata guard added (v4.13.0) ✓ shipped

Release metadata now guards the English and Korean distribution warning-policy language.

Changed

• tools/audit/release-metadata.py now checks docs/DISTRIBUTION.md and docs/DISTRIBUTION.ko.md for the MkDocs warning-policy terms covering refs-only warnings and the accepted baseline.
• npm run release:metadata:self-test now includes a distribution warning-policy drift fixture.
• docs/RELEASE-CHECKLIST.md now states that release metadata covers the bilingual distribution warning-policy guidance.

Impact

• Future docs edits cannot silently drop the Phase 68/69 warning-policy baseline language from either distribution guide.
• The release metadata gate now protects the bilingual release guidance before Real-CI verification.

Verified

• All 8 audits pass.
• npm run release:metadata:self-test
• npm run release:metadata
• npm run release:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Bilingual release docs stay aligned with the executable MkDocs warning policy as local CI hardening continues.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 69 — Korean distribution warning policy guidance synced (v4.13.0) ✓ shipped

The Korean distribution guide now matches the Phase 68 MkDocs warning policy.

Changed

• docs/DISTRIBUTION.ko.md now states that npm run ci:local blocks non-refs/ MkDocs warnings and requires refs-only warnings to stay within the accepted baseline cap.

Impact

• Korean release guidance now matches the English distribution docs before Real-CI verification.
• Maintainers using Korean docs get the same expectation for the docs warning policy.

Verified

• All 8 audits pass.
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run release:metadata
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The release checklist stays bilingual as the local docs policy continues to harden.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 68 — MkDocs refs warning baseline capped (v4.13.0) ✓ shipped

The local MkDocs warning policy now caps the intentional refs/ warning stream at the accepted baseline.

Changed

• tools/audit/local-ci.py now fails if refs-only MkDocs warnings exceed the current accepted baseline of 632.
• tools/audit/local-ci.py --self-test now covers refs-warning classification and baseline-regression behavior.

Impact

• New upstream-source links cannot silently grow the accepted warning stream before Real-CI verification.
• Maintainers get a focused failure that asks for either link normalization or a documented baseline update.

Verified

• All 8 audits pass.
• npm test
• npm run ci:local:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The remaining docs warning policy is now bounded by both category and count.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 67 — Docs workflow corpus path invariant expanded (v4.13.0) ✓ shipped

The local docs workflow drift check now guards all main corpus directory triggers.

Changed

• tools/audit/local-ci.py now requires the docs workflow path filter to include knowledge/**, examples/**, skills/**, agents/**, commands/**, and docs/**.

Impact

• Future workflow edits cannot silently stop deploying changes to the main MkDocs corpus directories.
• The docs workflow trigger invariant now covers corpus directories, top-level site files, shared helper scripts, and the workflow file itself.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• GitHub Pages trigger coverage stays aligned with the directories symlinked into the MkDocs site.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 66 — Korean top-level docs trigger Pages deploy (v4.13.0) ✓ shipped

The GitHub Pages workflow now watches the Korean top-level files that are symlinked into the MkDocs source tree.

Changed

• .github/workflows/docs.yml now includes README.ko.md and AGENTS.ko.md in its paths filter.
• tools/audit/local-ci.py now treats the top-level MkDocs source files as required docs workflow paths.

Impact

• Korean landing page and Korean agent entry point changes now trigger docs deployment directly.
• Local CI catches future path-filter drift for the top-level site inputs created by tools/build-docs.sh.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Korean top-level documentation changes no longer wait for another docs path change to deploy.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 65 — Docs workflow policy parser tightened (v4.13.0) ✓ shipped

The docs workflow drift check now validates extracted workflow fields instead of broad file substrings.

Changed

• tools/audit/local-ci.py now parses one-line run: commands from workflow text.
• tools/audit/local-ci.py now parses entries under paths: and checks required docs helper paths from that list.
• The expected docs workflow command and path constants are stored separately.

Impact

• The docs workflow policy check is less sensitive to indentation and unrelated text.
• Failure messages remain focused on the actual invariant: missing --docs-only, direct MkDocs build use, or missing helper path filters.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Workflow policy enforcement can evolve without adding a ninth repository audit or relying on fragile whole-file substring checks.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 64 — Docs workflow policy drift check (v4.13.0) ✓ shipped

The docs deployment workflow alignment from Phase 63 is now enforced by local CI.

Added

• tools/audit/local-ci.py checks .github/workflows/docs.yml for the shared --docs-only build path.
• tools/audit/local-ci.py --self-test now covers passing and failing docs workflow policy fixtures.

Changed

• npm run ci:local and python3 -B tools/audit/local-ci.py --docs-only now fail if the docs workflow calls mkdocs build --clean directly or omits shared docs helper paths from the workflow trigger.
• Release checklist documentation now calls out docs workflow policy alignment as part of local CI.

Impact

• Future workflow edits cannot silently bypass the non-refs/ MkDocs warning policy.
• Real-CI docs deployment remains aligned with local parity unless maintainers deliberately update the policy and its checks together.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run ci:local -- --skip-release-check --skip-vscode --skip-docs
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Docs workflow policy is now an executable invariant rather than a manual review note.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 63 — Docs workflow uses local MkDocs policy (v4.13.0) ✓ shipped

The GitHub Pages deployment workflow now runs through the same docs-only warning-policy path as local CI.

Added

• tools/audit/local-ci.py --docs-only runs MkDocs version check, tools/build-docs.sh, mkdocs build --clean, and non-refs/ warning enforcement without release, VS Code, or package checks.

Changed

• .github/workflows/docs.yml now calls python3 -B tools/audit/local-ci.py --docs-only.
• The docs workflow path filter now includes tools/audit/local-ci.py and tools/build-docs.sh.
• README pre-push guidance now explicitly mentions the MkDocs non-refs/ warning policy.

Impact

• Local docs parity and GitHub Pages deployment share one warning-policy implementation.
• Real-CI docs deployment should fail on the same non-refs/ MkDocs warning regressions as local ci:local.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• python3 -B tools/audit/local-ci.py --docs-only
• npm run release:self-test
• npm run release:metadata
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Real-CI verification is more meaningful because docs deployment no longer uses a separate direct MkDocs command.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 62 — Local CI MkDocs output summarized (v4.13.0) ✓ shipped

Successful local CI docs runs now keep MkDocs output compact while preserving the Phase 61 warning policy.

Changed

• tools/audit/local-ci.py captures successful MkDocs build output without echoing the full accepted refs/ warning stream.
• Failed subprocesses still print captured output so MkDocs install, config, or build failures remain visible.

Impact

• Local parity logs no longer print hundreds of expected refs/ warning lines on success.
• Maintainers still get a clear MkDocs warning policy passed: N refs-only warning(s) summary.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• npm run release:self-test
• npm run ci:local -- --skip-release-check --skip-vscode
• npm run package:check
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Pre-push local CI output is short enough to inspect quickly before Real-CI verification.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 61 — Local CI enforces MkDocs warning policy (v4.13.0) ✓ shipped

The Phase 60 MkDocs warning baseline is now enforced by the local CI parity gate.

Added

• tools/audit/local-ci.py captures mkdocs build --clean output and classifies warning lines.
• tools/audit/local-ci.py --self-test now covers refs-only warning output and mixed warning output.

Changed

• npm run ci:local now fails on any non-refs/ MkDocs warning.
• Existing upstream refs/ source-link warnings remain allowed because they are a known documentation policy question, not current navigation breakage.

Impact

• New docs navigation regressions should be caught before push.
• Real-CI docs logs should stay focused on external confirmation rather than first-pass warning discovery.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• npm run release:self-test
• npm run ci:local -- --skip-release-check --skip-vscode
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Maintainers can rely on the existing local parity command to protect the non-refs/ warning baseline.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 60 — MkDocs warning stream narrowed to refs (v4.13.0) ✓ shipped

The local docs build now has 0 non-refs/ MkDocs warnings; remaining warnings are intentionally concentrated in upstream source-reference links.

Changed

• Stability-review command tooling references now render as code paths instead of links to files outside the MkDocs site tree.
• Npm dogfood tooling references now render as code paths where they refer to repository scripts.
• Korean launch draft and Korean contributor references now point at GitHub URLs to avoid static-i18n .ko.md resolution noise.

Impact

• MkDocs WARNING lines dropped to 632 in the latest local build.
• Non-refs/ MkDocs warnings are 0.
• Remaining warning volume is now policy-level refs/ source-link handling, not general docs navigation breakage.

Verified

• All 8 audits pass.
• ./tools/build-docs.sh
• python3 -m mkdocs build --clean
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Real-CI docs logs should now make any new non-refs/ warning stand out immediately.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Decide whether refs/ source links should remain visible repo references or be normalized through generated reference pages.

Phase 59 — Documentation link hygiene before Real-CI (v4.13.0) ✓ shipped

The public docs now avoid common directory-style links that MkDocs cannot resolve cleanly in the symlink-farm site build.

Changed

• README badges, language toggles, AGENTS references, skill catalog entries, MCP docs, and integration docs now point to concrete markdown files or public docs URLs.
• Worked examples now use correct relative paths from examples/ into knowledge/, commands/, docs/, and sibling component specs.
• Repository tool references that are intentionally outside the MkDocs docs tree now render as code paths instead of site links.

Impact

• Root index.md / index.ko.md link warnings are 0 in the local MkDocs build.
• Skill directory link INFO messages are 0 in the local MkDocs build.
• MkDocs WARNING lines dropped to 643 in the latest local build, with the remaining noise concentrated in repo-local source references and older launch/i18n materials.

Verified

• All 8 audits pass.
• ./tools/build-docs.sh
• python3 -m mkdocs build --clean
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Real-CI docs output should be easier to inspect because navigation-level false positives are no longer mixed into the warning stream.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Continue targeted coverage only when upstream adds product-relevant primitives.

Phase 58 — MkDocs-safe Ant Design token swatches (v4.13.0) ✓ shipped

The generated Ant Design token reference no longer produces false MkDocs hash-link warnings for preset palette swatches.

Added

• tools/extractors/ant_design_tokens.py --self-test validates seed parsing, preset parsing, swatch rendering, and decorative aria-hidden output.
• npm run tokens:ant-design:self-test exposes the extractor self-test directly.
• npm run release:self-test now includes the Ant Design token extractor self-test.

Changed

• Ant Design preset palette swatches now render as inline decorative HTML instead of ![](#HEX) image links.
• knowledge/design-tokens/ant-design.md was regenerated from the extractor.
• docs/DOGFOOD-V4-MKDOCS-FINDINGS.md now records that the old hex-anchor warning class is fixed.

Impact

• MkDocs no longer emits false internal-anchor messages for Ant Design colors such as #1677FF.
• Remaining docs-build warnings are easier to review because generated color swatch noise is gone.

Verified

• All 8 audits pass.
• python3 -B tools/extractors/ant_design_tokens.py --self-test
• python3 -B tools/extractors/ant_design_tokens.py
• ./tools/build-docs.sh
• python3 -m mkdocs build --clean

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Real-CI docs logs should be more readable when this branch is pushed, because one known generated-warning class has been removed at the source.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Continue targeted coverage only when upstream adds product-relevant primitives.

Phase 57 — Local CI parity self-test coverage (v4.13.0) ✓ shipped

The new local CI parity gate now has its own lightweight self-test and participates in the existing release self-test chain.

Added

• tools/audit/local-ci.py --self-test validates compile-file discovery, markdown line counting, warning threshold behavior, and hard-cap failure handling with temporary fixtures.
• npm run ci:local:self-test exposes the helper self-test directly.
• npm run release:self-test now includes the local CI self-test.

Changed

• local-ci.py now factors Python compile file discovery, markdown line counting, and size budget validation into reusable testable functions.

Impact

• Regressions in the pre-push local parity helper are caught by the fast release self-test path.
• Maintainers can edit ci:local behavior without having to run the full package smoke, VS Code compile, and mkdocs build for every small logic change.

Verified

• All 8 audits pass.
• npm run ci:local:self-test
• npm run release:self-test
• npm run release:metadata
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Local CI parity remains useful as it grows because its cheap logic checks run inside the standard release self-test command.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Continue targeted coverage only when upstream adds product-relevant primitives.

Phase 56 — CI cache hardening + local parity gate (v4.13.0) ✓ shipped

The branch is now better prepared for Real-CI verification: GitHub Actions npm caching points at the actual lockfile, and maintainers have a single local command that exercises workflow-only surfaces before pushing.

Added

• tools/audit/local-ci.py runs the local equivalent of the non-publishing GitHub workflows.
• npm run ci:local wraps release:check, Python syntax checks, knowledge/docs/examples size budget, VS Code extension compile/unit tests, and mkdocs site build.
• README.md, README.ko.md, docs/RELEASE-CHECKLIST.md, docs/DISTRIBUTION.md, and docs/DISTRIBUTION.ko.md document when to use the broader local gate.

Changed

• .github/workflows/audit.yml now sets cache-dependency-path: vscode-extension/package-lock.json for jobs using actions/setup-node npm caching.
• VS Code extension dependency installs in CI now use npm ci --no-audit --no-fund instead of npm install, matching the committed lockfile.

Impact

• A pushed branch should no longer depend on a root package-lock.json that does not exist.
• Local release verification now covers workflow-only checks that release:check intentionally did not run: Python py_compile, size budget, VS Code extension compile/unit tests, and mkdocs build.

Verified

• All 8 audits pass.
• npm run ci:local
• npm run release:metadata
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Real-CI verification can be treated as an external confirmation step after local parity passes, not as the first run of docs or VS Code workflow checks.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Continue targeted coverage only when upstream adds product-relevant primitives.

Phase 55 — Upstream refs refresh + BorderBeam coverage (v4.13.0) ✓ shipped

Fresh upstream refs were pulled, generated knowledge was regenerated, and the newly surfaced Ant Design border-beam canonical received a full worked spec so the corpus stays above the 90% coverage threshold.

Added

• examples/component-border-beam.md documents Ant Design BorderBeam as a decorative emphasis layer with host DOM requirements, portal behavior, aria-hidden, reduced-motion handling, gradient stops, and semantic-state boundaries.
• examples/README.md now lists BorderBeam in the component catalog.
• knowledge/COVERAGE.md now reports 181/200 canonical components with worked specs (90.5%).

Changed

• tools/clone-refs.sh now uses sparse-checkout --skip-checks so the nerd-fonts file path glyphnames.json does not abort refs refresh.
• Generated extractor outputs now preserve version, last_updated, and stability frontmatter when bash tools/extractors/run-all.sh rewrites knowledge files.
• tools/extractors/ui_ux_pro_max.py preserves the local Korean B2B SaaS sensitive-data palette overlay across upstream CSV refreshes.
• knowledge/components/INDEX.md now indexes 200 canonical components, including Ant Design border-beam.
• knowledge/patterns/brand-references.md now indexes 71 brands after upstream added Slack.

Impact

• Coverage remains 90.5% even after the canonical component denominator increases from 199 to 200.
• The quarterly drift baseline is refreshed: 33 components analyzed, 408 total conflicts, 1 CRITICAL, 2 HIGH, 8 MEDIUM, 397 LOW, 0 INFO.
• Re-running the extractor pipeline no longer silently strips versioning metadata from generated knowledge files.

Verified

• All 8 audits pass.
• bash tools/clone-refs.sh
• bash tools/extractors/run-all.sh
• python3 -B tools/extractors/component_spec_conflict_check.py --self-test
• python3 -B tools/extractors/component_spec_conflict_check.py --multi-source --summary-only
• python3 -B tools/audit/check-coverage.py

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Upstream component additions can be absorbed without losing the public 90%+ coverage claim.
• Future refs refreshes are safer because sparse checkout, generated metadata, and local Korean-market overlays are now repeatable.

What's still ahead (4.x — incremental only)

• Real-CI verification (push these workflows; observe green).
• External launch (held).
• Continue targeted coverage only when upstream adds product-relevant primitives.

Phase 54 — Korean maintenance docs audit-count sync (v4.13.0) ✓ shipped

Current Korean contributor and distribution docs now match the actual 8-audit release gate and the summary-first upstream drift workflow added in Phase 53.

Added

• docs/CONTRIBUTING.ko.md now documents npm run audit:strict, all 8 active audits, and the summary-first cross-source API reconciliation flow.
• docs/ARCHITECTURE.ko.md, docs/DISTRIBUTION.ko.md, and docs/QUICKSTART.ko.md now describe the current 8-audit CI/release gate.
• README.md and docs/SESSION-LOG.md now describe the current extractor/audit inventory without stale 7-audit wording.

Impact

• Korean contributors see the same quality gate as English contributors: frontmatter, link, Korean copy, raw hex, integration, stale, coverage, and example QA.
• Release/distribution guidance no longer understates the gate by omitting raw hex hygiene.

Verified

• All 8 audits pass.
• Full verification suite at close-out:
• python3 -B tools/audit/run-all.py --strict
• npm test
• npm run package:check
• npm run release:metadata
• npm run release:self-test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Korean-language maintenance docs can be used as the source of truth for PR prep instead of sending contributors back to English docs for current audit details.
• Future audit additions have a clearer set of current docs to update in one pass.

What's still ahead (4.x — incremental only)

• Run the quarterly upstream drift review after the next refs/ refresh and document the result.
• Real-CI verification (push these workflows; observe green).
• External launch (held).

Phase 53 — Upstream drift review ergonomics (v4.13.0) ✓ shipped

Quarterly upstream review now starts with a short risk summary before maintainers open the full cross-source conflict report. This keeps the drift workflow usable after crossing 90% component coverage.

Added

• tools/extractors/component_spec_conflict_check.py --summary-only suppresses per-component details and prints aggregate severity counts.
• tools/extractors/component_spec_conflict_check.py --self-test validates CRITICAL / HIGH / MEDIUM / LOW classification and summary rendering without requiring refs parsing.
• docs/CONTRIBUTING.md now documents the summary-first quarterly review flow.

Impact

• Current multi-source drift baseline remains explicit: 33 components analyzed, 413 total conflicts, 1 CRITICAL, 2 HIGH, 7 MEDIUM, 403 LOW, 0 INFO.
• Maintainers can quickly decide whether a refs refresh introduced new HIGH/CRITICAL risk before reading the full report.

Verified

• All 8 audits pass.
• python3 -B tools/extractors/component_spec_conflict_check.py --self-test
• python3 -B tools/extractors/component_spec_conflict_check.py --multi-source --summary-only
• Full verification suite at close-out:
• python3 -B tools/audit/run-all.py --strict
• npm test
• npm run package:check
• npm run release:metadata
• npm run release:self-test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Drift review becomes a fast triage gate first, then a detailed reconciliation task only when severity counts justify deeper work.
• Future provider/utility specs can be kept aligned with upstream without asking maintainers to parse hundreds of LOW library-specific differences every time.

What's still ahead (4.x — incremental only)

• Run the quarterly upstream drift review after the next refs/ refresh and document the result.
• Real-CI verification (push these workflows; observe green).
• External launch (held).

Phase 52 — Coverage 90% utility specs (v4.13.0) ✓ shipped

The corpus crossed the 90% canonical component coverage milestone by documenting three foundational utility/provider primitives that are useful to real design-system authors.

Added

• examples/component-button-base.md — low-level interactive primitive spec covering semantics, focus-visible handling, ripple boundaries, disabled behavior, and polymorphic root risks.
• examples/component-css-baseline.md — root global baseline spec covering reset ownership, body typography, color-scheme, print behavior, SSR ordering, and microfrontend boundaries.
• examples/component-config-provider.md — app-level provider spec covering theme, locale, direction, component defaults, portal containers, CSP, static APIs, and Korean product shell concerns.
• examples/README.md now exposes all three specs in the component catalog.

Impact

• Component spec coverage: 177/199 (88.9%) → 180/199 (90.5%).
• The remaining gap is now mostly low-level internals, registry metadata, and utility types rather than common product-facing primitives.

Verified

• All 8 audits pass.
• python3 -B tools/audit/check-coverage.py
• Full verification suite at close-out:
• python3 -B tools/audit/run-all.py --strict
• npm test
• npm run package:check
• npm run release:metadata
• npm run release:self-test
• git diff --check

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• The public corpus now has 90%+ canonical component coverage with no DRAFT banners, so adopter workflows can rely on polished specs for nearly all common primitives.
• Future coverage work can be selective: document only utility/provider entries that reduce real implementation ambiguity.

What's still ahead (4.x — incremental only)

• Quarterly upstream drift review for polished thin specs and provider primitives.
• Real-CI verification (push these workflows; observe green).
• External launch (held).

Phase 51 — Coverage alias accounting (v4.13.0) ✓ shipped

Coverage accounting now recognizes canonical components already covered by parent/alias specs. This moves component spec coverage from 161/199 (80.9%) to 177/199 (88.9%) without creating duplicate thin docs.

Added

• tools/audit/check-coverage.py has an explicit COVERAGE_ALIASES map for parent-covered subcomponents and naming aliases.
• knowledge/COVERAGE.md now separates direct canonical spec matches from parent/alias coverage.

Alias coverage recognized (16)

• Navigation/actions: bottom-navigation-action, card-action-area, speed-dial-icon.
• Layout/media: row, col, image-list-item, image-list-item-bar.
• Forms/lists: input-label, input-group, native-select, list-item-secondary-action.
• Data/controls: pagination-item, table-pagination-actions, toggle-group.
• Aliases/primitives: qrcode, svg-icon.

Verified

• All 8 audits pass.
• python3 -B tools/audit/check-coverage.py --self-test
• python3 -B tools/audit/check-coverage.py

Versions

• package.json + .claude-plugin/plugin.json: remains 4.13.0.

What this enables

• Coverage reports now distinguish missing specs from canonical entries already covered by parent component docs.
• The remaining path to 90% is narrowed to true utility/provider primitives instead of duplicate sub-component files.

What's still ahead (4.x — incremental only)

• Coverage 90%+ maintenance, with future additions focused on genuinely useful provider/utility docs rather than duplicate sub-component files.
• Quarterly upstream drift review for polished thin specs.
• Real-CI verification (push these workflows; observe green).
• External launch (held).

Phase 50 — DRAFT closure + reconciliation auto-apply (v4.13.0) ✓ shipped

22 DRAFT → 0 DRAFT. 22 polished. 9 families now 100% polished (Form / List / Dialog / Card / Menu / Inputs / Tabs / Steps / Accordion).

Polished (22)

• Input family: input-base (39 props), filled-input, input-adornment.
• Table family: table-cell, -body, -head, -pagination, -container, -footer, -sort-label.
• Step family: step-icon, -label, -content.
• Misc: snackbar-content, alert-title.
• Final thin sub-components: accordion-actions, accordion-details, accordion-summary, avatar-group, step-button, step-connector, tab-scroll-button.

Final DRAFT closure (7)

• 3 accordion subs now cover summary button semantics, disclosed body regions, and scoped action rows.
• 4 thin sub-components now cover minimal API surfaces, parent-derived state, accessibility boundaries, edge cases, and token usage.

Added

• component_spec_reconcile.py --apply-high updates existing API table rows for HIGH-confidence proposals only.
• --dry-run previews changes; --multi-source --apply-high requires --force before writing broadly.
• Auto-apply skips missing prop rows and leaves MEDIUM/MANUAL proposals for human review.
• raw-hex-check.py blocks new non-allowlisted examples/ raw hex colors so component specs stay token-alias-first.

Versions

• package.json + .claude-plugin/plugin.json: 4.12.0 → 4.13.0.

Verified

• All 8 audits pass.
• Reconciliation auto-apply self-test covers polished and scaffolded API table formats.
• Raw hex audit self-test covers token violations, allowlisted fixtures, line-level exceptions, CSS anchors, and order-number false positives.
• 22 new fully-polished specs follow established template.
• 3 cross-ref corrections (component-stepper.md → component-steps.md).

What this enables

• Release candidates can focus on distribution confidence instead of unresolved DRAFT-spec uncertainty.
• HIGH-confidence upstream reconciliation can be applied mechanically without rewriting component narratives.
• New component examples now fail CI if they hardcode raw hex colors instead of semantic token aliases.
• Component examples no longer contain v2 scaffold DRAFT banners.

What's still ahead at Phase 50 close

• Quarterly upstream drift review for polished thin specs.
• Coverage 80.9% → 90% (utility types — diminishing value).
• Real-CI verification (push these workflows; observe green).
• External launch (held).

Phase 49 — Extractor v3 reconciliation mode (v4.12.0) ✓ shipped

v3 detected drift; reconciliation mode now proposes unified-API resolutions. Closes the loop on cross-source maintenance.

Added

• tools/extractors/component_spec_reconcile.py — proposes unified API per component. 3-axis reconciliation (type / default / deprecation). Confidence: HIGH / MEDIUM / LOW / MANUAL. Migration notes for deprecation drift + library-specific props.
• docs/CONTRIBUTING.md — quarterly upstream-review 6-step workflow.

Verified

• 33 multi-source canonicals: 3 HIGH, 411 MEDIUM, 1 MANUAL (Switch.value boolean vs unknown — same one v3 flagged CRITICAL).
• Migration notes correctly route deprecation drift (Alert.closeText, Alert.onClose).
• Library-specific props classified MEDIUM with explicit adoption guidance.

Versions

• package.json + .claude-plugin/plugin.json: 4.11.0 → 4.12.0.

What this enables

• Quarterly upstream review becomes a 6-step ritual instead of an open-ended task.
• HIGH-confidence proposals can be auto-adopted by future tooling.
• MANUAL items concentrate human attention on real design calls (1 currently).
• Migration notes preserve adopter context across version transitions.

What's still ahead

• Polish remaining ~24 v2-DRAFT specs (incremental).
• Coverage 80.9% → 90% (utility types — diminishing value).
• Real-CI verification.
• v3 reconciliation auto-apply mode (HIGH-confidence proposals → spec edits).
• External launch (held).

Phase 48 — CI wiring (v4.11.0) ✓ shipped

The infrastructure from v4.3–v4.10 (unit tests / audit runner / e2e tests / conflict checker) wasn't being used by CI. v4.11 wires it all in.

Changed

• .github/workflows/audit.yml — 1 job → 4 jobs:
• audit: uses run-all.py (was 5 separate steps).
• unit-tests (NEW): runs CLI + VS Code lib unit tests (41 total).
• vscode-e2e (NEW): real VS Code instance under xvfb; gated to push-main or PR label.
• conflict-check (NEW): cross-source API drift; informational on push-main.
• .github/workflows/publish.yml — uses run-all.py --strict + adds unit-tests step.
• package.json + .claude-plugin/plugin.json: 4.10.0 → 4.11.0.

Verified

• All 4 workflows parse as valid YAML.
• All workflow commands execute locally.
• 6 audits + 41 unit tests + size budget all run via the new pipeline.

CI matrix

Trigger	Runs
PR	audit + unit-tests
PR + test:e2e label	+ vscode-e2e
push main	audit (--strict) + unit-tests + vscode-e2e + conflict-check
tag v*	audit (--strict) + unit-tests + npm pack + publish

What's still ahead

• Polish remaining ~24 v2-DRAFT specs (incremental).
• Coverage 80.9% → 90% (utility types — diminishing value).
• Real-CI verification (push these workflows; observe them green).
• v3 extractor reconciliation mode (auto-suggest unified API for HIGH conflicts).
• External launch (held).

Phases 45-47 — VS Code e2e + extractor v3 + SESSION-LOG (v4.10.0) ✓ shipped

Three independent threads in one release.

Phase 45 — VS Code @vscode/test-electron integration

• 8 e2e tests: activation, command registration (10/10), settings readability, view container, status/refresh/openSettings.
• Runs inside a real VS Code instance (downloaded ~300MB on first run, cached).
• Compiles cleanly; not exercised in this session due to download cost.

Phase 46 — SESSION-LOG comprehensive update

• At-a-glance table extended to v4.10 (3 columns).
• Phase log extended through v4.10 (v4.0 stable → v4.10 e2e).
• Patterns refactored: 2 new v4-era patterns (Dogfood drives next-pass quality, Honest DRAFTs > false completeness) + 1 anti-pattern (audit false negatives).

Phase 47 — Component spec extractor v3 (conflict detection)

• Cross-source conflict report: CRITICAL / HIGH / MEDIUM / LOW / INFO severity.
• Smart filtering: strips | undefined from type comparison; skips standard HTML props.
• First-pass scan of 33 multi-source canonicals: 1 CRITICAL (Switch.value), 2 HIGH (deprecation drift), 7 MEDIUM, 403 LOW (legitimate vendor specifics like Ant's autoInsertSpace for Korean).

Versions

• package.json + .claude-plugin/plugin.json: 4.9.0 → 4.10.0.
• vscode-extension/package.json: 0.3.0 → 0.4.0.

Verified

• All 6 audits pass.
• 25 VS Code unit + 16 CLI unit tests pass.
• VS Code .vsix builds cleanly.
• Conflict check runs end-to-end on 33 components.

What this enables

• VS Code regression coverage in CI (when set up).
• API drift visibility — --strict can gate PRs.
• Adopter switching guidance — the LOW conflict list tells adopters what they lose by switching libraries.

What's still ahead

• Polish remaining ~24 v2-DRAFT specs (incremental).
• Coverage 80.9% → 90%+ (mostly utility types — diminishing value).
• Real-VS-Code test run + CI matrix wiring (xvfb-run on Linux).
• v3 extractor "auto-suggest reconciliation" mode (for HIGH conflicts, propose unified API).
• External launch (held).

Phases 43-44 — Polish + coverage 80.9% (v4.9.0) ✓ shipped

Two phases combined: full polish on 18 of 21 DRAFT specs from v4.5/v4.7 (Phase 43) + coverage 68.8% → 80.9% with 24 new specs (Phase 44).

Phase 43 — DRAFT polish

• 18 fully polished specs (Dialog parent, Stack, 5 List subs, 4 Form subs, 2 Card subs, MenuList, ToggleButton, MobileStepper, InputNumber, DialogContentText).
• 3 intentionally left as DRAFT (accordion sub-components — rarely standalone).
• Cross-ref corrections (broken paths from polished specs fixed).

Phase 44 — Coverage push

• 24 new specs (5 polished, 19 v2 drafts).
• Polished: Fade, Grow, Tab, OutlinedInput, TableRow.
• Drafts: 19 across Transitions / Inputs / Tables / Steps / Misc families.
• Filled coverage gaps surfaced during the polish (TableCell + InputAdornment generated mid-phase to satisfy cross-refs from polished specs).

Versions

• package.json + .claude-plugin/plugin.json: 4.8.0 → 4.9.0.

Verified

• All 6 audits pass.
• Coverage: 137 → 161 of 199 (68.8% → 80.9%) — exceeded 80% target.
• 26 new fully-polished specs.
• 3 accordion drafts retain honest DRAFT banner.

Coverage milestone

80%+ canonical coverage. Every flagship MUI primitive is covered. Remaining 20% is mostly utility types (use-lazy-ripple, class-name, direction, theme) + edge primitives (overridable-component, _registry).

What's still ahead

• Phase 45: VS Code real-instance tests (@vscode/test-electron).
• Phase 46: SESSION-LOG v4 update (full v2 → v4.9 narrative).
• Phase 47: Component spec extractor v3 (cross-source conflict detection).
• Polish remaining ~24 drafts (incremental).
• Coverage 80.9% → 90% (low-priority utility types).

Phases 40-42 — Three-surface dogfood (v4.8.0) ✓ shipped

VS Code extension + npm distribution + mkdocs site build — three surfaces v4.7 explicitly didn't validate. All three exercised end-to-end; each surfaced real bugs that were fixed.

Phase 40 — VS Code extension dogfood

• Findings: docs/DOGFOOD-V4-VSCODE-FINDINGS.md.
• Extracted pure logic to vscode-extension/src/lib.ts (8 helpers, 230 LOC).
• 25 unit tests against shipped JS — including a real bug: search preview lost the matched word past column 120. Fixed via buildPreview() that centers on the match.
• Generated media/icon.png (was referenced but missing → vsce package failed).
• Excluded test/ from .vsix (was leaking into shipped package).
• Verified: 10/10 commands match between manifest and impl. tsc clean. .vsix 19.65 KB, 13 files.

Phase 41 — npm fresh install dogfood

• Findings: docs/DOGFOOD-V4-NPM-FINDINGS.md.
• Full lifecycle: pack → install in mktemp → version/help/list/install/status/uninstall against fake CLAUDE_HOME.
• Surfaced: tools/migrations/ not in npm allowlist — /stability-review slash command pointed adopters to scripts that weren't shipped. Fixed.
• Verified: 39 symlinks created (19 skills + 4 agents + 16 commands), all cleaned up on uninstall, sub-second install. PATH bin works.

Phase 42 — mkdocs site build dogfood

• Findings: docs/DOGFOOD-V4-MKDOCS-FINDINGS.md.
• Found and fixed false-negative in link-check.py: regex required ≥1 char of link text, but inline-code-strip pre-pass converted backtick-wrapped link patterns to empty-text links, masking ALL backtick-wrapped link references. Changed + → *.
• 11 real broken links surfaced after the fix — all fixed.
• Two missing primitive specs surfaced (component-dialog.md, component-stack.md — flagship MUI primitives that v4.5 family-completion claimed were shipped but weren't). Generated via v2 extractor.
• Disabled navigation.instant in mkdocs.yml (incompatible with mkdocs-static-i18n contextual switcher).
• Verified: 782 HTML pages, 15.84 s build, both languages render, all v4.x docs included.

Versions

• package.json + .claude-plugin/plugin.json: 4.7.0 → 4.8.0.
• vscode-extension/package.json: 0.2.0 → 0.3.0.

What this validates

• VS Code extension code shape + shippability.
• npm distribution + fresh-machine install lifecycle.
• Doc site builds cleanly with bilingual routing.
• Audit infrastructure (link-check now catches the previously-silent class of broken backtick links).

What's still ahead

• VS Code extension under real IDE (@vscode/test-electron future).
• npm publish flow (push to actual registry — deferred to launch).
• GitHub Pages deployment of doc site.
• Polish remaining drafts (now including dialog + stack from this dogfood).
• Coverage push 68.8% → 80%.

Phase 39 — Dogfood v4 + 5 fixes (v4.7.0) ✓ shipped

End-to-end practical test on Korean B2B HR onboarding scenario. v4.0/4.5/4.6 capabilities exercised in a real flow; 5 actionable gaps surfaced and fixed in the same commit.

Added

• examples/cases/dogfood-v4-korean-hr-onboarding.md — real deliverable: tokens → EmployeeInfoForm → Card + Dialog upload flow → UX audit → stability review.
• docs/DOGFOOD-V4-FINDINGS.md — self-critique. v3-vs-v4 time comparison: 3-5x faster on form/dialog/list-heavy work.
• examples/component-loading-button.md (Fix 1) — polished pattern spec.
• knowledge/patterns/b2b-onboarding-flows.md (Fix 3) — B2B onboarding-specific knowledge.
• Palette row 162 (Fix 4) — Korean B2B SaaS sensitive-data palette.

Changed

• tools/audit/stability-review.py (Fix 2) — skip generated artifacts (COVERAGE.md).
• tools/extractors/component_spec_scaffold_v2.py (Fix 5) — banner clarifies API table is AST-extracted and trustworthy.
• Versions: 4.6.0 → 4.7.0.

Verified

• All 6 audits pass.
• Dogfood deliverable + findings cite real specs and knowledge.
• v3 vs v4 time comparison: 3-5x faster on form/dialog/list work.

What v4 validated

• v4.0 graduation correct — 8 stable surfaces held up.
• v4.5 family completion right call — form/dialog/list specs paid off.
• v4.6 stability automation works — false positive surfaced and fixed.

What v4 did NOT validate (future)

• VS Code extension under real adopter load.
• npm install on fresh machine.
• Multi-language doc site rendering since v3.12.

These belong in a separate install / e2e test pass.

What's still ahead (4.x)

• VS Code extension dogfood test.
• npm fresh-install test.
• Doc site mkdocs build verification.
• Coverage push 68.8% → 80% (transitions, table sub-components).
• Polish remaining 21 v4.5 drafts.

Phase 38 — Stability re-review automation (v4.6.0) ✓ shipped

Operationalizes the quarterly stability review ritual. Until now, a manual step described in RELEASE-CHECKLIST. Now: report + 2 bulk tools + slash command + CONTRIBUTING walkthrough.

Added

• tools/audit/stability-review.py — quarterly report generator. Sections: summary, promotion candidates (exp/beta → stable), stale stable files, deprecated review, missing-metadata files, ritual checklist.
• tools/migrations/promote-stability.py — bulk stability: field promote/demote with --from enforcement + --dry-run + atomic write.
• tools/migrations/bump-last-updated.py — bulk last_updated: refresh with --dry-run. Idempotent.
• commands/stability-review.md — slash command /stability-review. Runs report, summarizes inline, suggests next bulk op with confirmation gate.
• docs/CONTRIBUTING.md "Quarterly stability review" — full 5-step ritual.

Changed

• .claude-plugin/plugin.json — registered 16^th command.
• Description strings across 3 manifests: "15 commands" → "16 commands".
• Versions: 4.5.0 → 4.6.0.

Verified

• All 6 audits pass.
• Stability review: 90 stable, 0 beta/experimental/deprecated, 1 file without metadata (knowledge/COVERAGE.md, generated artifact — intentional).
• Promote tool dry-run validates --from before mutating.
• Bump tool dry-run idempotent.
• Slash command file passes frontmatter + verification-phase checks.

Workflow (per quarter)

1. python3 tools/audit/stability-review.py --output docs/STABILITY-REVIEW.md
2. Walk the report; decide per file.
3. Apply via promote-stability.py / bump-last-updated.py.
4. Document outcome in CHANGELOG.
5. Commit.

Or /stability-review in Claude Code.

What this enables

• Knowledge freshness becomes routine, not a vague aspiration.
• Stability promotions happen on cadence; beta / experimental don't pile up.
• Deprecated files are surfaced every quarter until removed.
• Ritual discoverable in Claude Code via slash command.

What's still ahead (4.x)

• Polish remaining 21 v4.5 drafts.
• Coverage push 68.8% → 80% (transitions, table sub-components).
• Semantic search index (Algolia / Typesense).
• Dispatch / commands integration tests.
• Component spec extractor v3 (cross-source intersection — flag prop names/types that conflict between Ant and MUI).
• VS Code marketplace publish (when external launch happens).

Phase 37 — Coverage push 55% → 68.8% (v4.5.0) ✓ shipped

First coverage push using v2 extractor. Crosses ⅔ canonical coverage. Family-completion focus on the primitives Korean B2B / fintech UIs lean on most.

Added — 27 new specs (110 → 137 of 199)

• 6 fully polished (real spec style, not draft): list-item, menu-item, dialog-title, dialog-content, dialog-actions, card-content, card-actions, form-control.
• 21 v2-extracted drafts with DRAFT banner + accurate API table + placeholder narrative:
• List family (5): list-item-button / -icon / -text / -avatar, list-subheader.
• Form family (4): form-control-label, form-group, form-helper-text, form-label.
• Card family (2): card-header, card-media.
• Dialog family (1): dialog-content-text.
• Accordion family (3): accordion-actions / -details / -summary.
• Menu (1): menu-list.
• Standalone (2): toggle-button, mobile-stepper.
• From v4.4: input-number.

Changed

• tools/extractors/component_spec_scaffold_v2.py find_mui_source — fall back to .d.ts (MUI ships compiled JS + types). Unlocks AST extraction for all MUI sub-components.
• package.json + .claude-plugin/plugin.json: 4.4.0 → 4.5.0.

Verified

• All 6 audits pass.
• Coverage: 110 → 137 (55.3% → 68.8%).
• 6 polished specs follow established sub-component style.
• 21 drafts retain honest "DRAFT — scaffolded via TS-AST" banner.

Coverage check by family

Family	Status
Form (FormControl + 4 sub-roles)	complete
List (ListItem + 5 sub-roles)	complete
Dialog (Title / Content / Actions / ContentText)	complete
Card (Content / Actions / Header / Media)	complete
Accordion (Actions / Details / Summary)	complete
Menu (Item / List)	complete
Transitions (Fade / Grow / Zoom / Slide)	partial
Sub-components / utility types	thin (intentional)

Why honest drafts vs polished for all 27

v2 produces accurate API + structure but placeholder narrative. 6 flagship sub-components got full polish; remaining 21 retain DRAFT banner. False completeness > honest "in progress" — the banner tells reviewers what's still pending.

What this enables

• Family-completion: designers find all sub-roles together.
• Real-world Korean fintech UIs covered (List + Form + Dialog + Card).
• v2 extractor validated end-to-end (27 in one pass, zero parser bugs).

What's still ahead (4.x)

• Stability re-review automation (Phase 38).
• Polish remaining 21 v4.5 drafts (incremental, as user feedback comes in).
• Coverage push 68.8% → 80% (transitions, more table sub-components).
• Semantic search index.
• VS Code marketplace publish.

Phase 36 — Component spec extractor v2 (v4.4.0) ✓ shipped

TypeScript AST parsing replaces regex. The v2 extractor produces noticeably cleaner drafts and unlocks faster coverage pushes (Phase 37).

Added

• tools/extractors/ts-ast/parse-component.mjs — Node.js parser using TS Compiler API. AST walk covers interfaces, type aliases, components (function / arrow / forwardRef / memo), destructured defaults, JSDoc tags (@deprecated, @default, @since).
• tools/extractors/ts-ast/package.json — local dev package (typescript dep). Not shipped via npm.
• tools/extractors/component_spec_scaffold_v2.py — Python wrapper. Invokes parser, picks primary *Props interface, merges across Ant + MUI + shadcn with per-prop provenance, separates events, surfaces deprecated.

Changed

• package.json + .claude-plugin/plugin.json: 4.3.0 → 4.4.0.

Verified

• Parser correctly handles: Ant Button (deprecated iconPosition flagged), shadcn Button (intersection type + 3 destructured defaults), MUI components.
• v2 produced clean draft for input-number (14 props, 3 auto-flagged deprecated).
• 6 audits pass; 16 CLI unit tests pass.

v1 → v2 capability gain

Capability	v1 (regex)	v2 (AST)
Generic Props<T>	✗	✓
extends chains	✗	✓
Intersection types	partial	✓
Destructured defaults	✗	✓
@deprecated JSDoc	✗	✓
Event handler grouping	mixed	separate
Per-prop provenance	first-source	all sources

What this enables

• Coverage push 55→70% (Phase 37) becomes practical — drafts require less cleanup.
• Reviewer sees "prop X exists in Ant+MUI but not shadcn" at a glance.
• Deprecated props auto-surface for review.

What's still ahead (4.x)

• Coverage push 55% → 65% using v2 (Phase 37).
• Stability re-review automation (Phase 38).
• Semantic search index.
• Dispatch / commands integration tests.
• VS Code marketplace publish.

Phase 35 — Internal completeness (v4.3.0) ✓ shipped

Tightens internal quality. Pure dogfooding work — no new content, but the corpus and tooling are now more consistent and testable.

Added

• tools/audit/run-all.py — unified runner for all 6 audits. ~0.8s end-to-end. --strict for CI, --quiet for minimal output.
• CLI unit tests — 16 tests across cli/lib/paths.test.mjs + cli/lib/log.test.mjs. Covers path resolution, file/dir checks, color helpers in NO_COLOR mode. Uses node --test (Node 18+ built-in).
• VS Code extension design-ai.openReadme — language-aware README opener.
• VS Code extension design-ai.search — corpus-wide markdown search with jump-to-line.

Changed

• tools/audit/check-coverage.py — verification phase check tightened. Strict: canonical ## Verification phase heading. Loose-only cases surfaced separately for nudging.
• skills/figma-token-sync/PLAYBOOK.md — ### 7. Verification phase → ## Verification phase (run before declaring done).
• skills/slide-deck-author/PLAYBOOK.md — same standardization.
• VS Code extension design-ai.openWalkthrough — language-aware. Prefers .ko.md when design-ai.language: ko; quick-pick shows [KO] / [EN] tags.
• VS Code extension design-ai.status — Korean labels when design-ai.language: ko.
• VS Code extension commands.ts — extracted readManifest() + PluginManifest interface. Removed unused child_process import.
• vscode-extension/package.json — extension version 0.1.0 → 0.2.0. New commands registered.
• package.json scripts — npm test runs CLI tests; npm run audit uses unified runner; npm run audit:strict for CI.
• package.json + .claude-plugin/plugin.json: 4.2.0 → 4.3.0.

Verified

• All 6 audits pass via unified runner (0.81s).
• 16 CLI unit tests pass.
• VS Code extension compiles cleanly (tsc --noEmit zero errors).
• All 19 skills use canonical ## Verification phase heading.

What this enables

• One-command quality gate (npm run audit).
• First test-backed CLI helpers — foundation for further test growth.
• Language-aware VS Code experience for KR adopters.
• Searchable corpus from inside VS Code.
• Skill heading consistency — future audits can hard-fail on non-canonical formats.

What's still ahead (4.x)

• Coverage push 55% → 70%.
• Component spec extractor v2 (TS AST parsing).
• Semantic search index (Algolia / Typesense) — externally hosted, complements VS Code in-tree search.
• Dispatch / commands integration tests (currently only pure-logic helpers tested).
• VS Code marketplace publish (1.0.0).
• Stability re-review ritual (quarterly stale-check at warn-months 3).
• Homebrew formula refresh post-tag.

Phase 34 — Launch kit (v4.2.0) ✓ shipped

Ready-to-post announcement materials. Drafts only — posting is owner action. Each draft uses the voice/length its channel rewards.

Added — docs/announcements/ (7 drafts + index)

• README.md — index, posting order, tracking template, channel tone matrix.
• press-kit.md — one-liner / stats card / origin narrative / FAQ (EN + KO).
• show-hn.md — Show HN title alts + body + reply-prep for likely questions.
• okky-post.ko.md — OKKY long-form (해요체, ~600 words, KR adoption focus).
• hashnode-post.ko.md — hashnode blog (해요체, ~800 words, retrospective tone).
• dev-to-korea.md — dev.to (EN + bilingual examples, ~600 words).
• twitter-thread.md — parallel EN + KO threads (8 tweets each).
• reddit-r-korea.md — r/programming + r/korea + r/ClaudeAI with rule notes per sub.

Changed

• package.json + .claude-plugin/plugin.json: 4.1.0 → 4.2.0.

Verified

• All 6 audits pass.
• KR drafts in natural Korean (no auto-translation).

Posting cadence (suggested)

• Day 1: HN + dev.to.
• Day 2: r/programming.
• Day 3: r/korea + r/ClaudeAI.
• Day 4-7: OKKY + hashnode + Twitter threads (EN + KO 2hr offset).
• Track in docs/announcements/posted.md.

What this enables

• Owner pushes v4.0 tag → verifies CI publish → posts in any order without last-minute writing.
• Channel-tailored tone per draft — lower friction for owner, higher engagement per channel.
• Press kit reusable for v4.1 / v5.0 releases.

What's still ahead (4.x)

• VS Code marketplace publish (1.0.0).
• Coverage push 55% → 70%.
• Component spec extractor v2 (TS AST).
• Semantic search index (Algolia / Typesense).
• Stability re-review ritual (quarterly stale-check at warn-months 3).
• Homebrew formula refresh post-tag.

Phase 33 — Korean adopter / contributor docs (v4.1.0) ✓ shipped

First 4.x minor. Continues v3.6 / v3.10 KR i18n investment. Three foundational docs previously English-only are now Korean-native.

Added

• docs/USING.ko.md — 사용자 가이드 (5개 도구 통합, 토큰 예산, KR 컨텍스트 표).
• docs/CONTRIBUTING.ko.md — 기여 가이드 (스킬 / 에이전트 / 커맨드 추가, 버전 메타데이터, 한국어 톤 가이드, 6개 감사, PR 플로).
• docs/ARCHITECTURE.ko.md — 아키텍처 (4 계층 다이어그램, 계약, 6개 감사 표, 4개 배포 채널).

Changed

• mkdocs.yml — nav_translations에 사용 가이드 / 기여 가이드 추가. docs_structure: suffix로 .ko.md 자동 매핑.
• package.json + .claude-plugin/plugin.json: 4.0.0 → 4.1.0.

Verified

• All 6 audits pass.
• Korean copy check now scans 29 files (was 26).

Translation approach

• 사용자 / 기여자 대상: 해요체 (친근).
• 아키텍처 / 기술 문서: 중립적 톤 (해요체 유지하되 설명형).
• 코드 / 명령어: 영문 유지.
• 기술 용어 (API, frontmatter): 영문이 자연스러우면 영문.
• 한국 브랜드 / 컨벤션: 한국어 유지.

What this enables

• Korean adopters can sense-check (USING.ko, ARCHITECTURE.ko) before adopting.
• Korean contributors can follow the contribution flow without English friction.
• KR community announcement materials can link to Korean-native docs.

Korean docs coverage now

Doc	EN	KO
README	✓	✓ (v3.6)
QUICKSTART	✓	✓ (v3.6)
AGENTS	✓	✓ (v3.6)
DISTRIBUTION	✓	✓ (v3.6)
USING	✓	✓ (v4.1)
CONTRIBUTING	✓	✓ (v4.1)
ARCHITECTURE	✓	✓ (v4.1)
5 integration walkthroughs	✓	✓ (v3.10)
8 KR-specific knowledge files	✓	KR-native already

Foundational doc set: now fully bilingual.

Phase 32 — Stable (v4.0.0) ✓ shipped

Graduation release. No code changes from v3.12.0 — this phase promotes the corpus to stable, codifies the API surface, and commits to a deprecation policy. The major bump signals to adopters: design-ai is no longer a moving target.

Added

• docs/MIGRATION-v4.md — graduation migration guide:
• TL;DR: no code changes required.
• What v4.0 promises (8 surfaces: knowledge / skills / commands / agents / CLI / plugin / VS Code / doc site).
• What v4.0 does NOT promise (content evolution still expected).
• Stability levels recap.
• Deprecation policy: deprecate in 4.x → maintain in 4.x → remove in 5.0.
• Upgrade instructions per channel (npm / git / Homebrew / VS Code).
• Verification commands.

Changed

• package.json + .claude-plugin/plugin.json: 3.12.0 → 4.0.0.

Verified (RELEASE-CHECKLIST.md run)

• All 6 audits pass (frontmatter / link / Korean copy / coverage / integration-check / stale-check).
• Version alignment: package.json + plugin.json + CHANGELOG.md top entry all match.
• CLI smoke test: version / help / status / list skills clean.
• npm pack --dry-run: tarball within budget; allowlist correct.
• Doc site builds.
• VS Code extension compiles.

Deprecation policy (effective from v4.0)

Anything publicly documented (skills, commands, CLI flags, plugin fields, knowledge file IDs) follows:

1. Deprecate in 4.x: Mark deprecated: true (or stability: deprecated for knowledge); update docs; log warning.
2. Maintain in 4.x: All deprecated surfaces keep working through the 4.x line.
3. Remove in 5.0: Only at next major.

Adopters always get one full minor cycle of warnings.

The journey (v2.0 → v4.0)

Surface	v2.0	v4.0
Knowledge files	55	91
Worked examples	83	160
Skills	12	19
Slash commands	8	15
Review agents	4	4
Component coverage	~24%	55.3%
Distribution channels	1	4
Integration walkthroughs	0	5 (EN + KO)
Site languages	0	2
CI audits	4	6

What's still ahead (4.x)

• KR tech community announcement (OKKY, hashnode.kr, dev.to/korea).
• VS Code marketplace publish (1.0.0).
• Homebrew formula refresh post-tag (sha256 + version).
• Coverage push 55% → 70%.
• More Korean translations (CONTRIBUTING.ko.md, ARCHITECTURE.ko.md, USING.ko.md).
• Semantic search index (Algolia / Typesense).
• Component spec extractor v2 (TS AST parsing).
• Stability re-review ritual (quarterly cycle defined in RELEASE-CHECKLIST.md).

Phase 31 — Release readiness (v3.12) ✓ shipped

Closes the v3.x arc. Operationalizes the versioned frontmatter from v3.11 with a stale-content audit, codifies the pre-release ritual, and narrates the journey for adopters / contributors / future maintainers.

Added

• tools/audit/stale-check.py — flags knowledge files whose last_updated is too old:
• Default thresholds: warn at 6 months, error at 12 months.
• Configurable via --warn-months / --error-months.
• --strict exits 1 on stale (for CI).
• --today YYYY-MM-DD for testing.
• Files without last_updated are skipped (backward-compatible).
• Treats YYYY-MM as last day of month (most generous reading).
• docs/RELEASE-CHECKLIST.md — pre-release ritual:
• 11 main sections: audits / version alignment / CHANGELOG / ROADMAP / CLI smoke test / NPM preview / doc site build / VS Code build / Korean copy spot-check / tag and push / post-tag.
• Major-version add-ons: migration guide / announcement template / stability re-review.
• Channel-specific: VS Code marketplace publish (vsce), Homebrew formula update (shasum -a 256).
• Common failure modes table (8 symptoms → causes → fixes).
• Stability promotion ritual (quarterly review cycle).
• docs/SESSION-LOG.md — single-page narrative v2.0 → v3.12:
• At-a-glance metrics table (knowledge / examples / skills / commands / coverage / channels / languages / audits).
• The arc: foundation → domain expansion → distribution → coverage acceleration → VS Code → Korean depth → release readiness.
• Phase log v2.1 → v3.12 (20 phases).
• Patterns that worked / didn't.
• Repo structure.

Changed

• .github/workflows/audit.yml — added stale-content audit step:
• Strict mode (--strict) on push to main (CI fails on ≥12-month-stale files).
• Warn-only on PRs (so contributors can see warnings without blocking).
• package.json + .claude-plugin/plugin.json: 3.11.0 → 3.12.0.

Verified

• All 6 audits pass (frontmatter / link / Korean copy / coverage / integration-check / stale-check).
• Stale-check output: "Fresh (≤ 6 months): 90, Skipped (no last_updated): 1, Total knowledge files: 91, All knowledge files within freshness window ✓".
• Stale-check tested with --today 2027-08-15 — correctly flagged 75 files as 15 months stale (would fail CI under --strict).

Audits — now 6

#	Script	Purpose
1	frontmatter-check.py	YAML frontmatter validity + version field shape
2	link-check.py	Internal link resolution
3	korean-copy-check.py	Korean voice / register / typography
4	check-coverage.py	Component coverage report
5	integration-check.py	Integration walkthrough completeness
6	stale-check.py	Knowledge freshness (last_updated thresholds)

What this enables

• Confident releases — RELEASE-CHECKLIST.md codifies the pre-tag ritual; nothing slips through.
• Continuous freshness — stale-check runs on every push to main; surfaces files that need review before they rot.
• Project narrative — adopters / contributors can read SESSION-LOG.md to understand the arc.
• v4.0 readiness — design-ai is now versioned, audited, distributed (4 channels), localized (EN + KO), release-checklisted.

What's still ahead (v4.0+)

• Tag v4.0.0 stable.
• VS Code marketplace publication (1.0.0).
• KR tech community announcement (OKKY, hashnode.kr, dev.to/korea).
• Coverage push 55% → 70%.
• Semantic search index (Algolia / Typesense).
• Component spec extractor v2 (TS AST parsing).
• More Korean translations (CONTRIBUTING.ko.md, ARCHITECTURE.ko.md, USING.ko.md).

Phase 30 — Versioned knowledge frontmatter (v3.11) ✓ shipped

Foundation for v4.0 stability. Every knowledge file now carries version, last_updated, and stability metadata. Adopters can pin to specific versions; future audits can flag stale content.

Added

• tools/migrations/add-version-frontmatter.py — one-shot migration script:
• Idempotent (re-running skips already-versioned files).
• Detects existing frontmatter (with optional leading HTML comment), inserts before closing ---.
• --write to apply; default is dry-run.
• Locates 91 knowledge files; all updated.
• tools/audit/frontmatter-check.py — validates new optional fields:
• version: semver-shaped (1.0.0, 1.2.3-beta).
• last_updated: YYYY-MM or YYYY-MM-DD.
• stability: one of stable / beta / experimental / deprecated.
• Missing keys remain OK (backward-compatible).
• tools/migrations/ directory — new home for one-shot migration scripts.

Changed

• All 91 knowledge files — frontmatter extended with version metadata; no content changes.
• package.json + .claude-plugin/plugin.json: 3.10.0 → 3.11.0.

Stability levels

Level	Meaning
stable	Reviewed; canonical; safe to depend on
beta	Substantively complete but pending review or polish
experimental	Active iteration; may change significantly
deprecated	Superseded; will be removed in a future major version

All current knowledge starts at stable.

Verified

• All 5 audits pass.
• Migration script idempotent.
• Format identical across 91 files.

What this enables

• Version pinning — "knowledge v1.0.0" reference for adopters.
• Stale-content detection — future audit can flag last_updated > 12 months ago.
• Stability-aware skills — skills can prefer stable knowledge.
• Migration tracking — last_updated will diverge over time as files are reviewed individually.

What's still ahead (v3.12+)

• Coverage push 55% → 70%.
• Semantic search index (Algolia / Typesense).
• Component spec extractor v2 (TS AST parsing).
• VS Code marketplace publication (1.0.0).
• Stale-content audit (flag files with old last_updated).
• More Korean translations.

Phase 29 — Korean integration walkthroughs (v3.10) ✓ shipped

Five integration walkthroughs translated to Korean. Continues v3.6 KR i18n investment — primary audience (KR designers / developers) can use Codex / Cursor / Aider / SDK / VS Code without English friction.

Added

• 5 Korean walkthroughs in docs/integrations/:
• codex-walkthrough.ko.md — Codex CLI 워크스루
• cursor-walkthrough.ko.md — Cursor 워크스루
• aider-walkthrough.ko.md — Aider 워크스루
• sdk-walkthrough.ko.md — Anthropic + OpenAI SDK 워크스루
• vscode-walkthrough.ko.md — VS Code 확장 워크스루
• Each translation includes 4-5 worked sessions (matching English depth), not abridged summaries.

Changed

• tools/audit/korean-copy-check.py — added .ko.md pattern; now scans 26 Korean-relevant files (was 17).
• package.json + .claude-plugin/plugin.json versions: 3.9.0 → 3.10.0.

Translation approach

• 어댑터 / 사용자 대상 콘텐츠는 해요체 (친근).
• 코드 블록은 영문 유지 (대부분 명령어 / API).
• 한국어 브랜드 이름은 한국어 유지 (Toss, KakaoPay, Pretendard).
• Direct word-for-word translation 거부 — 한국어 자연스러움 우선.
• Each Korean file mirrors the English structure (Prerequisites / Setup / Walkthroughs / Tips / Troubleshooting) but with Korean phrasing.

Verified

• All 5 audits pass.
• Korean copy check picks up 26 files (was 17).
• 358 internal links resolve.

What this enables

• Korean adopters can use any of 5 AI coding tools with full Korean walkthroughs.
• Korean B2B teams can share walkthroughs with non-developer stakeholders.
• Lower English-friction for KR designers evaluating design-ai.
• Audit coverage — Korean files validated by korean-copy-check on every PR.

What's still ahead (v3.11+)

• Coverage push 55% → 70%.
• Versioned knowledge files (semver in frontmatter).
• Semantic search index (Algolia / Typesense).
• Component spec extractor v2 (TS AST parsing).
• VS Code marketplace publication (1.0.0).
• More Korean translations (CONTRIBUTING.ko.md, ARCHITECTURE.ko.md, USING.ko.md).
• Brand identity polish for v4.0 (logo refinement, marketing landing).

Phase 28 — Coverage push 45% → 55% (v3.9) ✓ shipped

Component coverage from 45.2% → 55.3% (90 → 110 of 199 canonical components). Majority canonical coverage milestone. Form / overlay / transition / notification primitives largely complete.

Added (18 net new + 2 renames)

Form / control primitives (3): - component-switch.md — iOS-style toggle (Switch vs Checkbox decision) - component-textarea.md — multi-line input; Korean IME handling - component-textarea-autosize.md — grows-with-content variant

Notifications (2): - component-snackbar.md — Material's bottom-Toast variant - component-sonner.md — modern shadcn library; stacking + promise wrapper

Overlays (3): - component-popconfirm.md — inline confirmation - component-popper.md — low-level positioning primitive - component-click-away-listener.md — outside-click utility

Display / layout (4): - component-tag.md — closeable chip - component-resizable.md — IDE-style panels - component-image-list.md — uniform-grid photos - component-toolbar.md — action container

Mobile (1): - component-swipeable-drawer.md — swipe-to-open

Floating / scroll (2): - component-back-top.md — scroll-to-top - component-speed-dial-action.md — sub-action

Transitions (2): - component-zoom.md — scale + fade - component-slide.md — direction-based

Sub-components (1): - component-step.md — sub-component of Steps

Renames (2): - component-autocomplete.md → component-auto-complete.md - component-mention.md → component-mentions.md

Versions

• CLI: 3.8.0 → 3.9.0
• Plugin / corpus: 3.8.0 → 3.9.0

Verified

• All 5 audits pass.
• 110/199 = 55.3% coverage.
• Examples: 142 → 160 (+18).

What this enables

• Majority canonical coverage — over half the 199-component surface.
• Notification family complete — Toast / Snackbar / Sonner / Message / Notification / Banner / Alert distinguished + comparable.
• Transition primitives complete — Fade / Zoom / Slide / Grow / Collapse referenced from one consistent vocabulary.
• Form primitives complete — Switch / Checkbox / Radio / Label / Textarea + autosize / Field family all distinct.

What's still ahead (v3.10+)

• Coverage push 55% → 70% (next batch).
• Versioned knowledge files (semver in frontmatter).
• Semantic search index (Algolia / Typesense).
• Component spec extractor v2 (TS AST parsing).
• VS Code marketplace publication (1.0.0 milestone).
• Korean translations of integration walkthroughs.

Phase 27 — VS Code extension (v3.8) ✓ shipped

design-ai is now accessible inside VS Code via a dedicated extension. New distribution surface for the millions of VS Code users — pairs with any AI assistant (Copilot Chat / Cursor / Continue / Claude / CodeWhisperer) without competing.

Added

• vscode-extension/ — TypeScript-based VS Code extension:
• package.json manifest:
  • 8 commands (Install / Status / Open knowledge / Open spec / Open skill / Open walkthrough / Refresh / Settings).
  • 4 sidebar TreeViews (Skills / Knowledge / Examples / Walkthroughs) under a dedicated activity bar entry.
  • 2 settings (design-ai.path, design-ai.language).
• src/extension.ts — entry point. Path auto-probing on activation; reactive to setting changes.
• src/paths.ts — locates design-ai source via setting → workspace folder → common locations (~/dev/design-ai, ~/.local/lib, /opt, npm-global, Homebrew lib).
• src/commands.ts — 8 command implementations. Install invokes the project's install.sh. Status reads .claude-plugin/plugin.json for version + counts. Open commands use showQuickPick for fast filtering across the corpus.
• src/providers/trees.ts — 4 TreeDataProviders. Knowledge tree is recursive (categories → files); Skills / Examples / Walkthroughs are flat lists.
• media/icon.svg — gradient indigo/violet "D" mark.
• tsconfig.json, .vscodeignore, LICENSE, README.md, CHANGELOG.md.
• docs/integrations/vscode-walkthrough.md — 5 worked sessions:
• Browse + reference in chat
• Audit existing component
• Generate from skill PLAYBOOK
• Quick-pick across the corpus
• Multi-file design system bootstrap
• tools/audit/integration-check.py — added vscode-walkthrough.md to validation list (5 walkthroughs total).

Changed

• README.md agent table — VS Code added as supported environment with link to walkthrough.
• mkdocs.yml Integrations nav — VS Code entry added.
• package.json + .claude-plugin/plugin.json: 3.7.0 → 3.8.0.

Verified

• All 5 audits pass.
• Integration audit covers all 5 walkthroughs (added vscode-walkthrough.md).
• Extension scaffold compiles cleanly via tsc -p . (TypeScript 5.3+ required).

Versions

• CLI: 3.7.0 → 3.8.0
• Plugin / corpus: 3.7.0 → 3.8.0
• VS Code extension: 0.1.0 (initial release; lives in vscode-extension/)

What this enables

• VS Code users browse design-ai content without leaving the editor.
• Pair with any AI assistant — Copilot Chat / Cursor / Continue / Claude / CodeWhisperer.
• Korean preference setting — design-ai.language: "ko" opens Korean translations.
• Doesn't compete with AI assistants — surfaces design-aware content, complements AI tools.

Publication path (maintainer)

The extension is scaffolded but not yet published to the VS Code Marketplace. Steps:

cd vscode-extension
npm install
npm run compile
npx @vscode/vsce package        # produces .vsix
npx @vscode/vsce publish        # requires Azure DevOps PAT + publisher account

Until then, distribute via GitHub Releases.

What's still ahead (v3.9+)

• Coverage push 45% → 60%.
• Versioned knowledge files (semver in frontmatter).
• Semantic search index (Algolia / Typesense).
• Component spec extractor v2 (TS AST parsing).
• VS Code marketplace publication (1.0.0 milestone).
• More Korean translations.
• VS Code extension: walkthroughs panel (vscode walkthrough API), code actions for spec compliance.

Phase 26 — Coverage push 36.2% → 45.2% (v3.7) ✓ shipped

Component coverage from 36.2% → 45.2% (72 → 90 of 199 canonical components). Crosses the halfway-to-100% threshold for canonical primitive coverage.

Added (18 specs)

17 net new + 1 rename.

Form / control primitives (5): - component-checkbox.md — indeterminate state, "select all", KR marketing-consent rule - component-radio.md (+ RadioGroup) — mutually exclusive choice; Korean payment-method picker - component-label.md — htmlFor linking; required / optional indicators - component-icon.md — base primitive (size, currentColor, decorative vs meaningful) - component-icon-button.md — icon-only variant; mandatory aria-label

Layout primitives (4): - component-box.md — most generic styled <div> (system props pattern) - component-flex.md — flex layout (direction / gap / align / justify) - component-grid.md — 2D layout (Ant Row+Col / MUI v2 / CSS Grid) - component-space.md — inline-gap utility (sibling to Flex / Stack)

Navigation / overlays (3): - component-menu.md — Ant-style structured nav (distinct from Dropdown / NavigationMenu / Sidebar) - component-button-group.md — visually unified action cluster - component-speed-dial.md — FAB + 2-5 sub-action FABs (mobile compose pattern)

Feedback / data (3): - component-message.md — Ant top thin pill notification (vs Toast / Notification / Banner) - component-notification.md — richer corner card (title + description + actions) - component-list.md — semantic wrapper around Item rows; pagination + virtualization

Pickers (2): - component-time-picker.md — hour/minute/second; 24/12-hour; KR step conventions - component-tree-select.md — dropdown hierarchy picker (vs Cascader / Tree)

Utility (1): - component-backdrop.md — semi-opaque scrim overlay

Renamed (1): - component-qrcode.md → component-qr-code.md (canonical kebab-case)

Verified

• All 5 audits pass.
• Coverage: 72 → 90 (45.2%).
• Examples: 124 → 142.
• Versions bumped: 3.6.0 → 3.7.0.

What this enables

• Halfway to 100% — 45.2% milestone for canonical primitive coverage.
• Form construction primitives complete — Checkbox / Radio / Label / Field family / Switch (form-controls) all specced. Form skill output uses real spec foundations.
• Layout primitives covered — Box / Flex / Grid / Stack / Space / Masonry — adopters pick the right tool.
• Notification family unified — Toast / Message / Notification / Banner / Alert all distinct + comparable.
• Pickers complete enough — DatePicker / TimePicker / TreeSelect / Cascader / Combobox / Select all specced.

What's still ahead (v3.8+)

• Coverage push 45% → 60% (next 30+ specs).
• VS Code extension wrapper.
• Semantic search index for the doc site.
• Versioned knowledge files (semver in frontmatter).
• Component spec extractor v2 (TS AST parsing).
• More Korean translations of integration walkthroughs.

Phase 25 — Doc site Korean i18n (v3.6) ✓ shipped

design-ai's primary audience is Korean. The doc site was English-only; this phase makes it bilingual so KR users can evaluate and adopt without English friction. Direct lever for the user's stated 시장성 / 대중성 goal.

Added

• 4 Korean translations of high-traffic pages:
• README.ko.md — Korean primary landing with full feature coverage, install paths, agent table, KR market focus, source material, status, contribution guidelines, changelog highlights.
• docs/QUICKSTART.ko.md — 5-minute getting-started in Korean.
• docs/DISTRIBUTION.ko.md — Distribution guide (NPM / Homebrew / git clone) in Korean with 한국어 어댑터 가이드 section.
• AGENTS.ko.md — Universal agent entry point in Korean. Mirrors English AGENTS.md with KR-specific guidance built in.
• mkdocs-static-i18n plugin — file-suffix translation pattern. Same content tree, two languages.
• mkdocs nav translations — Home / Quickstart / Distribution / Architecture / Knowledge / Skills / Commands / Agents / Examples / Integrations / Reference all translated.
• Header language switcher — mkdocs-material's extra.alternate provides English / 한국어 toggle in nav.
• README badges — language toggle at top of both READMEs.
• tools/build-docs.sh updated to symlink Korean translations into site-src/.

Changed

• docs/requirements.txt — added mkdocs-static-i18n>=1.3.0.
• mkdocs.yml — i18n plugin config + nav_translations + extra.alternate.
• README.md (English) — language toggle to Korean variant.
• package.json + .claude-plugin/plugin.json versions: 3.5.0 → 3.6.0.

Verified

• All 5 audits pass (frontmatter / link / Korean / coverage / integration-check).
• mkdocs build succeeds in 12s with both languages.
• Korean pages render at /ko/ with translated nav.
• Search supports both English and Korean tokenizers.

Voice / register choices

For Korean translations: - README + QUICKSTART: 해요체 (friendly) — adopters / explorers - AGENTS.md: 해요체 — agent-facing instructions - DISTRIBUTION: mixed — code blocks in code, narrative in 해요체 - Direct translation rejected — adapted to natural Korean (e.g., "let's get started" → "시작해 봐요" not "시작합시다 우리는")

What this enables

• Korean adopters can evaluate without bouncing off English.
• SEO for the primary market — Korean meta tags improve Naver / Google KR indexing.
• B2B Korean teams can share Korean docs with non-developer stakeholders.
• Lower adoption barrier — KR designers see "made for our market" via the toggle alone.

What's still ahead (v3.7+)

• Translate more pages (CONTRIBUTING.ko.md, ARCHITECTURE.ko.md, integrations Korean).
• Coverage push 36% → 50% (extractor accelerates).
• VS Code extension wrapper.
• Semantic search index (Algolia / Typesense) for cross-language search.
• Versioned knowledge files (semver in frontmatter).
• Component spec extractor v2 (TS AST parsing).

Phase 24 — Component spec scaffolder + coverage push (v3.5) ✓ shipped

Component coverage from 30.7% → 36.2% (61 → 72 of 199 canonical components). Builds an extractor that scaffolds future spec drafts from upstream sources, then exercises the muscle with 11 new manual specs.

Added

• tools/extractors/component_spec_scaffold.py — leverage tool:
• Given a canonical name (e.g., combobox), reads upstream sources from refs/{ant,mui,shadcn}.
• Best-effort prop extraction from TypeScript interfaces.
• Emits examples/component-{name}.md as a draft following the established skill template.
• Banner clearly marks output as DRAFT — maintainer must review narrative sections + tokens before shipping.
• CLI flags: --name X, --all-missing, --limit N, --force, --dry-run.
• Graceful degradation when refs/ is missing — produces template anyway.
• 11 component specs (manual, full-quality):
• component-alert-dialog.md — destructive confirmation; role="alertdialog" + Cancel default focus
• component-bottom-navigation.md — mobile primary nav; iOS + Android + M3 conventions
• component-chart.md — Recharts wrapper; KR stock convention (red=up); chart-type selection
• component-combobox.md — searchable select; WAI-ARIA combobox; Korean IME handling
• component-field.md — Field family form-wrapper (Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend)
• component-item.md — list-item primitive (Item / ItemMedia / ItemContent / ItemTitle / etc.)
• component-link.md — text link primitive; Link vs Button decision; external indicator
• component-paper.md — MUI surface primitive (elevation + outlined)
• component-spinner.md — indeterminate loading; Spinner vs Progress vs Skeleton
• component-empty.md — inline "no data" primitive; distinct from EmptyState (custom)
• component-masonry.md — Pinterest-style staggered grid; CSS multicolumn vs JS trade-offs

Changed

• examples/README.md — added new specs to Component specs table.
• package.json + .claude-plugin/plugin.json versions: 3.4.0 → 3.5.0.

Verified

• All 5 audits pass (frontmatter / link / Korean / coverage / integration-check).
• Scaffolder dry-run + smoke-test produces valid output.
• No regressions in existing specs.

Coverage

• Examples: 113 → 124 (+11)
• Component coverage: 61 → 72 (30.7% → 36.2%)

What this enables

• Future coverage pushes are 5-10× faster — scaffold 30 drafts in seconds, then maintainers refine the narrative sections (anatomy, edge cases, code examples, "Don'ts").
• Closer parity with shadcn-ui — most flagship primitives now have specs (alert-dialog, command, sheet, dropdown, navigation-menu, menubar, sidebar, combobox, field, item, hover-card, context-menu).
• Form construction primitives ready — Field family is the canonical form-wrapper across the corpus, used internally by Form skill output.
• Korean stock convention canonicalized — chart spec captures the red=up / blue=down inversion as a token-driven default.

What's still ahead (v3.6+)

• Versioned knowledge files (version: in frontmatter for fine-grained pinning).
• Coverage push 36% → 50% (next 30+ specs — extractor accelerates this).
• VS Code extension wrapper.
• Semantic search index for the doc site (Algolia / Typesense).
• Doc site i18n (Korean translations of QUICKSTART, README, AGENTS).
• Component spec extractor v2 — TypeScript AST parsing for fuller prop extraction.

Phase 23 — Multi-agent integration + Homebrew (v3.4) ✓ shipped

Concrete proof that design-ai's "model-agnostic" tagline is real. Until now, the corpus had been heavily exercised through Claude Code; this phase adds worked walkthroughs for Codex CLI / Cursor / Aider / SDK and a Homebrew formula for broader install reach.

Added

• 4 integration walkthroughs in docs/integrations/:
• codex-walkthrough.md — 4 sessions (component spec, design system, iterate critique, Figma audit) + Codex-specific tips (paths, MCP config, AGENTS.md fragments).
• cursor-walkthrough.md — 5 sessions (inline spec, audit existing, Figma critique, token gen, Cmd+K inline) + Composer mode + MCP config.
• aider-walkthrough.md — 4 sessions (impl, refactor, design-system bootstrap, audit-then-fix) + Aider patterns (architect mode, auto-test, bash aliases).
• sdk-walkthrough.md — Anthropic + OpenAI SDK adoption with prompt caching, tool use, streaming. Production chatbot example.
• Formula/design-ai.rb — Homebrew formula:
• Installs corpus to libexec.
• Wraps install.sh as design-ai-install binary.
• Symlinks the npm CLI as design-ai if Node is present.
• Includes a test do block validating plugin manifest + skill counts.
• Formula/README.md — maintainer release runbook (tag, release, get sha256, update formula, test, push).
• tools/audit/integration-check.py — verifies each walkthrough has required sections (Prerequisites / Setup / ≥3 Walkthroughs / Next). Catches structural drift over time.
• .github/workflows/audit.yml — wired the new audit into CI. 5 audits now run on every PR.

Changed

• docs/CODEX-INTEGRATION.md + CURSOR-INTEGRATION.md + AIDER-INTEGRATION.md — top-of-file callouts linking to the corresponding walkthrough.
• README.md — Option B: Homebrew install path added; agent table links to per-agent walkthroughs.
• mkdocs.yml — Integrations nav restructured per agent (Setup + Walkthrough sub-entries); SDK + Distribution promoted to top-level entries.

Verified

• All 5 audits pass (frontmatter / link / Korean / coverage / integration-check).
• Integration audit confirms all 4 walkthroughs have the required structure.
• CLI smoke tests still pass.
• mkdocs build with new nav succeeds.

Versions

• CLI: 3.3.0 → 3.4.0
• Plugin / corpus: 3.3.0 → 3.4.0

What this enables

• Model-agnostic adoption — adopters can choose Codex / Cursor / Aider / SDK without reverse-engineering setup. Each walkthrough is self-contained.
• Homebrew install — brew install design-ai lowers friction for Mac users (especially designers who aren't comfortable with npm or git clones).
• Production SDK adoption — concrete patterns (prompt caching, streaming, tool use, chatbot example) lower the barrier for embedding design-ai into products.
• CI safeguards — integration walkthroughs can't silently rot; audit catches missing sections.

What's still ahead (v3.5+)

• Versioned knowledge files (version: in frontmatter for fine-grained pinning).
• Coverage push 30% → 40%+ (next batch of canonical specs).
• VS Code extension wrapper.
• Component spec extractor (scaffold from upstream diff).
• Semantic search index for the doc site (algolia / typesense).
• Internationalization of the doc site (English primary; Korean translation of key pages).

Phase 22 — Component coverage push (v3.3) ✓ shipped

Component spec coverage from 23.6% → 30.7% (47 → 61 of 199 canonical components).

Added (15 specs total)

13 net new + 2 renames (to align filenames with canonical names from knowledge/components/index.json).

Overlay primitives (5): - component-badge.md — Standalone label + Indicator dual modes (Ant + MUI + shadcn synthesis). - component-dropdown.md — Dropdown / DropdownMenu; WAI-ARIA Menu pattern, sub-menus, checkbox / radio items, shortcuts. (Renamed from component-dropdown-menu.md.) - component-context-menu.md — Right-click / long-press triggered; same Menu pattern as Dropdown. - component-hover-card.md — Hover-triggered floating preview; profile previews, link previews. - component-sheet.md — Side-anchored modal panel; mobile-first detents (peek vs full). - component-command.md — Command / CommandPalette (cmdk-based); Cmd+K pattern, fuzzy match, async results, multi-page navigation. (Renamed from component-command-palette.md.)

Navigation / layout (3): - component-sidebar.md — Persistent collapsible navigation (the shadcn flagship); icon-only mode, mobile offcanvas. - component-navigation-menu.md — Top horizontal nav with mega-menu panels; marketing site / SaaS header. - component-menubar.md — Desktop File / Edit / View pattern; hover-roving between menus, keyboard nav.

Utilities (7): - component-aspect-ratio.md — Lock child to specific aspect ratio. - component-collapsible.md — Single expandable section primitive. - component-toggle.md — Toggle + ToggleGroup pressable buttons (single + multiple). - component-scroll-area.md — Custom-styled scrollbar; visibility modes. - component-banner.md — Persistent in-page strip (system status, trial, cookie consent); distinct from Alert + Toast. - component-kbd.md — Keyboard shortcut display; platform-aware Mac/Win symbols. - component-separator.md — Horizontal / vertical divider; decorative vs semantic.

Renamed

• component-dropdown-menu.md → component-dropdown.md (matches canonical dropdown from Ant)
• component-command-palette.md → component-command.md (matches canonical command from shadcn)

Cross-references updated

All in-corpus links updated via sed. link-check.py confirms no broken references.

Coverage

• Examples: 99 → 113 (+14)
• Component coverage: 47 → 61 (23.6% → 30.7%)
• Versions bumped: CLI 3.1.0 → 3.3.0, Plugin 3.1.0 → 3.3.0

Verified

• All 4 audits pass (frontmatter / link / Korean / coverage).
• mkdocs build still succeeds.
• npm pack tarball clean.

What this enables

• Stronger component-spec-writer output — more canonical patterns matched, better synthesis quality.
• Closer parity with shadcn-ui — most flagship primitives (sidebar, command, sheet, dropdown-menu) now have specs.
• 30%+ canonical coverage milestone — the corpus now covers 30% of the canonical Ant + MUI + shadcn surface.

What's still ahead (v3.4+)

• Versioned knowledge files (version: in frontmatter for fine-grained pinning).
• Cross-tool integration tests (Codex CLI / Cursor / Aider sessions captured as worked examples).
• Coverage push from 30% → 40%+ (more canonical specs).
• Homebrew formula.
• VS Code extension wrapper.
• Component spec extractor (scaffold a spec from upstream source diff).

Phase 21 — Public doc site (v3.2) ✓ shipped

mkdocs-material site auto-deploying to GitHub Pages. Discoverability + search for prospective adopters before they install.

Added

• mkdocs.yml — site config:
• Material theme, indigo / violet brand palette (light + dark schemes via prefers-color-scheme).
• Pretendard variable font for Korean, Inter for Latin, JetBrains Mono for code.
• Full nav tree covering Knowledge / Skills / Commands / Agents / Examples / Integrations / Reference.
• 17 markdown extensions enabled (admonition, tabs, tasklist, mermaid, etc).
• tools/build-docs.sh — populates site-src/ with a symlink farm (mkdocs requires docs_dir to be a sibling/descendant of config, not parent). Idempotent. Index symlink: site-src/index.md → ../README.md.
• docs/site-overrides/ — theme customizations:
• extra.css — Pretendard variable font from jsDelivr CDN, brand color tweaks, Korean reading optimizations (word-break: keep-all, font-feature-settings: "kern").
• main.html — announcement bar pushing the npx install command + OpenGraph / Twitter Card metadata.
• logo.svg, favicon.svg — gradient indigo/violet "D" mark.
• docs/requirements.txt — pinned mkdocs-material >=9.7.0 (older 9.5.x had a pygments/pymdown-extensions interaction bug that caused build to crash on highlight.pygments_lang_class: true).
• .github/workflows/docs.yml — auto-deploy to GitHub Pages:
• Triggers on push to main (paths-filtered to docs-relevant changes only) + manual dispatch.
• Uses actions/configure-pages@v4, actions/upload-pages-artifact@v3, actions/deploy-pages@v4.
• Concurrency-grouped under pages with cancel-in-progress: false.
• Runs ./tools/build-docs.sh then mkdocs build --clean (deliberately not --strict — informational cross-reference warnings aren't blocking; actual broken links are caught by the existing link-check.py audit on every PR).

Changed

• README.md — added doc-site badge linking to the live site.
• tools/audit/link-check.py + korean-copy-check.py — now skip site-src/, site/, node_modules/ walk paths so audits don't double-count symlinked content.
• .gitignore — excludes site/, site-src/ build artifacts.

Local preview

pip install -r docs/requirements.txt
./tools/build-docs.sh
mkdocs serve
# → http://127.0.0.1:8000

Verified

• All 4 audits still pass (frontmatter / link / Korean copy / coverage).
• mkdocs build --clean succeeds in 8 seconds.
• 333 HTML files generated, 35MB total (includes search index + asset duplication).
• Theme overrides loaded (Pretendard, indigo brand colors, custom logo).

What this enables

• Discoverability — prospective adopters can browse the corpus on the public site before deciding to install.
• Search — built-in mkdocs-material search across all 91 knowledge files + 99 examples + skill playbooks. Korean + English search both supported.
• Korean readability — Pretendard font + word-break rules render Hangul correctly across all pages.
• Lower-friction evaluation — open-source evaluators can read full skill / pattern docs without cloning.
• SEO — structured site improves Google indexing for design-ai content.

What's still ahead (v3.3+)

• Versioned knowledge files (version: in frontmatter for fine-grained pinning).
• Cross-tool integration tests (Codex CLI / Cursor / Aider sessions captured as worked examples).
• Component coverage push 23.6% → 30%+.
• Homebrew formula.
• VS Code extension wrapper.
• Search analytics (which knowledge files are most-read).
• Versioned doc site (mkdocs mike plugin) for snapshotting v3.x docs.

Phase 20 — Distribution (v3.1) ✓ shipped — productization phase

NPM CLI distribution. Adopters now go from zero to installed in one command (npx @design-ai/cli install) without cloning the repo.

Added

• package.json — npm package @design-ai/cli, bin design-ai, ESM, Node ≥18.
• cli/ — Node.js CLI:
• cli/bin/design-ai.mjs — entry point.
• cli/lib/dispatch.mjs — command router with aliases (i / u / s / ls / v).
• cli/lib/paths.mjs — path resolution (npm package vs git clone, env overrides).
• cli/lib/log.mjs — colorized terminal output (NO_COLOR-aware).
• cli/lib/exec.mjs — shell exec helpers.
• 7 commands: install, update, uninstall, status, list, version, help.
• install / uninstall delegate to the existing install.sh (single source of truth).
• list reads from .claude-plugin/plugin.json to show full catalog.
• .npmignore — safety net for what stays out of the npm tarball; primary control via package.json files allowlist.
• .github/workflows/publish.yml — auto-publish on v* tag. Verifies tag matches package.json, plugin.json matches package.json, runs all 4 audits, runs npm pack --dry-run, publishes with --provenance.
• docs/DISTRIBUTION.md — three install paths (npm / git clone / manual symlinks), CLI command reference, env override reference, versioning rules, publishing checklist, troubleshooting.

Changed

• .claude-plugin/plugin.json version: 3.0.0 → 3.1.0 (aligned with CLI).
• README.md — lead with npx @design-ai/cli install as primary install path; git clone retained as Option B for contributors.
• docs/ROADMAP.md updated with this section.

Coverage (no corpus change in this phase)

• Knowledge: 91 (no change)
• Examples: 99 (no change)
• Skills: 19 (no change)
• Commands: 15 (no change) — different from CLI commands; refers to slash commands
• New: NPM CLI with 7 commands, publish workflow, DISTRIBUTION docs

What this enables

• One-command install — npx @design-ai/cli install works on any Node ≥ 18 machine.
• Update path — design-ai update pulls + reinstalls without manual git work.
• Catalog browsing — design-ai list skills shows what's available before deciding to install.
• Cross-machine consistency — npm-published version is the canonical reference; git clone tracks main for contributors.
• Provenance attestation — npm --provenance flag verifies builds came from this GitHub repo.

What's still ahead (v3.x and beyond)

• Public doc site (mkdocs-material on GitHub Pages) for browsing knowledge without install.
• Versioned knowledge files (version: in frontmatter for fine-grained pinning).
• Cross-tool integration tests (Codex CLI / Cursor / Aider sessions captured as worked examples).
• Component coverage push 23.6% → 30%+.
• Homebrew formula.
• VS Code extension wrapper.

Phase 19 — Stabilization (v3.0) ✓ shipped — productization phase

The v2 expansion proved the corpus works across 7 new design domains. Phase 19 is the stabilization step the user requested: "안정화 후 시장성, 대중성이 있으면 프로그램화 진행" — stabilize first, productize next.

Added

• .claude-plugin/plugin.json — Claude Code plugin manifest. All 19 skills, 15 commands, 4 agents declared with names + paths + descriptions; supports plugin discovery and future /plugin install flow.
• install.sh — automated installer:
• Symlinks skills/, agents/, commands/ into ~/.claude/ with design- prefix.
• Idempotent (safe to re-run).
• Subcommands: install (default), --uninstall, --status, --help.
• Configurable: DESIGN_AI_PREFIX, CLAUDE_HOME env overrides.
• CHANGELOG.md — full release history, v1.0 through v3.0, semver-compliant.
• README.md overhaul — coverage-at-a-glance table reflecting v2 expansion (motion / illustration / print / video / game UI / conversational / spatial); install instructions; first-task tour; Korean market focus section.
• docs/QUICKSTART.md — 5-minute getting-started for new adopters.
• CI: Korean copy check added to audit.yml (was missing despite the script existing).
• CI: size budget updated from 50K-line warning (long since exceeded) to 100K warn / 150K hard-cap.

Changed

• Knowledge size now ~57K lines; budget recalibrated.
• docs/ROADMAP.md updated with v3.0 entry (this section).

Coverage

• Knowledge: 91 (no change in this phase)
• Examples: 99 (no change)
• Skills: 19 (no change)
• Commands: 15 (no change)
• New: plugin manifest, install script, CHANGELOG, QUICKSTART
• CI checks: 4 → 5 (added korean-copy-check)

What this enables

• Adopters can install design-ai globally with ./install.sh instead of the manual symlink loop documented in PLUGIN-PACKAGING.md.
• CHANGELOG.md is the canonical reference for "what changed when" — adopters can pin to a version.
• README stops being a launch-day artifact and becomes a maintained adoption surface.
• CI parity — all 4 audits (frontmatter / link / Korean copy / coverage) run on every PR; no skipped checks.

What's still ahead (v3.x and beyond)

• Versioned knowledge files (version: in frontmatter; version field optional today).
• Public doc site (mkdocs / docusaurus). Knowledge already markdown-friendly.
• NPM package distribution (npx design-ai install).
• Cross-tool integration tests (real sessions in Codex CLI / Cursor / Aider captured as worked examples).
• Component coverage push to 30%+ (currently 23.6%).

Phase 18 — AR / VR / spatial design (v2.7) ✓ shipped — completes v2 expansion

Final phase of the v2 expansion. Adds spatial computing as a first-class design surface alongside motion / illustration / print / video / game UI / conversational. Covers fundamentals (Milgram continuum, FOV, comfort zones, units, vergence-accommodation), VR patterns (Quest / PSVR2 / Vision Pro immersive / locomotion), AR patterns (ARKit / ARCore / HoloLens / world + image + object anchors), spatial UI elements (panels, billboards, controls, menus), and comfort + accessibility (motion sickness mitigations, vision / hearing / motor / cognitive / photosensitive / mobility).

• 5 spatial knowledge files:
• spatial/spatial-design-fundamentals.md — Milgram continuum, spatial units, visual angle, FOV, comfort zones (vertical + horizontal), stereoscopic depth, vergence-accommodation conflict, locomotion overview, comfort vignette, spatial audio, hand vs controller vs gaze, anchoring, resolution + PPD, performance budget, platforms, Korean market context.
• spatial/vr-patterns.md — VR experience categories, three core principles (presence / comfort / use-the-body), HUD anti-patterns + diegetic alternatives, locomotion in detail (teleport / smooth / snap turn / room-scale / hybrid), spatial UI placement, hands + avatars, multiplayer / social, reading text in VR, cinema in VR, performance.
• spatial/ar-patterns.md — three AR contexts (mobile handheld / glasses / world-anchored), visibility against real backgrounds, spatial mapping, anchoring strategies (world / image / body / screen), onboarding, common interactions, permission + privacy, tracking failure handling, Korean AR market.
• spatial/spatial-ui-elements.md — panels (the core), billboarding, buttons (push / tap), sliders, menus (wrist / floating / radial / pie), input affordances (pointer / hand cursor / gaze / voice), notifications, lists, forms, Korean text in spatial, dialogs, loading / progress, icons.
• spatial/comfort-and-accessibility.md — motion sickness triggers + mitigations, comfort settings menu, vision / hearing / motor / cognitive / photosensitive accessibility, eye strain, physical safety, wheelchair / mobility, Korean accessibility, hygiene for shared headsets, session length guidance.
• 2 component specs:
• component-spatial-panel.md — floating 2D-in-3D panel; anchoring (world / wrist / hand / head), visual angle vs absolute sizing, billboarding, hand + gaze + ray-cast + direct-touch input handling, comfort positioning, occlusion.
• component-spatial-locomotion.md — VR locomotion controller; teleport (with arc + landing indicator + fade), smooth (with vignette), snap-turn (with fade), room-scale, hybrid; comfort settings menu; one-handed + voice alt; comfort defaults for new users.
• skills/spatial-designer/ — pick mode (VR / AR / MR / WebXR) + platform; spec geometry, anchoring, locomotion, input, UI elements, comfort, accessibility, onboarding.
• /spatial slash command.
• AGENTS.md / skills/README / commands/README / examples/README / ROADMAP updated.

Coverage: - Knowledge: 86 → 91 (+5 spatial). - Examples: 97 → 99 (+2 spatial components). - Skills: 18 → 19 (+ spatial-designer). - Commands: 14 → 15 (+ /spatial).

v2 expansion summary (Phases 12 → 18)

Phases 12-18 added 7 new design domains:

Phase	Domain	Knowledge	Examples	Skill	Command
12	Motion design depth	5	4	motion-designer	/motion-design
13	Illustration systems	5	2	illustration-designer	/illustration
14	Print / physical design	6	2	print-designer	/print
15	Video content	5	2	video-designer	/video
16	Game UI	5	2	game-ui-designer	/game-ui
17	Voice / conversational	5	2	conversational-ui-designer	/conversational
18	Spatial / AR / VR	5	2	spatial-designer	/spatial
	Total v2.1-v2.7	+36	+16	+7	+7

Full repo: knowledge 55→91, examples 83→99, skills 12→19, commands 8→15. Korean market focus across all phases. All audits pass throughout. Ready for v3 stabilization / productization phase.

Phase 17 — Voice / conversational UI (v2.6) ✓ shipped

Conversational UI as a first-class design surface. Covers fundamentals (turn-taking, intents, modalities, latency, hallucinations), voice UI patterns, traditional chatbot design, AI chat (LLM-based) interfaces, and Korean conventions (Bixby, Clova, NUGU, KakaoTalk channel, 해요체 / 합쇼체).

• 5 conversational knowledge files:
• conversational/conversational-ui-fundamentals.md — modalities, turn-taking, intents + slots, conversational design principles, streaming, latency budgets, personality, STT/TTS, code-switching.
• conversational/voice-ui-patterns.md — wake word / tap-to-talk / multi-turn / voice search; smart speaker UX, phone assistant UX, in-car, IVR; Korean assistants; SSML; accessibility.
• conversational/chatbot-design.md — rule-based / intent-based / hybrid; anatomy, conversation patterns (greeting, quick replies, forms, lists, cards, confirmation); KakaoTalk channel; human handoff.
• conversational/ai-chat-interfaces.md — LLM chat: streaming, markdown / code rendering, stop / regenerate / continue, context length, hallucination handling, voice mode, memory, keyboard shortcuts.
• conversational/korean-voice-conventions.md — KR voice assistants (Bixby / Clova / NUGU / GiGA Genie / Kakao i), 합쇼체 / 해요체 selection, code-switching, TTS / STT options, KR regulatory (개인정보보호법, 정보통신망법, 자본시장법), KakaoTalk channel.
• 2 component specs:
• component-chat-interface.md — generic chat UI for chatbot / AI / live agent; markdown / code rendering, streaming, suggested chips, attachments, Korean IME handling.
• component-voice-input.md — push-to-talk + transcript voice input; Web Speech / Clova / Whisper backends, listening visualization, permission handling, accessibility alt.
• skills/conversational-ui-designer/ — pick type, modality, persona, intents, flows, error recovery, KR compliance, accessibility.
• /conversational slash command.
• AGENTS.md / skills/README / commands/README / examples/README / ROADMAP updated.

Coverage: - Knowledge: 81 → 86 (+5 conversational). - Examples: 95 → 97 (+2 conversational components). - Skills: 17 → 18 (+ conversational-ui-designer). - Commands: 13 → 14 (+ /conversational).

Phase 16 — Game UI (v2.5) ✓ shipped

Game UI as a first-class design surface. Covers fundamentals (diegetic / spatial taxonomy, genre conventions, platform variations), HUD design, menu systems, Korean gaming conventions (PC bang, 확률 표시, mobile gacha, MMO), and game accessibility.

• 5 game UI knowledge files:
• game-ui/game-ui-fundamentals.md — Russell taxonomy (diegetic / non-diegetic / spatial / non-spatial), genre conventions (FPS / RPG / MMO / gacha / casual / strategy), platform variations (PC / console / mobile / VR), input methods, button prompts.
• game-ui/hud-design.md — health bars, ammo / resources, crosshair, mini-map, damage numbers, cooldowns, buffs / debuffs, quest markers, notifications, subtitles, customization.
• game-ui/menu-systems.md — main menu, pause, inventory (grid / list / Tetris / stacked), settings, store, gacha (확률 표시), quest log, character / stats, navigation patterns, transitions.
• game-ui/korean-gaming-conventions.md — KR market context (NEXON / NCSoft / Krafton / Smilegate), 게임산업진흥에관한법률, 확률 표시 mandatory, 본인인증 / PASS / NICE, GRAC ratings, PC bang culture, auto-battle, daily login, VIP / 출석, gacha pity / 천장.
• game-ui/game-accessibility.md — four axes (vision / hearing / motor / cognitive), universal options menu standard, subtitles + closed captions, color-blind modes (protanopia / deuteranopia / tritanopia), motor (remap / toggle hold / auto-aim), cognitive (HUD options / hints / save anywhere), motion sickness reduction.
• 2 component specs:
• component-game-hud.md — composable HUD shell with anchored slots, customization, color-blind / contrast modes, UI scale, cross-platform input.
• component-game-menu.md — composable menu shell with focus management, controller / d-pad nav, platform-specific button-prompt swapping, modal stacking.
• skills/game-ui-designer/ — pick genre, platform, layout, input handling, accessibility, KR compliance.
• /game-ui slash command.
• AGENTS.md / skills/README / commands/README / examples/README / ROADMAP updated.

Coverage: - Knowledge: 76 → 81 (+5 game-ui). - Examples: 93 → 95 (+2 game-ui components). - Skills: 16 → 17 (+ game-ui-designer). - Commands: 12 → 13 (+ /game-ui).

Phase 15 — Video content (v2.4) ✓ shipped

Add video as a first-class design surface alongside motion / illustration / print. Covers fundamentals (codecs, resolution, captions, accessibility), marketing video, social/short-form (Reels / Shorts / TikTok), in-product video (onboarding / help), and Korean conventions (자막, 표시광고법, KFDA, 방송통신심의위원회). Two component specs for HTML5 video.

• 5 video knowledge files:
• video/video-fundamentals.md — codecs (H.264/H.265/AV1), resolution, framerate, bitrate, audio loudness (-14 LUFS), captions (WebVTT), color space, file size estimation, accessibility.
• video/marketing-video.md — hero loop / brand film / product demo; production budget tiers; Korean conventions (Toss / Kakao / Naver style).
• video/social-and-short-form.md — Reels / Shorts / TikTok / vertical; hook in 1 second; safe areas; subtitle styling; algorithm signals.
• video/in-product-video.md — onboarding / help / changelog; screen recording vs filmed; player UX; localization; reduced-motion fallback.
• video/korean-video-conventions.md — KR platforms (YouTube / Naver TV / KakaoTV / SOOP), 자막 style conventions, voiceover (해요체 / 합쇼체), 표시광고법 ad disclosure, KFDA / KFTC compliance.
• 2 component specs:
• component-video-player.md — accessible HTML5 player with multi-lang captions, speed control, transcript link, reduced-motion.
• component-video-hero.md — autoplay loop with poster fallback, art-direction (mobile vs desktop video), slow-connection / reduced-motion skip, WCAG-compliant pause control.
• skills/video-designer/ — pick surface category, technical spec, length, captions, voiceover, music, KR compliance, file delivery.
• /video slash command.
• AGENTS.md / skills/README / commands/README / examples/README / ROADMAP updated.

Coverage: - Knowledge: 71 → 76 (+5 video). - Examples: 91 → 93 (+2 video components). - Skills: 15 → 16 (+ video-designer). - Commands: 11 → 12 (+ /video).

Phase 14 — Print / physical design (v2.3) ✓ shipped

Expand beyond screen design into print + physical: business cards, stationery, brochures, posters, packaging. Korean print conventions (KFDA / KATS regulatory, 명함 size, 분리배출 표시, Pretendard typography for print) baked in. Includes 2 worked print specs.

• 6 print knowledge files:
• print/print-fundamentals.md — CMYK vs RGB vs spot, DPI, bleed/trim/safe area, paper weight + finish, file formats, ICC.
• print/stationery.md — business cards (KR 90×50 vs international 85×55), bilingual KR+EN, letterhead, envelopes.
• print/brochures-and-flyers.md — flyer / bi-fold / tri-fold / Z-fold / booklet / saddle-stitched; reading order, gutter, imposition.
• print/signage-and-posters.md — large-format; reading distance × size formula, materials, OOH compliance.
• print/packaging.md — folding cartons, labels, mailers; dielines; sustainability.
• print/korean-print-conventions.md — KR sizes, KFDA / KATS regulatory, 분리배출 표시, print districts, MOQ, lead times, costs.
• 2 worked print specs:
• print-business-card-spec.md — Korean fintech 명함 (premium tier): 90×50, 350gsm uncoated, soft-touch + spot UV, Pretendard, Pantone + CMYK.
• print-packaging-spec.md — Korean cosmetics folding carton: dieline, KFDA regulatory content, FSC + soy ink, press proof.
• skills/print-designer/ — pick piece type, spec dimensions / paper / color / finish / regulatory / file delivery.
• /print slash command.
• AGENTS.md / skills/README / commands/README / examples/README / ROADMAP updated.

Coverage: - Knowledge: 65 → 71 (+6 print). - Examples: 89 → 91 (+2 print specs). - Skills: 14 → 15 (+ print-designer). - Commands: 10 → 11 (+ /print).

Phase 13 — Illustration systems (v2.2) ✓ shipped

Lift illustration from an unwritten gap into a full subsystem: knowledge per type, component specs, dedicated skill, slash command. Covers spot illustrations, hero illustrations, mascots (Korean fintech relevance), and SVG production. Korean-market conventions baked in.

• 5 illustration knowledge files:
• illustration/illustration-systems.md — style, voice, system design (geometric vs organic, line weight, color treatment, perspective).
• illustration/spot-illustrations.md — empty / success / error / onboarding / permissions; composition + sizing + voice.
• illustration/hero-illustrations.md — marketing-led; conceptual / product-in-context / character-driven archetypes.
• illustration/mascot-design.md — Kakao / Toss / Naver mascot conventions, design process, governance.
• illustration/svg-optimization.md — SVGO, currentColor, accessibility, file size targets.
• 2 component specs:
• component-empty-state.md — illustration + headline + description + CTA stack with registry + voice rules.
• component-illustration.md — themeable SVG / Lottie display backed by typesafe illustration registry.
• skills/illustration-designer/ — pick scope, style, voice, color, format; spec assets; SVGO checklist.
• /illustration slash command.
• AGENTS.md / skills/README / commands/README / examples/README / ROADMAP updated.

Coverage: - Knowledge: 60 → 65 (+5 illustration). - Examples: 87 → 89 (+2 illustration components). - Skills: 13 → 14 (+ illustration-designer). - Commands: 9 → 10 (+ /illustration).

Phase 12 — Motion design depth (v2.1) ✓ shipped

Lift motion from a single principles file into a full subsystem: knowledge per category, component specs, a dedicated skill, and a slash command. Covers marketing, app loading, micro-interactions, and multi-element choreography. Reduced-motion-safe by default.

• 5 motion knowledge files:
• motion/marketing-motion.md — hero entrance, scroll-triggered, parallax, choreographed sequences, hover/cursor, loop animations; KR conventions.
• motion/app-loading-sequences.md — cold launch / warm launch / route changes, splash strategy, View Transitions API, FLIP, progressive content loading.
• motion/micro-interactions.md — 5 categories (press, state change, hover, focus, loading), 4 laws (be fast / functional / match input / no stagger redundancy).
• motion/choreography-depth.md — 5 patterns (cascade, FLIP, View Transitions, choreographed sequences, reactive choreography), stagger formulas, exit choreography, timing diagrams.
• motion/motion-tools.md — CSS / Framer Motion / GSAP / Lottie / Rive / react-spring decision tree + comparison matrix.
• 4 motion component specs:
• component-loading-sequence.md — splash + biometric gate + first-screen reveal coordination.
• component-page-transition.md — route-level wrapper (fade / slide / hero variants) using Framer Motion or View Transitions API.
• component-lottie-player.md — designer-led After Effects animation embed with lazy-load, offscreen pause, poster fallback.
• component-scroll-reveal.md — viewport-triggered animation primitive (fade-up / fade-in-blur / scale-in) with stagger.
• skills/motion-designer/ — pick category, duration tier, easing, tool; choreograph; verify reduced motion + performance budget.
• /motion-design slash command.
• AGENTS.md / skills/README / commands/README / examples/README / ROADMAP updated.

Coverage: - Knowledge: 55 → 60 (+5 motion). - Examples: 83 → 87 (+4 motion components). - Skills: 12 → 13 (+ motion-designer). - Commands: 8 → 9 (+ /motion-design).

Phase 11 — Completion (v2.0) ✓ shipped

Final completion of v2.0 scope. Adds the worked examples that prove the documentation skills work end-to-end, plus a focused component coverage push, plus 3 universal pattern knowledge files.

• 6 doc/deck/report/email worked examples:
• doc-tutorial-example.md (Diátaxis tutorial)
• doc-how-to-example.md (how-to with Korean localization)
• doc-explanation-example.md (W3C DTCG choice rationale)
• slide-deck-example.md (17-slide Korean conference talk)
• report-example.md (UX audit with severity-aggregated findings)
• email-transactional-example.md (Korean fintech receipt email)
• 7 component specs:
• component-descriptions.md (key-value list, dl semantics)
• component-hero-block.md (landing hero with 4 layouts + video variants)
• component-feature-grid.md (3-up/4-up feature display)
• component-testimonial-carousel.md (single-large/3-up/auto-scroll variants)
• component-pricing-cards.md (2-4 tier pricing with anchoring + KR subscription disclosure)
• component-pass-auth.md (Korean 본인인증 wrapper — PASS/NICE/KCB)
• component-otp-countdown.md (SMS code expiration + resend cooldown)
• 3 universal pattern knowledge files:
• auth-flow-design.md — signup / login / reset / 2FA / KakaoTalk / 본인인증
• pricing-page-design.md — tier strategy, anchoring, billing toggle, FAQ, KR legal
• landing-hero-design.md — 6 archetypes, headline formulas, video rules, A/B testing
• AGENTS.md / examples/README / ROADMAP updated.

Coverage: - Knowledge: 52 → 55 (+3 patterns). - Examples: 70 → 83 (+13: 6 doc examples + 7 component specs). - Component spec coverage: ~24% → ~27% (more canonical-matched + 4 new custom). - Total lines: ~52K → ~62K.

Phase 10 — Document design + brand + email (v1.9) ✓ shipped

Expansion beyond product UI into the full design domain.

• 5 document design knowledge files:
• document-typography.md — long-form reading (body 18px+, vertical rhythm, paragraph styling).
• information-architecture.md — Diátaxis 4 types, sidebar structure, naming, versioning, search.
• technical-writing.md — active/imperative/second-person voice, sentence length, code samples, voice-per-doc-type.
• slide-deck-design.md — talk vs pitch vs reading archetypes, message-led titles, layouts.
• report-design.md — TL;DR pyramid, audit format, severity rating, research findings template.
• 3 brand/medium knowledge files:
• brand-identity.md — logo / color / type / voice / imagery foundations.
• email-design.md — HTML email constraints, transactional vs marketing, bulletproof button, Korean spam law.
• i18n/korean-app-store-visual.md — icon design, screenshot composition, Korean storefront expectations.
• i18n/korean-document-style.md — honorific level (합쇼체 vs 해요체), hierarchy (가/나/다 + numeric), spacing rules, common Korean technical-writing errors.
• 4 doc component specs:
• component-callout.md — info/warning/note for docs (distinct from Alert).
• component-blockquote.md — attributed quotations.
• component-doc-page.md — full doc site layout (header / sidebar / TOC / footer).
• component-email-layout.md — table-based responsive email scaffolding.
• 2 new skills: document-author (Diátaxis-aware doc writing), slide-deck-author (deck outlining).
• 2 new commands: /document-from-brief, /slide-deck.
• PRINCIPLES.md extended with rules 36–41 (documentation & long-form).
• AGENTS.md / examples/README / skills/README / commands/README / ROADMAP updated.

Coverage: - Knowledge: 43 → 52 (28 hand-written + 15 generated → 37 hand-written + 15 generated). - Skills: 10 → 12 (all with verification phase). - Commands: 6 → 8. - Examples: 66 → 70. - Total lines: ~42K → ~52K.

Phase 9 — MCP integrations (v1.8) ✓ shipped

• MCP-INTEGRATION.md overview — supported MCPs (Tier 1: Figma/Notion/GitHub/Slack; Tier 2: Linear/Atlassian/Asana/Intercom), setup per agent, graceful fallback strategy, MCP catalog with design-ai relevance.
• 5 per-MCP integration guides in docs/integrations/:
• figma-mcp.md — read variables/components, audit Figma designs, spec components from Figma, write tokens (limited), Code Connect via MCP.
• notion-mcp.md — mirror knowledge to Notion, capture design decisions, read brand briefs, weekly status.
• github-mcp.md — PR design review, issue creation for design debt, status reports, token-bump notifications.
• slack-mcp.md — design review summaries, token version notifications, palette artifacts, scheduled status posts.
• linear-mcp.md — convert audit findings to issues, track design system rollout, severity → priority mapping.
• 3 MCP-aware skills:
• skills/design-pr-review/ — reviews GitHub PRs for design compliance (uses GitHub MCP, falls back to markdown output).
• skills/figma-token-sync/ — bidirectional token sync Figma↔code (uses Figma MCP, falls back to Tokens Studio).
• skills/design-broadcast/ — post artifacts to Slack/Notion (uses Slack + Notion MCPs, falls back to formatted paste).
• AGENTS.md adds "Use MCPs when available" section + skill lookup entries. Skills: 7 → 10.

Phase 8 — Last big push (v1.7) ✓ shipped

• 10 component specs: FloatButton, QRCode, Splitter, Anchor, AppBar, Layout, InputOTP, Watermark, Code, Typography. Coverage 18.6% → ~22%.
• 3 Korean fintech custom specs: StockChart (KR-inverted convention), KRWAmount (display-only), PaymentReceipt (Korean dotted-divider receipt).
• Figma plugin scaffold (tools/figma-plugin/): manifest.json, code.ts (sandbox), ui.html (paste-to-import), Code Connect examples for Button/Input/Card.
• CI workflows (.github/workflows/): audit.yml (frontmatter + link + coverage validation on PR + size budget), release.yml (CHANGELOG + tarball on tag push).
• Korean copy validator (tools/audit/korean-copy-check.py): heuristic scan of Korean-relevant files for English UI strings, suggests Korean equivalents.
• AGENTS.md / examples/README / ROADMAP updated. Examples: 53 → 66.

Phase 7 — Coverage push + automation tooling (v1.6) ✓ shipped

• Cursor + Aider integration guides (docs/CURSOR-INTEGRATION.md, docs/AIDER-INTEGRATION.md): .cursorrules template, @-mention patterns, Aider --read configuration, per-task aliases.
• 10 component specs (Cascader, ColorPicker, Transfer, Spin, Segmented, AutoComplete, Mention, Timeline, Tour, Affix): coverage 14.6% → 19.6%.
• 3 Korean fintech custom specs: CategoryPicker (가계부 emoji-first), TransactionListItem (high-volume row), AccountCard (banking card).
• 3 automation tools (tools/audit/):
• changelog-generate.py — generates CHANGELOG.md from git log
• frontmatter-check.py — validates YAML frontmatter on knowledge files
• link-check.py — validates internal markdown links resolve
• AGENTS.md / examples/README / README updated. Knowledge: 43 → 43 (added 0 — all of v1.6 was examples + tooling). Examples: 40 → 53.

Phase 6 — Token references + QA + integrations ✓ shipped (v1.5)

• 3 design token reference docs:
• knowledge/design-tokens/tailwind-v4.md — OKLCH defaults, full color/spacing/typography/motion
• knowledge/design-tokens/material-3.md — HCT tonal palettes, container pattern, M3 type scale
• knowledge/design-tokens/polaris-and-carbon.md — Shopify + IBM enterprise reference
• New skill: design-system-qa — 5-layer test pyramid audit (TypeScript / token drift / contract / a11y / visual regression)
• knowledge/patterns/design-system-qa.md — full QA layer model
• docs/CODEX-INTEGRATION.md — Codex CLI deep-dive: skill invocation, slash command translation, MCP setup, token budget per task, common pitfalls
• docs/PLUGIN-PACKAGING.md — current symlink approach + future Claude Code plugin format, distribution channels, versioning, CI for releases
• AGENTS.md / skills/README / README updated. Skills: 6 → 7.
• Token references: 1 → 4. Knowledge: 39 → 43.

Phase 5 — Coverage push + data viz + Korean fintech ✓ shipped (v1.4)

• 8 component specs: Tag+Badge, Tree, Statistic, Upload, Result+Empty, Carousel, Image, Calendar.
• 3 Korean fintech custom specs: BiometricGate, PaymentMethodSelector, PaymentBrandButton (KakaoPay/NaverPay/Toss/Apple/Samsung).
• 3 data visualization knowledge files: dashboard-composition (3 archetypes, KPI→chart→table), chart-color-encoding (sequential/diverging/categorical, colorblind, KR stock convention), realtime-data (WebSocket vs polling, optimistic UI, disconnection, throttling).
• Component spec coverage: 23 → ~32 worked specs (~16% — exceeds the 20% canonical target since several specs cover multiple canonical components).
• PRINCIPLES.md extended with data viz rules (31–35).
• AGENTS.md / examples/README / ROADMAP updated.

Phase 4 — Depth + agent priming ✓ shipped (v1.3)

• knowledge/PRINCIPLES.md — agent priming cheat sheet. 30 load-bearing rules across the system, each citing its deeper file. Loaded at session start.
• 5 universal pattern knowledge files: empty-states.md, error-states.md, onboarding.md, search-ux.md, settings-page.md.
• 6 more component specs: Drawer, Slider, Popover, Divider, Steps, Rate.
• 2 custom component specs (Korean fintech): component-amount-input.md, component-address-input.md — proves the system handles non-upstream patterns.
• Component spec coverage: 19 → 27 worked specs (8.5% → ~13%).
• AGENTS.md updated with new lookup-table entries. ROADMAP marked.

Phase 3 — Connective ✓ shipped (v1.2)

• /design-from-brief — full design from a one-paragraph product brief. Orchestrates color-palette + design-system-builder + handoff-spec.
• /iterate — apply a critique and produce a revision + changelog.
• HTML preview generator (tools/preview/render-tokens.py) — extracts tokens, renders light+dark swatches, contrast matrix, live component previews, theme toggle.
• Component spec coverage push: 11 → 19 worked specs (5% → 8.5%). New: Alert, Tooltip, Form-controls (Switch/Checkbox/Radio combined), Skeleton, Progress, Avatar, Breadcrumb, Accordion.
• Optional embedding index if knowledge base exceeds 100K tokens. (Deferred — base is currently ~13K lines / well under threshold.)

Phase 4 — Multi-tool ✓ shipped

• Codex CLI: real-world session against this repo, captured as a worked example. (docs/integrations/codex-walkthrough.md)
• Cursor .cursorrules overlay. (docs/integrations/cursor-walkthrough.md)
• Aider configuration. (docs/integrations/aider-walkthrough.md)

Phase 5 — Maturity (public site / packaging shipped)

• Versioned knowledge files (semver headers). (frontmatter version field on every knowledge file, enforced by the frontmatter audit)
• CHANGELOG that summarizes upstream-source updates affecting refs/.
• Public site (knowledge/ as a browsable doc site). (GitHub Pages: https://sungjin9288.github.io/design-ai/)
• Plugin packaging — install design-ai as a Claude Code plugin / VS Code extension. (.claude-plugin/plugin.json + VS Code Marketplace sungjin.design-ai-vscode v0.4.1)

Out of scope

• Image generation. We produce specs, tokens, and code-ready artifacts. Visual mockups go through Figma / external tools.
• Brand strategy. We assume a brand has constraints and translate them into tokens/components.
• Custom font design. We pair existing fonts.
• Implementing actual product code. design-ai produces the contract; the consuming product implements.