@design-ai/cli 4.56.0 → 4.57.0

package/docs/RELEASE-GATES.md

@@ -0,0 +1,234 @@
+# Release gates — full assertion detail
+
+This file preserves the complete, unabridged text that previously lived in
+`README.md`'s `## Status` and `## Contributing` sections. It exists so the
+README can carry a short summary while this document keeps every factual
+claim about what `release:check`, packed-tarball smoke, and registry smoke
+actually verify. Nothing below has been dropped or reworded from the
+original README prose — only split into bullets at natural boundaries
+(", plus ", " also verifies ", "and ", etc.) for readability.
+
+See `README.md` for the short version, [`docs/ROADMAP.md`](ROADMAP.md)
+for the full phase log, and [`docs/PRODUCT-READINESS.md`](PRODUCT-READINESS.md)
+for the current completion boundary.
+
+## Status detail (v4.56.0)
+
+Currently at **v4.56.0**: public npm publish, provenance-backed GitHub Actions
+release, public registry smoke, Website Console MCP readiness, workspace
+learning restore/eval coverage, handoff bundle verification, and 90%+
+component coverage are complete.
+
+Core design consulting workflows are locally release-ready. The website
+improvement control tower is available as a zero-dependency static Web App at
+[`docs/website-console/index.html`](website-console/index.html), plus a
+`website-improvement` route/skill/command for:
+
+- Site Profiles, audit checklists, MCP readiness, refactor prompts
+- Browser-local handoff evidence tracking
+- CLI/bundle evidence export with verified bundle evidence metadata
+- Generated bundle contract verification
+- Bundle repair preview/apply with repair report `--out file` output-file persistence
+- Packed-tarball evidence preservation smoke coverage
+- Handoff reports
+
+Local learning preferences are available through `design-ai learn`, with:
+
+- Starter profile bootstrap via preview-first `learn --init`
+- Explicit `learn --feedback` keep/improve/avoid guidance
+- Explicit `check --learn --yes` capture for local QA warning/failure results
+- Read-only `learn --signals` registry reports that join learning audit, usage sidecar, eval signal files, check capture entries, deterministic agent development backlog actions, and workspace readiness without mutating `learning.json`
+- Focused read-only `learn --agent-backlog` reports that expose only the local AI/agent next-action queue with JSON/Markdown output and strict gating
+- `learn --signals --report --out learning-signals.md` Markdown handoff artifacts
+- `learn --signals --strict` gating for warning/failing signal registry or backlog status
+- Preview-only `learn --propose-skills` reports that convert repeated check-capture signals into candidate skill instruction deltas without editing skill files
+- Adjustable `learn --propose-skills --min-evidence N` thresholds for stricter or faster local proposal review
+- Read-only `learn --propose-skills --review-file skill-proposals.review.json` decision joins for applied/rejected proposal state
+- Read-only `learn --propose-skills --review-file skill-proposals.review.json --review-check` review-file readiness checks for current proposals
+- Read-only `learn --propose-skills --review-file skill-proposals.review.json --apply-plan` accepted proposal apply plans for manual skill edits
+- `--review-template --out skill-proposals.review.json` JSON decision scaffolds
+- `--report --out skill-proposals.md` Markdown review artifacts
+- Preview-only `--patch --out skill-proposals.patch` unified diff handoffs for manual review
+- `learn --propose-skills --strict` gating when proposal review or upstream signal readiness is pending
+- Read-only `design-ai workspace` dogfood readiness snapshots for git, canonical repository remote/metadata alignment, learning, optional or sibling `--learning-usage` sidecar summaries with stale selected-id/profile-mismatch readiness warnings
+- Optional `--learning-eval` checkpoint summaries with freshness metadata
+- Automatic sibling `learning-eval.json` checkpoint detection
+- Checkpoint freshness warnings when the active learning profile changed after checkpoint generation or no longer matches checkpoint metadata
+- Shell-safe learning usage/eval next-action commands for local paths
+- Usage-aware `learn --curate --usage-file` next actions when learning profile audit or usage sidecar drift needs review
+- Companion `learn --curate --report --out learning-curation-report.md` workspace report next actions before archive cleanup
+- Eval-template bootstrap next-action hints when a clean learning profile has entries but no checkpoint
+- Release-script state with `--strict` readiness gating
+
+`design-ai site` covers:
+
+- Sample workspace generation, prompt template listing
+- Deterministic MCP readiness checks through `--mcp-check`
+- Opt-in read-only MCP probe checks through `--mcp-check --probes`
+- Markdown or JSON MCP action plan export through `--mcp-plan`, `--mcp-plan --probes`, and `--mcp-plan --probes --json`
+- Portable workflow graph export through `--graph --json`
+- Complete handoff bundle export through `--bundle --out`
+- Handoff bundle checksum/fingerprint and generated contract verification through `--bundle-check --strict --json`
+- Handoff bundle comparison through `--bundle-compare --strict --json`
+- Target-repo handoff prompt generation from a verified bundle through `--bundle-handoff --strict --json`
+- Local handoff bundle repair through `--bundle-repair --yes --json`
+- Refactor task generation, single prompt template export with task selection
+- Validation/report/prompt generation from Website Console JSON exports
+
+Additional learning surfaces:
+
+- Full portable `learn --backup --json` profile export with safe `--out` file output and `--force` overwrite control
+- Redacted portable `learn --redact --json` profile export for sharing from the local profile or portable JSON via `--from-file` / `--stdin`
+- Non-mutating `learn --verify` import validation
+- Read-only `learn --diff` profile comparison against portable JSON
+- Preview-first full-profile `learn --restore` replacement from portable backups with automatic rollback backup and optional `--backup-file` path
+- Read-only `learn --restore-backups` inventory for sibling rollback backups
+- Preview-first `learn --restore-backups --prune --keep N` cleanup for older sibling rollback backups
+- Portable `learn --import` dry-run/confirmed profile merge
+- Query-filtered `learn --list --explain` / `learn --export` inspection without recency fallback
+- Read-only `learn --audit` cleanup suggestions / `learn --stats`
+- Read-only `learn --usage` reports for local prompt/pack usage sidecar activity
+- Runnable `learn --eval-template` checkpoint generation from the active profile
+- Read-only `learn --eval` checkpoint reports for deterministic local learning selection QA with `--strict` failure gating and sanitized checkpoint metadata
+- Safe `learn --audit --fix --dry-run` previews plus confirmed `--fix --yes` cleanup
+- Archive-first `learn --curate` preview/apply flow for duplicate and sensitive learning entries plus `learn --curate --report --out` Markdown audit trails and advisory usage review hints for profile mismatch, stale selected ids, and unused active entries
+- Opt-in `prompt`/`pack --with-learning` with brief-relevance ranking, category/limit scoping, selection scoring metadata, learned-context audit summaries, and local `learning.usage.json` sidecar events that store selected entry ids plus a short brief hash instead of raw brief text
+
+**AI model training or fine-tuning remains outside the shipped scope.**
+
+The corpus has been audited under CI checks since v1.7. It currently runs 8 audits:
+- Frontmatter validity
+- Internal link resolution
+- Korean copy quality
+- Raw hex color hygiene in examples
+- Integration walkthrough completeness
+- Stale-content freshness
+- Component coverage report freshness
+- Top worked example QA for every routed workflow
+
+All 8 pass on every commit to `main`.
+
+## release:check coverage
+
+`npm run release:check` is the core gate before release PRs or tags. It covers:
+
+- `npm test` CLI unit tests
+- `npm run audit:strict` all 8 audits
+- `git diff --check` whitespace checks
+- `npm run package:check` package contents checks
+- `npm run release:metadata` release metadata checks with release metadata JSON `product_readiness_checked: true` Product Readiness guard coverage
+- `npm run release:self-test` release assertion self-tests (including audit runner exit-code and coverage timestamp preservation fixtures)
+- `npm run package:smoke` packed-tarball smoke for installed-bin plus one-shot `npm exec --package <tarball>` paths, covering:
+  - `design-ai workspace --strict --json` workspace strict failure/success readiness checks plus workspace `--learning-usage` sidecar summaries and workspace `--learning-eval` checkpoint summaries with freshness metadata plus `design-ai workspace` workspace learning restore-backups readiness with restore rollback backup inventory
+  - `design-ai site --stdin --json` Website Console export validation
+  - `design-ai site --stdin --next-actions --json --out file --force` Website Console next-action operator checklist output-file persistence
+  - `design-ai site --stdin --next-actions --out file --force` Website Console next-action human checklist output-file persistence
+  - `design-ai site --sample` Website Console sample workspace coverage
+  - `design-ai site --intake-template` Website Console intake template coverage for JSON stdout, Markdown stdout, Markdown `--out`, JSON `--out`, and `--language ko` Korean JSON/Markdown plus Korean Markdown `--out` in installed-bin and one-shot paths
+  - `design-ai site --from-intake` Website Console from-intake filled Markdown intake import coverage for workspace JSON stdout, stdin workspace JSON stdout, stdin next-actions JSON stdout, stdin next-actions JSON `--out` file output-file persistence, stdin next-actions human `--out` file output-file persistence, stdin workspace JSON `--out` file output-file persistence, workspace JSON `--out` file output-file persistence, from-intake task generation, stdin from-intake task JSON `--out` output-file persistence, from-intake task handoff bundle generation, stdin from-intake task handoff bundle generation, stdin handoff bundle generation, and from-intake handoff bundle generation in installed-bin and one-shot paths
+  - `design-ai site --init` Website Console project init workspace coverage in installed-bin and one-shot paths
+  - `design-ai site --init --bundle --out <dir>` Website Console init handoff bundle coverage in package bin path and one-shot paths
+  - `design-ai site --prompt-list --json` Website Console prompt template listing
+  - `design-ai site --stdin --mcp-check --json` Website Console MCP readiness check
+  - `design-ai site --stdin --mcp-check --probes --json` Website Console MCP readiness probe JSON with `--out` file-write confirmation plus shared MCP probe output-file smoke assertions plus embedded MCP check probe next-step commands plus executable embedded MCP check probe command smoke coverage plus human MCP check probe command guidance and output-file smoke coverage plus embedded MCP check probe human report output command
+  - `design-ai site --stdin --mcp-plan` Website Console MCP action plan
+  - `design-ai site --stdin --mcp-plan --probes` Website Console MCP probe action plan
+  - `design-ai site --stdin --mcp-plan --probes --json` Website Console MCP probe action plan JSON with `--out` file-write confirmation plus embedded MCP action plan probe output-file commands plus MCP action plan human report output command parity plus MCP action plan emitted human report command smoke coverage plus MCP action plan emitted check JSON command smoke coverage plus MCP action plan emitted self-archive command smoke coverage plus shared MCP action plan command mapping self-test coverage
+  - `design-ai site --stdin --graph --json` Website Console workflow graph export
+  - `design-ai site --stdin --bundle --out <dir>` Website Console handoff bundle
+  - `design-ai site <bundle-dir> --bundle-check --strict --json` Website Console handoff bundle check with SHA-256 checksum verification, bundle digest/fingerprint verification, and generated bundle contract verification
+  - `design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> --strict --json` Website Console handoff bundle compare with bundle digest comparison plus packed-tarball and public-registry smoke for warning-state Website Console bundle-compare strict failures where identical warning bundles keep `sameBundle: true` while exiting non-zero under `--strict`
+  - `design-ai site <bundle-dir> --bundle-handoff --strict --json` Website Console target-repo handoff prompt from a verified bundle digest plus `--bundle-handoff --task task-content-quality --strict --json` task-selected bundle handoff
+  - `design-ai site <bundle-dir> --bundle-repair --yes --json` Website Console bundle repair preview/apply drift recovery with repair report `--out file` output-file persistence, shared repair guidance smoke helpers, and shared repair report assertion helpers
+  - `design-ai site --stdin --tasks` Website Console refactor task generation
+  - `design-ai site --stdin --prompt codex-implementation --task task-homepage-cta` Website Console task-selected single prompt generation
+  - Human `design-ai version` and machine-readable version metadata from JSON `design-ai version --json`
+  - `design-ai help` top-level help, the `design-ai help --json` topic catalog with probe-capable Website Console site help usage, command alias help and functional alias output, command-specific help topic output, shared Website Console site help topic example smoke assertions including the `design-ai site website-workspace.json --next-actions --out website-next-actions.md` next-actions Markdown help example plus from-intake stdin help examples (`cat company-website-intake.ko.md | design-ai site --from-intake --stdin --out website-workspace.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --next-actions --out website-next-actions.md --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --tasks --out website-workspace.tasks.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --bundle --tasks --out website-handoff-bundle`)
+  - All three `list` catalog domains in human and JSON mode, human / JSON corpus discovery output, route JSON output, route catalog output, and route stdin input
+  - Explicit `show --lines` output and `route --explain` output
+  - Unknown command failure, unknown help-topic failure, unknown list-domain failure, and unknown search-dir failure
+  - Unknown route-id suggestion, unknown option suggestion, unknown value suggestion, and numeric range failure
+  - 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
+  - Prompt/pack forced `--out` overwrite and prompt/pack file-write confirmations
+  - Check examples output, check artifact output, check stdin output, check all-routes output, and check learning capture output
+  - Human `design-ai audit --strict --quiet` output and JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output
+  - JSON `design-ai learn --feedback` output plus learn feedback `--out` file-write confirmation
+  - JSON `design-ai learn --init` output, JSON `design-ai learn --backup` output, JSON `design-ai learn --redact` output, `design-ai learn --redact --from-file` output, `design-ai learn --redact --stdin` output, learn JSON `--out` file-write confirmation and forced overwrite coverage
+  - JSON `design-ai learn --verify` output plus learn verify `--out` file-write confirmation
+  - JSON `design-ai learn --restore` preview/apply output plus learn restore `--out` file-write confirmation plus learn restore rollback backup verification plus learn restore `--backup-file` path coverage plus `design-ai learn --restore-backups` restore rollback backup inventory coverage plus `design-ai learn --restore-backups --prune` restore rollback backup pruning coverage
+  - JSON `design-ai learn --import` dry-run/apply output plus learn import `--out` file-write confirmation
+  - Human / JSON `design-ai learn --stats` profile summary output plus learn stats `--out` file-write confirmation
+  - Query-filtered human learn list explanation and export JSON output
+  - Brief-relevant prompt/pack learning selection, prompt/pack learning usage sidecar recording
+  - Human / JSON `design-ai learn --usage` usage sidecar report plus learn usage `--out` file-write confirmation
+  - Human / JSON `design-ai learn --signals` learning signal registry plus `design-ai learn --signals --strict --json` strict gate plus learn signals `--out` file-write confirmation
+  - Human / JSON `design-ai learn --eval-template` checkpoint generation plus generated checkpoint strict validation
+  - Human / JSON `design-ai learn --eval` checkpoint report plus learn eval `--out` file-write confirmation plus learn eval `--strict` failure gate
+  - Human / JSON `design-ai learn --audit` cleanup suggestion output plus learn audit `--out` file-write confirmation
+  - Human / JSON `design-ai learn --curate` archive-first curation output plus usage-aware curation JSON review
+  - Human `design-ai update --dry-run` output, `design-ai update --dry-run --json` machine-readable update plan
+  - Human diagnostics output from `design-ai doctor --strict`, machine-readable diagnostics output from `design-ai doctor --json`
+  - Human `design-ai install` output plus `design-ai install --json` machine-readable install lifecycle output
+  - Human `design-ai status` output plus JSON status including `design-ai status --json` machine-readable install-state output
+  - Human `design-ai uninstall` output plus `design-ai uninstall --json` machine-readable uninstall lifecycle output
+
+Additional preserved guard phases under the same `npm run release:check` gate:
+
+- Website Console bundle `mcp-probes.json` saved-payload guard phases through package contents, release self-tests, and packed-tarball smoke.
+- Website Console bundle boundary metadata guard phases for bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata plus full `release:self-test` evidence recording through unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
+- The Product Readiness release policy full gate guard for Website Console bundle boundary metadata full `release:check` evidence through unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
+- The Product Readiness release policy full gate evidence guard through unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
+
+## Packed-tarball smoke coverage
+
+In addition to the release:check coverage above, packed-tarball smoke also verifies:
+
+- Route eval, prompt eval, and pack eval checkpoint output for installed-bin and one-shot `npm exec --package <tarball>` paths.
+- `design-ai learn --signals --report --out learning-signals.md` Markdown signal reports, learn signals JSON `--out` file-write confirmations, and `design-ai learn --agent-backlog --report --out agent-backlog.md` focused agent backlog Markdown reports plus agent backlog JSON `--out` file-write confirmations and `design-ai learn --agent-backlog --strict --json` agent backlog strict gates, focused agent backlog readiness summaries, `optionalGapDetails` JSON field coverage, check index JSON field coverage, Markdown check index section coverage, and check-capture optional-gap semantics for installed-bin and one-shot `npm exec --package <tarball>` paths. That smoke coverage also preserves the optional refresh-only runbook selection reason so no-command agent backlog output treats refresh as status metadata, not an executable handoff command.
+- `design-ai learn --propose-skills --min-evidence 3 --json` threshold skipping, learn skill proposals JSON `--out` file-write confirmations, `design-ai learn --propose-skills --report --out skill-proposals.md` Markdown review artifacts, `design-ai learn --propose-skills --review-file skill-proposals.review.json --json` read-only review decision joins, `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --json` read-only review-file readiness checks, `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md` read-only review-check Markdown reports, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json` read-only accepted proposal apply plans, human apply-plan command contract summaries via `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan` with the `Command contract` section, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --report --out skill-proposal-apply-plan.md` read-only apply-plan Markdown reports, `design-ai learn --propose-skills --review-template --out skill-proposals.review.json` JSON review templates, `design-ai learn --propose-skills --patch --out skill-proposals.patch` unified diff handoffs, and `design-ai learn --propose-skills --strict --json` as an expected-failure skill proposal readiness gate for installed-bin and one-shot `npm exec --package <tarball>` paths.
+
+## Registry smoke coverage
+
+After npm publish completes, `npm run registry:smoke` verifies the public `npm exec --package` install path, including:
+
+- Human `design-ai version` and machine-readable version metadata from JSON `design-ai version --json`
+- `design-ai help` top-level help, the `design-ai help --json` topic catalog with probe-capable Website Console site help usage, functional aliases
+- All three `list` catalog domains in human and JSON mode, human / JSON corpus discovery output, route JSON output, route catalog output, and route stdin input
+- Explicit `show --lines` output and `route --explain` output
+- Unknown command failure, unknown help-topic failure, unknown list-domain failure, and unknown search-dir failure
+- Unknown route-id suggestion, unknown option suggestion, unknown value suggestion, and numeric range failure
+- 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
+- Prompt/pack forced `--out` overwrite and prompt/pack file-write confirmations
+- Check examples output, check artifact output, check stdin output, check all-routes output, and check learning capture output
+- Human `design-ai audit --strict --quiet` output and JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output
+- Public registry JSON `design-ai learn --verify` output plus public registry learn verify `--out` file-write confirmation
+- Public registry JSON `design-ai learn --backup` output plus public registry learn backup `--out` file-write confirmation
+- Public registry human / JSON `design-ai learn --stats` profile summary output plus public registry learn stats `--out` file-write confirmation
+- Human `design-ai update --dry-run` output, `design-ai update --dry-run --json` machine-readable update plan
+- Human diagnostics output from `design-ai doctor --strict`, machine-readable diagnostics output from `design-ai doctor --json`
+- Human `design-ai install` output plus `design-ai install --json` machine-readable install lifecycle output
+- Human `design-ai status` output plus JSON status including `design-ai status --json` machine-readable install-state output
+- Human `design-ai uninstall` output plus `design-ai uninstall --json` machine-readable uninstall lifecycle output
+
+Additional registry smoke assertions:
+
+- Registry smoke also verifies public registry `design-ai workspace --strict --json` workspace strict failure/success readiness checks from the published package path.
+- Registry smoke also verifies public registry `design-ai workspace --learning-eval learning-eval.json --strict --json` checkpoint summaries with freshness metadata plus auto-detected learning usage sidecar summaries from the published package path.
+- Registry smoke also verifies public registry `design-ai workspace` workspace restore-backups readiness with restore rollback backup inventory from the published package path.
+- Registry smoke also verifies public registry `design-ai site` Website Console export validation, including public registry `design-ai site --stdin --next-actions --json` next-action operator checklist contract with `mcpProbeCounts` probe count telemetry plus shared smoke assertion self-test coverage for Website Console next-actions MCP probe counts plus public registry `design-ai site --stdin --next-actions --json --out file --force` next-action operator checklist output-file persistence plus public registry `design-ai site --stdin --next-actions --out file --force` next-action human checklist output-file persistence, sample workspace coverage, prompt template listing, MCP readiness, MCP readiness probes, MCP readiness probe JSON with `--out` file-write confirmation plus shared MCP probe output-file smoke assertions plus embedded MCP check probe next-step commands plus executable embedded MCP check probe command smoke coverage plus human MCP check probe command guidance and output-file smoke coverage plus embedded MCP check probe human report output command, MCP action plan, MCP probe action plan, MCP probe action plan JSON with `--out` file-write confirmation plus embedded MCP action plan probe output-file commands plus MCP action plan human report output command parity plus MCP action plan emitted human report command smoke coverage plus MCP action plan emitted check JSON command smoke coverage plus MCP action plan emitted self-archive command smoke coverage plus shared MCP action plan command mapping self-test coverage, handoff bundle, bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata for deterministic-local, no-external-call, and no-target-repo-mutation handoff validation, bundle-check/compare/handoff `mcpProbeCounts` probe count telemetry plus package smoke self-test coverage for Website Console bundle MCP probe counts plus bundled Website Console `mcp-probes.json` saved probe evidence payload assertion instead of the full `site --mcp-check --probes --json` response, bundle-repair, refactor task generation, and task-selected prompt generation from the published package path.
+- Registry smoke also verifies public registry JSON `design-ai learn --feedback` output plus public registry learn feedback `--out` file-write confirmation, public registry `design-ai learn --feedback --from-file`, public registry `design-ai learn --feedback --stdin`, public registry JSON `design-ai learn --init` preview/apply output, and public registry learn init duplicate-skip output.
+- Registry smoke also verifies public registry JSON `design-ai learn --restore` preview/apply output plus public registry learn restore `--out` file-write confirmation, public registry learn restore rollback backup verification, public registry learn restore `--backup-file` path coverage, public registry `design-ai learn --restore-backups` restore rollback backup inventory coverage, and public registry `design-ai learn --restore-backups --prune` restore rollback backup pruning coverage.
+- Registry smoke also verifies public registry JSON `design-ai learn --import` dry-run/apply output plus public registry learn import `--out` file-write confirmation plus public registry JSON `design-ai learn --redact` output, public registry `design-ai learn --redact --from-file`, public registry `design-ai learn --redact --stdin`, and public registry learn redact `--out` file-write confirmation.
+- Registry smoke also verifies public registry human / JSON `design-ai learn --audit` cleanup suggestion output plus public registry learn audit `--out` file-write confirmation and public registry `design-ai learn --audit --fix --dry-run` cleanup preview and confirmed apply output.
+- Registry smoke also verifies public registry query-filtered learn list explanation/export JSON output, public registry brief-relevant prompt/pack learning selection and prompt/pack learning usage sidecar recording with public registry prompt/pack --with-learning, and public registry `design-ai learn --eval-template` checkpoint generation plus public registry generated checkpoint strict validation.
+- Registry smoke also verifies public registry learning readiness Markdown report coverage so `design-ai learn --signals --report --out learning-signals.md` and `design-ai learn --agent-backlog --report --out agent-backlog.md` preserve the `Readiness check index` section from the published package path.
+
+## Other release:check bar items
+
+These are short items that were already concise in the README and remain there as well as here for completeness:
+
+- Knowledge files use `<!-- hand-written -->` marker if hand-authored.
+- Skill PLAYBOOKs include a verification phase checklist.
+- Korean strings spelled out in Korean (no machine translation passing through).
+- All audits pass.
+- Before pushing for CI, run `npm run ci:local` when you need local parity with the non-publishing GitHub workflows. It wraps `release:check`, Python syntax checks, knowledge size budget, VS Code extension compile/unit tests, the MkDocs build, and the MkDocs warning policy used by the docs deployment workflow: no non-`refs/` warnings, with refs-only warnings capped at the accepted baseline.

package/docs/ROADMAP.md

@@ -1,5 +1,50 @@
 # Roadmap
 
+## 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](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](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](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](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](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
+- [x] 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`.
+- [x] Phase A: opt-in `design-ai search --ranked` ranked corpus search with deterministic, fully ordered output.
+- [x] 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._
+- [x] Phase A: `design-ai index --status/--verify` staleness and digest reporting, plus `workspace` readiness integration.
+- [x] 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.
+- [x] 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.
+- [x] 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.
+- [x] Answer the open questions in [AI-LEARNING-PHASE2.md](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.
@@ -21653,18 +21698,18 @@ Coverage:
 - [x] 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
+## Phase 4 — Multi-tool ✓ shipped
 
-- [ ] Codex CLI: real-world session against this repo, captured as a worked example.
-- [ ] Cursor `.cursorrules` overlay.
-- [ ] Aider configuration.
+- [x] Codex CLI: real-world session against this repo, captured as a worked example. _([docs/integrations/codex-walkthrough.md](integrations/codex-walkthrough.md))_
+- [x] Cursor `.cursorrules` overlay. _([docs/integrations/cursor-walkthrough.md](integrations/cursor-walkthrough.md))_
+- [x] Aider configuration. _([docs/integrations/aider-walkthrough.md](integrations/aider-walkthrough.md))_
 
-## Phase 5 — Maturity
+## Phase 5 — Maturity (public site / packaging shipped)
 
-- [ ] Versioned knowledge files (semver headers).
+- [x] 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).
-- [ ] Plugin packaging — install design-ai as a Claude Code plugin / VS Code extension.
+- [x] Public site (knowledge/ as a browsable doc site). _(GitHub Pages: https://sungjin9288.github.io/design-ai/)_
+- [x] 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
 

package/docs/external-status.md

@@ -5,24 +5,24 @@
 
 ## Summary
 
-Local release readiness is verified, GitHub Pages docs are publicly reachable, GitHub Release `v4.56.0` is published, and the Homebrew tap formula points at the `v4.56.0` release source tarball with a verified SHA-256. npm is still publicly published at `@design-ai/cli@4.55.0`; the latest `v4.56.0` npm publish attempt authenticated as `sungjin9288`, passed package smoke, signed provenance, then failed on registry `E403` because npm requires either two-factor authentication during publish or a granular access token with Bypass 2FA enabled. Replace `NPM_TOKEN` with a publish-capable granular token for `@design-ai/cli` that has Bypass 2FA enabled, or migrate the workflow to npm Trusted Publishing, before rerunning. The VS Code extension `sungjin.design-ai-vscode` is published to the VS Code Marketplace at version `0.4.1`; the Gallery API is reachable. The public npm MCP entrypoint and the local Claude Code / Codex MCP client registrations were rechecked on 2026-07-02.
+Local release readiness is verified, GitHub Pages docs are publicly reachable, GitHub Release `v4.56.0` is published, and the Homebrew tap formula points at the `v4.56.0` release source tarball with a verified SHA-256. npm is publicly published at `@design-ai/cli@4.56.0`; publish run `28569283984` succeeded with provenance and the public registry smoke passed. The VS Code extension `sungjin.design-ai-vscode` is published to the VS Code Marketplace at version `0.4.1`; the Gallery API is reachable. The public npm MCP entrypoint and the local Claude Code / Codex MCP client registrations were rechecked on 2026-07-02.
 
 ## Results
 
 | Surface | Checked target | Result | Evidence |
 |---|---|---|---|
-| npm registry | `@design-ai/cli` | Published latest remains `4.55.0`; public registry smoke passed for `@design-ai/cli@4.55.0`. Latest `v4.56.0` publish run `28568106904` authenticated `NPM_TOKEN`, passed package smoke, signed provenance, then failed with `E403` because npm requires 2FA during publish or a granular access token with Bypass 2FA enabled. | `evidence/cli-logs/npm-registry-status.log`, `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/npm-publish-v4.56.0-failed.log`, `evidence/cli-logs/npm-publish-v4.56.0-preflight-failed.log`, `evidence/cli-logs/npm-publish-v4.56.0-bypass-2fa-required-20260702.log` |
+| npm registry | `@design-ai/cli` | Published latest is `4.56.0`; publish run `28569283984` succeeded and public registry smoke passed for `@design-ai/cli@4.56.0`. | `evidence/cli-logs/npm-registry-status.log`, `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/npm-publish-v4.56.0-success.log` |
 | GitHub Pages | `https://sungjin9288.github.io/design-ai/` | Published and reachable: HTTP `200`, design-ai MkDocs page rendered | `evidence/cli-logs/github-pages-status.log` |
 | Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.56.0` release source tarball with SHA-256 `507d2519296497defcd486c0ffc2b5164967a0bc540ddc31bc89502350688212`; Ruby syntax and `brew style` passed | `evidence/cli-logs/homebrew-formula-status.log` |
 | VS Code Marketplace | `sungjin.design-ai-vscode` | Published: run `28431571256` published `v0.4.1`, and the Marketplace Gallery API returned visible version `0.4.1` on 2026-07-02. | `evidence/cli-logs/vscode-marketplace-status.log`, `evidence/cli-logs/vscode-marketplace-secret-status.log`, `evidence/cli-logs/vscode-extension-vsce-package.log`, `evidence/cli-logs/vscode-publish-workflow-status.log` |
 | GitHub Release | `v4.56.0` | Published with release tarball asset `design-ai-cli-4.56.0.tgz` | `evidence/cli-logs/github-release-v4.56.0.log` |
-| MCP server | `@design-ai/cli@4.55.0` / local clone | Public npm `design-ai-mcp` responds to initialize and tools/list with 10 tools; local Codex and Claude Code both report `design-ai` MCP as configured and connected. | `evidence/cli-logs/design-ai-mcp-public-registry-smoke.log`, `evidence/cli-logs/design-ai-mcp-client-status.log` |
+| MCP server | `@design-ai/cli@4.56.0` / local clone | Public npm `design-ai-mcp` responds to initialize and tools/list with 10 tools; local Codex and Claude Code both report `design-ai` MCP as configured and connected. | `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/design-ai-mcp-client-status.log` |
 
 ## Interpretation
 
 - The repository is locally release-ready based on `npm run release:check`.
 - GitHub Pages docs can now be described as publicly deployed.
-- Public npm install can be described as published and smoke-tested at `4.55.0`; `4.56.0` must not be described as npm-published until `NPM_TOKEN` is replaced with a Bypass 2FA-enabled granular token, or the workflow is migrated to npm Trusted Publishing, and the publish workflow succeeds.
+- Public npm install can now be described as published and smoke-tested at `4.56.0`.
 - Homebrew tap install can now be described as pinned to the `v4.56.0` release tarball; full tap audit/install/test remains a maintainer-side verification step because this Homebrew version rejects path-based `brew audit Formula/...` calls.
 - VS Code Marketplace can now be described as published and publicly reachable at version `0.4.1`.
 - Claude Code and Codex can now be described as locally connected to the clone-backed `design-ai` MCP server, while public npm users can verify the published `design-ai-mcp` entrypoint from a clean working directory.
@@ -36,10 +36,8 @@ curl -sL https://github.com/sungjin9288/design-ai/archive/refs/tags/v4.56.0.tar.
 ruby -c Formula/design-ai.rb
 brew style Formula/design-ai.rb
 gh release view v4.56.0 --repo sungjin9288/design-ai --json tagName,isDraft,isPrerelease,publishedAt,name,url,assets
-gh run view 28561753737 --repo sungjin9288/design-ai --log-failed
-gh run view 28562868536 --repo sungjin9288/design-ai --log-failed
-gh run view 28568106904 --repo sungjin9288/design-ai --log-failed
-npm exec --yes --package=@design-ai/cli@4.55.0 -- design-ai-mcp
+gh run view 28569283984 --repo sungjin9288/design-ai --json status,conclusion,name,url,createdAt,updatedAt
+npm exec --yes --package=@design-ai/cli@4.56.0 -- design-ai-mcp
 codex mcp get design-ai
 claude mcp list
 curl -sS -H 'Content-Type: application/json' \

package/docs/inspection-20260630.md

@@ -0,0 +1,169 @@
+# design-ai 리팩토링·디밸롭 점검 리포트 (2026-06-30)
+
+> 읽기 전용 점검. 코드 변경 없음. 대상: `/Users/sungjin/dev/design` (`@design-ai/cli@4.55.0`).
+> 전제: RAG/파인튜닝이 아니라 **deterministic 지식 코퍼스 + 라우팅**. README도 "Not a model. Not a fine-tune."로 명시 — 전제 유지 확인됨.
+
+---
+
+## 1. 현황 요약
+
+| 항목 | 실측값 | 배경값(2026-06-23) 대비 |
+|---|---|---|
+| 브랜치 | `main` | 동일 |
+| 미커밋 변경 | 없음 (working tree clean) | 동일 |
+| origin 동기화 | `0 0` (ahead 0 / behind 0, 완전 동기화) | 동일 |
+| 패키지 버전 | `4.55.0` | 동일 |
+| `npm test` | **332 pass / 0 fail** (`node --test cli/lib/*.test.mjs`) | 신규 실측 |
+| `npm run audit` | **8/8 audit 통과** (2.16s) | 신규 실측 |
+| `npm audit` (루트) | 실행 불가 — ENOLOCK(락파일 없음, deps 0개) | — |
+| `npm audit` (vscode-extension) | 3건(moderate 2, high 1) — **전부 devDependencies** | 신규 실측 |
+
+최근 커밋 흐름은 전부 VS Code Marketplace publish 마무리 + MCP 서버 추가 + 배포 상태 문서화에 집중되어 있다 (`adf74a3`, `70f72df`, `9387f99`, `6ed2eb6`, `617dd4e` 등). 핵심 코어(라우팅·지식·스킬)는 안정적이고, 활동은 "배포 표면 완성"과 "학습/MCP 부가기능"에 쏠려 있다.
+
+---
+
+## 2. 리팩토링 후보
+
+사용자 코딩 스타일 규칙(파일 800줄 max, 함수 50줄, many-small-files)을 기준으로 측정.
+
+### P1 — 800줄 한계 초과 대형 모듈 (구조적 부채)
+
+| 파일 | 줄 수 | 한계 대비 | 비고 |
+|---|---|---|---|
+| `cli/lib/site.mjs` | **6617** | **8.3×** | Website Improvement 전체 로직 단일 파일. 테스트도 5525줄. |
+| `cli/lib/learn.mjs` | **3694** | 4.6× | 학습 프로필/백업/복원/큐레이션/시그널 전부 응집. |
+| `cli/lib/signals.mjs` | 2337 | 2.9× | 학습 시그널 레지스트리. |
+| `cli/lib/skill-proposals.mjs` | 2046 | 2.6× | 스킬 제안 생성. |
+| `cli/commands/learn.mjs` | 1871 | 2.3× | learn 커맨드 디스패치/플래그. |
+| `cli/lib/workspace.mjs` | 1056 | 1.3× | 워크스페이스 리포트. |
+
+- 권고: `site.mjs`를 기능 경계(intake / bundle / mcp-check / mcp-plan / next-actions / repair)로 모듈 분할. 던전 수호자 씬 분할 패턴(Shared 순수헬퍼 + 렌더 모듈 + ctx 콜백)과 동일한 전략 적용 가능.
+- 주의: 대형 파일 리팩터는 컨텍스트 윈도우 후반부에서 truncation 위험이 큼(메모리 기록된 함정). 모듈당 1 PR로 쪼개고 각 단계 후 `npm test`로 회귀 확인.
+
+### P2 — CLI 커맨드 구조
+
+- `cli/commands/*.mjs` 19개 + `cli/lib/*.mjs` 페어 구조는 일관적이며 양호. 각 lib에 `.test.mjs` 페어(26개 테스트 파일)도 잘 유지됨.
+- `learn` 표면이 비대(README 한 문장에 `--init/--feedback/--signals/--propose-skills/--curate/--restore/--restore-backups/--eval/--audit/...` 등 30+ 서브플래그). 라우팅은 정상이나, **기능 표면 자체가 과적재**되어 신규 기여자 진입장벽이 높다. 서브커맨드 그룹화(`learn signals`, `learn restore`) 고려 여지.
+
+---
+
+## 3. 디밸롭 후보 (publish · MCP 중심)
+
+### 3-A. VS Code Marketplace publish — 현재 진척과 남은 작업
+
+**진척(완료):**
+- `.github/workflows/vscode-publish.yml` 완비: `workflow_dispatch`(dry_run 기본 true), npm ci → compile → test → `vsce package` → VSIX 아티팩트 업로드.
+- publish 단계는 `VSCE_PAT` 부재 시 명확한 에러로 차단(`Verify Marketplace token is configured`).
+- publish 후 Marketplace `extensionquery` API로 listing 존재를 **검증하는 단계**까지 포함 — 견고함.
+- 확장 identity 정합성 OK: `vscode-extension/package.json` → name `design-ai-vscode`, publisher `sungjin`, 워크플로 쿼리 id `sungjin.design-ai-vscode`와 일치. 버전 `0.4.0`.
+- 런타임 의존성 0개(`dependencies: {}`) → VSIX 공급망 위험 없음.
+
+**남은 작업(blocker):**
+1. **`VSCE_PAT` repository secret 미설정** — 유일한 실질 blocker. Azure DevOps에서 Marketplace publish 권한 PAT 발급 → GitHub repo secret 등록 필요(코드/CI 변경 불요).
+2. PAT 등록 후 `dry_run=false`로 워크플로 1회 수동 실행 → 자동 listing 검증 단계 통과 확인.
+3. publish 성공 시 `docs/external-status.md`의 VS Code 행과 README L15 "VS Code Marketplace distribution is not currently confirmed" 문구를 "published"로 갱신.
+
+**리스크:**
+- 코드/설정 리스크는 **낮음**(워크플로 완비, dry-run 검증 경로 존재). 순수하게 **계정/시크릿 운영(operational)** 블로커이며 코드로 풀 수 없음.
+- 부차: 확장 devDependencies 취약점(아래 4장)은 VSIX에 포함되지 않으나, Marketplace 심사/이미지에 영향은 없음.
+
+### 3-B. MCP 서버 안정화 — 현재 진척과 견고성
+
+`cli/lib/mcp-server.mjs`(426줄) + `cli/bin/design-ai-mcp.mjs` + 테스트 135줄.
+
+**견고함(강점):**
+- 11개 툴 모두 **read-only 기본**(`withLearning=true`일 때만 로컬 메타 기록). 입력 스키마 `additionalProperties:false` + `required` 명시 → 경계 검증 양호.
+- 에러 처리 충실: `spawn` 실패 `child.on("error")` 캡처, `assertString` 입력 검증, JSON-RPC 표준 에러코드(`-32700/-32600/-32601/-32602/-32603`), 출력 `MAX_TOOL_OUTPUT_BYTES`(220KB) 트렁케이션.
+- `tools/call` 핸들러는 미지 툴은 `-32602`, 실행 예외는 `isError:true`로 graceful 처리.
+- 테스트가 계약을 잘 고정: tools/list 이름 순서, initialize serverInfo/instructions, `buildCliInvocation` 인자 매핑, 주입 러너 tools/call, **실제 stdio 서브프로세스 왕복**(initialize→list→route) 검증.
+
+**잠재 이슈(우선순위순):**
+1. **계약 안정성 — 프로토콜 버전 고정 리스크 (P1):** `PROTOCOL_VERSION = "2025-11-25"`. `initialize`는 클라이언트가 보낸 `params.protocolVersion`을 그대로 에코백한다(L359). 클라이언트가 미지원 버전을 보내도 서버가 무비판 수용 → 버전 협상(negotiation) 로직 부재. Claude/Codex가 다른 버전을 요구할 때 silent mismatch 가능. **버전 화이트리스트 검증 + 미스매치 시 서버 지원 버전으로 다운그레이드** 권고.
+2. **부분 입력 라인 처리 — readline 경계 (P2):** `startMcpStdioServer`는 `readline` line 단위로 JSON-RPC를 파싱한다. 한 줄에 들어온 잘못된 JSON은 `-32700`으로 안전 응답하지만, **stdout 백프레셔/대형 메시지 분할** 시 라인 기반 가정이 깨질 수 있다. 현재 테스트는 정상 경로만 커버 — `tools/call` 예외/타임아웃/대용량 출력 트렁케이션 경로에 대한 **부정(negative) 테스트가 없음**.
+
+**MCP 테스트 커버리지 평가:** 핵심 정상 경로는 견고하나, (a) 에러/예외 응답, (b) 트렁케이션, (c) 프로토콜 버전 미스매치 — 3개 부정 경로 테스트 보강이 가장 가성비 높은 다음 작업.
+
+---
+
+## 4. 기술 부채 · 위험
+
+| 심각도 | 항목 | 근거 |
+|---|---|---|
+| HIGH | `cli/lib/site.mjs` 6617줄 — 800줄 한계 8배 | 유지보수·리뷰·리팩터 비용 폭증, truncation 위험 |
+| MEDIUM | vscode-extension devDeps 취약점 3건(moderate 2, high 1) | `mocha`→`serialize-javascript`. **VSIX 미포함(runtime deps 0)**이라 출시 차단은 아니나 CI 신호 정리 필요. `npm audit fix` 가능 |
+| MEDIUM | MCP 프로토콜 버전 무검증 에코백 | `mcp-server.mjs` L359 — 버전 협상 부재 |
+| LOW | MCP 부정 경로 테스트 부재 | 에러/트렁케이션/버전 미스매치 미커버 |
+| LOW | `learn` 기능 표면 과적재 | 30+ 서브플래그, 신규 기여자 진입장벽 |
+
+루트 패키지는 **의존성 0개**라 `npm audit`이 ENOLOCK으로 실행 자체가 불가 — 이는 결함이 아니라 zero-dependency 보안 자세의 결과(공급망 표면 최소). vscode-extension만 락파일 보유.
+
+---
+
+## 5. 정직성 · 문서 (배지 수치 포함)
+
+### 배지 수치 검증 (코드/파일 카운트 실측) — **가장 중요**
+
+검증 기준은 저장소 자체 coverage 툴(`tools/audit/check-coverage.py`)의 canonical 카운트와 `knowledge/COVERAGE.md`.
+
+| 배지 | README 주장 | 실측(coverage 툴 canonical) | 일치? |
+|---|---|---|---|
+| Knowledge files | **92** | **92** (77 hand-written + 15 generated) | ✅ 일치 |
+| Skills | **20** | **20** (전부 verification phase 보유) | ✅ 일치 |
+| Examples | **223** | **221** (coverage 툴 + COVERAGE.md L17 모두 221) | ❌ **불일치** |
+
+- **Examples 배지(223)가 stale.** 저장소의 단일 진실원(`check-coverage.py` 출력 `Examples: 221`, `knowledge/COVERAGE.md` "Worked examples | 221")은 **221**을 보고한다. README 배지 L6과 본문 L128("223 worked outputs")이 옛 값.
+  - 참고: `examples/` 디렉터리에는 top-level `component-*.md` 등 **221개** + `README.md` + `cases/`(1 파일) = 디렉터리 엔트리 226개. "223"은 어느 카운트와도 매칭되지 않는 **과거 잔존 수치**로 판단.
+  - 권고(읽기 전용 점검이므로 변경은 미수행): README L6 배지와 L128을 `221`로 갱신, 또는 배지를 coverage 툴이 자동 생성하도록 배선해 drift 재발 차단.
+- Knowledge(92)·Skills(20)는 정확.
+
+### 정직성 스탠스 (양호)
+
+- "**Not a model. Not a fine-tune.**"(README L13), "AI model training or fine-tuning remains outside the shipped scope" — RAG/파인튜닝 아닌 deterministic 전제 일관 유지. ✅
+- 검증 안 된 정량 성과·채택률 주장 **없음**. "fastest/best-selling/adoption %" 류 카피 미발견. ✅
+- VS Code Marketplace를 "not currently confirmed" / "prepared for, not publicly shipped"로 **정직하게** 기술(`external-status.md` L26-27). ✅
+- 배포 상태에 검증 날짜(2026-06-23)·evidence 로그 경로 명시 — 추적 가능. ✅
+
+### 문서 품질 이슈 (LOW)
+
+- README L216/L218/L235가 **극단적 run-on 단락**(changelog 전체를 한 문장에 나열, 수천 자). 정직하지만 가독성·유지보수성 저하. 변경 로그는 `CHANGELOG.md`(이미 존재, 505KB)로 위임하고 README는 요약만 권고.
+
+---
+
+## 6. 우선순위 P0/P1/P2
+
+**P0 (즉시):**
+- (없음) — 출시 차단 코드 결함 없음. 테스트/감사 전부 green. Marketplace blocker는 코드가 아닌 시크릿 운영 이슈.
+
+**P1 (다음 스프린트):**
+- P1-a. **Examples 배지 221로 정정** (정직성·문서 정확성). README L6 배지 + L128 본문. 가능하면 coverage 툴 자동 생성으로 배선.
+- P1-b. **MCP 프로토콜 버전 협상 추가** — 미지원 버전 화이트리스트 검증/다운그레이드. 계약 안정성.
+- P1-c. **`cli/lib/site.mjs`(6617줄) 모듈 분할 시작** — 기능 경계별. 단계당 `npm test` 회귀 게이트.
+
+**P2 (백로그):**
+- P2-a. MCP 부정 경로 테스트 보강(에러/트렁케이션/버전 미스매치).
+- P2-b. vscode-extension `npm audit fix`로 devDeps 취약점 정리(출시 영향 없음, CI 신호 위생).
+- P2-c. `learn` 서브플래그 그룹화 검토.
+- P2-d. README run-on 단락 → CHANGELOG 위임.
+
+---
+
+## 7. 권장 다음 액션
+
+**"Marketplace publish 마무리" vs "MCP 서버 안정화" — 무엇이 더 가치 있는가**
+
+> **권고: MCP 서버 안정화를 우선.** 근거:
+> 1. **Marketplace publish는 코드 작업이 끝났다.** 워크플로·dry-run·listing 검증까지 완비되어 남은 건 `VSCE_PAT` 발급/등록이라는 **1회성 운영 행동**(코드로 풀 수 없음). 즉, 엔지니어링이 더 투입할 표면이 거의 없다.
+> 2. **MCP는 최근 추가(2026-06-23)된 신규·확장 중인 계약 표면**이고, Claude/Codex라는 외부 클라이언트와의 프로토콜 호환이 제품 가치에 직접 연결된다. 버전 협상 부재(P1-b)와 부정 경로 테스트 공백(P2-a)은 실제 사용 시 silent 실패로 이어질 수 있는 **코드로 해결 가능한 리스크**다.
+> 3. 가치 대비 노력: Marketplace는 노력↓·코드기여↓(시크릿만), MCP는 노력 투입이 곧 계약 견고성으로 환원된다.
+>
+> **결론:** Marketplace는 "PAT 등록 1건 + dry_run=false 실행 + 문서 갱신"으로 병렬 클로즈하고, **엔지니어링 집중은 MCP 안정화(버전 협상 + 부정 테스트)에 둔다.**
+
+**구체 다음 액션 순서:**
+1. (운영) Azure DevOps PAT 발급 → GitHub `VSCE_PAT` secret 등록 → `vscode-publish.yml` `dry_run=false` 실행 → external-status/README 갱신.
+2. (코드, P1) Examples 배지 221 정정 + MCP 프로토콜 버전 협상 추가.
+3. (코드, P1) `site.mjs` 모듈 분할 1차(intake/bundle 분리)로 시작, 단계별 `npm test`.
+4. (코드, P2) MCP 부정 경로 테스트 3종 추가, vscode-extension `npm audit fix`.
+
+---
+
+*점검 방법: `git status/log`, `node --test`, `tools/audit/run-all.py`, `tools/audit/check-coverage.py`, 파일 라인 카운트, `mcp-server.mjs` 정독, `vscode-publish.yml`·`external-status.md` 정독, README/COVERAGE.md 배지 대조. 코드 무변경.*

package/docs/integrations/design-ai-mcp-server.md

@@ -9,9 +9,9 @@ The server is local, stdio-based, and deterministic. It wraps existing `design-a
 | Tool | Purpose | Mutation risk |
 |---|---|---|
 | `design_ai_route` | Recommend the best design-ai route, skill, command, and knowledge files for a task brief. | Read-only |
-| `design_ai_prompt` | Generate a ready-to-use prompt from a brief. | Read-only by default; `withLearning` records local usage metadata |
-| `design_ai_pack` | Generate a prompt plus bounded context files. | Read-only by default; `withLearning` records local usage metadata |
-| `design_ai_search` | Search `knowledge/`, `examples/`, `skills/`, `docs/`, `agents/`, and `commands/`. | Read-only |
+| `design_ai_prompt` | Generate a ready-to-use prompt from a brief. Optional `withRecall` (with `recallLimit`, 1-20) augments the output with brief-relevant shipped corpus knowledge ranked by the deterministic lexical scorer; requires no index and makes no network call. | Read-only by default; `withLearning` records local usage metadata |
+| `design_ai_pack` | Generate a prompt plus bounded context files. Optional `withRecall` (with `recallLimit`, 1-20) augments the output with brief-relevant shipped corpus knowledge ranked by the deterministic lexical scorer; requires no index and makes no network call. | Read-only by default; `withLearning` records local usage metadata |
+| `design_ai_search` | Search `knowledge/`, `examples/`, `skills/`, `docs/`, `agents/`, and `commands/`. Optional `ranked` opts into deterministic BM25-style results (`design-ai search --ranked`); requires no index and never builds one. | Read-only |
 | `design_ai_show` | Read a corpus file or line range. | Read-only |
 | `design_ai_examples` | Find worked examples by query or route. | Read-only |
 | `design_ai_check` | Check generated Markdown artifacts for grounding, accessibility, responsive notes, and unresolved markers. | Read-only |
@@ -43,7 +43,7 @@ cd "$tmp"
 printf '%s\n' \
   '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}' \
   '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
-  | npm exec --yes --package=@design-ai/cli@4.55.0 -- design-ai-mcp
+  | npm exec --yes --package=@design-ai/cli@4.56.0 -- design-ai-mcp
 ```
 
 Running that one-shot command from the package source root can make npm prefer the local checkout context, which may hide the temporary package bin shim.