chore(template): reconcile fix SPEC/README scaffolds with canonical docs (#107)

## What

Reconciles the exportable `template/docs/fix/**` scaffolds with the
canonical `docs/fix/**` versions, which had drifted since the initial
commit.

**Direction decided:** `docs/fix/_TEMPLATE/SPEC.md` is canonical — it
carries the workflow machinery the skills hard-require (`## Depends on`,
`## Detected in`, `### Spec-lint`, the 8-box Phase-lint, the
`Layer:`/`Done-when:` phase scaffold, `## Testing`, `## Status`). The
template-only sections (`Impact`, `Rules that must never be violated`,
`Risks`, `Effort`) are **`plan-fix`'s own extension sections** — its
SKILL.md appends them at drafting time ("SPEC sections (extends the base
template)"), so the base scaffold must not pre-carry them.

## Changes

- `docs/fix/_TEMPLATE/SPEC.md` — issue line made forge-agnostic
("tracked issue in the project's forge … or the forge's equivalent
auto-close convention"), then copied **byte-identical** to
`template/docs/fix/_TEMPLATE/SPEC.md`.
- `docs/fix/README.md` + `template/docs/fix/README.md` — conventions
unified in generic phrasing (folder/branch format, forge-agnostic issue
wording, remove-after-merge rule, generic skills pointer). Structural
text is now identical in both (`diff` ignoring table rows is empty);
only the dogfooded table rows differ, which is the intentional delta.

## Drift audit of the remaining pairs

| Pair | Verdict |
|---|---|
| `features/_TEMPLATE/SPEC.md` | Re-synced in [PR
#106](#106) (this
branch is off `main`, so it still shows there until that merges) |
| `features/ROADMAP.md` | Status legend + Conventions byte-identical;
only real roadmap rows differ (dogfood — intentional) |
| `LOGS.md` | Header identical; only real session entries differ
(dogfood — intentional) |
| all other `template/docs/**` | No `docs/**` counterpart (template-only
stubs) — nothing to drift against |

No SKILL.md touched → no version bumps.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: gtrabanco

docs/fix/README.md

@@ -1,14 +1,14 @@
 # Active fixes
 
-Index of in-progress and pending fixes. Merged fixes are removed from
-this table — history lives in git log + closed issues.
+Index of in-progress and pending fixes. Merged fixes are removed from this
+table — history lives in git log + closed issues.
 
 ## Status legend
 
 - `pending` — SPEC drafted, branch not yet open
 - `in-progress` — branch open, work ongoing
 - `done` — built, PR open, awaiting merge (merge state lives in the forge — same
-  meaning as the roadmap's `done`); the entry is removed only **after** the PR merges
+  meaning as the roadmap's `done`); the row is removed only **after** the PR merges
 
 ## Active
 
@@ -23,9 +23,10 @@ this table — history lives in git log + closed issues.
 
 - Folder: `docs/fix/<issue-number>-<topic>/`
 - Branch: `fix/<issue-number>-<topic>`
-- Every fix has a GitHub issue; PR closes it with `Closes #<n>`.
-- Entry is removed from this table on merge — do not maintain history
-  here.
+- Every fix has a tracked issue in the project's forge; the PR closes it via
+  `Closes #<n>` (or the forge's equivalent auto-close convention).
+- The row is removed from this table only **after** the PR merges — do not
+  maintain history here.
 - See `_TEMPLATE/SPEC.md` for the spec format.
-- Workflow rules: `.claude/skills/execute-phase/SKILL.md` (`--fix`
-  mode).
+- Workflow rules: the `execute-phase` skill's `--fix` mode (wherever your
+  agent installed the skills).

docs/fix/_TEMPLATE/SPEC.md

@@ -13,8 +13,9 @@ regular feature cycle.
 
 ## Issue
 
-`#<n>` — GitHub issue. Required. The PR must close it via
-`Closes #<n>` in the body.
+`#<n>` — tracked issue in the project's forge. Required. The PR must close it
+via `Closes #<n>` in the body (or the forge's equivalent auto-close
+convention).
 
 ## Branch
 

template/docs/fix/README.md

@@ -1,23 +1,31 @@
 # Active fixes
 
-Index of in-progress and pending fixes. Merged fixes are removed from this table —
-history lives in git log + closed issues.
+Index of in-progress and pending fixes. Merged fixes are removed from this
+table — history lives in git log + closed issues.
 
 ## Status legend
 
 - `pending` — SPEC drafted, branch not yet open
 - `in-progress` — branch open, work ongoing
 - `done` — built, PR open, awaiting merge (merge state lives in the forge — same
-  meaning as the roadmap's `done`); remove the row only **after** the PR merges
+  meaning as the roadmap's `done`); the row is removed only **after** the PR merges
 
 ## Active
 
 | Folder | Topic | Status | Depends on | Issue |
-|--------|-------|--------|------------|-------|
+| ------ | ----- | ------ | ---------- | ----- |
 | | | | | |
 
+---
+
 ## Conventions
 
-- One folder per fix: `docs/fix/<issue-number>-<topic>/SPEC.md`.
-- Every fix has a tracked issue; the PR closes it.
-- Remove the row when the PR merges.
+- Folder: `docs/fix/<issue-number>-<topic>/`
+- Branch: `fix/<issue-number>-<topic>`
+- Every fix has a tracked issue in the project's forge; the PR closes it via
+  `Closes #<n>` (or the forge's equivalent auto-close convention).
+- The row is removed from this table only **after** the PR merges — do not
+  maintain history here.
+- See `_TEMPLATE/SPEC.md` for the spec format.
+- Workflow rules: the `execute-phase` skill's `--fix` mode (wherever your
+  agent installed the skills).

template/docs/fix/_TEMPLATE/SPEC.md

@@ -1,68 +1,110 @@
 # fix/<issue-number>-<topic>
 
-> Fix specification. Copy this folder to `docs/fix/<issue-number>-<topic>/`, fill
-> every section, and register the entry in `docs/fix/README.md`. Lighter than a
-> feature spec — no separate planning artifacts: the SPEC alone is the source of
-> truth, and its `## Phases` section is the execution ledger.
+> Fix specification. Copy this folder to
+> `docs/fix/<issue-number>-<topic>/`, fill every section, register the
+> entry in `docs/fix/README.md`. Lighter than a feature spec — no
+> separate planning artifacts: the SPEC alone is the source of truth,
+> and its `## Phases` section is the execution ledger.
 
 ## Goal
 
-One paragraph: what this fix repairs and why it cannot wait for a regular feature
-cycle.
+One paragraph: what this fix repairs and why it cannot wait for a
+regular feature cycle.
 
 ## Issue
 
-`#<n>` — tracked issue. Required. The PR must close it.
+`#<n>` — tracked issue in the project's forge. Required. The PR must close it
+via `Closes #<n>` in the body (or the forge's equivalent auto-close
+convention).
 
 ## Branch
 
 `fix/<issue-number>-<topic>`
 
+## Depends on
+
+Other fixes (by folder name) that must merge first. Empty if
+independent.
+
 ## Root cause
 
-What actually causes the defect, with evidence (file paths, line refs).
+What broke, where, and why. Reference the commit, feature, or
+decision where the defect was introduced if known.
+
+## Detected in
+
+When and how the defect surfaced — review finding, incident, failing
+test, customer report, etc.
 
 ## Scope
 
 ### In scope
 
-The smallest change set that closes the issue.
+The exact change set.
 
 ### Out of scope
 
-Adjacent problems found during analysis — each with a one-line pointer to where
-it should be filed instead.
-
-## Impact
-
-- Modules/files touched (paths).
-- Blast radius: what breaks if the fix is wrong.
-- Detection lead time: how fast production would surface a failure.
+Adjacent issues this fix deliberately does NOT touch. Link to their
+own fix folder or feature where each belongs.
 
-## Rules that must never be violated
+## Acceptance
 
-Project invariants the fix must preserve (from `CLAUDE.md` hard rules and the
-architecture doc).
+Objective, verifiable conditions for "done". Each criterion is a runnable
+command where possible, or labelled `read-verified` — never unlabelled prose.
 
-## Risks
+### Spec-lint (mechanical — presence checks only)
 
-Operational, security, and compliance touchpoints. State "n/a" explicitly where
-none apply — that forces a deliberate check.
+Run by `plan-fix` before committing the draft; fail-closed, no quality
+judgement. Any FAIL → fix the SPEC before the commit.
 
-## Acceptance criteria
-
-Objective checkboxes, each independently verifiable. Map each to a test layer.
+- [ ] No template placeholders left (`grep -nE '<(topic|n|task|command|expected)'`
+      over the filled sections returns nothing — the `### P1` scaffold lines
+      are replaced, not kept).
+- [ ] `### Out of scope` has ≥ 1 concrete bullet — never empty.
+- [ ] Every `## Acceptance` criterion is a runnable command OR labelled
+      `read-verified`.
+- [ ] Every phase passes the 8-box Phase-lint below (already mandatory).
 
 ## Phases
 
-Execution ledger — `execute-phase --fix` runs **one phase per invocation** and
-ticks tasks here. **Always ≥ 2 phases**: `P1..Pn` implement the fix (each task
-independently checkable, no judgement); the final phase is always
-`Hardening & PR` — keep its pre-written tasks **literally**, never paraphrase
-or merge them into an implementation phase.
+Execution ledger — `execute-phase --fix` runs **one phase per invocation**
+and ticks tasks here. **Always ≥ 2 phases**: `P1..Pn` implement the fix
+(each task independently checkable, no judgement); the final phase is
+always `Hardening & PR` — keep its pre-written tasks **literally**, never
+paraphrase or merge them into an implementation phase.
+
+### Phase-lint (authoritative copy — keep in sync with `docs/features/_TEMPLATE/SPEC.md` `### Phases`)
+
+Every implementation phase below must pass all 8 boxes before it is emitted
+(planner skills) or executed (`execute-phase` pre-flight). Fail-closed: any
+unticked box blocks emission/execution until the phase is re-cut or split.
+
+- [ ] Title names ONE deliverable — FAIL if it joins nouns with `+`, `,`,
+      `&`, `and`/`y`, or `/`.
+- [ ] One declared layer — each phase declares exactly one of the fixed enum
+      `schema/db | domain | api | ui | config/infra | docs | hardening |
+      close-out`; FAIL if any task's target file belongs to another. Tests
+      for the phase's own layer belong to the phase; a test-only phase
+      declares `hardening`.
+- [ ] ≤ 8 tasks (close-out phase: ≤ 10, only the literal close-out chain).
+- [ ] One checkbox = one deliverable — FAIL if a task contains a `→` chain
+      of implementation steps, enumerates > 3 cases/scenarios, or creates
+      > 1 file of distinct concerns.
+- [ ] Zero decision words — FAIL on `Decide`, `choose`, `OR` between
+      alternatives, `If … then <change scope>`.
+- [ ] No conditional scope mutation — a task may not move work between
+      phases at runtime.
+- [ ] No external/manual gates inside implementation phases —
+      human/out-of-repo verifications live in the hardening/close-out phase,
+      marked `manual`.
+- [ ] Machine-checkable done-when — every phase ends with one verifiable
+      invariant (a command + expected outcome).
 
 ### P1 — <implementation>
 
+Layer: `<schema/db|domain|api|ui|config/infra|docs|hardening>`. Done-when:
+`<command>` → `<expected outcome>`.
+
 - [ ] <task — independently checkable, mapped to evidence>
 
 ### P2 — Hardening & PR
@@ -77,10 +119,18 @@ or merge them into an implementation phase.
 - [ ] Update the fix-index row to `done · [#<pr>](<pr-url>)`
 - [ ] Commit `docs: link PR #<n>` and push
 
+## Testing
+
+What test confirms the fix, at what layer (unit / integration /
+architecture). Prefer integration over heavy mocking.
+
 ## Rollback
 
-How to revert safely, and any data-side cleanup needed.
+How to revert safely if the fix misbehaves in production. State the
+single command or PR-revert flow, plus any data-side cleanup.
+
+## Status
 
-## Effort
+`pending` · `in-progress` · `done` (built, PR open — merge state lives in the forge)
 
-T-shirt size (XS / S / M / L) with a one-line justification.
+(Removed from `docs/fix/README.md` only **after** the PR merges.)