docs-cli 1.5.0__tar.gz → 1.6.5__tar.gz

{docs_cli-1.5.0 → docs_cli-1.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docs-cli
-Version: 1.5.0
+Version: 1.6.5
 Summary: Prescriptive CLI for managing trees of structured Markdown docs.
 Project-URL: Homepage, https://github.com/ArtRichards/docs-cli
 Project-URL: Repository, https://github.com/ArtRichards/docs-cli
@@ -124,22 +124,13 @@ python3 -m venv .venv
 
 ## Status
 
-**docs-cli 1.3.0 shipped 2026-05-25** — the first public release. Install with `pip install docs-cli`. **docs-cli 1.4.0 is ready locally** (M10 adoption-flow polish); the M11 publish milestone will lift it onto PyPI. Milestone history:
+Released on PyPI — `pip install docs-cli`. The on-disk Markdown convention is stable; the only breaking keyword change to date is the one-time `Status:` → `Lifecycle:` rename (no backward-compat alias).
 
-- M1 — Parser and `docs index` (shipped 2026-05-20)
-- M2 — Mutating verbs `new`, `archive`, `mv`, `touch` (shipped 2026-05-21)
-- M3 — Validation and query `check`, `list` (shipped 2026-05-22)
-- M4 — Migration helper `docs migrate` (shipped 2026-05-22)
-- M5 — Claude Code skill — drives the verbs automatically when an agent does documentation work in a `docs`-managed tree, with self-contained convention and CLI references bundled alongside (shipped 2026-05-22)
-- M6 — PyPI distribution preparation as `docs-cli`; relocates the CLI to a proper package at `src/docs_cli/`, ships the skill inside the wheel as package data, and adds `docs install-skill` for one-shot host materialisation (closed 2026-05-24 as preparation-only; publish landed at M9 batched 1.3.0)
-- M7 — Migration accuracy: `Status:` → `Lifecycle:` controlled-vocab rename, broadened role inference (H1 / section-header / sibling-set / word-boundary / `_M\d+` / non-role-suffix strip), `medium` confidence level, project-name normalisation, per-file mtime archive dates, multi-project hints, `--config-project` override, `[migrate]`-only sidecar (shipped 2026-05-25; the version-internal 1.2.0 was published at M9 batched 1.3.0)
-- M8 — Adoption workflow agent-driveable: tree-wide `--exclude` + `[exclude]` + `.docsignore`; migrate triage flags (`--summary`, `--only ambiguous`, `--group-by`); default plan footer summary; non-md sibling surfacing; `docs new --body-from` for one-call atomic doc authoring; substantial skill-reference rewrite (adoption playbook + `.docs.toml` template) (shipped 2026-05-25; the version-internal 1.3.0 is the published number)
-- M9 — PyPI publish (shipped 2026-05-25). `docs-cli==1.3.0` is live at [pypi.org/project/docs-cli/1.3.0/](https://pypi.org/project/docs-cli/1.3.0/); source tag at [github.com/ArtRichards/docs-cli/releases/tag/v1.3.0](https://github.com/ArtRichards/docs-cli/releases/tag/v1.3.0).
-- M10 — Adoption-flow polish + 1.3.0 carry-overs (ready locally as 1.4.0): multi-file atomic `docs touch <file>...`; `docs migrate --apply` writes/extends `.docs.toml` automatically + opportunistically removes empty archive-style parents; `docs migrate --apply --quiet` suppresses the per-file plan block; `[vocabulary] add_fields` allowlist + `docs check` `unknown-field` warning; `Confidence` enum replacing the M4 `bool | str` tri-value (JSON wire format byte-stable); `MigrationPlan.excluded_count` removed (set but never read); adoption playbook restructured to 4 steps (plan / triage / apply / verify). Publish deferred to M11.
+For current state, see the canonical sources — kept in sync by the tooling rather than duplicated here:
 
-**Publish strategy.** v1.1.0 and v1.2.0 never reached PyPI by design; M9 batched the M6 + M7 + M8 surface into a single public release at version 1.3.0 (one publish event, per operator OQ-C). The on-disk Markdown convention is otherwise stable; the M7 `Lifecycle:` rename is a one-time keyword change with no backward-compat alias.
-
-See [`docs/status.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/status.md) for per-milestone summaries, [`docs/plan.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/plan.md) for the roadmap, and [`docs/m9-pypi-publish.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/m9-pypi-publish.md) for the publish record (artifact sha256, deviations recorded for future releases). The [CHANGELOG](https://github.com/ArtRichards/docs-cli/blob/main/CHANGELOG.md) tracks every release.
+- [CHANGELOG](https://github.com/ArtRichards/docs-cli/blob/main/CHANGELOG.md) — the current version and full release history.
+- [`docs/status.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/status.md) — development progress.
+- [`docs/plan.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/plan.md) — the roadmap.
 
 ## License
 

{docs_cli-1.5.0 → docs_cli-1.6.5}/README.md

@@ -78,22 +78,13 @@ python3 -m venv .venv
 
 ## Status
 
-**docs-cli 1.3.0 shipped 2026-05-25** — the first public release. Install with `pip install docs-cli`. **docs-cli 1.4.0 is ready locally** (M10 adoption-flow polish); the M11 publish milestone will lift it onto PyPI. Milestone history:
-
-- M1 — Parser and `docs index` (shipped 2026-05-20)
-- M2 — Mutating verbs `new`, `archive`, `mv`, `touch` (shipped 2026-05-21)
-- M3 — Validation and query `check`, `list` (shipped 2026-05-22)
-- M4 — Migration helper `docs migrate` (shipped 2026-05-22)
-- M5 — Claude Code skill — drives the verbs automatically when an agent does documentation work in a `docs`-managed tree, with self-contained convention and CLI references bundled alongside (shipped 2026-05-22)
-- M6 — PyPI distribution preparation as `docs-cli`; relocates the CLI to a proper package at `src/docs_cli/`, ships the skill inside the wheel as package data, and adds `docs install-skill` for one-shot host materialisation (closed 2026-05-24 as preparation-only; publish landed at M9 batched 1.3.0)
-- M7 — Migration accuracy: `Status:` → `Lifecycle:` controlled-vocab rename, broadened role inference (H1 / section-header / sibling-set / word-boundary / `_M\d+` / non-role-suffix strip), `medium` confidence level, project-name normalisation, per-file mtime archive dates, multi-project hints, `--config-project` override, `[migrate]`-only sidecar (shipped 2026-05-25; the version-internal 1.2.0 was published at M9 batched 1.3.0)
-- M8 — Adoption workflow agent-driveable: tree-wide `--exclude` + `[exclude]` + `.docsignore`; migrate triage flags (`--summary`, `--only ambiguous`, `--group-by`); default plan footer summary; non-md sibling surfacing; `docs new --body-from` for one-call atomic doc authoring; substantial skill-reference rewrite (adoption playbook + `.docs.toml` template) (shipped 2026-05-25; the version-internal 1.3.0 is the published number)
-- M9 — PyPI publish (shipped 2026-05-25). `docs-cli==1.3.0` is live at [pypi.org/project/docs-cli/1.3.0/](https://pypi.org/project/docs-cli/1.3.0/); source tag at [github.com/ArtRichards/docs-cli/releases/tag/v1.3.0](https://github.com/ArtRichards/docs-cli/releases/tag/v1.3.0).
-- M10 — Adoption-flow polish + 1.3.0 carry-overs (ready locally as 1.4.0): multi-file atomic `docs touch <file>...`; `docs migrate --apply` writes/extends `.docs.toml` automatically + opportunistically removes empty archive-style parents; `docs migrate --apply --quiet` suppresses the per-file plan block; `[vocabulary] add_fields` allowlist + `docs check` `unknown-field` warning; `Confidence` enum replacing the M4 `bool | str` tri-value (JSON wire format byte-stable); `MigrationPlan.excluded_count` removed (set but never read); adoption playbook restructured to 4 steps (plan / triage / apply / verify). Publish deferred to M11.
-
-**Publish strategy.** v1.1.0 and v1.2.0 never reached PyPI by design; M9 batched the M6 + M7 + M8 surface into a single public release at version 1.3.0 (one publish event, per operator OQ-C). The on-disk Markdown convention is otherwise stable; the M7 `Lifecycle:` rename is a one-time keyword change with no backward-compat alias.
-
-See [`docs/status.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/status.md) for per-milestone summaries, [`docs/plan.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/plan.md) for the roadmap, and [`docs/m9-pypi-publish.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/m9-pypi-publish.md) for the publish record (artifact sha256, deviations recorded for future releases). The [CHANGELOG](https://github.com/ArtRichards/docs-cli/blob/main/CHANGELOG.md) tracks every release.
+Released on PyPI — `pip install docs-cli`. The on-disk Markdown convention is stable; the only breaking keyword change to date is the one-time `Status:` → `Lifecycle:` rename (no backward-compat alias).
+
+For current state, see the canonical sources — kept in sync by the tooling rather than duplicated here:
+
+- [CHANGELOG](https://github.com/ArtRichards/docs-cli/blob/main/CHANGELOG.md) — the current version and full release history.
+- [`docs/status.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/status.md) — development progress.
+- [`docs/plan.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/plan.md) — the roadmap.
 
 ## License
 

docs_cli-1.6.5/docs/INDEX.md

@@ -0,0 +1,99 @@
+# docs — Documentation
+
+This directory is the docs root for the `docs` CLI itself. We eat our own dog food: once the tool is built, running `docs index` here should reproduce the auto-generated section below.
+
+The hand-written preamble (this paragraph, and anything outside the marker block) is preserved by the tool. Only content between `<!-- docs:generated start -->` and `<!-- docs:generated end -->` is rewritten.
+
+<!-- docs:generated start -->
+_Generated 2026-06-12. 19 docs active, 34 archived._
+
+## Project — docs
+
+### Active — Status
+
+- [status.md](status.md) — _status_ — **This is the single source of truth for project progress. Update only this file when milestones complete or phases…. Updated 2026-06-12.
+
+### Active — Charter
+
+- [charter.md](charter.md) — _charter_ — A small, opinionated CLI (`docs`) that manages a tree of Markdown documentation by treating each file as a…. Updated 2026-05-24.
+
+### Active — Plan
+
+- [plan.md](plan.md) — _plan_ — Three milestones to v1, then a migration helper, then a Claude Code skill wrapper. v1.1 picks up with packaging, then…. Updated 2026-06-12.
+
+### Active — Spec
+
+- [cli.md](cli.md) — _spec_ — This spec defines the `docs` command-line surface: subcommands, flags, output formats, and exit codes. The on-disk…. Updated 2026-06-12.
+- [convention.md](convention.md) — _spec_ — This spec defines the on-disk convention that `docs` reads and writes. It is the portable, tool-independent part: any…. Updated 2026-06-12.
+
+### Active — Milestone
+
+- [m19-post-edit-validation.md](m19-post-edit-validation.md) — _milestone_ — - Milestone: M19 (v1.6.5) - Title: Post-edit validation ergonomics (touch --check + configurable stale window) -…. Updated 2026-06-12.
+- [m20-pypi-publish.md](m20-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-06-12, post M19 implementation-complete.** M20 > enters active state immediately — M19 is…. Updated 2026-06-12.
+- [m18-archive-edge-integrity.md](m18-archive-edge-integrity.md) — _milestone_ — - Milestone: M18 - Title: Archive edge integrity (intra-archive Related: rewriting) - Surface: a correctness fix to…. Updated 2026-06-03.
+
+### Active — Log
+
+- [m19-post-edit-validation-impl.md](m19-post-edit-validation-impl.md) — _log_ — Chronological log of work on M19 — Post-edit validation ergonomics (`docs touch --check` + configurable stale window).…. Updated 2026-06-12.
+- [m20-pypi-publish-impl.md](m20-pypi-publish-impl.md) — _log_ — Chronological log of work on M20 — PyPI publish 1.6.5. Append a section per runbook phase (operator prep → pre-publish…. Updated 2026-06-12.
+- [m17-pypi-publish-impl.md](m17-pypi-publish-impl.md) — _log_ — Chronological log of work on M17 — PyPI publish 1.6.0. Append a section per runbook phase (operator prep → pre-publish…. Updated 2026-06-03.
+- [m18-archive-edge-integrity-impl.md](m18-archive-edge-integrity-impl.md) — _log_ — Chronological log of work on M18 — Archive edge integrity (intra-archive `Related:` rewriting). Append a section per…. Updated 2026-06-03.
+
+### Active — Decision
+
+- [dual-status-adr.md](dual-status-adr.md) — _decision_ — A doc's lifecycle state could be expressed by:. Updated 2026-05-20.
+- [vocab-adr.md](vocab-adr.md) — _decision_ — The convention requires controlled vocabularies for `Status` and `Role`. Too small a set fails to express common…. Updated 2026-05-20.
+
+### Active — Runbook
+
+- [release-runbook.md](release-runbook.md) — _runbook_ — The operator-driven checklist for shipping `docs-cli` to PyPI. This runbook drove **M9 — `docs-cli==1.3.0`** (shipped…. Updated 2026-06-03.
+
+### Active — Reference
+
+- [architecture.md](architecture.md) — _reference_ — Single Python module at `src/docs_cli/cli.py`, exposed as the `docs` console-script via the `docs_cli.cli:main` entry…. Updated 2026-05-28.
+- [definition-of-ready.md](definition-of-ready.md) — _reference_ — Gate-check before implementation begins. Implementation does not start until every item is green.. Updated 2026-05-22.
+- [test-strategy.md](test-strategy.md) — _reference_ — | Layer | Tool | Scope | |---|---|---| | Unit | pytest | Parser, walker, render, vocab loading. Pure-function focus. |…. Updated 2026-05-20.
+
+## Project — ideas
+
+### Active — Plan
+
+- [agent-native-invocation.md](agent-native-invocation.md) — _plan_ — > **Source.** Prompted by ["I read the Claude Code source >…. Updated 2026-06-03.
+
+## Archived
+
+- [archive/2026-06-03/m14-robustness-agent-native-impl.md](archive/2026-06-03/m14-robustness-agent-native-impl.md) — _log_ — Chronological log of work on M14 — Robustness + agent-native surface. Append a section per TDD phase with objective,…. Updated 2026-06-03.
+- [archive/2026-06-03/m14-robustness-agent-native.md](archive/2026-06-03/m14-robustness-agent-native.md) — _milestone_ — - Milestone: M14 (v1.6.0, part 1 of 2) - Title: Robustness + autonomous archive - Surface: correctness/atomicity…. Updated 2026-06-03.
+- [archive/2026-06-03/m15-agent-native-authoring-impl.md](archive/2026-06-03/m15-agent-native-authoring-impl.md) — _log_ — Chronological log of work on M15 — Agent-native doc authoring. Append a section per TDD phase with objective, files…. Updated 2026-06-03.
+- [archive/2026-06-03/m15-agent-native-authoring.md](archive/2026-06-03/m15-agent-native-authoring.md) — _milestone_ — - Milestone: M15 (v1.6.0, part 2 of 2) - Title: Agent-native doc authoring - Surface: the agent-native *authoring* set…. Updated 2026-06-03.
+- [archive/2026-06-03/m17-pypi-publish.md](archive/2026-06-03/m17-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-06-03, post M14 + M15 closeout.** M17 > enters active state immediately — M14 and M15 are both >…. Updated 2026-06-03.
+- [archive/2026-06-01/m16-bundled-docs-skill-quality-impl.md](archive/2026-06-01/m16-bundled-docs-skill-quality-impl.md) — _log_ — Chronological log for M16. This milestone records the docs-cli bundled `docs` skill changes required by the Agent…. Updated 2026-06-01.
+- [archive/2026-06-01/m16-bundled-docs-skill-quality-test-matrix.md](archive/2026-06-01/m16-bundled-docs-skill-quality-test-matrix.md) — _spec_ — Lite. Updated 2026-06-01.
+- [archive/2026-06-01/m16-bundled-docs-skill-quality.md](archive/2026-06-01/m16-bundled-docs-skill-quality.md) — _milestone_ — - Milestone: M16 - Title: Bundled docs skill quality artifacts - Surface: bundled `docs` skill guidance under…. Updated 2026-06-01.
+- [archive/2026-05-29/m13-pypi-publish-impl.md](archive/2026-05-29/m13-pypi-publish-impl.md) — _log_ — Chronological log of work on M13 — PyPI publish 1.5.0. Append a section per runbook phase (operator prep → pre-publish…. Updated 2026-05-29.
+- [archive/2026-05-29/m13-pypi-publish.md](archive/2026-05-29/m13-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-05-29, post M12 closeout.** M13 enters > active state immediately — the M12 wheel + sdist already…. Updated 2026-05-29.
+- [archive/2026-05-28/m12-project-rename-impl.md](archive/2026-05-28/m12-project-rename-impl.md) — _log_ — Chronological log of work on M12 — Project rename verb + M11 wart fixes + version SoT (v1.5.0). Append a section per…. Updated 2026-05-28.
+- [archive/2026-05-28/m12-project-rename.md](archive/2026-05-28/m12-project-rename.md) — _milestone_ — > **Stub-drafted 2026-05-28** following M11 closeout. M12 bundles > one operator-facing headline feature (`docs project…. Updated 2026-05-28.
+- [archive/2026-05-27/m10-adoption-polish-impl.md](archive/2026-05-27/m10-adoption-polish-impl.md) — _log_ — Chronological log of work on M10 — Adoption-flow polish + 1.3.0 carry-overs. Append a section per phase with objective,…. Updated 2026-05-27.
+- [archive/2026-05-27/m10-adoption-polish.md](archive/2026-05-27/m10-adoption-polish.md) — _milestone_ — - Milestone: M10 (v1.4.0) - Title: Adoption-flow polish + 1.3.0 carry-overs - Surface: two new CLI features (`docs…. Updated 2026-05-27.
+- [archive/2026-05-27/m11-pypi-publish-impl.md](archive/2026-05-27/m11-pypi-publish-impl.md) — _log_ — Chronological log of work on M11 — PyPI publish `docs-cli` 1.4.0. Append a section per phase (Operator prep →…. Updated 2026-05-27.
+- [archive/2026-05-27/m11-pypi-publish.md](archive/2026-05-27/m11-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-05-27, post M10 closeout.** M11 enters > active state immediately — the M10 wheel + sdist already…. Updated 2026-05-27.
+- [archive/2026-05-25/m7-migration-accuracy-log.md](archive/2026-05-25/m7-migration-accuracy-log.md) — _log_ — - Project: docs - Milestone: M7 — Migration plan accuracy - Started: 2026-05-24 - Progress: **Phase 1 complete; Phase 2…. Updated 2026-05-25.
+- [archive/2026-05-25/m7-migration-accuracy.md](archive/2026-05-25/m7-migration-accuracy.md) — _milestone_ — - Milestone: M7 (v1.1) - Title: Migration plan accuracy - Surface: extensions to `docs migrate`'s inference…. Updated 2026-05-25.
+- [archive/2026-05-25/m8-adoption-workflow-log.md](archive/2026-05-25/m8-adoption-workflow-log.md) — _log_ — - Project: docs - Milestone: M8 — Adoption workflow (agent-driveable) - Started: 2026-05-24 - Progress: **All 10 TDD…. Updated 2026-05-25.
+- [archive/2026-05-25/m8-adoption-workflow.md](archive/2026-05-25/m8-adoption-workflow.md) — _milestone_ — - Milestone: M8 (v1.1) - Title: Adoption workflow — agent-driveable - Surface: new CLI flags + verbs (`--exclude`,…. Updated 2026-05-25.
+- [archive/2026-05-25/m9-pypi-publish-log.md](archive/2026-05-25/m9-pypi-publish-log.md) — _log_ — Per-phase log for M9. Entries appended as the operator walked [release-runbook.md](release-runbook.md) post-M8.. Updated 2026-05-25.
+- [archive/2026-05-25/m9-pypi-publish.md](archive/2026-05-25/m9-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-05-24, post M6 scope reframe.** M9 enters > active state once M8 ships. The operative checklist…. Updated 2026-05-25.
+- [archive/2026-05-24/m6-pypi-distribution-log.md](archive/2026-05-24/m6-pypi-distribution-log.md) — _log_ — - Project: docs - Milestone: M6 — PyPI distribution as `docs-cli` - Started: 2026-05-23 - Progress: **Milestone-setup…. Updated 2026-05-24.
+- [archive/2026-05-24/m6-pypi-distribution.md](archive/2026-05-24/m6-pypi-distribution.md) — _milestone_ — > **Scope reframe 2026-05-24 (operator decision).** M6 is now > **preparation only** — the milestone delivered the…. Updated 2026-05-24.
+- [archive/2026-05-23/m5-claude-code-skill-log.md](archive/2026-05-23/m5-claude-code-skill-log.md) — _log_ — - Project: docs - Milestone: M5 — Claude Code skill - Started: 2026-05-22 - Progress: **M5 complete — shipped…. Updated 2026-05-23.
+- [archive/2026-05-23/m5-claude-code-skill.md](archive/2026-05-23/m5-claude-code-skill.md) — _milestone_ — - Milestone: M5 - Title: Claude Code skill - Surface: a Claude Code **skill** — a `SKILL.md` artifact (plus, if needed,…. Updated 2026-05-23.
+- [archive/2026-05-22/m3-validation-and-query-log.md](archive/2026-05-22/m3-validation-and-query-log.md) — _log_ — - Project: docs - Milestone: M3 — Validation and query (`check`, `list`) - Started: 2026-05-22 - Progress: Complete —…. Updated 2026-05-22.
+- [archive/2026-05-22/m3-validation-and-query.md](archive/2026-05-22/m3-validation-and-query.md) — _milestone_ — - Milestone: M3 - Title: Validation and query (`check`, `list`) - Surface: two new read-only CLI subcommands on the…. Updated 2026-05-22.
+- [archive/2026-05-22/m4-migration-helper-log.md](archive/2026-05-22/m4-migration-helper-log.md) — _log_ — - Project: docs - Milestone: M4 — Migration helper (`docs migrate`) - Started: 2026-05-22 - Completed: 2026-05-22 -…. Updated 2026-05-22.
+- [archive/2026-05-22/m4-migration-helper.md](archive/2026-05-22/m4-migration-helper.md) — _milestone_ — - Milestone: M4 - Title: Migration helper (`docs migrate`) - Surface: one new CLI subcommand on the `docs` executable…. Updated 2026-05-22.
+- [archive/2026-05-21/m2-mutating-verbs-log.md](archive/2026-05-21/m2-mutating-verbs-log.md) — _log_ — - Project: docs - Milestone: M2 — Mutating verbs (`new`, `archive`, `mv`, `touch`) - Started: 2026-05-21 - Progress:…. Updated 2026-05-21.
+- [archive/2026-05-21/m2-mutating-verbs.md](archive/2026-05-21/m2-mutating-verbs.md) — _milestone_ — - Milestone: M2 - Title: Mutating verbs (`new`, `archive`, `mv`, `touch`) - Surface: four new CLI subcommands on the…. Updated 2026-05-21.
+- [archive/2026-05-20/m1-parser-and-index-log.md](archive/2026-05-20/m1-parser-and-index-log.md) — _log_ — - Project: docs - Milestone: M1 — Parser and `docs index` - Started: 2026-05-20 - Shipped: 2026-05-20 - Progress: Phase…. Updated 2026-05-20.
+- [archive/2026-05-20/m1-parser-and-index.md](archive/2026-05-20/m1-parser-and-index.md) — _milestone_ — - Milestone: M1 - Title: Parser and `docs index` - Surface: Python module `docs`, CLI subcommand `docs index` - Status:…. Updated 2026-05-20.
+<!-- docs:generated end -->

docs_cli-1.6.5/docs/agent-native-invocation.md

@@ -0,0 +1,384 @@
+# Agent-Native Invocation — applying Claude Code harness techniques to docs's skills
+
+Lifecycle: draft
+Role: plan
+Project: ideas
+Updated: 2026-06-03
+
+Related:
+- pairs-with: cli.md
+- pairs-with: convention.md
+- pairs-with: plan.md
+
+> **Source.** Prompted by ["I read the Claude Code source
+> code"](https://buildingbetter.tech/p/i-read-the-claude-code-source-code)
+> (buildingbetter.tech), which catalogues ~18 techniques Claude
+> Code uses internally. Most are **harness** features — hooks,
+> agent memory, system-reminders, session-context injection,
+> effort/model selection, fresh-eyes reviewers. The first
+> instinct is "a CLI can't use those." But `docs` is almost
+> never invoked by an agent *directly* — it's invoked **through
+> skills** (`docs`, `project-foundation`, `create-milestones`,
+> `ship-milestone`) running inside that very harness. The skill
+> layer **can** use every one of those features. This doc maps
+> the harness techniques onto `docs`'s invocation surface.
+> Scope: design suggestions only. Feeds into [plan.md](plan.md).
+
+## The reframe: the leverage is in the invocation layer
+
+There are four ways an agent calls `docs`, in rising order of
+how much harness machinery they can carry:
+
+1. **The `docs` skill** (`src/docs_cli/skill/SKILL.md`) — the
+   always-loaded instruction sheet. Can declare **hooks**,
+   **system-reminders**, **memory** directives.
+2. **Companion workflow skills** (`project-foundation`,
+   `create-milestones`, `ship-milestone`) — multi-agent
+   orchestrations. Can use **effort/model selection**,
+   **fresh-eyes (omitClaudeMd) reviewers**, **forked
+   subagents**.
+3. **Claude Code settings/hooks shipped by `install-skill`** —
+   PostToolUse / PreToolUse / SessionStart wired into the host.
+4. **An MCP server wrapping the verbs** — an alternative
+   invocation surface that gets structured tool-use,
+   permissions, and auto-approve *for free* from the harness.
+
+The CLI barely changes. The win is teaching these four layers
+to use what the harness already offers.
+
+## What we already do (a version of it)
+
+- **`ship-milestone` already uses fresh-eyes reviewers** —
+  independent sub-agents that "did NOT build this code." That's
+  the article's `omitClaudeMd` reviewer pattern (#14), done by
+  convention rather than by flag.
+- **`ship-milestone` already prescribes model + thinking** —
+  conductor on the largest model with high thinking, sub-agents
+  spawned `model: opus`. That's effort/model specialization
+  (#6, #11), done in prose.
+- **The `docs` SKILL already states the core invariant** —
+  "run the verb, never hand-edit INDEX/metadata/archive" — and
+  warns that the cwd-fallback "is easy to misuse — confirm
+  before any verb that writes." Those are exactly the
+  instructions worth promoting to *enforced* hooks and
+  *re-injected* reminders below.
+
+So several proposals are "formalize what we already improvise."
+
+---
+
+## Proposals, by invocation layer
+
+### Layer 1 — the `docs` skill
+
+#### 1A — Skill-scoped hooks that *enforce* "never hand-edit" (#1,#2,#7)
+
+- **Technique:** skills register PostToolUse/PreToolUse hooks
+  in frontmatter; they activate only while the skill is live
+  and auto-deregister (skill-scoped, keeps context lean).
+- **Today:** the SKILL *asks* the agent not to hand-edit
+  `INDEX.md`, metadata blocks, or files under `archive/`. A
+  hand edit "silently drifts the tree" — but nothing stops it.
+- **Proposal:** ship hooks with the skill:
+  - **PreToolUse** on `Write`/`Edit` whose path is `INDEX.md`,
+    a file under `archive/`, or a metadata block → **deny**
+    with a reason that names the right verb:
+    `permissionDecisionReason: "INDEX.md is generated — run
+    \`docs index\` instead of editing it."` The invariant
+    becomes mechanical, not hopeful.
+  - **PreToolUse** auto-**allow** the read-only verbs
+    (`docs check`, `docs list`, `docs index --dry-run`) so the
+    agent is never prompted for a safe call.
+  - **PostToolUse** on Write/Edit of any `*.md` under a
+    `.docs.toml` root → run `docs check` (non-blocking) and
+    surface violations immediately, so drift is caught at the
+    edit that caused it rather than at the next `check`.
+- **Payoff:** the skill's central rule stops depending on the
+  model's memory; the harness guarantees it.
+
+#### 1B — A critical system-reminder for the one non-negotiable rule (#15)
+
+- **Technique:** `criticalSystemReminder_EXPERIMENTAL`
+  re-injects a short instruction every turn, surviving context
+  compaction.
+- **Today:** "run the verb, never hand-edit" lives once at the
+  top of the SKILL — and can fade from attention across a long
+  session, exactly when an agent starts hand-patching INDEX.md.
+- **Proposal:** carry the single most drift-prone invariant as
+  a critical reminder: *"In a `.docs.toml` tree, never hand-edit
+  INDEX.md, metadata blocks, or archive/ — always run the
+  matching `docs` verb."* (Flag is experimental; treat as
+  opt-in.)
+- **Payoff:** the rule holds at turn 200 as well as turn 1.
+
+#### 1C — Tree conventions as scoped agent memory (#9,#10)
+
+- **Technique:** agents persist learned patterns as
+  `memory: project|user`; an auto-consolidation loop dedupes,
+  resolves contradictions, converts relative→absolute dates,
+  prunes stale entries.
+- **Today:** every session re-derives a tree's specifics from
+  `.docs.toml` + `convention.md` — its custom vocab
+  (`add_roles`, `role_suffixes`), `archive.date_format`, the
+  milestone cadence, "impl logs stay `Lifecycle: active` after
+  archive."
+- **Proposal:** have the skill write durable `memory: project`
+  entries for tree-specific facts the first time it learns
+  them, so later sessions skip the re-derivation. The article's
+  consolidation loop keeps them honest (absolute dates, no
+  dupes) — which happens to be the same hygiene `docs` itself
+  wants.
+- **Payoff:** "the skill teaches itself this tree"; faster,
+  more consistent runs without re-reading the convention each
+  time.
+
+#### 1D — A load-time capability gate (#16)
+
+- **Technique:** `requiredMcpServers` hides an agent that would
+  fail; tools self-describe so callers don't assume.
+- **Today:** the SKILL version-gates features *in prose* ("v1.2
+  for `Lifecycle:`, v1.3 for `--body-from`"). An agent only
+  discovers a missing verb (`project rename`) when the call
+  errors mid-task.
+- **Proposal:** the skill preamble runs `docs --version` (or a
+  future `docs capabilities --json`, see Layer 5) and degrades
+  gracefully if `docs` is absent or too old — "this tree needs
+  docs-cli ≥ 1.5.0; install or fall back to manual." Make the
+  prose gate a load-time check.
+- **Payoff:** clean refusal up front instead of a confusing
+  mid-task failure.
+
+### Layer 2 — companion workflow skills
+
+#### 2A — Per-role model & effort (#6,#11)
+
+- **Technique:** `effort: low|max` and `model:` per skill/agent
+  match compute to task; `context: fork` + `model: inherit`
+  runs heavy work async without breaking the prompt cache.
+- **Today:** `ship-milestone` says "opus + high thinking" in
+  prose for every sub-agent — including mechanical ones.
+- **Proposal:** make it explicit and graded: cheap model / low
+  effort for mechanical steps (running `docs index`,
+  `docs check`, lint, the consistency-audit file walk);
+  opus / high for planning, triage, and fresh-eyes review.
+  Use `context: fork` + `model: inherit` for the review agent
+  so it doesn't stall the conductor or bust the cache.
+- **Payoff:** the same conductor pattern, cheaper and faster,
+  with compute spent where judgment is actually needed.
+
+#### 2B — Formalize fresh-eyes with `omitClaudeMd` (#14)
+
+- **Technique:** `omitClaudeMd: true` makes a reviewer ignore
+  the project's CLAUDE.md/conventions and judge against
+  industry standards — catching when local conventions have
+  drifted from good practice.
+- **Today:** `ship-milestone`'s fresh-eyes reviewer rebuilds
+  context from the specs and code, but still inherits CLAUDE.md
+  and the tree's own conventions — so it can't easily flag that
+  a *convention itself* has drifted.
+- **Proposal:** give the fresh-eyes reviewer the explicit
+  `omitClaudeMd` posture for a pass that judges doc hygiene and
+  contract quality against general standards, not the tree's
+  (possibly self-justifying) rules.
+- **Payoff:** a genuinely independent check on the conventions,
+  not just on conformance to them.
+
+### Layer 3 — settings/hooks shipped by `install-skill`
+
+#### 3A — SessionStart context injection (#3)
+
+- **Technique:** SessionStart hooks inject `additionalContext`
+  (branch, uncommitted changes) to ground the model before it
+  acts and cut hallucinated assumptions.
+- **Today:** to understand a tree an agent runs `check` +
+  `list` + reads `.docs.toml` + skims `INDEX.md` — several
+  calls, many tokens.
+- **Proposal:** `install-skill` optionally writes a SessionStart
+  hook that, when a `.docs.toml` is present, injects a compact
+  tree snapshot (counts by role/lifecycle, violation totals,
+  stale docs, index-in-sync, docs-cli version). Needs the small
+  CLI enabler in Layer 5 (`docs context --json`).
+- **Payoff:** the agent starts every session already oriented,
+  for one cheap injected blob instead of a discovery dance.
+
+#### 3B — `install-skill --with-hooks` (#1,#2,#7)
+
+- **Technique:** the host's hook config is where PreToolUse /
+  PostToolUse safety actually runs.
+- **Today:** `install-skill` installs the SKILL.md only; the
+  Layer-1 hooks have no delivery vehicle on hosts that key hooks
+  off `settings.json` rather than skill frontmatter.
+- **Proposal:** `install-skill --with-hooks` emits a reviewed
+  hook block (the agent/user approves before enabling) carrying
+  1A's deny/allow rules and 3A's SessionStart injection.
+- **Payoff:** the integration becomes *ambient* on any host —
+  drift caught at the edit, safe verbs un-prompted, sessions
+  pre-grounded — without the SKILL having to nag.
+- **Caveat:** emitting hooks couples `docs` to one harness's
+  hook schema. Keep it behind a flag and version the emitted
+  block.
+
+### Layer 4 — an MCP server as an alternative invocation surface
+
+- **Technique (composite):** the article's structured-output
+  channels (#17), contextual permissions/auto-approve (#2), and
+  glob permission syntax (#12) are things MCP clients give a
+  tool *for free*.
+- **Today:** agents drive `docs` by shelling out and parsing
+  prose; permissions are coarse (`Bash(docs *)`).
+- **Proposal:** expose the verbs as an MCP server (`docs-mcp`),
+  one tool per verb with typed inputs and a structured result
+  object. The harness then supplies: per-tool permissions
+  (auto-allow `docs_check`/`docs_list`, confirm `docs_archive`),
+  no-prompt structured I/O, and tool schemas the agent reads
+  instead of scraping `--help`.
+- **Payoff:** most of the article's "legible, non-blocking,
+  structured" benefits arrive without reinventing them in the
+  CLI — for any MCP-capable client, not just Claude Code.
+- **Open question:** maintain two surfaces (CLI + MCP), or
+  generate the MCP layer from one verb registry?
+
+### Layer 5 — the minimal CLI enablers the above need
+
+The skill/hook/MCP work above leans on a few small,
+agent-friendly CLI affordances. These are the *only* core
+changes worth doing, and only because the layers above need
+them:
+
+- **`docs context --json`** — the one-shot tree snapshot 3A
+  injects and 1D can read.
+- **Non-interactive invariant** — *`docs` never prompts unless
+  asked*. Concretely, replace the interactive
+  `docs archive --cascade` prompt (which stalls an autonomous
+  agent — this `/ship-milestone` run had to avoid `--cascade`
+  for exactly that reason) with pre-answerable flags
+  (`--cascade`, `--cascade-dry-run`, `--cascade-only <glob>`).
+  Hooks and MCP both assume verbs never block on stdin.
+- **`--json` result object on every verb** (today only
+  `check`/`list`/`migrate`) with a `changed: true|false` flag —
+  so PostToolUse hooks and MCP tools have a structured channel
+  to read, and a re-run reports "no change" detectably.
+- **`docs capabilities --json`** — verbs/flags/feature-flags so
+  1D's gate and MCP schemas are generated truth, not
+  hand-maintained prose.
+
+#### 5E — `docs project set`: reassign one doc's project (NOT `migrate`)
+
+- **The gap (how this idea surfaced).** Changing a single
+  doc's `Project:` has no verb. To file *this* doc under
+  `ideas` we deleted it and recreated it with
+  `docs new --project ideas` — destructive: it drops the
+  doc's `Related:` edges, re-runs scaffolding, and (for a
+  *tracked* doc) breaks history continuity. `docs new --project`
+  covers project-at-creation; `docs project rename` covers the
+  *whole root*; the post-hoc single-doc case falls in the gap.
+  An agent recreating a doc to change one field is exactly the
+  clunky, error-prone move the rest of this doc argues against.
+- **Should it be `docs migrate`? No.** `migrate` adopts
+  *foreign, unmanaged* markdown into the convention:
+  inference-driven (it guesses `Role`/`Project`), dry-run by
+  default, a one-shot import of external files. Reassigning a
+  field on an already-managed doc is the inverse — a precise,
+  known mutation inside the tree. Routing it through `migrate`
+  would overload that verb's "import external" model and blur a
+  clean boundary. Reject.
+- **Where it belongs: the `docs project` namespace.**
+  `docs project --help` already reserves the namespace for
+  "future per-project verbs (show, validate, …)". `rename` is
+  the *whole-root* operation (rewrite `.docs.toml` `[project]
+  name` + every matching `Project:` line); **`project set`** is
+  its *single-doc* counterpart. Same concept, two scopes,
+  co-located — most discoverable, least surprising.
+- **Proposed shape:**
+  ```
+  docs project set <doc>... <new-project>
+      [--root DIR] [--quiet] [--dry-run] [--new-project]
+  ```
+  - Reassigns `Project:` on one or more docs; **one**
+    end-of-batch INDEX refresh; atomic all-or-nothing on
+    validation failure (mirrors `touch` / `project rename`).
+  - `<new-project>` normalised via M7's
+    `normalise_project_name()` — same as `rename`; empty
+    post-normalised input → exit 2.
+  - Archived docs are read-only. **Divergence from `rename` (resolved
+    2026-06-03, binding — see cli.md `project set` + M15 Decisions):**
+    `rename` walks the *whole tree* and *skips + reports* archived docs it
+    meets incidentally (they are out of scope for a root-wide rewrite); but
+    `set` takes **explicitly named** doc paths, so a *named* archived doc is
+    an error, not an incidental skip. Naming an archived doc therefore
+    **refuses the whole batch with exit 2** (nothing written), naming the
+    offending path — unlike `rename`'s incidental skip.
+  - **No path change ⇒ no `Related:`-edge rewrite** (unlike
+    `rename`/`archive`/`mv`). It only edits the `Project:` line
+    and the doc's INDEX grouping — strictly simpler than those.
+- **The interesting design decision — a typo guard.** The way
+  an agent silently fragments the INDEX is a typo
+  (`idea` vs `ideas` → two project groups). Rather than prompt
+  (we never prompt — see the non-interactive invariant above),
+  **refuse a project value new to the tree unless `--new-project`
+  is passed**, with a prescriptive, did-you-mean error (this is
+  proposal P0-3 dogfooded):
+  ```
+  docs: project set: 'idea' is not a project in this tree; refusing
+    → did you mean 'ideas'? to create a new project group, pass --new-project
+  ```
+  An *existing* project value needs no flag. Creating a new
+  group (as we just did for `ideas`) is a deliberate act the
+  flag acknowledges — catching typos without a blocking prompt.
+- **Composes with `rename`.** `project rename` only rewrites
+  docs matching the *old* root name, so docs already reassigned
+  by `set` are correctly left alone (its existing
+  "non-matching docs reported, not mutated" behaviour). `set`
+  and `rename` are orthogonal halves that don't fight.
+- **Rejected alternative — a generic `docs set <doc> <field>
+  <value>`.** Too broad: it would let an agent poke arbitrary
+  metadata and bypass the controlled vocab (`Role`/`Lifecycle`
+  have constrained transitions; `Project` is the one
+  identifier-like free field). Keep it a focused
+  `project set`.
+- **TDD sketch.** Counterpart tests to `project rename`'s set:
+  single-doc set; multi-doc atomic batch; `--dry-run` plan;
+  named-archived-doc → **refuse the whole batch, exit 2** (NOT a skip —
+  see the archived divergence above); empty-name → exit 2;
+  unknown-project-without-`--new-project` → exit 2 with did-you-mean;
+  INDEX regrouping; idempotent re-set reports no change.
+
+## Explicitly *not* worth porting
+
+- **Hook command-*rewriting*** (silently injecting `--dry-run`):
+  opaque for a tool an agent must reason about; prefer the
+  explicit non-interactive invariant + visible `--dry-run`.
+- **Auto-*rewriting* the agent's file from a PostToolUse hook:**
+  surface drift (advise), never silently re-edit what the agent
+  just wrote.
+- **Colour identity, fire-once provisioning, auto-dream as a
+  `docs` feature:** these belong to the harness/runtime, not to
+  `docs`. Be a clean tool the harness wraps.
+
+## Suggested sequencing
+
+1. **Layer 5 enablers first** (`docs context --json`,
+   non-interactive `--cascade` redesign, uniform `--json` +
+   `changed`) — small, and everything else depends on them.
+   Natural TDD milestone (**M14 — agent-native surface**).
+2. **Layer 1** skill hooks + critical reminder + capability
+   gate (mostly SKILL.md + a shipped hook block).
+3. **Layer 3** `install-skill --with-hooks` / SessionStart.
+4. **Layer 2** model/effort + `omitClaudeMd` edits to
+   `ship-milestone` (no CLI change — pure skill edits, can land
+   anytime).
+5. **Layer 4** MCP server — largest, evaluate after Layer 5
+   settles the result schema it would reuse.
+
+## Open questions
+
+- **Hook schema coupling:** is emitting Claude-Code-specific
+  hooks from `install-skill` acceptable, or should hooks stay
+  documented-only to keep `docs` harness-neutral?
+- **Memory ownership:** should the `docs` skill write
+  `memory: project` entries itself, or only *recommend* facts
+  for the host to remember?
+- **CLI vs MCP as the strategic surface:** if MCP (Layer 4) is
+  the future, how much Layer-5 CLI polish is worth doing first?
+- **Critical-reminder risk:** the flag is experimental — is the
+  drift it prevents worth depending on an unstable field?

{docs_cli-1.5.0 → docs_cli-1.6.5}/docs/architecture.md

@@ -10,7 +10,7 @@ Related:
 - pairs-with: convention.md
 - pairs-with: cli.md
 - pairs-with: test-strategy.md
-- pairs-with: m5-claude-code-skill.md
+- pairs-with: archive/2026-05-23/m5-claude-code-skill.md
 
 ## Shape
 

{docs_cli-1.5.0/docs → docs_cli-1.6.5/docs/archive/2026-05-20}/m1-parser-and-index-log.md

@@ -1,12 +1,12 @@
 # M1 — Implementation Log
 
-Lifecycle: done
+Lifecycle: archived
 Role: log
 Project: docs
 Updated: 2026-05-20
 
 Related:
-- child-of: m1-parser-and-index.md
+- child-of: archive/2026-05-20/m1-parser-and-index.md
 - pairs-with: status.md
 
 ## Implementation metadata

{docs_cli-1.5.0/docs → docs_cli-1.6.5/docs/archive/2026-05-20}/m1-parser-and-index.md

@@ -1,12 +1,12 @@
 # M1 — Parser and `docs index`
 
-Lifecycle: done
+Lifecycle: archived
 Role: milestone
 Project: docs
 Updated: 2026-05-20
 
 Related:
-- parent-of: m1-parser-and-index-log.md
+- parent-of: archive/2026-05-20/m1-parser-and-index-log.md
 - child-of: plan.md
 - implements: charter.md
 - pairs-with: convention.md

{docs_cli-1.5.0/docs → docs_cli-1.6.5/docs/archive/2026-05-21}/m2-mutating-verbs-log.md

@@ -1,12 +1,12 @@
 # M2 — Implementation Log
 
-Lifecycle: active
+Lifecycle: archived
 Role: log
 Project: docs
 Updated: 2026-05-21
 
 Related:
-- child-of: m2-mutating-verbs.md
+- child-of: archive/2026-05-21/m2-mutating-verbs.md
 - pairs-with: status.md
 
 ## Implementation metadata

{docs_cli-1.5.0/docs → docs_cli-1.6.5/docs/archive/2026-05-21}/m2-mutating-verbs.md

@@ -1,12 +1,12 @@
 # M2 — Mutating verbs (`new`, `archive`, `mv`, `touch`)
 
-Lifecycle: active
+Lifecycle: archived
 Role: milestone
 Project: docs
 Updated: 2026-05-21
 
 Related:
-- parent-of: m2-mutating-verbs-log.md
+- parent-of: archive/2026-05-21/m2-mutating-verbs-log.md
 - child-of: plan.md
 - implements: charter.md
 - pairs-with: convention.md