From 137dc46172e1eb5724bacde06531651238940acb Mon Sep 17 00:00:00 2001 From: Levi Figueira Date: Tue, 11 Aug 2026 14:58:34 +0100 Subject: [PATCH] docs: shape the spec-conversion-and-guidance-sweep into eight implementation units Promotes the capture-only carrier to a structurally executable Change: full hard cut of the loaf spec/task/breakdown surface reaffirmed, a mechanical rows-to-intake migration (loaf migrate work-records) with human brief promotion at triage, guidance convergence across skills, docs, and the flipped hygiene gate, and a dogfood run that archives Loaf's own SPEC files. The brief's 0.3.0 strong-gate framing is retired to arc-of-one semantics per the revised ADR-026; execution sequences after linear-native-coordination lands. Claude-Session: https://claude.ai/code/session_014SSND9qNjHmJNhmmDrNsKD --- .../shape.md | 134 ++++++++++++++++++ .../TASK-001-rows-to-intake-migration.md | 42 ++++++ .../tasks/TASK-002-cli-surface-removal.md | 45 ++++++ .../tasks/TASK-003-state-layer-quarantine.md | 42 ++++++ ...TASK-004-init-install-hooks-convergence.md | 46 ++++++ .../tasks/TASK-005-skills-convergence.md | 44 ++++++ .../tasks/TASK-006-docs-convergence.md | 42 ++++++ .../tasks/TASK-007-hygiene-gate-flip.md | 44 ++++++ .../TASK-008-dogfood-migration-and-archive.md | 44 ++++++ 9 files changed, 483 insertions(+) create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/shape.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-001-rows-to-intake-migration.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-002-cli-surface-removal.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-003-state-layer-quarantine.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-004-init-install-hooks-convergence.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-005-skills-convergence.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-006-docs-convergence.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-007-hygiene-gate-flip.md create mode 100644 docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-008-dogfood-migration-and-archive.md diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/shape.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/shape.md new file mode 100644 index 00000000..74281d05 --- /dev/null +++ b/docs/changes/20260727-spec-conversion-and-guidance-sweep/shape.md @@ -0,0 +1,134 @@ + + +# Spec Conversion and Guidance Sweep — Retiring the Legacy Work Surface + +## Problem + +The Change model is the bounded-work contract for new work, but the legacy spec/task workflow it replaced is still fully alive, not deprecated: `loaf spec` (9 subcommands) and `loaf task` (8) plus markdown-compat machinery span roughly 3,600 lines of `internal/cli/cli.go` and 3,800 lines of `internal/state/`, all with active write paths. `loaf init` still scaffolds `.agents/specs` and `.agents/tasks` into new projects, the fenced AGENTS.md block installed into user projects still advertises `loaf task/spec/kb`, and a shipping post-tool hook still runs `loaf task refresh` to regenerate a `TASKS.md` that no longer exists anywhere. The guidance contradicts itself: the shape skill documents breakdown as "retired" while the breakdown skill ships wholesale to every target, and `cmd/loaf/content_hygiene_test.go` pins the compatibility stance as exact substrings across 12 files, making the contradiction load-bearing. + +Live work intent is trapped in the legacy stores: Loaf's own database holds 15 open specs and 17 open tasks (several naming real unresolved problems, such as TASK-406's secrets-indexed-in-FTS finding), and `.agents/specs/` holds 24 top-level SPEC files with no marker linking any of them to the Change model. There is no conversion mechanism of any kind — "deliberately converted" is aspirational prose. + +This Change is the terminal carrier of the `change-model-hard-cut` lineage promise, materialized by change-work-model TASK-004 and unpinned from `0.3.0` by the ADR-026 arc-boundary revision (2026-08-10, the first pin-late application). + +## Hypothesis + +If the public spec/task/breakdown surface is hard-removed, trapped work intent migrates mechanically into the intake queue, and every live and generated guidance surface converges on the Change-first flow, then no conversation can be routed into a retired workflow, guidance stops contradicting itself and the code, and no open work goes dark — completing the arc the lineage promised, as the sweep's own X-bump release. + +## Scope + +**In** + +- A mechanical `loaf migrate work-records` migration: open/draft specs (each carrying its open tasks) and orphan open tasks become Intents preserving full text and provenance; completed/archived rows stay quarantined; a migrate-on-open nudge gates projects holding open legacy rows. +- Removal of the `loaf spec` and `loaf task` command surfaces, the markdown-compat machinery (including the `loaf migrate markdown` spec/task importers), and their argument parsers and help surfaces. +- State-layer quarantine: legacy writers and readers removed, the migration becomes the tables' only reader; entity registry, lifecycle vocabulary, export, housekeeping, render-sweep, and the transitional-tasks digest layer converge. +- Init/install/hooks convergence: no legacy scaffolding, fenced-block text updated, the `generate-task-board` hook removed, an install-deprecation entry retires the breakdown skill on installed harnesses. +- Skills convergence: the breakdown skill deleted; every referencing skill, template, agent profile, and hook instruction rewritten; the CLI reference regenerated. +- Docs convergence: README, AGENTS.md, ARCHITECTURE, STRATEGY, VISION, PR template, knowledge files, and schema docs; dated in-place revision notes on ADR-013 and ADR-016 under the living-record convention. +- The hygiene gate flipped: `TestPlanningVocabularyConverged` pins the new stance — legacy workflow references forbidden outside historical evidence. +- Dogfood: Loaf's own migration runs, the 24 top-level SPEC files move to archive, and `loaf change verify` writes the receipt. + +**Out** (deferred, not rejected) + +- Physical deletion of the `specs`/`tasks` schemas — the zero-row cleanup remains a later Change, unlocked once no project retains rows. +- The fate of legacy-layout `change.md` folders — owned by the removal boundary named in change-work-model, not this sweep. +- `linear-native-coordination` — the predecessor this sweep now sequences behind; captured at `docs/changes/20260811-linear-native-coordination/` with the operator mandate that Linear's ontology informs the internal model. It owns ADR-011's supersession. +- A lighter-than-Change work container ("loose plans") — captured as a spark for its own future pitch; vocabulary collision with Change-internal `plan.md` noted. +- `suggestReleaseBump` realignment to arc evidence — named pending by ADR-026, not this sweep's business. +- Migrating GridSight, mvault, dots, or any other project's rows — the mechanism ships here; their runs happen when those projects next open. Triage of the migrated intake items likewise happens later, in the queue. + +**Cut** (explicitly rejected) + +- Public read-only compatibility commands — inherited stub no-go, reaffirmed at interview. +- Machine-authored briefs: the migration never writes into `docs/changes/` — SQLite is the unattended landing zone; the authored surface stays human. +- Global deletion of legacy rows while any project retains them. +- A broad skill-quality or routing audit riding along with the guidance rewrite. +- Implementing from the parked `59fbcdcf` draft without revalidation against current main. + +## Observable Workflow + +`loaf spec` and `loaf task` are unknown commands; root help, agent help, and the generated CLI reference carry no trace of them. Opening a project whose database holds open legacy rows produces a migration nudge naming `loaf migrate work-records`; running it reports each converted record, and `loaf intake list` shows the resulting Intents with their origin provenance. At triage, an item still wanted is promoted with `loaf change init --brief` — the same promotion path every capture uses. `loaf init` scaffolds no `.agents/specs` or `.agents/tasks`. After `loaf upgrade`, no harness offers a breakdown command, and the installed fenced block no longer advertises the retired surface. Historical evidence — archived SPEC files, old Changes, the changelog, journal history — still reads naturally with its legacy vocabulary intact. + +## Rabbit Holes and No-Gos + +- **The 792-line test file.** `internal/cli/cli_test.go`'s legacy coverage is remediation, not redesign — delete and replace with refusal tests; do not refactor the surviving suite's structure while in there. +- **Entity-registry ripples.** Journal entries, findings, and git history reference `SPEC-*`/`TASK-*` ids as text; those references stay as text. Only resolution machinery goes — do not chase historical mentions. +- **Guidance rewrite scope creep.** Each skill edit removes/redirects legacy references only; improving unrelated prose in the same files is the audit this Change cuts. +- **The removal boundary.** Legacy `change.md` folders surface constantly during this work (11 show `state=executing` forever in `loaf change list`); their fate is a separately named decision — resist folding it in. +- **Quarantine is not cleanup.** No schema drops, no row deletion, no `0001_initial.sql` edits beyond what the migration itself requires. + +## Decisions + +Provenance: shaping interview 2026-08-11 (four grilling rounds, recorded in this session's journal entries); inherited decisions from the `journal-reliability-foundation` terminal stub; the ADR-026 arc-boundary revision and its unpin commit (`8eac0210`). + +1. **Full hard cut, no read-only compat.** The inherited stub decision reaffirmed at interview: the public surface disappears entirely; the migration is the tables' only remaining reader. Forecloses a demoted `list/show` surface and the maintenance tail it would carry. +2. **Tables quarantine physically; the zero-row cleanup is a later Change.** Inherited: no global deletion while any project retains rows. +3. **Hybrid disposition.** The migration is mechanical and unattended — open/draft specs (with their open tasks folded in) and orphan open tasks become Intents with full text and provenance; promotion to a brief is a human act at triage via `loaf change init --brief`. The boundary is ADR-016's: SQLite is the safe unattended landing zone, `docs/changes/` is an authored surface where everything implies a human chose it. +4. **Markdown spec files are never trapped.** Projects in markdown-compat mode keep their readable `.md` files in Git; the migration reads SQLite rows only and never ingests markdown. Files, unlike rows, need no liberation mechanism. +5. **The strong gate is retired; the promise survives as arc semantics.** The brief's "target_release: 0.3.0 / stable cannot cut" framing predates the ADR-026 revision and its unpin. The sweep stays unpinned per pin-late discipline: when executed it derives as an arc of one and bumps X at its own cut (stated via explicit `--bump` until the suggestion realignment lands). Execution still ends with `loaf change verify`, so the receipt exists with nothing demanding it. +6. **Linear designs first; the sweep executes after.** Operator directive: Linear-native mode is critical and its ontology informs the internal model. `linear-native-coordination` (captured 2026-08-11) lands before this sweep executes and owns ADR-011's supersession; this restores the recorded 2026-07-17 successor order. Implement's preflight re-checks whether the landed Linear model shifts any convergence target here. +7. **No new work container.** The "loose plan" idea is a spark for a future pitch, not a disposition target — the Change already scales down to zero ceremony unpinned, and below it the journal+commit path needs no container. +8. **ADRs follow the living-record convention.** ADR-013 and ADR-016 get dated in-place revision notes where the artifact-kind lists and SPEC framing go stale; ADR-011 is not this Change's to touch (Decision 6). No new ADR: the hard cut is the execution of decisions ADR-022 and this lineage already recorded, and reversal would be a code change, not a lost rationale. +9. **The hygiene gate flips inside the sweep.** `TestPlanningVocabularyConverged` is rewritten to pin the new stance — legacy workflow references forbidden on current-guidance surfaces, required convergence sentences asserted — so the stance change is atomic and enforced from the first commit after the flip. +10. **`loaf kb` is not legacy.** The knowledge-base/glossary surface stays untouched. +11. **Historical evidence keeps its vocabulary.** Inherited: `docs/changes/`, `.agents/specs/archive/`, CHANGELOG, ADR history, and journal renders retain SPEC/TASK mentions; enforcement scopes to current-guidance surfaces only. + +## Planning Contract + +### Approach + +Removal proceeds data-path-first: the migration lands before anything that reads or writes legacy state disappears, so no window exists where rows are unreachable. CLI and state removal follow as two slices, then the install/init surface, then content and docs convergence, then the gate flip, then the dogfood run. Every content-touching commit rebuilds and commits the `dist/` + `plugins/` mirrors alongside sources per house rules, and every commit touching a hygiene-pinned file updates the pinned strings in the same commit so the suite never reds between slices. + +### Migration semantics + +`loaf migrate work-records` converts, per project: each open/draft spec row to one Intent carrying the spec body verbatim plus its open task rows as structured content; each open task without a parent spec to its own Intent; provenance fields record origin ids and timestamps. Completed and archived rows are untouched. The operation is idempotent by operation key — re-running creates nothing new (precedent: the deferred-intent capture from journal-reliability-foundation). The nudge follows the ADR-013 worktree-storage pattern but triggers only when open/draft rows exist — work that would go dark; projects holding only completed rows quarantine silently with no ceremony. Nudge wording, exempt commands, and exit code are TASK-001's to fix. + +### Sequencing + +This Change executes after `linear-native-coordination` lands (Decision 6) — implement's preflight confirms it and re-checks convergence targets against the landed Linear model. Internally: TASK-001 precedes TASK-002, which precedes TASK-003; TASK-004 follows TASK-002; TASK-005 and TASK-006 can run in parallel after TASK-004; TASK-007 requires both; TASK-008 runs last and writes the receipt. + +### Risks + +The `cli_test.go` remediation is the largest single hazard — 792 matching lines interleaved with surviving coverage; the refusal-test replacement must not silently drop unrelated assertions. Entity-registry removal ripples into `trace`, `link`, and alias machinery; the boundary is Decision text-vs-resolution (Rabbit Holes). Installed harnesses carry stale guidance until `loaf upgrade` runs; install markers and the deprecation entry make the drift visible rather than silent. The receipt-staleness warnings currently shown by `loaf change list` for older cohort members are pre-existing noise, not this Change's regression. + +## Implementation Units + +Ordered by likelihood-of-change; packets in `tasks/`. + +- **TASK-001 — Rows-to-intake migration.** `loaf migrate work-records`, the open-rows nudge, idempotency, round-trip tests. +- **TASK-002 — CLI surface removal.** `runSpec`/`runTask`, markdown-compat machinery, parsers, help surfaces, `cli_test.go` remediation, refusal tests. +- **TASK-003 — State-layer quarantine.** Legacy writers/readers, entity registry, lifecycle vocabulary, export/housekeeping/render paths, transitional-tasks digest layer, schema docs. +- **TASK-004 — Init, install, and hooks convergence.** Init scaffolding, fenced block, hook catalog, breakdown deprecation entry. +- **TASK-005 — Skills convergence.** Breakdown deleted; ~25 referencing content files rewritten; CLI reference regenerated. +- **TASK-006 — Docs convergence.** Public docs, knowledge files, schema diagrams, ADR-013/016 revision notes. +- **TASK-007 — Hygiene gate flip.** `TestPlanningVocabularyConverged` pins the new stance; straggler sweep. +- **TASK-008 — Dogfood migration and archive.** Loaf's own run, SPEC files archived, `loaf change verify` receipt. + +## Verification Contract + +- **V1.** The full suite is green. Command: `go test ./...`. Expect: exit 0. +- **V2.** The legacy surface refuses. Command: `go test ./internal/cli -run TestLegacyWorkSurfaceRemoved -v`. Expect: exit 0 and contains `TestLegacyWorkSurfaceRemoved`. +- **V3.** Guidance pins the new stance. Command: `go test ./cmd/loaf -run TestPlanningVocabularyConverged -v`. Expect: exit 0 and contains `TestPlanningVocabularyConverged`. +- **V4.** Build and artifact parity hold. Command: `npm run build`. Expect: exit 0. +- **V5.** The migration round-trips. Command: `go test ./internal/state -run TestWorkRecordsMigration -v`. Expect: exit 0 and contains `TestWorkRecordsMigration`. + +- **H1.** Migrated intake items read faithfully against their source rows — spot-checked at the first triage session that consumes them. +- **H2.** After `loaf upgrade`, no installed harness surface offers breakdown or advertises `loaf spec`/`loaf task`. + +## Definition of Done + +- All eight task packets' checkboxes flipped in their delivering commits. +- V1–V5 green through `loaf change verify` with the receipt committed. +- Loaf's own database holds zero open legacy rows; `.agents/specs/` top level holds only `archive/`. +- `dist/` and `plugins/` mirrors committed alongside every content-changing source commit. +- The X-bump cut itself is out of scope — releases decouple from merges (ADR-026); this Change is done when it is merged, verified, and receipt-carried. + +## Durable Outputs + +After execution proves what is true: the `docs/knowledge/task-system.md` record retitles/rescopes to the post-sweep work model (or folds into `work-model.md`); CHANGELOG carries the removal narrative at the arc cut; no new ADR anticipated (Decision 8) — if implementation surfaces a constraint passing the reversal test, promote it at reflect time. + +## Open Questions + +- [KU] Exact new-stance strings and forbidden-pattern scoping for the flipped hygiene gate → TASK-007. +- [KU] Which of the 24 top-level SPEC files hold unharvested content deserving an Intent beyond the mechanical migration → TASK-008 review step. +- [KU] Nudge wording, exempt-command list, and exit code for the migrate-on-open gate → TASK-001. +- [KU] Whether the landed `linear-native-coordination` model shifts any convergence target here → implement preflight, per Decision 6. diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-001-rows-to-intake-migration.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-001-rows-to-intake-migration.md new file mode 100644 index 00000000..686847fa --- /dev/null +++ b/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 diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-002-cli-surface-removal.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-002-cli-surface-removal.md new file mode 100644 index 00000000..a2deeaf6 --- /dev/null +++ b/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 diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-003-state-layer-quarantine.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-003-state-layer-quarantine.md new file mode 100644 index 00000000..71132ed4 --- /dev/null +++ b/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` diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-004-init-install-hooks-convergence.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-004-init-install-hooks-convergence.md new file mode 100644 index 00000000..07c22651 --- /dev/null +++ b/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` diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-005-skills-convergence.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-005-skills-convergence.md new file mode 100644 index 00000000..996de024 --- /dev/null +++ b/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 diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-006-docs-convergence.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-006-docs-convergence.md new file mode 100644 index 00000000..7e0cfc32 --- /dev/null +++ b/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 diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-007-hygiene-gate-flip.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-007-hygiene-gate-flip.md new file mode 100644 index 00000000..0370b10f --- /dev/null +++ b/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) diff --git a/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-008-dogfood-migration-and-archive.md b/docs/changes/20260727-spec-conversion-and-guidance-sweep/tasks/TASK-008-dogfood-migration-and-archive.md new file mode 100644 index 00000000..a19d2657 --- /dev/null +++ b/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