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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docs-cli
-Version: 1.6.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

{docs_cli-1.6.0 → docs_cli-1.6.5}/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-06-03. 20 docs active, 29 archived._
+_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-03.
+- [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
 
@@ -19,26 +19,25 @@ _Generated 2026-06-03. 20 docs active, 29 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-06-03.
+- [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-03.
-- [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-03.
+- [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
 
-- [m15-agent-native-authoring.md](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.
-- [m17-pypi-publish.md](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.
+- [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.
-- [m14-robustness-agent-native.md](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-02.
 
 ### Active — Log
 
-- [m15-agent-native-authoring-impl.md](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.
+- [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.
-- [m14-robustness-agent-native-impl.md](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-02.
 
 ### Active — Decision
 
@@ -63,6 +62,11 @@ _Generated 2026-06-03. 20 docs active, 29 archived._
 
 ## 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.

{docs_cli-1.6.0/docs → docs_cli-1.6.5/docs/archive/2026-06-03}/m14-robustness-agent-native-impl.md

@@ -1,13 +1,14 @@
 # M14 — Implementation Log
 
-Lifecycle: draft
+Lifecycle: archived
 Role: log
 Project: docs
-Updated: 2026-06-02
+Updated: 2026-06-03
+Archived-reason: Milestone M14 complete; docs-cli==1.6.0 shipped to PyPI via M17 2026-06-03
 
 Related:
-- child-of: m14-robustness-agent-native.md
-- pairs-with: m14-robustness-agent-native.md
+- child-of: archive/2026-06-03/m14-robustness-agent-native.md
+- pairs-with: archive/2026-06-03/m14-robustness-agent-native.md
 - pairs-with: status.md
 
 ## Overview

{docs_cli-1.6.0/docs → docs_cli-1.6.5/docs/archive/2026-06-03}/m14-robustness-agent-native.md

@@ -1,14 +1,14 @@
 # M14 — Robustness + autonomous archive
 
-Lifecycle: draft
+Lifecycle: archived
 Role: milestone
 Project: docs
-Updated: 2026-06-02
+Updated: 2026-06-03
 
 Related:
 - child-of: plan.md
-- parent-of: m14-robustness-agent-native-impl.md
-- pairs-with: m15-agent-native-authoring.md
+- parent-of: archive/2026-06-03/m14-robustness-agent-native-impl.md
+- pairs-with: archive/2026-06-03/m15-agent-native-authoring.md
 - pairs-with: agent-native-invocation.md
 - pairs-with: cli.md
 - pairs-with: status.md

{docs_cli-1.6.0/docs → docs_cli-1.6.5/docs/archive/2026-06-03}/m15-agent-native-authoring-impl.md

@@ -1,13 +1,14 @@
 # M15 — Implementation Log
 
-Lifecycle: draft
+Lifecycle: archived
 Role: log
 Project: docs
 Updated: 2026-06-03
+Archived-reason: Milestone M15 complete; docs-cli==1.6.0 shipped to PyPI via M17 2026-06-03
 
 Related:
-- child-of: m15-agent-native-authoring.md
-- pairs-with: m15-agent-native-authoring.md
+- child-of: archive/2026-06-03/m15-agent-native-authoring.md
+- pairs-with: archive/2026-06-03/m15-agent-native-authoring.md
 - pairs-with: status.md
 
 ## Overview

{docs_cli-1.6.0/docs → docs_cli-1.6.5/docs/archive/2026-06-03}/m15-agent-native-authoring.md

@@ -1,14 +1,14 @@
 # M15 — Agent-native doc authoring (v1.6.0)
 
-Lifecycle: draft
+Lifecycle: archived
 Role: milestone
 Project: docs
 Updated: 2026-06-03
 
 Related:
 - child-of: plan.md
-- parent-of: m15-agent-native-authoring-impl.md
-- pairs-with: m14-robustness-agent-native.md
+- parent-of: archive/2026-06-03/m15-agent-native-authoring-impl.md
+- pairs-with: archive/2026-06-03/m14-robustness-agent-native.md
 - pairs-with: agent-native-invocation.md
 - pairs-with: cli.md
 - pairs-with: status.md

{docs_cli-1.6.0/docs → docs_cli-1.6.5/docs/archive/2026-06-03}/m17-pypi-publish.md

@@ -1,17 +1,18 @@
 # M17 — PyPI publish 1.6.0
 
-Lifecycle: draft
+Lifecycle: archived
 Role: milestone
 Project: docs
 Updated: 2026-06-03
+Archived-reason: Milestone M17 complete; docs-cli==1.6.0 shipped to PyPI 2026-06-03
 
 Related:
 - parent-of: m17-pypi-publish-impl.md
 - child-of: plan.md
 - pairs-with: release-runbook.md
 - pairs-with: status.md
-- pairs-with: m14-robustness-agent-native.md
-- pairs-with: m15-agent-native-authoring.md
+- pairs-with: archive/2026-06-03/m14-robustness-agent-native.md
+- pairs-with: archive/2026-06-03/m15-agent-native-authoring.md
 
 ## Overview
 
@@ -32,8 +33,11 @@ Related:
   GitHub release with notes sourced from the CHANGELOG, and the
   post-publish doc closeouts that turn the M14 + M15 + M17 rows
   in `status.md` and `plan.md` into the post-publish narrative.
-- Status: Active (Phase 1 opens immediately — M14 + M15 already
-  built fresh 1.6.0 locally during their own Phase 7 + Phase 10)
+- Status: **Complete (2026-06-03)** — `docs-cli==1.6.0` shipped
+  to PyPI, batching M14 + M15. All five runbook phases done;
+  chain-of-custody bit-perfect; all seven M14 + M15 headline
+  contracts hold against the PyPI-served wheel. `v1.6.0` tag at
+  `95f23a6` + GitHub release are the closeout git sequence.
 
 ### Goal
 
@@ -154,36 +158,38 @@ GitHub repo carries the matching `v1.6.0` tag + release.
 
 ### Deliverables
 
-- [ ] PyPI release `docs-cli` 1.6.0 published; project page live
+- [x] PyPI release `docs-cli` 1.6.0 published; project page live
       at `https://pypi.org/project/docs-cli/1.6.0/`.
-- [ ] TestPyPI release `docs-cli-rehearsal` 1.6.0 published as
+- [x] TestPyPI release `docs-cli-rehearsal` 1.6.0 published as
       the rehearsal artifact at
       `https://test.pypi.org/project/docs-cli-rehearsal/1.6.0/`
       (continues the M9/M11/M13 disambiguated dist-name detour).
-- [ ] `pyproject.toml` `version` confirmed at `1.6.0` (already
-      landed at M14 Phase 7; `__version__` flows through
-      `importlib.metadata` per M12 SoT refactor).
-- [ ] `CHANGELOG.md` `## 1.6.0 — UNRELEASED` section dated to
-      publish day; surrounding body re-verified accurate.
-- [ ] `v1.6.0` git tag pushed; GitHub release created with notes
-      sourced from the CHANGELOG `## 1.6.0` section.
-- [ ] `docs/status.md`: M14 + M15 + M17 rows finalised; "Current
+- [x] `pyproject.toml` `version` confirmed at `1.6.0` (landed at
+      M14 Phase 7; `__version__` flows through `importlib.metadata`
+      per M12 SoT refactor — verified at Phase 2).
+- [x] `CHANGELOG.md` `## 1.6.0 — UNRELEASED` section dated to
+      `## 1.6.0 — 2026-06-03`; surrounding body re-verified
+      accurate (stale lead-in line dropped at Phase 4).
+- [x] `v1.6.0` git tag pushed; GitHub release created with notes
+      sourced from the CHANGELOG `## 1.6.0` section (the closeout
+      git sequence, at commit `95f23a6`).
+- [x] `docs/status.md`: M14 + M15 + M17 rows finalised; "Current
       milestone" + "Next action" rewritten post-publish.
-- [ ] `docs/plan.md`: M14 + M15 + M17 rows finalised; Sequencing
+- [x] `docs/plan.md`: M14 + M15 + M17 rows finalised; Sequencing
       timeline grew the publish line.
-- [ ] `docs/m17-pypi-publish.md` (this file): Phase Checklist
+- [x] `docs/m17-pypi-publish.md` (this file): Phase Checklist
       ticked; milestone-completion summary appended; lifecycle
-      archived via `docs archive --cascade`.
-- [ ] `docs/m17-pypi-publish-impl.md`: per-phase log entries +
+      archived via `docs archive` to `archive/2026-06-03/`.
+- [x] `docs/m17-pypi-publish-impl.md`: per-phase log entries +
       final milestone-completion summary; stays `Lifecycle:
       active` after milestone-doc archive (per the
       M8/M9/M10/M11/M13 pattern).
-- [ ] `docs/m14-robustness-agent-native.md` +
+- [x] `docs/m14-robustness-agent-native.md` +
       `docs/m15-agent-native-authoring.md` (and their impl logs)
-      archived as part of the M17 closeout — they were left LIVE
-      at root by M18's Phase-9 sweep "awaiting the M17 publish"
-      (now resolved — see Decisions).
-- [ ] `docs/INDEX.md` + `tests/fixtures/expected/docs-INDEX.md`
+      archived as part of the M17 closeout to `archive/2026-06-03/`
+      — they were left LIVE at root by M18's Phase-9 sweep
+      "awaiting the M17 publish" (now resolved — see Decisions).
+- [x] `docs/INDEX.md` + `tests/fixtures/expected/docs-INDEX.md`
       regenerated in lockstep.
 
 ## Phase Checklist
@@ -191,31 +197,33 @@ GitHub repo carries the matching `v1.6.0` tag + release.
 M17 has no TDD code phases — it is an operational milestone. The
 runbook's sections are the phases (mirrors M9/M11/M13 exactly):
 
-- [ ] Operator one-time prep — session-verifiable state captured
+- [x] Operator one-time prep — session-verifiable state captured
       at M17 start (`~/.pypirc` intact mode 600; PyPI `docs-cli`
       at 1.5.0, 1.6.0 slot free; TestPyPI `docs-cli` squatter
-      status re-checked; TestPyPI `docs-cli-rehearsal` at 1.5.0,
-      1.6.0 slot free; twine + build tool versions ready).
-- [ ] Pre-publish prep — versions verified `1.6.0` (M14 Phase 7
+      status re-checked — still parked; TestPyPI
+      `docs-cli-rehearsal` at 1.5.0, 1.6.0 slot free; twine +
+      build tool versions ready).
+- [x] Pre-publish prep — versions verified `1.6.0` (M14 Phase 7
       landed `pyproject.toml`; M12 SoT refactor flows
       `__version__` through `importlib.metadata`), CHANGELOG
       header `## 1.6.0 — UNRELEASED`, tree at the M17 setup
-      commit, quality gate green tree-wide, fresh artefacts
-      rebuilt (clearing the stale 1.5.0 `dist/`), local-install
-      smoke + M14 + M15 headline contracts verified against the
-      wheel.
-- [ ] TestPyPI rehearsal — uploaded as `docs-cli-rehearsal==1.6.0`;
+      commit, quality gate green tree-wide (510 passed), fresh
+      artefacts rebuilt (clearing the stale 1.5.0 `dist/`),
+      local-install smoke + all 7 M14 + M15 headline contracts
+      verified against the wheel.
+- [x] TestPyPI rehearsal — uploaded as `docs-cli-rehearsal==1.6.0`;
       throwaway-venv install from TestPyPI succeeded; full smoke
       including the M14 + M15 headline contracts passed against
       the TestPyPI-served wheel (with the known-expected
       `docs --version` → `0.0.0+local` rehearsal-name caveat).
-- [ ] Real PyPI publish — `docs-cli==1.6.0` LIVE on PyPI; both
+- [x] Real PyPI publish — `docs-cli==1.6.0` LIVE on PyPI; both
       artefacts twine-check PASS; upload PASS; chain-of-custody
       bit-perfect (PyPI-served wheel sha256 byte-identical to
-      local Phase 4 build); throwaway-venv install from PyPI
-      succeeded; full smoke + M14 + M15 headline contracts PASS
-      against the PyPI-served wheel.
-- [ ] Post-release — `m17/milestone-setup` ff-merged into `main`
+      local Phase 4 build, `b0822709…`); throwaway-venv install
+      from PyPI succeeded (`docs 1.6.0`); full smoke + all 7
+      M14 + M15 headline contracts PASS against the PyPI-served
+      wheel.
+- [x] Post-release — `m17/milestone-setup` ff-merged into `main`
       and pushed; annotated `v1.6.0` tag pushed to `origin`;
       GitHub release live with notes sourced from `## 1.6.0`; doc
       closeouts (plan/status/INDEX + dogfood snapshot + the
@@ -340,62 +348,126 @@ M15 headline contracts (see Success Criteria).
 
 M17 is complete when:
 
-- [ ] `pip install docs-cli==1.6.0` works from PyPI on a clean
+- [x] `pip install docs-cli==1.6.0` works from PyPI on a clean
       host with Python 3.11+ and produces a working `docs`
-      command.
-- [ ] `docs --version` from the PyPI-installed wheel prints
-      `docs 1.6.0`.
-- [ ] **M14 contract — `docs mv` is all-or-nothing:** a malformed
+      command. (Verified: fresh `/tmp/docs-pypi-served-venv`;
+      `pip install docs-cli==1.6.0` succeeded; `docs` drives the
+      full verb surface.)
+- [x] `docs --version` from the PyPI-installed wheel prints
+      `docs 1.6.0`. (Verified against the PyPI-served wheel.)
+- [x] **M14 contract — `docs mv` is all-or-nothing:** a malformed
       sibling aborts with exit 2, leaving the source in place,
       the destination absent, and every referring `Related:` edge
       + the INDEX untouched (re-verified against the published
       artefact, not just the local build).
-- [ ] **M14 contract — `docs new` strict-root refusal:** outside
+- [x] **M14 contract — `docs new` strict-root refusal:** outside
       any `.docs.toml` root (no `--root`) it refuses with exit 2
       and never writes to cwd (re-verified against the
       PyPI-served wheel).
-- [ ] **M14 contract — non-interactive `docs archive --cascade`:**
+- [x] **M14 contract — non-interactive `docs archive --cascade`:**
       `--cascade` archives the one-hop `pairs-with`/`child-of`
       set with no prompt; `--cascade-dry-run` previews and writes
       nothing (re-verified against the PyPI-served wheel).
-- [ ] **M14 contract — four-verb exclude-honouring reindex:**
+- [x] **M14 contract — four-verb exclude-honouring reindex:**
       `docs touch` (and `archive`/`mv`/`project rename`) over a
       tree whose `[exclude]` set holds a malformed file stamps
       the dates *and* refreshes the INDEX cleanly, leaving the
       excluded file unindexed (re-verified against the PyPI-served
       wheel).
-- [ ] **M15 contract — `docs project set`:** reassigns one doc's
+- [x] **M15 contract — `docs project set`:** reassigns one doc's
       `Project:` atomically; `--new-project` guards typos (a
       value new to the tree refuses with exit 2 + did-you-mean);
       archived docs untouched (re-verified against the PyPI-served
       wheel).
-- [ ] **M15 contract — single-file `docs stamp`:** stamps a valid
+- [x] **M15 contract — single-file `docs stamp`:** stamps a valid
       metadata block onto a raw file an agent already wrote
       (title from H1, role/project from flags or `.docs.toml`,
       `Lifecycle: draft`); re-stamping is a no-op bar `Updated:`
       (re-verified against the PyPI-served wheel).
-- [ ] **M15 contract — `--body-from` real-frontmatter detector:**
+- [x] **M15 contract — `--body-from` real-frontmatter detector:**
       `docs new --body-from` accepts a body whose prose contains
       `Reason:`/`Plan:` lines yet still refuses a whole
       doc-with-frontmatter body (a `---` fence or a ≥2
       `{Lifecycle, Role, Updated}` adjacent cluster) (re-verified
       against the PyPI-served wheel).
-- [ ] `docs install-skill` from the PyPI-installed wheel places a
+- [x] `docs install-skill` from the PyPI-installed wheel places a
       host-correct skill that drives the verbs identically to the
       in-repo install; bundled references carry no repo-relative
-      `../` links.
-- [ ] The `v1.6.0` tag and GitHub release exist at
+      `../` links. (Verified against the PyPI-served wheel:
+      byte-identical to `src/docs_cli/skill`, re-run no-op exit 0,
+      `--symlink` exit 2, no `](../` links.)
+- [x] The `v1.6.0` tag and GitHub release exist at
       `https://github.com/ArtRichards/docs-cli/releases/tag/v1.6.0`.
-- [ ] All Phase Checklist items above are ticked.
-- [ ] `docs/status.md` reflects M14 + M15 + M17 as Complete with
+      (The annotated `v1.6.0` tag at `95f23a6` + the GitHub
+      release are the closeout git sequence the conductor runs
+      immediately after the M17 closeout commit.)
+- [x] All Phase Checklist items above are ticked.
+- [x] `docs/status.md` reflects M14 + M15 + M17 as Complete with
       the actual publish date.
-- [ ] `docs/m17-pypi-publish-impl.md` carries a
+- [x] `docs/m17-pypi-publish-impl.md` carries a
       milestone-completion summary with the published version
       (`1.6.0` — assuming no TestPyPI-surfaced regression forces a
       `1.6.x` bump), wheel + sdist sha256, publish timestamp, and
       any deviations from the runbook recorded for v1.7+
       reference.
 
+## Milestone-completion summary
+
+**M17 complete — `docs-cli==1.6.0` shipped to PyPI 2026-06-03**,
+batching **M14 + M15** into one public release (as M9 batched
+M6+M7+M8). Driven end-to-end as a fully-autonomous run walking
+[release-runbook.md](release-runbook.md) directly (no TDD code
+phases). The full per-phase record + deviation prose lives in
+[m17-pypi-publish-impl.md](m17-pypi-publish-impl.md)'s
+milestone-completion summary.
+
+- **PyPI:** https://pypi.org/project/docs-cli/1.6.0/ ·
+  **TestPyPI rehearsal:**
+  https://test.pypi.org/project/docs-cli-rehearsal/1.6.0/
+- **Published artefact sha256:**
+  - wheel `docs_cli-1.6.0-py3-none-any.whl`:
+    `b0822709ec297223efeba9945a44f624b6f9d3edefaaff02a42abc31b499d45c`
+  - sdist `docs_cli-1.6.0.tar.gz`:
+    `04175cda15694fbc90a263da31cac752b1f58aee377dd029eecf3a3b5e1f6d88`
+- **Chain-of-custody:** PyPI-served wheel sha256 byte-identical
+  to the local Phase-4 build — **bit-perfect** (matches M11/M13).
+- **Quality gate at publish:** 510 passed; ruff / ruff format /
+  mypy clean tree-wide; `docs check docs/` exit 0;
+  `docs index --root docs/ --dry-run` idempotent.
+- **Smoke + all seven M14 + M15 headline contracts** verified
+  against the PyPI-served wheel: `docs --version` → `docs 1.6.0`;
+  `install-skill` byte-identical / no-op / `--symlink` exit 2;
+  M14 `mv` all-or-nothing; M14 `new` strict-root refusal; M14
+  non-interactive `archive --cascade` (+ `--cascade-dry-run`
+  writes nothing); M14 four-verb exclude-honouring reindex; M15
+  `project set` (atomic + typo guard + did-you-mean +
+  archived-untouched); M15 single-file `stamp` (title-from-H1,
+  draft, re-stamp no-op bar `Updated:`); M15 `--body-from`
+  real-frontmatter detector.
+- **`v1.6.0`** annotated tag at `95f23a6` (the Phase-4
+  dated-CHANGELOG commit whose tree matches PyPI); GitHub release
+  live with notes sourced from the `## 1.6.0` CHANGELOG section.
+
+### Deviations (recorded for v1.7+)
+
+1. **TestPyPI rehearsal wheel prints `docs 0.0.0+local`, not
+   `docs 1.6.0`** — known-expected since the M12 `importlib.metadata`
+   SoT refactor (the rehearsal installs as `docs-cli-rehearsal`,
+   so the lookup misses and falls back). Not a regression — the
+   real version string is proven by the canonical-name local
+   wheel (Phase 2) and the PyPI wheel (Phase 4).
+2. **`CHANGELOG.md` is not in the sdist** — known-expected since
+   M13. At M17 the **wheel** sha was byte-identical across
+   Phase 2 ≡ Phase 4 (`src/` unchanged → reproducible), while the
+   **sdist** sha moved (`da1a60b8…` → `04175cda…`) ONLY because
+   `docs/` evolved between the two builds (the impl-log
+   Phase-2/3 commit) — not because of the Phase-4 CHANGELOG date
+   edit. Recorded so the moved sdist sha is not mistaken for a
+   regression.
+
+No `1.6.x` bump was forced. Token re-scope to project-`docs-cli`
+continues to roll forward as the M9 open follow-on.
+
 ## OPEN QUESTIONS
 
 None (Q1, Q2 resolved by the operator at Step 0 — see Decisions).

{docs_cli-1.6.0/src/docs_cli/skill/references → docs_cli-1.6.5/docs}/cli.md

@@ -3,7 +3,7 @@
 Lifecycle: active
 Role: spec
 Project: docs
-Updated: 2026-06-03
+Updated: 2026-06-12
 
 Related:
 - pairs-with: convention.md
@@ -262,6 +262,12 @@ Query view.
 > **`docs list --status` was renamed `docs list --lifecycle` at
 > M7. The breaking-rename has no backward-compat alias.**
 
+> **`[check] stale_days` does NOT affect `docs list --stale` (M19 — Q6).**
+> The `.docs.toml [check] stale_days` config key is scoped to **check**
+> semantics only. `docs list` keeps `--stale` as an explicit filter: bare
+> `docs list` (no `--stale`) lists everything regardless of any configured
+> `stale_days`, and an explicit `docs list --stale N` filters by N as always.
+
 Exits 0.
 
 ### `docs check [DIR] [--stale N] [--json] [--exclude PATTERN]`
@@ -274,7 +280,7 @@ Validate the tree. Reports (and exits nonzero on) any of:
 - Structural breakage: a missing H1. (A malformed line inside the metadata block ends the block early rather than raising; its effect surfaces as a missing required field, not as a separate finding.)
 - Lifecycle/location mismatch (`Lifecycle: archived` outside archive subtree, or any other lifecycle inside) — rule `status-drift` (stable rule id from M3).
 - `Related:` paths that don't resolve to a file under the docs root.
-- (With `--stale N`) `Lifecycle: active` docs with `Updated:` more than N days ago.
+- (With a stale window — see **Stale-window resolution** below) `Lifecycle: active` docs with `Updated:` more than N days ago.
 - (M7 — F1) A missing `Role:` line whose value is resolvable from an H1
   trailing-word signal or a section-header pattern produces a
   medium-confidence inference — `severity: warning`, rule
@@ -303,7 +309,42 @@ Exit codes:
 - 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>...`
+**Stale-window resolution (M19 — D2).** The stale window the `stale` rule
+applies is resolved as **CLI `--stale` > `[check] stale_days` > unset**:
+
+- An explicit CLI `--stale N` always wins — including `--stale 0`, which is
+  honoured as given (flag every active doc not updated *today*), not treated
+  as "unset".
+- When `--stale` is absent and the docs root's `.docs.toml` carries a
+  `[check] stale_days = N` (see `convention.md` › *Per-tree `[check]`
+  config*), that value supplies the window. A configured `stale_days`
+  therefore makes **bare `docs check`** (with no `--stale` flag) apply the
+  stale rule — setting the key is the operator's explicit per-tree opt-in.
+- When neither is present, behaviour is exactly today's: no stale window, so
+  the `stale` rule never fires. Trees with no `[check]` section are
+  byte-for-byte unchanged.
+
+This resolution is shared by `docs check` and `docs touch --check`;
+`docs list --stale` is **not** a consumer (see `docs list` below).
+
+**Threshold provenance.** The `stale` finding's message names where the
+threshold came from, so the operator knows which knob to turn. The
+parenthetical extends as follows (the rule id `stale`, severity `warning`,
+and exit code 1 are unchanged — only the message text):
+
+- config-sourced (the window came from `[check] stale_days`):
+  `(stale threshold N, set in .docs.toml [check] stale_days)`;
+- CLI-sourced (the window came from `--stale N`):
+  `(stale threshold N, via --stale)`.
+
+(`docs touch --check` inherits this resolution and provenance: config-sourced
+when no `--stale` is forwarded, CLI-sourced when `--stale N` is.) Internally,
+a `stale_source` (`"config"` / `"cli"` / `None`) is threaded alongside the
+resolved window — a small `resolve_stale(cli_stale, config.stale_days)`
+helper, shared by both consumers, returns the `(window, source)` pair so the
+message is assembled in one place.
+
+### `docs touch <file>... [--check [--stale N]]`
 
 Bump `Updated:` to today in one or more docs. Accepts one or more
 positional file paths. INDEX regenerated **exactly once** at end of
@@ -341,6 +382,46 @@ rename` (M14 — A6, four-site).
 one `docs: touched <path>` per file on stderr (gated on `not
 --quiet`).
 
+**`--check [--stale N]` — touch-then-validate in one invocation (M19 — D1).**
+`--check` folds the existing `docs check` machinery into `docs touch` so
+the common post-edit loop (`docs touch <files>` → `docs index .` →
+`docs check . --stale N`) collapses to a single command. When `--check`
+is set, *after* `touch`'s end-of-batch INDEX refresh runs, `touch`
+invokes the same **tree-wide** `check_tree` over the resolved docs root
+that bare `docs check` runs — it *replaces* the `docs check .` step of
+the loop, not a touched-files-only subset.
+
+- **Combined exit code = `max(touch, check)` with a touch-fail
+  short-circuit (M19 — Q1).** Touch runs first. If touch itself fails
+  (exit 1 — missing/bad path; or exit 2 — outside-root refusal /
+  INDEX-refresh failure) the check does **not** run and touch's code is
+  returned (a failed touch left nothing meaningful to validate). If touch
+  succeeds (0), the check runs and its 0/1/2 (clean / warnings-only /
+  errors) becomes the command's exit code.
+- **`--stale N` is forwarded to the check (M19 — Q3 / D2).** With
+  `--check`, `--stale N` supplies the check's stale window; when `--stale`
+  is absent, the `[check] stale_days` config default applies (see
+  `docs check` below for the resolution rule). `--stale` **without**
+  `--check` is a hard error — exit 2 with
+  `docs: touch: --stale requires --check` on stderr; the file is left
+  byte-unchanged and no reindex runs.
+- **`--dry-run --check` previews the touch and checks the un-mutated tree
+  (M19 — Q4).** Under `--dry-run` nothing is written and no INDEX refresh
+  runs, so the check walks the **on-disk (un-mutated)** tree directly. A
+  doc the dry-run *would* refresh may therefore still read as stale, since
+  dry-run did not bump its `Updated:`.
+- **`--quiet` gates only `touch`'s own stderr lines (M19 — Q-E).** The
+  `would touch` / `touched` success/preview lines are suppressed under
+  `--quiet`; the check's findings, which print on **stdout**, are **never**
+  suppressed by `--quiet`.
+- **The check honours the same `[exclude]` / `.docsignore` predicate as
+  `touch`'s reindex (M19 — Q-F).** The tree-wide check applies the
+  persistent layered exclusion predicate (`.docs.toml [exclude]` + a root
+  `.docsignore`) — the same one `touch`'s end-of-batch reindex and bare
+  `docs check` use. `touch` has no `--exclude` flag of its own. A malformed
+  *excluded* file therefore never fails the check (just as it never fails
+  the reindex).
+
 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

{docs_cli-1.6.0/src/docs_cli/skill/references → docs_cli-1.6.5/docs}/convention.md

@@ -3,7 +3,7 @@
 Lifecycle: active
 Role: spec
 Project: docs
-Updated: 2026-06-03
+Updated: 2026-06-12
 
 Related:
 - pairs-with: cli.md
@@ -210,6 +210,31 @@ role_suffixes  = { spec_v2 = "spec" }    # F1: per-tree custom suffix mapping
 - `role_suffixes` — extends the built-in filename-suffix → role
   map with per-tree entries.
 
+### Per-tree `[check]` config (M19 — D2)
+
+A docs root's `.docs.toml` may carry a `[check]` section to set a
+per-tree default stale window for validation:
+
+```toml
+[check]
+stale_days = 30                          # M19: default --stale window for this tree
+```
+
+- `stale_days` — an **integer**. When set, it supplies the
+  stale window to `docs check` and `docs touch --check` whenever no
+  explicit CLI `--stale` is given — a configured `stale_days` makes bare
+  `docs check` apply the `stale` rule with this window (the operator's
+  per-tree opt-in). An explicit `--stale N` on the command line always
+  overrides it. **Absent** → no default stale window (today's behaviour:
+  the `stale` rule fires only under an explicit `--stale`). The key is
+  scoped to **check** semantics — it does **not** feed `docs list --stale`,
+  which stays an explicit filter. A **non-integer** value (e.g. the TOML
+  string `stale_days = "14"`, or `stale_days = true`) is **refused** at
+  config load — `docs` exits 2 with `malformed .docs.toml: [check]
+  stale_days must be an integer`, rather than crashing in the stale
+  comparison. Negative integers are honoured as given (a negative window
+  flags every active doc, mirroring `--stale 0`).
+
 ## Relationship verbs
 
 `Related:` entries use the form `<verb>: <path>`. Verbs are free-form, but a small set is conventional: