@rubytech/create-sitedesk-code 0.1.523 → 0.1.525

package/payload/platform/docs/superpowers/plans/2026-07-25-task-1976-intra-folder-hygiene.md

@@ -1,215 +0,0 @@
-# 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/<name>/` and `contacts/<name>/` only. `documents/` is allowed one document-folder deep (`documents/<doc>/file`) and is out of scope for the subfolder rule.
-- Version-group definition: `<base>.ext` and `<base>-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.** `<base>.ext` and `<base>-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/<name>/` or
-  `contacts/<name>/`; 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/<name>/`, `contacts/<name>/`), count three intra-folder drifts from disk structure alone, no graph resolution needed: (f) files in a version group, where `<base>.ext` and `<base>-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/<name>/` or `contacts/<name>/` 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 (`<base>.ext` and `<base>-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/<name>/` or `contacts/<name>/` 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.<brand>.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.