feat(conventions): topic-docs v3.0.0 — recursive slices with per-slice INDEX.md

.github/workflows/ci.yml

@@ -629,6 +629,26 @@ jobs:
           BASE_REF: ${{ github.base_ref }}
         run: scripts/sync-resolve-convention-pattern.sh --check-bump "origin/$BASE_REF"
 
+  index-regen-sync:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Fetch base
+        uses: ./.github/actions/checkout-with-base
+      - name: Verify plugin copies match the shared regen script
+        run: scripts/sync-index-regen.sh --check
+      - name: Run shared regen-script tests
+        run: bash lib/index-regen.test.sh
+      - name: Verify consuming plugins bumped when the lib changed
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: scripts/sync-index-regen.sh --check-bump "origin/$BASE_REF"
+
   standards-contract-sync:
     runs-on: ubuntu-24.04
     timeout-minutes: 15
@@ -1699,6 +1719,7 @@ jobs:
       - managed-scope-sync
       - state-key-sync
       - resolve-convention-pattern-sync
+      - index-regen-sync
       - standards-contract-sync
       - cross-plugin-source-drift
       - loop-lane-floor-drift-gate

.worktreeinclude

@@ -3,16 +3,16 @@
 # The self-ignore file rides along so carried files stay ignored in the new
 # worktree from creation, not only after the first memory-tier write heals it.
 .work/.gitignore
-.work/*/EXPLORE.md
-.work/*/EXPLORE-*.md
-.work/*/RESEARCH.md
-.work/*/RESEARCH-*.md
-.work/*/*-checklist.md
-# Sub-slices (<memory_dir>/<slug>/<sub-slug>/) — a parallel fan-out assigns one
-# per topic. Globs do not descend, so without these a worktree carries the
-# top-level index and silently drops every nested index, sidecar, and ledger.
-.work/*/*/EXPLORE.md
-.work/*/*/EXPLORE-*.md
-.work/*/*/RESEARCH.md
-.work/*/*/RESEARCH-*.md
-.work/*/*/*-checklist.md
+# Keyed on the reserved memory-tier filenames, not on how deep the topic folder
+# happens to sit. `.work/**/NAME` matches zero or more intervening directories,
+# so one line covers the top level, a slice, a sub-slice under an epic, and
+# anything deeper a fan-out invents. Depth-enumerated globs (`.work/*/`,
+# `.work/*/*/`) silently dropped every level past the last one written down.
+.work/**/INDEX.md
+.work/**/EXPLORE.md
+.work/**/EXPLORE-*.md
+.work/**/RESEARCH.md
+.work/**/RESEARCH-*.md
+.work/**/INTENT.md
+.work/**/INTENT-*.md
+.work/**/*-checklist.md

docs/MIGRATION-PLAYBOOK.md

@@ -459,8 +459,9 @@ Separate **plugin-owned** logic from **consumer-owned** extension points:
 **The marketplace `renames` map is frozen-historical.** Its twelve entries stay: a consumer whose
 `enabledPlugins` still names a pre-rename plugin id resolves only through the map, and removing an
 entry strands them. But nothing new is added to it. A rename from here on is a clean breaking change
-carried by a version bump and a changelog note — the standing posture in
-[shadowed-skill-renames](topics/shadowed-skill-renames/PLAN.md) — so the map records migrations
+carried by a version bump and a changelog note — the standing posture locked in
+`docs/topics/shadowed-skill-renames/` (pruned per the topic-docs convention; read it
+in history at `c70d8867ccd9f9921fdde25de70cb9a91e718c80`) — so the map records migrations
 already shipped rather than serving as the go-forward mechanism.
 
 ### Same-version commit drift (directory-source marketplaces)

docs/PLUGIN-ARTIFACT-PROTOCOL.md

@@ -1,6 +1,6 @@
 # Plugin lifecycle artifact protocol
 
-Protocol version: 2
+Protocol version: 3
 
 This protocol is the lifecycle interoperability profile for repo-facing plugins that participate in
 discovery, planning, implementation, verification, or handoff. The marketplace-wide topic-docs convention
@@ -23,8 +23,13 @@ the convention's guards rather than silently falling back to another location.
 
 Lifecycle plugins exchange these public artifacts:
 
-- Memory tier: `EXPLORE.md`, `RESEARCH.md`, `<stage>-checklist.md`, `baselines/`, raw captures, and
-  scratch under `<memory_dir>/<topic-slug>/`.
+- Memory tier: `INDEX.md` (the reserved per-slice index), `EXPLORE.md`, `RESEARCH.md`,
+  `<stage>-checklist.md`, `baselines/`, raw captures, and scratch under
+  `<memory_dir>/<topic-slug>/`. A topic slice is recursive: a decomposed slice holds child slices,
+  and the same names are reserved at every depth. Entering a slice follows the convention's
+  read-first binding (read `INDEX.md` first; in an index-less leaf the sole artifact is the entry
+  point), whose single home is the convention README's slice-tree section, cited here rather than
+  restated.
 - Contract tier: `PRD.md`, `PLAN.md`, `design/`, and distilled `verification/` manifests under
   `<contract_dir>/<topic-slug>/` when `contract_tier: branch`.
 - In `contract_tier: local`, contract kinds join the memory slice with the same relative layout.

docs/conventions/commit-convention/README.md

@@ -173,4 +173,4 @@ file is not renamed.
 
 ## Sources
 
-- Design topic for the well-known-path decision: [`docs/topics/commit-convention-well-known-path/`](../../topics/commit-convention-well-known-path/), carrying PR #1185.
+- Design topic for the well-known-path decision: `docs/topics/commit-convention-well-known-path/`, carried by PR #1185. That slice was Contract tier and has since been pruned per the topic-docs convention, so the path no longer resolves; read it in history at its pre-prune commit `01c8c6f3aada6710014aa299c43c70c65d1d6f48`.

docs/conventions/topic-docs/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog — topic-docs convention
 
+## 3.0.0 — 2026-09-01
+
+Major under the Versioning rule: the memory tier's slice shape, the reserved-name set, and the
+worktree-carry recipe all change, and every implementer flips in this same release wave (clean
+break; this contract carries no compatibility machinery, and there is no v2 mode). The design
+record is the work-folder-hierarchy Brief (PR #3552) and its nine resolved design threads;
+the substrate (regen lib, gate rework, carry patterns, renames) landed in the same PR ahead of
+this flip.
+
+Breaking:
+
+- **Recursive topic slices.** A slice is the same thing at every depth; an epic is a slice with
+  child slices. Levels are created lazily, on decomposition or on collision, never pre-built.
+  Recursion scopes to topic slices only; reserved first-level concern names stay flat unless
+  their own contract says otherwise.
+- **`INDEX.md` reserved at every depth**, required for a slice with child slices or more than one
+  artifact family; a single-artifact leaf omits it. "Read `INDEX.md` first; in an index-less leaf
+  the sole artifact is the entry point" is now a normative binding that implementers cite.
+- **Frontmatter is the single home for slice state** (`slice`, one-unwrapped-line `abstract`,
+  `status: active | parked | done`, ordered `children`). Ordering is index-declared and scoped to
+  child-slice names; numeric prefixes on slice directory names are forbidden.
+- **Marker-delimited generated body**, regenerated only by the shared `lib/index-regen.sh`
+  (registered copies synced byte-identical). Exit codes 0 ok / 1 parity / 2 shape / 3 size cap
+  (~25KB, `INDEX_REGEN_MAX_BYTES`); a cap failure names the two levers and preserves any
+  pre-existing body. Declared-children parity, both directions, lives in this script via the
+  child-slice predicate (`INDEX.md` or a reserved UPPERCASE artifact at a subdirectory root,
+  precedence INDEX > EXPLORE > RESEARCH > INTENT > PLAN > PRD > SOURCES); every other
+  subdirectory is slice-interior under the interior-freedom clause.
+- **Dispatch discipline**: parents assign every slice path (fan-out and collision sub-slices)
+  before dispatching; the discovery gate grades exactly the assigned path and never scans;
+  workers report occupancy by value instead of relocating.
+- **`SOURCES.md`** is docpage-digest's renamed source inventory (was `INDEX.md`), freeing the
+  index name and joining the reserved artifact set with the required `abstract:` header.
+- **`lanes/`** joins the reserved first-level concern names (claude-ops lane state, which
+  resolves a literal `.work` root by its own stated carve-out).
+- **`done` + same-slug re-derivation disambiguates, never resumes.**
+- **Depth-proof carry recipe**: `.worktreeinclude` patterns are reserved-name-keyed
+  (`.work/**/NAME`), covering `INDEX.md` and the `INTENT` family for the first time. The carry is
+  not asserted as verified git-native behavior: `worktree-create.sh` reimplements it via
+  `git ls-files --exclude-from`, where the `**` semantics are verified; corpus-slice indexes are
+  carried and corpus snapshots are not, both deliberately.
+- **Corpus seam shape-unified**: inside the knowledge `library_dir` seam the same slice and
+  `INDEX.md` rules apply, and this contract does not recurse into corpora; topic slices hold
+  pointers.
+- **Artifact protocol version 3**: `INDEX.md` joins the memory-tier kinds and the five registered
+  copies cite the read-first binding.
+
+Unchanged, deliberately: `contract_tier: branch` default, the prune-with-pointer lifecycle and
+pre-prune SHA record, the visibility matrix, the runtime guards, the resolution order, and the
+one-way `.worktreeinclude` copy semantics. `topic-docs.schema.json` renames no key; only its
+`memory_dir` description text follows the new reserved-name roster.
+
 ## 2.5.3 — 2026-08-28
 
 Patch under the Versioning rule: no tier moves, no `topic-docs.yaml` key is renamed, the slug spec