docs: shape the spec-conversion-and-guidance-sweep

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-001-rows-to-intake-migration.md

@@ -0,0 +1,42 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-001
+title: Rows-to-intake migration
+blocks:
+  - TASK-002
+---
+
+# TASK-001 — Rows-to-intake migration
+
+## Objective
+
+`loaf migrate work-records` exists and is the legacy tables' sanctioned exit: open/draft specs (each carrying its open tasks) and orphan open tasks become Intents preserving full text and provenance; completed/archived rows stay untouched; a nudge gates projects holding open legacy rows until they run it.
+
+## Scope boundaries
+
+**In:** New migrate source under the existing `loaf migrate` umbrella; Intent creation with provenance (origin spec/task ids, timestamps); idempotency by operation key; the open-rows nudge (ADR-013 worktree-storage pattern — exempting `migrate`, `help`, `--version`); round-trip tests (`TestWorkRecordsMigration` in `internal/state`).
+
+**Out:** Removing any legacy command or reader (TASK-002/003). No markdown ingestion (Decision 4). No row deletion, and no mutation of source rows — idempotency lives in the operation key, never in a converted-marker column (a status field in disguise).
+
+## Context pointers
+
+- Contract: `shape.md` — Decisions 3–4, Planning Contract "Migration semantics"
+- Precedent: idempotent deferred-intent capture (journal-reliability-foundation); nudge gate in ADR-013
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-001 — rows-to-intake migration"
+```
+
+## Steps
+
+- [ ] Converter: open/draft spec → one Intent (spec body verbatim + open tasks as structured content); orphan open task → own Intent; provenance recorded
+- [ ] Idempotency: operation-keyed — re-run creates nothing new
+- [ ] Nudge: triggers only on open/draft rows; completed-only projects quarantine silently; wording, exempt commands, exit code fixed here
+- [ ] `TestWorkRecordsMigration` round-trip: source rows → Intents → content and provenance verified faithful
+
+## Verification
+
+- `go test ./internal/state -run TestWorkRecordsMigration -v` green
+- Re-run on a migrated fixture creates zero new Intents

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-002-cli-surface-removal.md

@@ -0,0 +1,45 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-002
+title: CLI surface removal
+blocked-by:
+  - TASK-001
+blocks:
+  - TASK-003
+---
+
+# TASK-002 — CLI surface removal
+
+## Objective
+
+`loaf spec` and `loaf task` are unknown commands; the markdown-compat machinery and the `loaf migrate markdown` spec/task importers are gone; refusal is tested.
+
+## Scope boundaries
+
+**In:** `runSpec`/`runTask` dispatch + implementations + help writers + arg parsers + status helpers in `internal/cli/cli.go` (~3,600 lines); markdown-compat spec/task machinery; `loaf migrate markdown` spec/task import paths; `loaf state export spec`; root-help and `agent_help.go` rows; `cli_reference.go` generator entries; `cli_test.go` remediation (replace legacy coverage with refusal tests — `TestLegacyWorkSurfaceRemoved`); `cmd/loaf/main_test.go` root-help assertion.
+
+**Out:** State-layer internals (TASK-003). Hook catalog and install surfaces (TASK-004). Generated skill content lands with TASK-005's regeneration; keep the reference-contract test green by pairing generator + generated output in this commit if required by `TestCLIReferenceSourceMatchesGeneratedContract`. Watch: this task is heavyweight — split if writing the packet's first slice reveals more than one coherent commit (sanctioned).
+
+## Context pointers
+
+- Contract: `shape.md` — Decision 1, Rabbit Holes ("The 792-line test file")
+- Inventory anchors: `cli.go:4369-6330`, `cli.go:7765-8960`, `cli.go:11798-13040`, `cli_reference.go:405-479`
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-002 — CLI surface removal"
+```
+
+## Steps
+
+- [ ] Remove dispatch, implementations, parsers, helpers, and help surfaces for `spec` and `task`
+- [ ] Remove markdown-compat machinery and `migrate markdown` spec/task importers; `state export spec` gone
+- [ ] Regenerate the CLI reference; pair generator + output so the contract test stays green
+- [ ] `TestLegacyWorkSurfaceRemoved`: both commands refuse with unknown-command errors
+- [ ] Remediate `cli_test.go`: legacy coverage deleted, surviving suite untouched structurally
+
+## Verification
+
+- `go test ./internal/cli -run TestLegacyWorkSurfaceRemoved -v` green
+- `go test ./...` green; `grep -r "runSpec\|runTask" internal/cli` returns nothing

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-003-state-layer-quarantine.md

@@ -0,0 +1,42 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-003
+title: State-layer quarantine
+blocked-by:
+  - TASK-002
+---
+
+# TASK-003 — State-layer quarantine
+
+## Objective
+
+The migration is the legacy tables' only reader: spec/task writers and readers are removed from `internal/state/`, the entity registry and lifecycle vocabulary no longer name them, and derived surfaces (export, housekeeping, render sweep, journal-context digest) stop projecting them.
+
+## Scope boundaries
+
+**In:** The 11 dedicated `spec_*.go`/`task_*.go` files; `entity_registry.go` and `lifecycle_status.go` entries; `export.go`, `housekeeping.go`, `status.go`, `trace.go`, `link.go`, alias machinery legacy paths; `durable_render*` spec paths; the `transitional_tasks` journal-context layer and its cursor; `docs/schema/` README + DBML/MMD diagrams annotated as quarantined; associated state tests.
+
+**Out:** Schema drops or `0001_initial.sql` edits beyond what TASK-001's migration required (Rabbit Holes: quarantine is not cleanup). Historical `SPEC-*`/`TASK-*` text in journal entries stays as text.
+
+## Context pointers
+
+- Contract: `shape.md` — Decisions 2 and 11, Rabbit Holes ("Entity-registry ripples")
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-003 — state-layer quarantine"
+```
+
+## Steps
+
+- [ ] Remove legacy writers/readers; migration reader survives as the sole access path
+- [ ] Deregister `spec`/`task` from entity registry and lifecycle vocabulary; text mentions in history unaffected
+- [ ] Converge export, housekeeping, render sweep, trace/link/alias paths
+- [ ] Remove the `transitional_tasks` digest layer and cursor
+- [ ] Annotate schema docs: tables quarantined, zero-row cleanup later
+
+## Verification
+
+- `go test ./internal/state ./internal/cli` green
+- No non-migration code path issues `INSERT/UPDATE/DELETE` against `specs`/`tasks`

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-004-init-install-hooks-convergence.md

@@ -0,0 +1,46 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-004
+title: Init, install, and hooks convergence
+blocked-by:
+  - TASK-002
+blocks:
+  - TASK-005
+  - TASK-006
+---
+
+# TASK-004 — Init, install, and hooks convergence
+
+## Objective
+
+Nothing Loaf writes into a project or harness advertises the retired surface: init scaffolds no legacy directories, the fenced block and hook catalog are converged, and the breakdown skill is retired on installed harnesses through the deprecation machinery.
+
+## Scope boundaries
+
+**In:** `init.go` scaffolding (`.agents/specs`, `.agents/tasks`); `install_fenced.go` block text; `install_target.go` recognized-hook allowlist (`loaf task refresh`); `config/hooks.yaml` — `generate-task-board` removed, `ephemeral-provenance` description converged; `content/hooks/instructions/post-merge.md` checklist; `install_deprecations.go` entry quarantining the breakdown skill on upgrade; associated tests (`install_target_test.go`, `hook_catalog_test.go`, `install_deprecations_report_test.go`).
+
+**Out:** Skill body rewrites (TASK-005); public docs (TASK-006).
+
+## Context pointers
+
+- Contract: `shape.md` — Observable Workflow, Planning Contract "Risks" (installed-harness staleness)
+- Inventory anchors: `init.go:45-46`, `install_fenced.go:306-311`, `install_target.go:33`, `config/hooks.yaml:147-153`
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-004 — init/install/hooks convergence"
+```
+
+## Steps
+
+- [ ] Init scaffolds no legacy directories
+- [ ] Fenced block drops `loaf task/spec` (kb stays); existing installs converge on next upgrade
+- [ ] `generate-task-board` hook removed from hooks.yaml, catalogs, and built hook manifests
+- [ ] Breakdown deprecation entry: upgrade quarantines the installed skill
+- [ ] `post-merge.md` instruction rewritten for the Change flow
+
+## Verification
+
+- `go test ./internal/cli -run 'TestInstall|TestHook' -v` green
+- A fresh `loaf init` in a fixture creates no `.agents/specs` or `.agents/tasks`

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-005-skills-convergence.md

@@ -0,0 +1,44 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-005
+title: Skills convergence
+blocked-by:
+  - TASK-004
+blocks:
+  - TASK-007
+---
+
+# TASK-005 — Skills convergence
+
+## Objective
+
+The breakdown skill is deleted and no shipped skill, template, agent profile, or reference routes anyone toward the retired surface; the regenerated CLI reference and rebuilt target mirrors carry the converged content.
+
+## Scope boundaries
+
+**In:** Delete `content/skills/breakdown/` (4 files). Rewrite legacy references in: implement (SKILL.md, sidecar argument-hint, batch-orchestration, branch-and-completion), housekeeping (SKILL.md, report template), orchestration (SKILL.md breakdown link + local-tasks, linear touchpoints that are spec/task-bound, background-agents, journal, script-surface, parallel-agents, subagent-development, context-management), foundations (SKILL.md exemplar, code-review/tdd/verification rows), git-workflow commits reference, council frontmatter example, reflect (SKILL.md, sidecar), research (SKILL.md, templates), refactor-deepen (SKILL.md, plan template `spec:` field), wrap, documentation-standards, shape templates (pr.md legacy line, task.md slug rule stays), pitch interview-guide, librarian agent profile. Regenerate loaf-reference from the TASK-002 generator state. Rebuild and commit `dist/` + `plugins/` mirrors.
+
+**Out:** Prose improvements beyond reference removal/redirection (Cut: no skill audit). Public docs (TASK-006). Linear guidance that the landed `linear-native-coordination` model owns — converge only what is spec/task-bound, per implement-preflight's re-check (Decision 6). Watch: wide but mechanical — split by skill cluster if one rebuild-and-commit cycle proves too large (sanctioned).
+
+## Context pointers
+
+- Contract: `shape.md` — Decision 6 and 11, Rabbit Holes ("Guidance rewrite scope creep")
+- Inventory: the content-surface table in this shaping session's inventory (40 files)
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-005 — skills convergence"
+```
+
+## Steps
+
+- [ ] Delete breakdown; orchestration's required link updated with the hygiene pin in the same commit
+- [ ] Rewrite each referencing skill/template/agent file: remove or redirect to the Change flow
+- [ ] Regenerate loaf-reference; contract test green
+- [ ] `loaf build`; commit mirrors with sources
+
+## Verification
+
+- `npm run build` green; `git grep -l "loaf spec\|loaf task\|breakdown" content/ | grep -v infracost` returns nothing unexpected
+- Routing sanity: shape/implement/housekeeping descriptions carry no dangling "use breakdown" pointers

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-006-docs-convergence.md

@@ -0,0 +1,42 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-006
+title: Docs convergence
+blocked-by:
+  - TASK-004
+blocks:
+  - TASK-007
+---
+
+# TASK-006 — Docs convergence
+
+## Objective
+
+Every public and strategic doc describes only the Change-first flow: the compatibility-stance sentences are gone, the knowledge record reflects the post-sweep model, and ADR-013/016 carry dated revision notes.
+
+## Scope boundaries
+
+**In:** `README.md` (command + skill tables), root `AGENTS.md` (compat sentences, breakdown exemplar, command index), `docs/ARCHITECTURE.md` (work-records section, layout tree, Linear-native paragraph as spec/task-bound), `docs/STRATEGY.md` + `docs/VISION.md` stance sentences, `.github/PULL_REQUEST_TEMPLATE.md` legacy line, `docs/knowledge/task-system.md` (retitle/rescope or fold into `work-model.md`), `docs/knowledge/README.md` index, incidental mentions in `work-model.md`/`loaf-flow.md`/`glossary.md`/`hook-system.md`, `docs/schema/README.md` + diagrams (quarantine annotation with TASK-003), ADR-013 and ADR-016 dated in-place revision notes.
+
+**Out:** ADR-011 (owned by `linear-native-coordination`, Decision 6). CHANGELOG (written at the arc cut). Historical evidence — old Changes, archived specs, ADR bodies' original citations (Decision 11, ADR-026 citation rule).
+
+## Context pointers
+
+- Contract: `shape.md` — Decisions 8 and 11, Durable Outputs
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-006 — docs convergence"
+```
+
+## Steps
+
+- [ ] README/AGENTS.md/ARCHITECTURE/STRATEGY/VISION/PR template converged; hygiene pins updated in the same commits
+- [ ] Knowledge record rescoped to the post-sweep model; `covers:` globs updated
+- [ ] ADR-013 and ADR-016 revision notes: dated, in place, under the living-record convention
+
+## Verification
+
+- `go test ./cmd/loaf` green at each commit
+- `git grep -n "remain supported compatibility" README.md AGENTS.md docs/` returns nothing

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-007-hygiene-gate-flip.md

@@ -0,0 +1,44 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-007
+title: Hygiene gate flip
+blocked-by:
+  - TASK-005
+  - TASK-006
+blocks:
+  - TASK-008
+---
+
+# TASK-007 — Hygiene gate flip
+
+## Objective
+
+`TestPlanningVocabularyConverged` pins the new stance: legacy workflow references are forbidden on current-guidance surfaces, the converged sentences are required, and any straggler the new pins catch is swept in the same slice.
+
+## Scope boundaries
+
+**In:** Rewrite `cmd/loaf/content_hygiene_test.go` — drop the compatibility-stance requirements (including the requirement that orchestration link breakdown and the prohibition on naming this Change), add forbidden patterns (`loaf spec`, `loaf task`, breakdown-as-workflow) scoped to current-guidance surfaces, add required convergence sentences. Fix any straggler files the new pins surface. Exact strings and scoping are this task's deliverable (fog entry resolved here).
+
+**Out:** Historical-evidence surfaces stay exempt (Decision 11): `docs/changes/`, `.agents/specs/archive/`, `CHANGELOG.md`, ADR bodies, journal renders.
+
+## Context pointers
+
+- Contract: `shape.md` — Decision 9, Open Questions
+- Current pins: `cmd/loaf/content_hygiene_test.go:160-360`
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-007 — hygiene gate flip"
+```
+
+## Steps
+
+- [ ] Compatibility pins removed; forbidden-pattern + required-sentence sets written with explicit surface scoping
+- [ ] Straggler sweep: every hit from the new pins fixed or explicitly exempted as historical evidence
+- [ ] Exemption list documented in the test itself
+
+## Verification
+
+- `go test ./cmd/loaf -run TestPlanningVocabularyConverged -v` green
+- Intentionally reintroducing `loaf task` into README fails the test (falsification check, then revert)

docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-008-dogfood-migration-and-archive.md

@@ -0,0 +1,44 @@
+---
+change: spec-conversion-and-guidance-sweep
+id: TASK-008
+title: Dogfood migration and archive
+blocked-by:
+  - TASK-007
+relates-to:
+  - TASK-001
+---
+
+# TASK-008 — Dogfood migration and archive
+
+## Objective
+
+Loaf's own database holds zero open legacy rows, the 24 top-level SPEC files sit in `archive/` as historical evidence, and the Change carries a committed `loaf change verify` receipt.
+
+## Scope boundaries
+
+**In:** Run `loaf migrate work-records` against Loaf's production database (the dogfood); review the migration output — any SPEC file holding unharvested content beyond what the mechanical migration captured gets a note on its Intent (fog entry resolved here); move the 24 top-level `.agents/specs/*.md` into `archive/` with frontmatter statuses normalized; run `loaf change verify` and commit the receipt.
+
+**Out:** Triaging the migrated Intents — that happens later in the queue with everything else (Scope Out). Editing archived spec bodies (Decision 11). Other projects' migrations.
+
+## Context pointers
+
+- Contract: `shape.md` — Definition of Done, Open Questions
+- Live-row inventory as of shaping: 15 open specs, 17 open tasks (`loaf spec list` / `loaf task list`, 2026-08-11)
+
+## Acquisition
+
+```bash
+loaf journal log "skill(implement): TASK-008 — dogfood migration and archive"
+```
+
+## Steps
+
+- [ ] Migration run on Loaf's database; converted-record report captured in the journal
+- [ ] Harvest review: Intents annotated where the mechanical capture missed context worth keeping
+- [ ] SPEC files archived, statuses normalized; `.agents/specs/` top level holds only `archive/`
+- [ ] `loaf change verify` green; receipt committed
+
+## Verification
+
+- `loaf intake list` shows the migrated Intents with provenance
+- `loaf change check docs/changes/20260727-spec-conversion-and-guidance-sweep` clean; receipt present and fresh