docs-cli 1.3.0__tar.gz → 1.4.0__tar.gz

{docs_cli-1.3.0 → docs_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docs-cli
-Version: 1.3.0
+Version: 1.4.0
 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,20 +124,22 @@ python3 -m venv .venv
 
 ## Status
 
-**v1 complete; M8 shipped locally as 1.3.0 (publish DEFERRED to M9 batched 1.3.0).** Milestone history:
+**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 — no publish)
-- 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 (closed 2026-05-25 as 1.2.0 locally; publish DEFERRED to M9)
-- 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) (closed 2026-05-25 as 1.3.0 locally; publish DEFERRED to M9)
+- 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, v1.2.0, and v1.3.0 were never published to PyPI. M9 batches the post-M8 tree into the first PyPI release as 1.3.0 — one publish event covering M6 + M7 + M8 surface together (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.
+**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 and [`docs/plan.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/plan.md) for the v1.x backlog. The [CHANGELOG](https://github.com/ArtRichards/docs-cli/blob/main/CHANGELOG.md) tracks every release.
+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.
 
 ## License
 

{docs_cli-1.3.0 → docs_cli-1.4.0}/README.md

@@ -78,20 +78,22 @@ python3 -m venv .venv
 
 ## Status
 
-**v1 complete; M8 shipped locally as 1.3.0 (publish DEFERRED to M9 batched 1.3.0).** Milestone history:
+**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 — no publish)
-- 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 (closed 2026-05-25 as 1.2.0 locally; publish DEFERRED to M9)
-- 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) (closed 2026-05-25 as 1.3.0 locally; publish DEFERRED to M9)
+- 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, v1.2.0, and v1.3.0 were never published to PyPI. M9 batches the post-M8 tree into the first PyPI release as 1.3.0 — one publish event covering M6 + M7 + M8 surface together (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.
+**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 and [`docs/plan.md`](https://github.com/ArtRichards/docs-cli/blob/main/docs/plan.md) for the v1.x backlog. The [CHANGELOG](https://github.com/ArtRichards/docs-cli/blob/main/CHANGELOG.md) tracks every release.
+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.
 
 ## License
 

{docs_cli-1.3.0 → docs_cli-1.4.0}/docs/INDEX.md

@@ -5,13 +5,13 @@ This directory is the docs root for the `docs` CLI itself. We eat our own dog fo
 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-05-25. 29 docs active, 0 archived._
+_Generated 2026-05-27. 32 docs active, 1 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-05-25.
+- [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-05-27.
 
 ### Active — Charter
 
@@ -19,15 +19,16 @@ _Generated 2026-05-25. 29 docs active, 0 archived._
 
 ### 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-05-25.
+- [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-05-27.
 
 ### 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-05-25.
-- [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-05-25.
+- [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-05-27.
+- [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-05-27.
 
 ### Active — Milestone
 
+- [m11-pypi-publish.md](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.
 - [m7-migration-accuracy.md](m7-migration-accuracy.md) — _milestone_ — - Milestone: M7 (v1.1) - Title: Migration plan accuracy - Surface: extensions to `docs migrate`'s inference…. Updated 2026-05-25.
 - [m8-adoption-workflow.md](m8-adoption-workflow.md) — _milestone_ — - Milestone: M8 (v1.1) - Title: Adoption workflow — agent-driveable - Surface: new CLI flags + verbs (`--exclude`,…. Updated 2026-05-25.
 - [m9-pypi-publish.md](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.
@@ -40,9 +41,11 @@ _Generated 2026-05-25. 29 docs active, 0 archived._
 
 ### Active — Log
 
+- [m10-adoption-polish-impl.md](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.
+- [m11-pypi-publish-impl.md](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.
 - [m7-migration-accuracy-log.md](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.
 - [m8-adoption-workflow-log.md](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.
-- [m9-pypi-publish-log.md](m9-pypi-publish-log.md) — _log_ — Per-phase log for M9. Entries get appended as the operator walks [release-runbook.md](release-runbook.md) post-M8.. Updated 2026-05-24.
+- [m9-pypi-publish-log.md](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.
 - [m5-claude-code-skill-log.md](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.
 - [m6-pypi-distribution-log.md](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-23.
 - [m3-validation-and-query-log.md](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.
@@ -57,15 +60,15 @@ _Generated 2026-05-25. 29 docs active, 0 archived._
 
 ### Active — Runbook
 
-- [release-runbook.md](release-runbook.md) — _runbook_ — The operator-driven checklist for shipping `docs-cli` to PyPI. This runbook is **M9's operative artifact** — every…. Updated 2026-05-25.
+- [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-05-25.
 
 ### 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-25.
+- [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-27.
 - [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.
 
 ## Archived
 
-_None._
+- [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.
 <!-- docs:generated end -->

{docs_cli-1.3.0 → docs_cli-1.4.0}/docs/architecture.md

@@ -3,7 +3,7 @@
 Lifecycle: active
 Role: reference
 Project: docs
-Updated: 2026-05-25
+Updated: 2026-05-27
 
 Related:
 - implements: charter.md
@@ -24,7 +24,7 @@ inside the same wheel as package data.
 src/docs_cli/                            (Python 3.11+, stdlib only)
 ├── __init__.py                          ─ lazy re-export of `main`
 ├── cli.py                               ─ the CLI module (~3.8k lines)
-│   ├── dunder version                   (__version__ = "1.3.0")
+│   ├── dunder version                   (__version__ = "1.4.0")
 │   ├── config        — TOML load, Vocab merging, archive-dir resolution,
 │   │                   `[migrate]` per-tree overrides (M7),
 │   │                   `[exclude]` + `.docsignore` (M8)
@@ -201,7 +201,11 @@ the marker block and the derived content.
     (low). Word-boundary tolerance: tokeniser splits on `-`/`_`/whitespace
     AND case-transition (`MyPlan` → suffix `plan`). Optional `config`
     extends the built-in suffix map with `config.role_suffixes`.
-    Confidence is `True`/`"medium"`/`False`.
+    Confidence is a `Confidence(enum.Enum)` member (`HIGH | MEDIUM |
+    LOW`) — M10 replaces the legacy `True | "medium" | False` tri-value.
+    The enum's `value` strings (`"high"`/`"medium"`/`"low"`) match the
+    M4 JSON wire format byte-for-byte; `migration_to_json` crosses
+    enum→string via `fm.confidence.value` at the boundary.
   - `infer_project(filenames, dir_name) -> str` — the longest common
     `-`/`_`-delimited filename prefix, or the directory name.
   - `normalise_project_name(name) -> str` (M7 — F11) — splits on case
@@ -254,20 +258,41 @@ the marker block and the derived content.
   (F5) emits `MigrationPlan.multi_project_hints` via
   `_multi_project_hints` unless `cli_config_project` is set.
   `apply_migration(plan)` executes it: `insert_metadata_block` +
-  `atomic_write` per file, plus the archive moves.
+  `atomic_write` per file, plus the archive moves. After each
+  archive-move it calls `_opportunistic_rmdir(old_parent, plan.root)`
+  to clear the now-empty source dir (M10 — OQ-G; swallows OSError on
+  a non-empty parent so non-migrating siblings survive). After the
+  file loop it calls `_ensure_docs_toml(plan)` which writes (or
+  extends) the root `.docs.toml` sidecar so the adopted tree is
+  immediately self-describing — absent sidecar gets a minimal
+  `[project] name = "<resolved>"` + `[archive] date_format` block;
+  existing sidecar without `[project]` gets the new block appended
+  under a `# Added by docs migrate --apply` provenance comment;
+  existing `[project]` is never overwritten (M10 — OQ-A).
   `migration_to_json(plan)` serialises the whole plan to the `--json`
   schema pinned in [cli.md](cli.md).
 - **Models** — `FileMigration` (frozen) carries one per-file decision: the
   inferred `role`/`project`/`lifecycle` (M7-renamed)/`updated`,
-  `confidence` (`"high"|"medium"|"low"` — M7 widens to three values per
-  OQ-D; `medium` requires empty `ambiguities`), `ambiguities`,
-  `synthesized_h1`, `reconciled_metadata`, and an optional
-  `archive_move` destination. `MigrationPlan` (frozen) holds the `root`,
-  the tuple of `FileMigration`s in root-relative path order,
-  `project_original: str | None` (M7 — the pre-normalisation project
-  name when F11 changed the value, else `None`), and
-  `multi_project_hints: tuple[str, ...]` (M7 — F5 advisory hints, empty
-  when none apply or when the CLI override is in force).
+  `confidence: Confidence` (a `Confidence` enum member — M10 replaces
+  the M7 tri-string with the enum; `Confidence.MEDIUM` requires empty
+  `ambiguities`), `ambiguities`, `synthesized_h1`,
+  `reconciled_metadata`, and an optional `archive_move` destination.
+  `MigrationPlan` (frozen) holds the `root`, the tuple of
+  `FileMigration`s in root-relative path order, `project_original:
+  str | None` (M7 — the pre-normalisation project name when F11
+  changed the value, else `None`), and `multi_project_hints:
+  tuple[str, ...]` (M7 — F5 advisory hints, empty when none apply or
+  when the CLI override is in force). M10 — OQ-D — drops the unused
+  `excluded_count: int` field (set in `plan_migration` but read
+  nowhere in shipped code); consumers that need the total compute it
+  from `excluded_breakdown`.
+- **Config** — `Config` (frozen) carries the resolved configuration
+  for a docs root. M10 — OQ-H — adds `fields: frozenset[str]` (sourced
+  from `[vocabulary] add_fields`, case-sensitive exact match;
+  defaults to the empty set) which widens the `unknown-field` check's
+  allowlist on top of the built-in always-allowed metadata labels
+  (`_BUILTIN_METADATA_FIELDS`). The rule is opt-in: an empty
+  `Config.fields` switches the warning OFF entirely.
 - **Scope boundary** — the active-tree directory layout is left untouched;
   `--apply` adds metadata in place and only ever moves docs out of detected
   archive-style subdirs. No role-bucket flattening or project re-foldering.

docs_cli-1.4.0/docs/archive/2026-05-27/m10-adoption-polish.md

@@ -0,0 +1,268 @@
+# M10 — Adoption-flow polish + 1.3.0 carry-overs
+
+Lifecycle: archived
+Role: milestone
+Project: docs
+Updated: 2026-05-27
+Archived-reason: M10 complete (1.4.0 ready locally)
+
+Related:
+- parent-of: m10-adoption-polish-impl.md
+- child-of: plan.md
+- implements: charter.md
+- pairs-with: status.md
+
+## Overview
+
+- Milestone: M10 (v1.4.0)
+- Title: Adoption-flow polish + 1.3.0 carry-overs
+- Surface: two new CLI features (`docs touch <file...>`, `docs migrate --apply` writes `.docs.toml`), one behaviour fix (`migrate --apply --quiet` actually suppresses per-file output), one new check rule (`unknown-field` warning via `[vocabulary] add_fields`), one internal cleanup (`Confidence` enum replacing `bool | str`), one API tidy (`MigrationPlan.excluded_count` removal), and a sweep of the M8 adoption playbook to absorb the friction the fresh-subagent gate surfaced.
+- Progress: Stub-drafted 2026-05-25; active once Phase 1 lands and OPEN QUESTIONS resolve.
+
+### Goal
+
+Close the highest-leverage follow-ons from M1-M9 so the M8 adoption loop ships truly hands-off. The two user-suggested features (`touch` multi-file + `migrate --apply` writes `.docs.toml`) collapse the M8 playbook's three-pattern ordering note and remove the last steps every fresh M8 subagent had to perform manually. The cleanup items (`Confidence` enum, `excluded_count` removal, `add_fields` allowlist) discharge M3/M7/M8 carry-overs that have accumulated in plan.md's Open questions.
+
+### Requirements
+
+- `docs touch` accepts one or more positional file paths; atomic semantics (all-or-nothing on errors); INDEX refreshes once at end, not per file.
+- `docs migrate --apply` writes a minimal `.docs.toml` at the resolved root when one is absent, carrying `[project] name = "<resolved-project>"` + `[archive] date_format`. If a sidecar `.docs.toml` exists (M8 OQ1 carve-out: `[exclude]`-only or `[migrate]`-only), add `[project]` in place; never silently overwrite an existing `[project]` block.
+- `docs migrate --apply --quiet` suppresses the per-file plan output (not just the trailing stderr success line). Dry-run / `--summary` / `--json` modes are requested outputs and stay unaffected.
+- `docs check` learns a new `unknown-field` warning rule (exit 1, never 2) gated by an opt-in `[vocabulary] add_fields = [...]` allowlist in `.docs.toml`. Trees without the section see no change.
+- Internal: `infer_role` returns a `Confidence` enum (`HIGH | MEDIUM | LOW`) instead of `bool | str`. JSON `--json confidence` field stays a string for wire-format stability.
+- Internal: `MigrationPlan.excluded_count` removed; consumers (the human plan footer) use `sum(c for _, c in excluded_breakdown)`. CHANGELOG note; no known external consumer.
+- Bundled `references/adoption-playbook.md` swept to reflect the new `--apply` semantics — the three-pattern ordering note in Step 3 collapses to "run `--apply`, then commit"; Steps 5/6 lose the manual `.docs.toml` authoring.
+- `cli.md`, `convention.md`, `architecture.md`, README, CHANGELOG, bundled skill references all updated in lockstep.
+- Version bumps: `pyproject.toml` + `__version__` 1.3.0 → 1.4.0.
+
+### Deliverables
+
+- [x] `docs touch` accepts `file...` positional (`nargs="+"`); atomic semantics; single end-of-batch INDEX refresh.
+- [x] `docs migrate --apply` writes / extends `.docs.toml` at the resolved root.
+- [x] `docs migrate --apply --quiet` suppresses per-file plan output.
+- [x] `[vocabulary] add_fields` allowlist + `check_doc` `unknown-field` warning rule.
+- [x] `Confidence` enum + `infer_role` return-type tightening.
+- [x] `MigrationPlan.excluded_count` removed.
+- [x] `references/adoption-playbook.md` rewritten for the new `--apply` semantics.
+- [x] `cli.md`, `convention.md`, `architecture.md`, README updated; CHANGELOG `## 1.4.0` entry.
+- [x] Bundled skill references resynced.
+- [x] M10 dogfooded against the M7/M8 sanitised fixtures end-to-end (Phase 9) — confirm a fresh subagent adopts `kebab-tiny` without any manual `.docs.toml` write.
+
+## OPEN QUESTIONS
+
+Surfaced 2026-05-25 while drafting M10. Operator-resolution requested before Phase 2 starts; recommendations in brackets.
+
+1. **OQ-A — `migrate --apply` and existing `.docs.toml` shape.** When `--apply` finds a sidecar with `[migrate]` or `[exclude]` but no `[project]`, options: (a) add `[project]` in place (preserving the sidecar), (b) leave the file untouched and print a hint, (c) refuse with exit 2. **[Recommendation: (a)]** — append a `[project]` block after any existing sections; use a comment header `# Added by docs migrate --apply` so the provenance is visible. Preserving `[migrate]` / `[exclude]` honours the M8 OQ1 carve-out (operator-explicit "use migrate on this tree" signal).
+
+2. **OQ-B — `--quiet` scope.** Today `--quiet` only suppresses the trailing stderr success line. **[Recommendation: extend to suppress the per-file plan block on `--apply` only; keep dry-run / `--summary` / `--json` outputs unchanged]** since those are explicitly requested outputs, not status chatter.
+
+3. **OQ-C — `docs touch` error semantics on a missing/unreadable file.** Options: (a) atomic — exit nonzero, write nothing; (b) best-effort — skip and continue, report skipped count. **[Recommendation: (a) atomic]** — mirrors `migrate --apply`'s edit-then-move atomicity and the project's atomic-write discipline. Validate all paths first; refuse with exit 1 + named-bad-path if any fail validation; then mutate.
+
+4. **OQ-D — `MigrationPlan.excluded_count` removal as 1.4.0 breaking note.** The field is set in `plan_migration` but read nowhere in shipped code (the human footer iterates `excluded_breakdown` directly; `migration_to_json` omits it). No known external consumer. **[Recommendation: remove in 1.4.0 with CHANGELOG entry under Changed]**; deferring to a 2.0 buys nothing.
+
+5. **OQ-E — `Confidence` enum and the JSON wire format.** `migration_to_json` currently emits `"confidence": "high" | "medium" | "low"` (strings). **[Recommendation: keep emitting strings via `enum.value`]** so the wire format is byte-identical and no JSON consumer breaks. Internal code switches to the enum; serialisation crosses back to strings at the boundary.
+
+6. **OQ-F — `unknown-field` rule message shape.** Allowlist source (`[vocabulary] add_fields`) is the canonical example; the warning should name the field name encountered and the doc path. **[Recommendation: `Finding(severity="warning", rule="unknown-field", message="metadata field '<Label>:' not in [vocabulary] add_fields allowlist", path=<rel>)`]** — mirrors M3's existing rule-message shape. Exit 1 only (warning), never exit 2.
+
+7. **OQ-G — Empty `archive-style/` subdir cleanup after `migrate --apply`.** M4 left this deferred: `archived/old-doc.md` moves to `archive/<date>/old-doc.md` but the now-empty `archived/` stays. Adding `rmdir` is one line. **[Recommendation: include in M10 — `apply_migration` `try: parent.rmdir(); except OSError: pass`]** after each archive move. Opportunistic, behaviour-neutral.
+
+8. **OQ-H — `[vocabulary] add_fields` field-name canonicalisation.** Should the allowlist values be matched case-sensitively or case-insensitively against doc metadata labels? **[Recommendation: case-sensitive — exact match]**, matching how `add_lifecycles` and `add_roles` already work. The on-disk convention is `Capital:` (`Owner:`, `Tags:`); `owner:` is malformed (the parser already rejects it).
+
+9. **OQ-I — Playbook scope for the `references/adoption-playbook.md` rewrite.** Items #1-#3 collapse Steps 3/5/6 substantially. Options: (a) minimal edit — keep the playbook structure, drop the obsolete patterns; (b) restructure into "Step 1 plan → Step 2 triage → Step 3 apply → Step 4 verify" (4 steps not 6). **[Recommendation: (b) restructure]** — the playbook gets shorter and clearer; the M8 fresh-subagent gate's friction items dissolve into the simpler structure.
+
+## Current State Analysis
+
+- **Existing code (1.3.0):**
+  - `_cmd_touch` (`src/docs_cli/cli.py:3238`) — single positional `file`; refreshes INDEX per call.
+  - `apply_migration` (`src/docs_cli/cli.py:2471`) — writes metadata blocks + archives; does NOT write `.docs.toml`.
+  - `_cmd_migrate --quiet` — only suppresses success line, not per-file plan output (M8 simplify deferred).
+  - `infer_role` returns `tuple[str, bool | str]` where `True | "medium" | False` encodes confidence.
+  - `MigrationPlan.excluded_count: int` — set, never read.
+  - `check_doc` rules: `missing-field`, `malformed`, `bad-vocab`, `bad-date`, `status-drift`, `broken-ref`, `medium-confidence-inference`. No `unknown-field`.
+  - `Config.fields` does not exist; `load_config` knows `add_lifecycles` / `add_roles`, not `add_fields`.
+- **Missing for M10:**
+  - Multi-file touch surface + atomic batching.
+  - `apply_migration` `.docs.toml` writer (honouring M8 OQ1 sidecar carve-out).
+  - `--quiet` plan-output suppression.
+  - `Confidence` enum + JSON-boundary string serialisation.
+  - `MigrationPlan.excluded_count` removal + footer code update.
+  - `[vocabulary] add_fields` schema + `Config.fields` + `load_config` branch + `unknown-field` `check_doc` rule.
+  - Empty-archive-subdir `rmdir` in `apply_migration` (OQ-G).
+- **Known gotchas:**
+  - Bundled skill references at `src/docs_cli/skill/references/{cli,convention}.md` enforce byte-equality with `docs/{cli,convention}.md` via `tests/test_skill_refs.py`. Spec edits must be mirrored in the same commit.
+  - The dogfood snapshot at `tests/fixtures/expected/docs-INDEX.md` must stay in lockstep with `docs/INDEX.md`.
+  - `MigrationPlan` is part of the importable surface (`from docs import MigrationPlan` via the M6 conftest alias); removing `excluded_count` is technically breaking even without known consumers.
+
+## Files to Create / Modify
+
+| File | Action | Phase | Notes |
+|---|---|---|---|
+| `docs/m10-adoption-polish.md` | Create | 1 | This task plan. |
+| `docs/m10-adoption-polish-impl.md` | Create | 1 | This milestone's impl log. |
+| `docs/plan.md` | Modify | 1 | Add M10 row; flip the parked `[vocabulary] add_fields` Open question to "Scheduled in M10". |
+| `docs/status.md` | Modify | 1, …, 10 | Phase 1: "Current milestone" → M10. Phase 10: M10 → Complete. |
+| `tests/test_cli_touch.py` | Modify | 2 | Multi-file happy path, atomic-failure semantics, single-INDEX-refresh observation. |
+| `tests/test_cli_migrate.py` | Modify | 2 | `--apply` writes `.docs.toml`; `--apply` extends existing sidecar; `--apply` does NOT overwrite existing `[project]`; `--apply --quiet` suppresses per-file output; empty `archived/` rmdir (OQ-G). |
+| `tests/test_check.py` + `tests/test_cli_check.py` | Modify | 2 | `unknown-field` warning rule; `[vocabulary] add_fields` allowlist suppresses it; exit-1 wiring. |
+| `tests/test_config.py` | Modify | 2 | `add_fields` TOML key parses; `Config.fields` defaults to empty frozenset. |
+| `tests/test_migrate.py` | Modify | 2 | `Confidence` enum return; identity assertions widened. |
+| `tests/test_packaging.py` | Modify | 7 | Version 1.3.0 → 1.4.0 (3 spots: A3 + B1/B2 wheel-name + C2 `--version`). |
+| `src/docs_cli/cli.py` | Modify | 5, 6, 7 | Phase 5: `Confidence` enum, `Config.fields`, `MigrationPlan.excluded_count` removed, `touch` argparse `nargs="+"`, `unknown-field` rule scaffolding, `--quiet` argparse plumbed to `_print_migration_plan`. Phase 6: implementation — multi-file `_cmd_touch` (atomic), `apply_migration` writes `.docs.toml` + OQ-G rmdir, `_cmd_migrate --quiet` suppression, `check_doc` `unknown-field` rule. Phase 7: `__version__` → 1.4.0. |
+| `docs/cli.md` | Modify | 7 | `docs touch` synopsis: `<file>...`. `docs migrate --apply` documents `.docs.toml` write + `--quiet` semantics. `docs check` rule list gains `unknown-field`. `[vocabulary]` section gains `add_fields`. |
+| `docs/convention.md` | Modify | 7 | `[vocabulary] add_fields` documented in the Per-tree `[migrate]` config section neighbour. |
+| `docs/architecture.md` | Modify | 7 | `Confidence` enum + `MigrationPlan` field-list update + `check_doc` rule list update + `apply_migration` `.docs.toml` writer note. |
+| `README.md` | Modify | 7 | Status section gains M10 row + 1.4.0 narrative. |
+| `CHANGELOG.md` | Modify | 7, 10 | Phase 7: `## 1.4.0 — UNRELEASED` (Added / Changed / Notes). Phase 10: dated. |
+| `pyproject.toml` | Modify | 7 | `version = "1.4.0"`. |
+| `src/docs_cli/skill/references/adoption-playbook.md` | Rewrite | 7 | OQ-I — restructure to 4 steps (plan / triage / apply / verify); remove the three-pattern ordering note. |
+| `src/docs_cli/skill/references/cli.md` + `convention.md` | Resync | 7 | Byte-identical mirrors after `docs/{cli,convention}.md` edits. |
+| `docs/INDEX.md` + `tests/fixtures/expected/docs-INDEX.md` | Regenerate | 1, 5, 7, 10 | Lockstep after every doc-touching phase. |
+
+## TDD Implementation Plan
+
+### Phase 1 — Define Contract
+- Objective: Land the milestone-doc + log skeleton, register M10 in plan.md, flip status.md "Current milestone" to M10. No code change. Surface the OPEN QUESTIONS for operator review before Phase 2 starts.
+- Files: `docs/m10-adoption-polish.md`, `docs/m10-adoption-polish-impl.md`, `docs/plan.md`, `docs/status.md`, `docs/INDEX.md` + snapshot.
+- Exit: M10 docs created, lifecycle `active`; `docs check docs --stale 14` exit 0; 369 tests still GREEN.
+
+### Phase 2 — Write Tests (RED)
+- Objective: Express every M10 deliverable as a failing test before any implementation.
+- Files: `tests/test_cli_touch.py` (multi-file + atomic), `tests/test_cli_migrate.py` (apply-writes-toml + apply-extends-sidecar + apply-quiet-suppresses + empty-archive-rmdir), `tests/test_check.py` + `tests/test_cli_check.py` (unknown-field rule), `tests/test_config.py` (add_fields), `tests/test_migrate.py` (Confidence enum); minor regression-lock additions for `excluded_count` removal and JSON wire-format stability.
+- Exit: Suite collects cleanly; RED count matches deliverable count; M9's 369 GREEN preserved.
+
+### Phase 3 — Create Data/Fixtures
+- Objective: Stage fixtures the Phase-2 tests reference. Reuse M8's `body-from/` + M7's `real-trees/` heavily; new fixtures only for `add_fields` (1-2 small `.docs.toml` + doc pairs).
+- Files: `tests/fixtures/add-fields/{allowlist-empty,allowlist-populated}/`.
+- Exit: Every Phase-2 fixture path resolves; sanitisation grep zero hits.
+
+### Phase 4 — Run Tests (RED Baseline)
+- Objective: Capture verbatim RED baseline; confirm every failure traces to its intended unimplemented surface.
+- Files: log only (`/tmp/m10-phase-4-baseline.txt`).
+- Exit: Per-test attribution table in impl log; no RED-for-wrong-reason; quality gate clean.
+
+### Phase 5 — Update Base Interfaces
+- Objective: Schema + argparse + scaffolding. `Confidence` enum; `Config.fields`; `MigrationPlan.excluded_count` removed; `touch` argparse `nargs="+"`; `migrate --quiet` plumbed; `_cmd_check` wiring for `unknown-field`.
+- Files: `src/docs_cli/cli.py`; possibly `tests/_typing/docs.pyi` re-export adjustments.
+- Exit: M9 + Phase 5 GREEN where the bare scaffolding flips REDs without implementation; remaining REDs all behaviour-side for Phase 6.
+
+### Phase 6 — Implement Offline/Core Path
+- Objective: All business logic for the M10 deliverables.
+- Files: `src/docs_cli/cli.py` (`_cmd_touch`, `apply_migration`, `_print_migration_plan`, `check_doc`).
+- Exit: Every M10 RED → GREEN; M9 baseline still GREEN.
+
+### Phase 7 — Update Tool/Wrapper Layer
+- Objective: Spec sweep + version bump + skill-references resync.
+- Files: `docs/{cli,convention,architecture}.md`, `README.md`, `CHANGELOG.md`, `pyproject.toml`, `src/docs_cli/cli.py` (`__version__`), `tests/test_packaging.py` (version pins), `src/docs_cli/skill/references/{cli,convention,adoption-playbook}.md`.
+- Exit: All 369 + M10 new tests GREEN at 1.4.0; bundled skill references byte-equal to source.
+
+### Phase 8 — Run Tests (GREEN)
+- Objective: Capture verbatim GREEN gate at `/tmp/m10-phase-8-green.txt`.
+- Files: log only.
+- Exit: pytest 0 RED; ruff / format / mypy / `docs check docs` / `docs index --dry-run` / `python -m build` / `twine check` all clean.
+
+### Phase 9 — Implement Online/Integration (dogfood)
+- Objective: Re-run the M8 fresh-subagent gate against the M10-built wheel on `kebab-tiny`. Confirm the agent adopts the tree end-to-end with NO manual `.docs.toml` write and NO `--apply --quiet` per-file output. Update `tests/fixtures/trees/real-trees-adopted/` if behaviour delta is observable.
+- Files: log entry; possibly refreshed `real-trees-adopted/` fixtures.
+- Exit: 1/1 PASS unattended (single tree is enough — M8 proved the loop; M10 proves the polish).
+
+### Phase 10 — Quality, Docs, Refactor
+- Objective: Milestone-completion summary on both docs; flip status.md M10 → Complete; date CHANGELOG; build artefacts locally. Per the M7/M8 pattern, NO publish at this phase — publish to PyPI deferred to a separate M11 milestone (or batched into a future release).
+- Files: `docs/m10-adoption-polish.md`, `docs/m10-adoption-polish-impl.md`, `docs/status.md`, `CHANGELOG.md`, `dist/docs_cli-1.4.0-*`.
+- Exit: Full gate green; milestone ready to archive.
+
+## Phase Checklist
+
+- [x] Phase 1 — Define Contract (2026-05-25; OQ closeout 2026-05-26)
+- [x] Phase 2 — Write Tests (RED) (2026-05-26)
+- [x] Phase 3 — Create Data/Fixtures (2026-05-26 — no-op; tests use inline `tmp_path`)
+- [x] Phase 4 — Run Tests (RED Baseline) (2026-05-26)
+- [x] Phase 5 — Update Base Interfaces (2026-05-27)
+- [x] Phase 6 — Implement Offline/Core Path (2026-05-27)
+- [x] Phase 7 — Update Tool/Wrapper Layer (2026-05-27)
+- [x] Phase 8 — Run Tests (GREEN) (2026-05-27)
+- [x] Phase 9 — Implement Online/Integration (2026-05-27)
+- [x] Phase 10 — Quality, Docs, Refactor (2026-05-27)
+
+## Decisions
+
+_Recorded as the milestone progresses. Initial decisions inherited from the OPEN QUESTIONS block above will be promoted here as the operator confirms each one._
+
+- **OQ-A — `migrate --apply` sidecar handling** (operator-confirmed 2026-05-26): append `[project]` in place after any existing sections; prefix with comment header `# Added by docs migrate --apply`; never overwrite an existing `[project]`.
+- **OQ-B — `--quiet` scope** (operator-confirmed 2026-05-26): `migrate --apply --quiet` suppresses per-file plan block AND trailing success line. `--dry-run` / `--summary` / `--json` unaffected.
+- **OQ-C — `docs touch` atomic semantics** (operator-confirmed 2026-05-26): validate all paths first, exit 1 + named-bad-path if any fail, then mutate; single end-of-batch INDEX refresh.
+- **OQ-D — `MigrationPlan.excluded_count` removal** (operator-confirmed 2026-05-26): removed at 1.4.0; CHANGELOG entry under Changed.
+- **OQ-E — `Confidence` enum + JSON wire format** (operator-confirmed 2026-05-26): `Confidence(HIGH, MEDIUM, LOW)` enum internally; JSON wire format keeps strings via `enum.value`.
+- **OQ-F — `unknown-field` rule shape** (operator-confirmed 2026-05-26): `Finding(severity="warning", rule="unknown-field", message="metadata field '<Label>:' not in [vocabulary] add_fields allowlist", path=<rel>)`. Exit 1 only.
+- **OQ-G — `apply_migration` empty-archive rmdir** (operator-confirmed 2026-05-26): opportunistically `rmdir`s the now-empty parent after each archive move.
+- **OQ-H — `[vocabulary] add_fields` matching** (operator-confirmed 2026-05-26): case-sensitive exact match.
+- **OQ-I — `references/adoption-playbook.md` rewrite** (operator-confirmed 2026-05-26): restructured to 4 steps (plan / triage / apply / verify); three-pattern ordering note dropped.
+- **Carries from prior milestones:** M3 (`unknown-field` allowlist), M7 NIT 1 (`Confidence` enum), M8 (`--quiet` behaviour fix, `MigrationPlan.excluded_count` tidy, playbook polish), M4 (empty-archive-subdir rmdir under OQ-G).
+- **Conscious deferrals (NOT in M10):** LLM-assisted classification (M7), `--propose-excludes` heuristic (M8 OQ-A), `docs init --template` verb (M8 OQ-D), per-verb file split (M2), Trusted Publishing OIDC (M6), `importlib.metadata` `__version__` (M6 Q1), mechanical test-file rewrite from `docs` alias (M6), multi-line `Status:` prose continuation (M7 OQ-3), `Migrated-<Label>` rename rule review (M4), mtime-derived `Updated:` snapshot test (M4), M3 `malformed` rule expansion, M1 `Vocab` dataclass, M1 empty-body description cosmetics, PyPI token re-scope (M9), `explainer`/`architecture` roles into core vocab (M7).
+- **Version**: 1.4.0 — minor bump. `MigrationPlan.excluded_count` removal called out in CHANGELOG under Changed; no known external consumers.
+
+## Success Criteria
+
+- All Deliverables ticked.
+- Quality gate green at every phase boundary (`pytest`, `ruff`, `ruff format`, `mypy`, `docs check docs`).
+- `docs touch a.md b.md c.md` writes all three and refreshes the INDEX exactly once; failure on any path leaves all files untouched.
+- `docs migrate --apply <foreign-tree>` (no pre-existing `.docs.toml`) produces a tree that `docs check` accepts without any additional operator action.
+- `docs migrate --apply --quiet <foreign-tree>` produces no per-file plan output on stdout (errors still on stderr).
+- `docs check <tree>` against a tree with an `Owner:` field and no `[vocabulary] add_fields` allowlist exits 0 (no warning); with `add_fields = ["Owner"]` exits 0 (allowed); with `add_fields = ["Tags"]` exits 1 (warning for unknown `Owner:`).
+- M10's dogfood subagent (Phase 9) adopts `kebab-tiny` end-to-end with zero manual `.docs.toml` editing.
+- `CHANGELOG.md` `## 1.4.0` entry covers every M10 surface change.
+- All bundled skill references byte-equal to source after Phase 7.
+
+## Milestone-completion summary (2026-05-27)
+
+- **Version**: 1.4.0 — ready locally; not on PyPI (publish
+  deferred to M11 per the M7/M8 pattern).
+- **All Deliverables checked.** Multi-file atomic `docs touch
+  <file>...`; `docs migrate --apply` writes / extends
+  `.docs.toml` (OQ-A) + opportunistic empty-archive-parent
+  rmdir (OQ-G); `docs migrate --apply --quiet` suppresses
+  per-file plan output (OQ-B); `[vocabulary] add_fields`
+  allowlist + `docs check` `unknown-field` warning rule (OQ-F
+  + OQ-H); `Confidence` enum replacing the M4 `bool | str`
+  tri-value (OQ-E; JSON wire format byte-stable);
+  `MigrationPlan.excluded_count` removed (OQ-D); adoption
+  playbook restructured to 4 steps (OQ-I); cli.md /
+  convention.md / architecture.md / README / CHANGELOG
+  updated in lockstep; bundled skill references byte-equal
+  to source.
+- **All Success Criteria met.** 400/400 pytest; ruff / ruff
+  format / mypy / `docs check docs --stale 14` clean
+  tree-wide; multi-file `docs touch` writes all-or-nothing
+  + single INDEX refresh; foreign-tree `--apply` produces a
+  tree `docs check` accepts with zero manual steps; `--apply
+  --quiet` empty stdout + empty stderr; `unknown-field` rule
+  is opt-in (clean by default; case-sensitive exact match
+  against `add_fields`); Phase 9 kebab-tiny dogfood PASS.
+- **Carry-overs absorbed**: M3 (`[vocabulary] add_fields` —
+  the long-parked Open question now closes); M7 NIT 1
+  (`Confidence` enum); M8 (`MigrationPlan.excluded_count`
+  removal, `--quiet` per-file output, playbook polish);
+  M4 (empty-archive-parent rmdir under OQ-G).
+- **Conscious deferrals**: PyPI publish (M11); `docs project
+  rename` verb (the project-rename TODO at the bottom of
+  this doc); + the 16 items in the Decisions block's
+  "Conscious deferrals" list. None block the 1.4.0 local
+  ship.
+- **Artefacts**: `dist/docs_cli-1.4.0-py3-none-any.whl` +
+  `dist/docs_cli-1.4.0.tar.gz` both pass `twine check`.
+
+## Follow-on TODOs
+
+### Project rename (deferred — likely M11)
+
+Surfaced 2026-05-26 while adopting an existing tree into the docs convention.
+
+**Gap.** Renaming a docs-managed tree's `[project] name` today requires a re-`migrate` with a `[migrate] project_name = "..."` sidecar **plus** an `[exclude]` section in `.docs.toml` to waive the managed-tree refusal (the M8 carve-out). That is currently the only way to rewrite an already-conformant file's `Project:` line without hand-editing. Operators (and sub-agents) re-invent this sidecar dance each time.
+
+**Recommendation.** Build a first-class `docs project rename <new-name>` verb (or equivalent) that:
+- Rewrites `[project] name` in `.docs.toml`.
+- Rewrites every conformant `Project:` line across the tree atomically.
+- Refreshes the INDEX once at end.
+- Does **not** require the operator to add an `[exclude]` carve-out or a `[migrate]` sidecar.
+- Errors out cleanly if any path can't be rewritten (atomic semantics, mirroring `migrate --apply` and `touch`).
+
+**Why deferred from M10:** M10 scope is locked on adoption-flow polish + 1.3.0 carry-overs; a `project rename` verb is new surface, not polish. Captured here so it does not get lost.

{docs_cli-1.3.0/src/docs_cli/skill/references → docs_cli-1.4.0/docs}/cli.md

@@ -3,7 +3,7 @@
 Lifecycle: active
 Role: spec
 Project: docs
-Updated: 2026-05-25
+Updated: 2026-05-27
 
 Related:
 - pairs-with: convention.md
@@ -122,6 +122,15 @@ Validate the tree. Reports (and exits nonzero on) any of:
   trailing-word signal or a section-header pattern produces a
   medium-confidence inference — `severity: warning`, rule
   `medium-confidence-inference`, exit code 1.
+- (M10 — OQ-F + OQ-H) An extra metadata label that is neither on the
+  built-in always-allowed set (`Lifecycle` / `Role` / `Project` /
+  `Updated` / `Related` / `Archived-reason`) NOR on the
+  `[vocabulary] add_fields = [...]` allowlist in `.docs.toml`
+  produces `severity: warning`, rule `unknown-field`, exit code 1.
+  The rule is **opt-in**: an absent or empty `add_fields` switches
+  it off entirely (trees without the allowlist see no change).
+  Matching is case-sensitive exact match — `add_fields = ["Owner"]`
+  allows `Owner:` but not `owner:`.
 
 Output is grouped by file; one line per finding. `--json` emits an array of records, one per finding. Schema — **stable from M3 onward**:
 
@@ -129,17 +138,38 @@ Output is grouped by file; one line per finding. `--json` emits an array of reco
 |---|---|---|
 | `path` | string | Root-relative POSIX path of the doc. |
 | `severity` | string | `error` or `warning`. |
-| `rule` | string | Stable rule id: `missing-field`, `bad-vocab`, `bad-date`, `malformed`, `status-drift`, `broken-ref`, `stale`, or `medium-confidence-inference` (M7). |
+| `rule` | string | Stable rule id: `missing-field`, `bad-vocab`, `bad-date`, `malformed`, `status-drift`, `broken-ref`, `stale`, `medium-confidence-inference` (M7), or `unknown-field` (M10). |
 | `message` | string | Human-readable description of the finding. |
 
 Exit codes:
 - 0 — clean.
-- 1 — warnings only (stale docs; medium-confidence inferences).
+- 1 — warnings only (stale docs; medium-confidence inferences; unknown-field warnings).
 - 2 — errors (missing required fields, invalid vocab, malformed structure, lifecycle/location drift, broken refs).
 
-### `docs touch <file>`
+### `docs touch <file>...`
 
-Bump `Updated:` to today in `<file>`. No other changes. INDEX regenerated.
+Bump `Updated:` to today in one or more docs. Accepts one or more
+positional file paths. INDEX regenerated **exactly once** at end of
+batch, not once per file.
+
+The batch is **atomic** (M10 — OQ-C). `touch` validates every input
+path first — if any path is missing, isn't a regular file, or resolves
+outside the resolved docs root, the command exits 1 + a named-bad-path
+message on stderr and writes nothing. Otherwise every rewrite is
+prepared in memory (any `MetadataError` aborts the batch before any
+disk write), then `atomic_write` is run per file followed by a single
+end-of-batch INDEX refresh. A failure during the validate-or-prepare
+phase leaves every file byte-identical to its pre-call state.
+
+`--dry-run` prints one `docs: would touch <path>` per file on stderr
+(gated on `not --quiet`) and writes nothing. The success run prints
+one `docs: touched <path>` per file on stderr (gated on `not
+--quiet`).
+
+Multi-root invocation (`docs touch a.md b.md` where `a.md` and `b.md`
+resolve to different docs roots) is **undefined behaviour and out of
+M10 scope** — the validate-all-first pass refuses with exit 1 + an
+"outside the resolved docs root" message.
 
 ### `docs install-skill [--dest DIR] [--copy|--symlink] [--force] [--quiet]`
 
@@ -218,8 +248,23 @@ see before it runs.)
 - Without `--apply`, `migrate` writes nothing — it prints the plan (human, or
   `--json`) and exits.
 - With `--apply`, `migrate` inserts the inferred metadata block into each file
-  atomically and performs any archive-normalising moves. The result is a tree
-  `docs check` accepts.
+  atomically and performs any archive-normalising moves. After the file loop
+  it also writes (or extends) the root `.docs.toml` sidecar (M10 — OQ-A): an
+  absent sidecar gets a minimal `[project] name = "<resolved>"` + `[archive]
+  date_format = "%Y-%m-%d"` block (no redundant `dir = "archive"`); a sidecar
+  that already carries a `[migrate]` or `[exclude]` block but no `[project]`
+  gets `[project]` appended at the bottom under a
+  `# Added by docs migrate --apply` provenance comment header; a sidecar that
+  already carries `[project]` is left untouched. After every archive-move the
+  now-empty source parent directory is opportunistically removed (M10 — OQ-G;
+  swallows `OSError(ENOTEMPTY)` so a non-migrating sibling survives). The
+  result is a tree `docs check` accepts with no further operator action
+  required.
+- With `--apply --quiet` (M10 — OQ-B), the per-file plan block on stdout is
+  suppressed in addition to the trailing `docs: migrated <N> file(s) …`
+  success line on stderr. Empty stdout + empty stderr on a clean run. The
+  dry-run plan, `--summary` output, and `--json` array are **requested
+  outputs** and are NEVER suppressed — `--quiet` is scoped to chatter only.
 - `--date YYYY-MM-DD` sets the archive date used when normalising
   archive-style subdirectories into `archive/<date>/`. When set, the
   flag overrides every per-file date globally (M4 semantics