fix(publish): ship legacyDeletions ledger + AGENTS.md task-folder convention (v3.2.1)

v3.2.0 advertised "legacyDeletions 16→23" but the kit shipped with only 16 —
vc-publish bumped the manifest version and copied nothing else, silently
stranding the deprecation ledger. The kit's AGENTS.md likewise still taught the
deprecated reports/references sibling-dir layout.

- vc-manifest.json: legacyDeletions 16→23 (the 7 reports/references stale-dir
  paths now ship, so downstream vc-update cleans them up as intended)
- AGENTS.md: task-folder convention + safe legacy-dir migration guidance
- vc-publish SKILL.md + reference: explicit manifest reconciliation — version
  bump + legacyDeletions auto-sync dev→kit + field-level drift report for all
  other fields (root-cause fix so no manifest field silently desyncs again)
- README version badge + CHANGELOG 3.2.1 entry

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: withkynam

.claude/skills/vc-publish/SKILL.md

@@ -144,7 +144,45 @@ Version bump semantics:
          - Absolute paths (`/Users/...`)
          - Product name references (the project's product name and repo/directory name)
       5. Verify the result is harness-only methodology with no project leaks.
-    - Update `vc-manifest.json`: bump `version` field per the chosen bump type. **No other manifest changes needed** -- glob patterns are stable, new files are automatically included.
+    - **Manifest reconciliation** (`vc-manifest.json`) — the manifest is NOT a normally-copied
+      managed file (it is dev-only on one side and kit-resolved on the other), so its fields do
+      NOT auto-sync. Handle it explicitly:
+      1. **`version`**: bump per the chosen bump type. Kit-authoritative.
+      2. **`legacyDeletions`** (the deprecation ledger): **dev is authoritative and always the
+         superset.** Whenever dev removes a skill/dir/file from the harness it appends the path
+         here so downstream projects clean it up on their next `vc-update`. Set
+         `kit.legacyDeletions = dev.legacyDeletions` (preserve dev order). This field is a literal
+         path array, NOT a glob — it genuinely changes every time the harness deprecates something,
+         so it MUST be reconciled at every publish. (Historically this was skipped, which silently
+         stranded the kit with stale deletions — never skip it.)
+      3. **All OTHER non-version fields** (`include`, `exclude`, `strip`, `merge`, `copyIfMissing`,
+         `symlinks`, `kitOnly`): these legitimately diverge — the kit carries packaging-only rules
+         (e.g. excluding `**/*.test.mjs` and `__tests__/**` so tests are not shipped to users;
+         `kitOnly` tooling like `compute-sync-plan.mjs`). **Do NOT blindly overwrite them** — a
+         blanket dev→kit copy would strip the kit's test-excludes and ship test files. Instead run
+         the **field-level drift report** below and reconcile any unexpected drift by hand.
+
+      Drift-report command (run during Step 4 summary AND here before writing):
+      ```bash
+      node -e '
+      const d=require("<devRepoPath>/vc-manifest.json");
+      const k=require("<kitRepoPath>/vc-manifest.json");
+      let drift=0;
+      for(const key of new Set([...Object.keys(d),...Object.keys(k)])){
+        if(key==="version") continue;
+        if(JSON.stringify(d[key])!==JSON.stringify(k[key])){
+          drift++;
+          console.log("DRIFT field:",key);
+          console.log("  dev:",JSON.stringify(d[key]));
+          console.log("  kit:",JSON.stringify(k[key]));
+        }
+      }
+      console.log(drift?("\n"+drift+" manifest field(s) drift — legacyDeletions auto-syncs dev→kit; reconcile the rest consciously."):"manifest in sync (besides version)");
+      '
+      ```
+      `legacyDeletions` appearing in the drift report is EXPECTED and is auto-resolved (dev→kit).
+      Any OTHER field in the report is a conscious decision: confirm the kit value is the intended
+      packaging rule, or update dev/kit so they converge. Never let a drift go unexamined.
     - Create symlinks if missing (`.agents/skills -> ../.claude/skills`).
 
 ### Step 8: Leak Detection
@@ -308,7 +346,14 @@ Release:       https://github.com/<owner>/<repo>/releases/tag/v2.2.0
 
 ## Key Changes from v1.0
 
-- **No manifest array maintenance.** The glob patterns in `include`/`exclude`/`kitOnly` are stable. Adding a new skill or agent requires zero manifest edits. The only manifest change at publish time is the version bump.
+- **Glob arrays are stable; the deprecation ledger is not.** The glob patterns in
+  `include`/`exclude`/`kitOnly` are stable — adding a new skill or agent requires zero manifest
+  edits (new files are auto-included by the globs). BUT `legacyDeletions` is a literal path array,
+  not a glob: it grows every time the harness deprecates a skill/dir/file, and it MUST be
+  reconciled dev→kit at every publish (see Step 7 Manifest reconciliation). Skipping it strands
+  the kit with a stale deletion ledger so downstream `vc-update`s never clean up the newly
+  deprecated dirs. So publish-time manifest edits are: (1) version bump, (2) `legacyDeletions`
+  sync, (3) conscious reconciliation of any other field flagged by the drift report.
 - **Resolver-driven diffing.** The kit repo is resolved via `resolve-manifest.mjs` (which requires `vc-manifest.json` in its `--root`). The dev-side file comparison is handled inside `compute-sync-plan.mjs`, which reads the manifest from `--kit-root` (always the kit checkout). Dev repos do not carry `vc-manifest.json`.
 - **No `managed`/`managedDirs` arrays to update.** The old workflow of adding new files to these arrays is eliminated.
 

.claude/skills/vc-publish/references/vc-publish.md

@@ -42,7 +42,7 @@ The `--json` output provides all metadata needed for diffing:
 }
 ```
 
-**Key change from v1.0:** The publish step no longer needs to update `managed`/`managedDirs` arrays in the manifest. Glob patterns are stable -- new files are automatically included. The only manifest edit at publish time is the version bump.
+**Key change from v1.0:** The publish step no longer needs to update `managed`/`managedDirs` arrays in the manifest. Glob patterns (`include`/`exclude`/`kitOnly`) are stable -- new files are automatically included. Manifest edits at publish time are: (1) version bump, (2) `legacyDeletions` sync dev→kit (the deprecation ledger is a literal path array, NOT a glob -- it grows on every harness deprecation and must be reconciled every publish), and (3) conscious reconciliation of any other field flagged by the Step 7 drift report. Do NOT blanket-copy the dev manifest over the kit's -- the kit carries packaging-only deltas (test-file excludes, kit-only tooling) that must survive.
 
 ## CLAUDE.md / AGENTS.md Content Stripping
 

AGENTS.md

@@ -212,20 +212,22 @@ Feature-scoped storage for large feature clusters. Each feature folder contains:
 - `active/` - In-progress plans
 - `completed/` - Archived completed plans
 - `backlog/` - Deferred/future plans
-- `reports/` - Feature-specific operational reports
-- `references/` - Feature-specific research and reference documents
+
+Task-folder convention:
+- Reports, references, specs, and plans live inside the task folder under `active/` or `completed/`
+- Legacy sibling `reports/` and `references/` dirs may still appear during migration, but `vc-setup` and `vc-update` should migrate safe cases into task folders and remove emptied legacy dirs
 
 See `process/context/all-context.md` for current feature list.
 
-Routing rule: When a feature has 5+ artifacts, store new plans/reports in
-`process/features/{feature}/`. General or cross-cutting items go in
-`process/general-plans/` with `reports/` and `references/` inside.
+Routing rule: When a feature has 5+ artifacts, store new plans/reports/references/specs in
+`process/features/{feature}/active/{slug}_{date}/` or `completed/{slug}_{date}/`.
+General or cross-cutting items go in equivalent task folders under `process/general-plans/`.
 
 When routing to a subagent for a feature-scoped task, include `Feature: {feature-name}` in
 the prompt and override paths:
 
-- `Reports: {work_context}/process/features/{feature}/reports/`
 - `Plans: {work_context}/process/features/{feature}/active/`
+- When the selected task folder is known, pass that exact `active/{slug}_{date}/` or `completed/{slug}_{date}/` path as the authoritative artifact location
 
 #### Feature Folder Lifecycle
 
@@ -242,24 +244,21 @@ At plan creation time, use this decision logic:
 
 Promotion protocol from general to feature folder:
 
-1. Create `process/features/{new-feature}/` with subdirs: `active/`, `completed/`, `backlog/`, `reports/`, `references/`
-2. Move related artifacts from `process/general-plans/`, including reports and references, into the new feature's subdirs
+1. Create `process/features/{new-feature}/` with subdirs: `active/`, `completed/`, `backlog/`
+2. Move related artifacts from `process/general-plans/` into the new feature's task folders; migrate safe legacy `reports/` and `references/` artifacts into those task folders and remove emptied legacy dirs
 3. Update the Current features list above
 4. Inform subagents of the new feature scope going forward
 
 Feature list maintenance: The Current features list above must be updated whenever a new
 feature folder is created or an empty one is removed. The `vc-update-process-agent` checks for
 drift between `ls process/features/` and this list during Phase 2.
 
-### `process/general-plans/reports/`
-
-General/cross-cutting operational reports. Feature-specific reports live in
-`process/features/{feature}/reports/`.
-
-### `process/general-plans/references/`
+### Legacy sibling dirs
 
-General/cross-cutting research outputs. Feature-specific references live in
-`process/features/{feature}/references/`.
+`process/general-plans/reports/`, `process/general-plans/references/`,
+`process/features/{feature}/reports/`, and `process/features/{feature}/references/`
+are deprecated legacy surfaces. They should be drained into task folders when safe and
+removed once empty.
 
 When routing to subagents, always pass relevant `process/context/` files. As new context
 files are added, for example UI patterns or deployment procedures, agents automatically benefit.

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to vibecode-pro-max-kit are documented in this file.
 
+## [3.2.1] - 2026-06-20
+
+### Fixed
+
+- `legacyDeletions` ledger now actually shipped: the kit was stranded at 16 entries while v3.2.0's changelog advertised 23. The 7 deprecated `reports/`/`references/` stale-dir paths (`process/general-plans/reports`, `process/general-plans/references`, `process/development-protocols/references`, and 4 `_seeds` reports/references paths) are now present, so a downstream `vc-update` will clean them up as intended.
+- `AGENTS.md` task-folder convention propagated: the kit's `AGENTS.md` still taught the deprecated `reports/`/`references/` sibling-dir layout (instructing agents to *create* those dirs). It now describes the task-folder convention and safe legacy-dir migration, matching the seed guides and `vc-setup`/`vc-update`.
+
+### Changed
+
+- `vc-publish` no longer silently drops non-version manifest fields. The publish flow now reconciles `vc-manifest.json` explicitly: `version` is bumped, `legacyDeletions` (the deprecation ledger — a literal path array, not a glob) is auto-synced dev→kit every publish, and all other fields run through a field-level drift report so packaging deltas (test-file excludes, kit-only tooling) are reconciled consciously instead of silently desyncing. This is the root-cause fix for the two misses above.
+
 ## [3.2.0] - 2026-06-20
 
 ### Added

README.md

@@ -88,7 +88,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/github/license/withkynam/vibecode-pro-max-kit" alt="License"></a>
   <a href="https://github.com/withkynam/vibecode-pro-max-kit/graphs/contributors"><img src="https://img.shields.io/github/contributors/withkynam/vibecode-pro-max-kit" alt="Contributors"></a>
   <a href="https://github.com/withkynam/vibecode-pro-max-kit/actions/workflows/validate.yml"><img src="https://img.shields.io/github/actions/workflow/status/withkynam/vibecode-pro-max-kit/validate.yml" alt="CI"></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.2.0-2EA043" alt="Version"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.2.1-2EA043" alt="Version"></a>
   <img src="https://img.shields.io/badge/agents-15-orange" alt="Agents">
   <img src="https://img.shields.io/badge/skills-33-purple" alt="Skills">
   <img src="https://img.shields.io/badge/hooks-10-blue" alt="Hooks">

vc-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.2.0",
+  "version": "3.2.1",
   "include": [
     ".claude/agents/**",
     ".claude/skills/**",
@@ -77,6 +77,13 @@
     "process/development-protocols/references/example-simple-prd.md",
     "process/development-protocols/intent-clarification.md",
     "process/development-protocols/parallel-fan-out.md",
-    "process/development-protocols/archive/vc-system-behavior-reference_ARCHIVED_09-06-26.md"
+    "process/development-protocols/archive/vc-system-behavior-reference_ARCHIVED_09-06-26.md",
+    "process/general-plans/reports",
+    "process/general-plans/references",
+    "process/development-protocols/references",
+    "process/_seeds/features/_feature-template/reports",
+    "process/_seeds/features/_feature-template/references",
+    "process/_seeds/general-plans/reports",
+    "process/_seeds/general-plans/references"
   ]
 }