# Task 1976 Intra-folder Filing Hygiene Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Teach the `data-manager` reconcile audit to count three intra-folder drift kinds (superseded versions, format twins, stray subfolders) and state the three governing rules in `SCHEMA.md`, `data-manager.md`, and `internals.md`, so version and format sprawl becomes visible before a cleanup is asked for. **Architecture:** Detection-and-doctrine only, matching the 1930/1974 precedent. Three markdown source files gain the rules and counts; the `platform-architecture/SKILL.md` twin is regenerated from `internals.md` by the assembler, never hand-edited. No new write-time guard, no automatic deletion. **Tech Stack:** Markdown templates, Node ESM regen scripts (`docs/scripts/copy-docs.mjs`, `maxy-code/scripts/assemble-architecture-skill.mjs`), Bash test harness (`fs-schema-guard.test.sh`), drift gate (`check-architecture-skill-no-drift.mjs`). ## Global Constraints - Zero em-dashes in shipped prose (use commas, colons, or full stops). - Detection-only: the reconcile audit counts, it never removes. Removal is a stewardship dispatch under operator direction (deletion is destructive). - The three new fields are **appended** to the output contract, never substituted: `scratch-refs`, `stranded`, and `stranded-intake` all survive. - The no-subfolder rule is scoped to `projects//` and `contacts//` only. `documents/` is allowed one document-folder deep (`documents//file`) and is out of scope for the subfolder rule. - Version-group definition: `.ext` and `-vN.ext` sharing basename stem and extension are versions of one deliverable. - Format-twin definition: same basename where a delivered `.pdf` sits beside its source render `.html`/`.md`; count the source renders whose delivered twin exists. - The reconcile has no automated harness (it runs as a Sonnet agent). Verification of the counts is manual on a seeded folder; the automated gates that must stay green are `fs-schema-guard.test.sh` and `check-architecture-skill-no-drift.mjs`. --- ### Task 1: SCHEMA.md — Intra-folder hygiene section **Files:** - Modify: `platform/templates/account-schema/SCHEMA.md` (insert a new `## Intra-folder hygiene` section between `## Naming convention` and `## Tool-owned`) **Interfaces:** - Produces: the three named rules (current-version-only, one-canonical-format, no-subfolder) that Task 2 and Task 3 reference by name. - [ ] **Step 1: Insert the section** after the Naming convention section (currently ending at line 27), before `## Tool-owned`: ```markdown ## Intra-folder hygiene The operator-data buckets hold one current copy of each deliverable, in one canonical format, with no subtree. Three rules keep them that way; the standing reconcile counts any that predate them, and `data-manager` clears them on a stewardship dispatch. - **Current version only.** `.ext` and `-vN.ext` (for example `charlotte-deck.pdf` and `charlotte-deck-v2.pdf` through `charlotte-deck-v6.pdf`) are versions of one deliverable, not separate files. Keep the newest; the superseded copies are removed through `data-manager`. - **One canonical format.** A delivered `.pdf` and its source render sharing the same basename (`charlotte-deck.html` beside `charlotte-deck.pdf`, `invoice-rbt-2026-005.html` beside `invoice-rbt-2026-005.pdf`) are one deliverable in two formats. The pdf is the deliverable; the `.html` or `.md` render that produced it is not a second one and is removed through `data-manager`. - **No subfolder.** No folder nests under `projects//` or `contacts//`; files live directly inside the entity folder. This is the flat rule from the buckets above, restated as a standing invariant: the write guard blocks the depth as you create it, and the reconcile counts any subtree that predates the guard or was created off-path. ``` - [ ] **Step 2: Verify the section reads and has no em-dashes** Run: `grep -n 'Intra-folder hygiene' platform/templates/account-schema/SCHEMA.md && ! grep -n '—' platform/templates/account-schema/SCHEMA.md && echo "no em-dash"` Expected: the heading line prints, then `no em-dash`. - [ ] **Step 3: Verify the write guard is untouched (green baseline holds)** Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh 2>&1 | tail -1` Expected: `----- 22 passed, 0 failed -----` - [ ] **Step 4: Commit** ```bash git add platform/templates/account-schema/SCHEMA.md git commit -m "task: SCHEMA.md states intra-folder hygiene rules (1976)" ``` --- ### Task 2: data-manager.md — three counts, output contract, stewardship **Files:** - Modify: `platform/templates/specialists/agents/data-manager.md` (reconcile brief at line 25, output contract at line 31, "What success looks like" at line 17) **Interfaces:** - Consumes: the three rule names from Task 1. - Produces: the output-contract line `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U` that Task 3 mirrors verbatim. - [ ] **Step 1: Extend the reconcile brief** (line 25). Insert immediately before `Move nothing, dispatch nothing.`: ``` Then, per operator-data entity folder (`projects//`, `contacts//`), count three intra-folder drifts from disk structure alone, no graph resolution needed: (f) files in a version group, where `.ext` and `-vN.ext` share a basename stem and extension and all but the newest are superseded, counting every superseded copy as `versioned`; (g) format twins, a source-render file (`.html`, `.md`) whose delivered `.pdf` twin of the same basename sits in the same folder, counting each such render as `format-twins`; (h) stray subfolders nested under an entity folder, which the flat rule forbids, counting each subfolder as `stray-subdir`. ``` - [ ] **Step 2: Extend the output contract** (line 31). Change the reconcile-audit string from: ``` `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R` ``` to: ``` `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U` ``` - [ ] **Step 3: Add the stewardship bullet** to "What success looks like", immediately after the `uploads/` promotion bullet (line 17): ``` - Superseded versions and redundant format twins are removed, and a subfolder nested under `projects//` or `contacts//` is flattened or re-filed, when a stewardship brief asks for it. Each removal or move pairs with a `database-operator` reference update in the same pass, exactly as any other move: the surviving current render keeps the node reference, and a removed file's node is repointed or its reference dropped. Removal is destructive, so it happens only on an explicit stewardship dispatch, never in the read-only reconcile audit. ``` - [ ] **Step 4: Verify the contract line and no em-dashes** Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' platform/templates/specialists/agents/data-manager.md && grep -o 'scratch-refs=P stranded=Q stranded-intake=R' platform/templates/specialists/agents/data-manager.md && ! grep '—' platform/templates/specialists/agents/data-manager.md && echo "no em-dash"` Expected: `1`, then the preserved `scratch-refs=P stranded=Q stranded-intake=R` fragment, then `no em-dash`. - [ ] **Step 5: Commit** ```bash git add platform/templates/specialists/agents/data-manager.md git commit -m "task: data-manager reconcile counts versioned/format-twins/stray-subdir (1976)" ``` --- ### Task 3: internals.md — reconcile rules and contract string **Files:** - Modify: `platform/plugins/docs/references/internals.md` (the reconcile paragraph at line 411) **Interfaces:** - Consumes: the output-contract line from Task 2 (must match verbatim). - Produces: the corpus source the assembler reads to regenerate the SKILL.md twin in Task 4. - [ ] **Step 1: Insert the intra-folder description** into line 411, immediately before the final sentence `The reconcile output contract is ...`: ``` Beyond placement and intake, the same audit counts intra-folder sprawl inside each operator-data entity folder from disk structure alone: superseded version copies (`.ext` and `-vN.ext` are one deliverable, all but the newest counted `versioned`), format twins (a source `.html`/`.md` render kept beside its delivered `.pdf` of the same basename, counted `format-twins`), and subfolders nested under `projects//` or `contacts//` that the flat rule forbids (counted `stray-subdir`). These are read-only counts; removal or flattening happens only on a `data-manager` stewardship dispatch, each paired with a `database-operator` reference update. ``` - [ ] **Step 2: Update the contract string** in the same paragraph, from: ``` The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`. ``` to: ``` The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`. ``` - [ ] **Step 3: Verify the string matches Task 2 and no em-dashes in the changed region** Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' platform/plugins/docs/references/internals.md && grep -o 'counted `stray-subdir`' platform/plugins/docs/references/internals.md` Expected: `1`, then `counted `stray-subdir``. - [ ] **Step 4: Commit** ```bash git add platform/plugins/docs/references/internals.md git commit -m "task: internals.md documents intra-folder hygiene counts (1976)" ``` --- ### Task 4: Regenerate the platform-architecture SKILL.md twin and gate it **Files:** - Regenerate (do not hand-edit): `platform/plugins/admin/skills/platform-architecture/SKILL.md` **Interfaces:** - Consumes: the edited `internals.md` from Task 3 (via the docs corpus). - [ ] **Step 1: Rebuild the docs corpus** (mirrors internals.md into `docs/public/llms-full..txt`). From the repo root: Run: `cd "$(git rev-parse --show-toplevel)" && node docs/scripts/copy-docs.mjs 2>&1 | tail -2` Expected: no error. - [ ] **Step 2: Assemble both brand skills** (the maxy-code run writes SKILL.md): Run: `cd "$(git rev-parse --show-toplevel)" && node maxy-code/scripts/assemble-architecture-skill.mjs --brand maxy-code && node maxy-code/scripts/assemble-architecture-skill.mjs --brand realagent-code` Expected: `[platform-arch-assemble] op=write brand=maxy-code path=.../SKILL.md ...`. - [ ] **Step 3: Run the drift gate** Run: `cd maxy-code && node platform/scripts/check-architecture-skill-no-drift.mjs 2>&1 | tail -3` Expected: `[check-architecture-skill-no-drift] ok brand=maxy-code (...)` and `... ok brand=realagent-code (...)`. - [ ] **Step 4: Confirm the new fields reached the regenerated twin** Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' maxy-code/platform/plugins/admin/skills/platform-architecture/SKILL.md` Expected: `1` (or more). - [ ] **Step 5: Commit** ```bash git add maxy-code/platform/plugins/admin/skills/platform-architecture/SKILL.md maxy-code/docs docs/public 2>/dev/null; git add -A git commit -m "task: regenerate platform-architecture skill twin for 1976" ``` --- ## Self-Review **Spec coverage:** - SCHEMA.md three rules → Task 1. ✓ - data-manager three counts + contract + stewardship → Task 2. ✓ - internals.md rules + counts → Task 3. ✓ - SKILL.md regenerated twin → Task 4. ✓ - LANES.md Ready row + archive → Phase 6 of the sprint (not a plan task; the sprint owns archive/LANES). ✓ **Placeholder scan:** every edit shows verbatim insert text. No TBD/TODO. ✓ **Type consistency:** the output-contract string is byte-identical in Task 2, Task 3, and the Task 4 grep: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`. ✓ **Out of scope (deferred, no task needed here):** automatic deletion, a write-time guard for versions/twins, per-vertical canonical-format policy, the `uploads/` intake (1974, landed), the `/data` 524 (1975, archived), the `output/` promote-out counts (1930, landed). These are stated out-of-scope in the task brief, not dropped work.