groundwork-method 0.0.1 → 0.11.0

package/src/hidden-skills/groundwork-update/briefs/reconcile-worker.md

@@ -0,0 +1,196 @@
+---
+name: reconcile-worker
+description: >
+  Advances one update unit — a single upgrade-brief item or one Family Index family — to
+  the current GroundWork canonical, in an isolated subagent context, and returns a small
+  structured report. Dispatched by the groundwork-update driver
+  (groundwork-update/instructions.md) once per unit; the driver supplies the unit capsule,
+  the worker reads the canonical and the project's instances, produces the proposed change,
+  and only the report flows back — the transform reasoning stays in the worker's context.
+---
+
+# Reconcile Worker
+
+## How This Brief Is Invoked
+
+This brief runs in an **isolated subagent context** — never in the groundwork-update
+driver's main conversation. The driver dispatches one worker per unit, hands it a tight
+capsule, and receives back only a short structured report. The canonical reads, the
+instance reads, the merge or relocation reasoning — all of it stays in the worker's context
+and dies with it when the worker returns.
+
+This isolation is the point. Running the whole catch-up inline piles every family's
+transform reasoning — the canonical templates, the project's instances, the diff judgement —
+into one window; the driver's context grows until it can no longer reason well about the
+update as a whole. Farming each unit to a disposable worker keeps the driver thin enough to
+hold the brief, the Family Index, the pacing, the review gate, and the commits — the work
+only it can do.
+
+### Invocation environments
+
+| Environment | How the driver dispatches the worker |
+|---|---|
+| Claude Code | Via the `Task` tool with a general-purpose subagent. The prompt loads this file and supplies the capsule below. |
+| Other environments | Any mechanism that runs this brief in an isolated context with file-read, file-write, and shell tools, and returns the final text. |
+
+The contract is environment-agnostic — the capsule and the returned report are the same
+regardless of how the isolated execution is realised.
+
+### Model
+
+The worker may run on a cheaper tier than the driver. Its correctness is not taken on
+trust: the driver gates every mutated canonical doc through an independent review
+(Protocol 9) before it commits the unit. The worker's job is to advance honestly and report
+honestly, not to be the final judge of its own work.
+
+---
+
+## Inputs — the unit capsule
+
+The driver passes one unit and the small set of pointers that let the worker advance it
+without re-deriving the whole framework:
+
+- `unit_kind` — one of:
+  - `brief-item:tier2-merge`, `brief-item:tier1-custom`, `brief-item:regenerate` — a single
+    item from `.groundwork/cache/upgrade-brief.json`, passed verbatim (its `path`,
+    `incoming`, `base_hash`, `options`, `artifact`, … fields).
+  - `family:<name>` — one row of the driver's Family Index (e.g. `family:architecture-docs`,
+    `family:doc-contracts`, `family:bets`, `family:naming`, `family:surfaces-registry`,
+    `family:docs-site`, `family:nextjs-tokens`).
+- **Canonical owner path(s)** — the live current shape to read in full and treat as the
+  worked example: the brief item's staged `incoming` payload, or the family's Owner column
+  (a skill/template/generator under `.groundwork/skills/` or `.groundwork/config/`). The
+  canonical is the source of truth for the target shape; it is never restated in the capsule.
+- **Project instance path(s)** — the exact files/dirs this unit transforms, to read in full
+  before changing anything.
+- **Advance approach** — the one-line recipe from the Family Index row (or the item type's
+  recipe below): what the legacy signal is and what advancing it means.
+- **Scope boundary** — touch only this unit's files. Do not advance another family, refactor
+  unrelated docs, or reach outside the named instances.
+
+---
+
+## The work
+
+### 1. Read before you change
+
+Most reconciliation failures are context failures — the agent relocates a doc and breaks
+the cross-references it never read. Before editing anything:
+
+- **Read the canonical owner in full.** It is the target shape. For a generator-owned family,
+  read the generator's output contract; for a prose family, read the skill/template that
+  defines the current layout.
+- **Read every project instance this unit touches, in full** — and, for a relocation or
+  rename, grep the project for live cross-references to the paths you will move.
+- **Detect-first.** Confirm the legacy signal actually holds. If the instances already match
+  canonical, make no change and return an `already-current` report — the driver checks the
+  unit off untouched.
+
+### 2. Advance to canonical — by unit kind
+
+Apply the `groundwork-writer` skill whenever you edit a `docs/` document.
+
+**`brief-item:tier2-merge`** — a framework-seeded doc the user edited, where the framework
+improved its copy. Reason over both: what did the user change, what did the framework
+improve? Produce a merge that **preserves the user's intent and adopts the framework's
+improvements** — never a mechanical overwrite either way, never conflict markers. Where a
+user edit and a framework improvement **collide on the same passage**, do not pick for the
+user — leave the user's text in place and record the collision under `COLLISIONS/AMBIGUITY`
+for the driver to resolve. `AGENTS.md` deserves extra care: it routes every agent session.
+
+**`brief-item:tier1-custom`** — a framework-owned file (typically the `dev` launcher) the
+user customized. Port the customization onto the `incoming` framework version. If the
+customization looks obsolete, do not decide it — apply the framework version and record the
+customization under `COLLISIONS/AMBIGUITY` so the driver confirms with the user.
+
+**`brief-item:regenerate`** — generator output whose generator moved. Regenerate and
+reconcile:
+1. Create `.groundwork/cache/upgrade/regen/<artifact>/` with minimal Nx markers
+   (`package.json` `{"name":"regen"}`, empty `nx.json`) and copy
+   `.groundwork/config/brand-tokens.json` in if the generator themes from it.
+2. Run the generator there with the item's recorded `options`, via
+   `.groundwork/config/generators.json` (`npx nx g <generators.json-path>:<generator> …`).
+   If `options` is null, reconstruct them from the artifact (e.g. `.dev/dev.config.json`
+   carries app name and colours) and record the reconstruction under `COLLISIONS/AMBIGUITY`
+   for the driver to confirm.
+3. Diff the regenerated files against the project. Apply framework-section changes; leave
+   user-section changes alone (a docker-compose service the user added is theirs; the
+   generator's infra block is the framework's). An empty diff is a clean `already-current`.
+
+   This is also how the **generator-owned families** (`family:docs-site`,
+   `family:nextjs-tokens`) advance — regenerate from the recorded generator and reconcile.
+
+**`family:<name>`** — advance the project's instances to the canonical the Owner defines,
+following the row's advance approach. The common shapes:
+- **Relocate** (e.g. flat `docs/architecture.md` → nested `docs/architecture/index.md`):
+  move the files into the canonical layout, rewrite the affected `meta.json`(s), and carry
+  every live cross-reference forward. Leave historical records alone.
+- **Rename + carry refs** (e.g. `docs/ux-design.md` → `docs/design-system.md`): rename, carry
+  every live cross-reference forward, remove the orphaned old file.
+- **Reference rewrite** (no file moves — only dangling references): rewrite a stale token in
+  place across project-owned docs, scripts, and CI — `npx groundwork ` → `npx groundwork-method `,
+  or the relocated hidden-skills prefix `.agents/groundwork/skills/` → `.groundwork/skills/`.
+  Touch only the changed token; leave the rest of each line intact. Stay off the user-owned
+  `config.toml`, lockfiles, archived/historical records, and any unrelated string that merely
+  contains the word. If a reference is genuinely ambiguous (it could name an unrelated thing),
+  record it under `COLLISIONS/AMBIGUITY` rather than rewriting blindly.
+- **Graduate + stamp** (doc-contracts): graduate each still-binding Key Decision / Binding
+  Constraint out of a `## Summary for Downstream` section into a `docs/architecture/
+  decisions/` ADR (or confirm it already lives in the body), strip the section, and stamp
+  the drift-tracking frontmatter. Never delete a binding decision without first landing it
+  in an ADR or the body — if a decision's disposition is genuinely unclear, record it under
+  `COLLISIONS/AMBIGUITY` rather than dropping it.
+- **Restructure** (bets): restructure an in-flight bet to the current prose shape, infer and
+  stamp `status`, drop the dead machine-readable artifacts. Leave shipped/archived bets as
+  historical record, removing only stray obsolete files.
+- **Bootstrap / register** (surfaces): bootstrap the registry twins or register runners per
+  the Owner skill, without touching db/jaeger compose.
+
+**Scope discipline.** Make only the changes this unit's advance requires. Compare against the
+live canonical directly; reach for the framework's own git history only to disambiguate a
+genuinely ambiguous transform. Do not advance other families or refactor unrelated subsystems.
+
+### 3. Do not commit
+
+The worker advances the unit and stops. It does **not** commit, gate its own review, or
+do the driver's bookkeeping — those are the driver's, after its independent review and the
+user pacing only it holds. Leave the working tree with this unit's changes unstaged; return
+the report.
+
+---
+
+## The report
+
+Return a short structured report and nothing else — no narration of the transform, no
+replay of files read. Keep it to what the driver needs to review, gate, and commit:
+
+```
+UNIT: <unit_kind> — <one-line what this unit is>
+RESULT: advanced | already-current | blocked
+
+FILES:
+- added: <path>, ...
+- modified: <path>, ...
+- deleted: <path>, ...
+- moved: <from> -> <to>, ...
+
+REVIEW-NEEDED:
+- <canonical doc path>  document_type: <product-brief|design-system|architecture|infrastructure|domain-entity|maturity|...>
+- ...   (the canonical docs this unit mutated; none for a non-canonical change)
+
+COLLISIONS/AMBIGUITY: none | <each decision the driver must take with the user — a tier2
+  passage where a user edit and a framework improvement collide, a customization that may be
+  obsolete, reconstructed generator options to confirm, an advance that implies a product
+  decision the code does not prove>
+
+BLOCKING CONCERN: none | <why this unit cannot be honestly advanced as scoped>
+```
+
+Set **BLOCKING CONCERN** when the unit cannot be honestly advanced:
+- The canonical and the instance disagree in a way the advance approach does not cover.
+- Advancing would require a decision the code does not prove (a removal that might be
+  temporary, a capability that might be an experiment) — surface it; do not assume it.
+- A generator or dependency the advance needs cannot be run or reached in this environment.
+
+The report is the worker's entire output. Keep it tight: if it runs long, it is explaining
+instead of reporting — cut the explanation.

package/src/hidden-skills/groundwork-update/instructions.md

@@ -0,0 +1,200 @@
+---
+name: groundwork-update
+description: >
+  The single call to bring a project up to the current GroundWork framework — files,
+  structure, and docs site. Works the residual upgrade-brief items `npx groundwork-method
+  update` compiles (merging framework improvements into edited docs, reconciling
+  regenerated scaffold output), then reconciles every artifact family against the live
+  current canonical shape, advancing legacy structure forward. One unit, one explained
+  proposal, one commit. Route here for "upgrade groundwork", "bring this project up to
+  date", or whenever `.groundwork/cache/upgrade-brief.json` exists. Distinct from
+  groundwork-doc-sync, which syncs project docs to the project's own code.
+---
+
+# groundwork-update
+
+You bring a project to the current framework's canonical shape. The CLI has already done
+everything mechanical — refreshed the skills under `.groundwork/skills/`, replaced the
+framework-owned `./dev` bundle, copied pristine seeded docs, run the scripted CLI
+migrations. Two kinds of work remain, and both need eyes:
+
+- **Residual brief items** — the user edited a doc the framework also improved, customized
+  the launcher, or runs a generator whose output drifted from its template. The CLI
+  compiled these into the **upgrade brief**.
+- **Structural drift** — the project's bets, architecture docs, or contracts were authored
+  against an older *shape* of the framework. Nothing tracked that, and nothing needs to:
+  you detect it by comparing the project's own artifacts against the framework's current
+  canonical — already sitting in `.groundwork/skills/` after the CLI refresh — and advance
+  the divergent ones forward.
+
+## You are the driver
+
+You hold the **thin spine** — the brief, the Family Index, the detection, the user pacing,
+the review gate, and the commits — and you keep that context small so you can reason about
+the update as a whole. You **do not** read canonical templates and rewrite project files in
+your own context. Each unit of work — one brief item, or one family — is advanced by a fresh
+**`reconcile-worker` subagent** (`.groundwork/skills/groundwork-update/briefs/reconcile-worker.md`)
+you dispatch with a tight capsule; it reads the canonical and the project's instances, makes
+the change, and returns a short report, and its transform reasoning dies with its context.
+
+Running the whole catch-up inline piles every family's transform — the canonical, the
+instances, the diff judgement — into one window until you can no longer pace, gate, and
+commit well. Farming each unit to a disposable worker is what keeps you thin enough to do
+the work only the driver can do.
+
+You leave the project as if it had been set up at the current version all along.
+
+---
+
+## Operating Contract
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1)
+governs this skill in **Maintenance** mode: Protocols 1 (Discovery Notes), 2 (Living
+Documents), and 4 (Pacing) apply, and Protocols 8 and 9 (Review Gate, Review Invocation)
+apply whenever a brief item or a reconcile advance mutates a canonical doc — the driver runs
+that gate, never the worker that authored the change. There is no phase cache beyond the
+brief itself.
+
+Run **Phase A first** — it clears the brief the CLI staged — then **Phase B**, which
+reconciles what no brief can see. A run that finds no brief skips straight to Phase B.
+
+### The `fan_out` hint
+
+The orchestrator passes a `fan_out` hint when it invokes this skill: `parallel` when a
+sub-agent dispatch tool is available in this environment, `sequential` otherwise. Honour it
+rather than probing your own tool set — a runtime that misjudges its capabilities and calls
+a dispatch tool that does not exist breaks the run. If no hint reached you, default to
+`sequential`.
+
+- `parallel` — **dispatch** each unit to a `reconcile-worker` subagent, as above. This is
+  the context-lean path the driver is built for.
+- `sequential` — no dispatch tool exists, so advance each unit **inline, one at a time**:
+  do the worker's read-and-transform yourself for a single unit, gate and commit it, then
+  **purge that unit's detail from context** before the next. Slower and heavier, but still
+  bounded — never load the whole catch-up into one window at once.
+
+Either way the units run **serially, in the order below** — families overlap on files and
+carry ordering dependencies (graduate ADRs before nesting the architecture docs), so they
+are advanced one at a time, not concurrently.
+
+---
+
+## Phase A — Work the brief (framework files)
+
+Read `.groundwork/cache/upgrade-brief.json`. If it does not exist, there is no brief-lane
+work; go to Phase B.
+
+The brief carries `from` (the version this install was stamped at), `to` (the version it is
+being raised to), and `items[]`, each with a stable `id`, a `type` (`tier2-merge`,
+`tier1-custom`, or `regenerate`), a `status`, and pointers to payloads the CLI staged under
+`.groundwork/cache/upgrade/` — the worker never needs the npm package itself.
+
+Open the session with the shape of the work: the version jump and a one-line list of pending
+items. Then walk the items **top to bottom** — the CLI ordered them. For each, run the
+driver loop:
+
+1. **Propose.** Explain what this item will change and why in two or three sentences. Never
+   batch approvals across items.
+2. **Dispatch the worker.** Hand a `reconcile-worker` the item verbatim as the capsule —
+   `unit_kind: brief-item:<type>`, the staged `incoming`/`options`/`base_hash` pointers, and
+   the project path it touches. The worker produces the merged / ported / regenerated change
+   and returns its report. (Under `sequential`, do the worker's recipe inline — the item-type
+   recipes live in the worker brief's "the work" section; do not duplicate them here.)
+3. **Resolve what the worker flagged.** Any `COLLISIONS/AMBIGUITY` the report raises — a
+   passage where a user edit and a framework improvement collide, a customization that may be
+   obsolete, reconstructed generator options — is a **user** decision: surface it and let the
+   user pick before committing. A `BLOCKING CONCERN` stops the item; route it as the report
+   describes.
+4. **Gate.** For every doc named under `REVIEW-NEEDED`, run the review subagent (Protocol 9)
+   with the matching `document_type`. Proceed only on a parseable `VERDICT: PRESENT`; the gate
+   is fail-closed. On `REVISE`, apply the 🔴 findings and re-invoke, to the 3-revise cap.
+5. **Commit.** One item, one commit, referencing the item id —
+   `chore(groundwork): <what changed> (<id>)`. The worker left its changes unstaged; the
+   driver stages and commits them. Nothing outside the item's scope goes into its commit.
+6. **Record completion** (bookkeeping contract below) before moving on.
+
+Stop at any point the user asks; the brief survives across sessions and `update` re-runs
+merge into it without duplicating items.
+
+---
+
+## Phase B — Reconcile to the current canonical (structure)
+
+The brief only knows about files the framework seeds or generates. It cannot see that a
+project's *structures* — how its bets are laid out, where its architecture docs live, what
+its published docs may contain — were authored against an older shape. There is no change
+log to replay and none is needed: the framework now sitting in `.groundwork/skills/` **is**
+the definition of the current shape, and it cannot drift, because it is the source. So you
+reconcile the project to it.
+
+**Detect in the driver; advance in a worker.** For each family in the **Family Index** below:
+
+1. **Detect cheaply, yourself.** The legacy signal is a structural check — `ls`/`grep`-level
+   (is there a flat `docs/architecture.md`? a `## Summary for Downstream` section? a
+   `pitch.md` without `status`? no `app/brand.css`?). This is cheap; keep it in the driver so
+   you only spin a worker for a family that has actually drifted. A family already matching
+   canonical is checked off untouched — and leaves no ledger entry, because the next run
+   re-derives the same answer from the artifacts. Detect-first *is* the bookkeeping.
+2. **Propose.** One family, one explained proposal. Pause where an advance would imply a
+   product decision the code does not prove — a removal that might be temporary, a capability
+   that might be an experiment — and surface it rather than assume it.
+3. **Dispatch the worker.** Hand a `reconcile-worker` the capsule: `unit_kind: family:<name>`,
+   the **Owner** column path(s) as the canonical to read, the project instance paths it found,
+   and the row's advance approach. The worker reads canonical + instances *in its own
+   context*, advances them, and returns its report. (Under `sequential`, do the advance inline
+   for this one family, then purge the detail.)
+4. **Resolve, gate, commit.** Resolve any `COLLISIONS/AMBIGUITY` with the user. Run the review
+   subagent (Protocol 9) on every `REVIEW-NEEDED` canonical doc with its `document_type`,
+   fail-closed, to the 3-revise cap. Then commit — one family, one commit
+   (`chore(groundwork): advance <family> to current shape`); the worker left its changes
+   unstaged.
+
+### Family Index
+
+The artifact families that drift as the framework evolves. Each row is a *pointer to the
+owner* (the canonical shape — the worker reads it there, it is never duplicated here), the
+*legacy signal* that flags an old instance, and the *advance* that carries it forward. This
+index is ownership, not change history: it grows only when a genuinely new family appears,
+not on every change. When a structure changes again, its owning skill changes (as it must)
+and this pass picks the drift up for free.
+
+| Family | Owner — current canonical | Legacy signal → advance |
+|---|---|---|
+| **Bets** | `.groundwork/skills/groundwork-bet/` workflows `03-decomposition.md` + `04-delivery.md` and its templates | A bet under `docs/bets/<slug>/` carrying `decomposition.json`, `decomposition.md`, a `contracts/` dir, or a `test-manifest.json`; or a `pitch.md` missing `status` frontmatter → restructure to the prose `decomposition/` tree, infer and stamp `status`, drop the dead machine-readable artifacts (the suite + git are the record), take the approval baseline from the git tag `bet/<slug>/approved`. Restructure in-flight bets; leave shipped/archived ones as historical record, removing only stray obsolete files. |
+| **Architecture docs** | The nested `docs/architecture/` layout the `groundwork-architecture` skill builds + its `meta.json` ordering | Flat architecture docs at the `docs/` root (`docs/architecture.md`, `docs/infrastructure.md`, `docs/domain/`, `docs/services/`, `docs/api/`, `docs/decisions/`) → relocate under `docs/architecture/` (`architecture.md` → `index.md`), rewrite `docs/meta.json` and seed `docs/architecture/meta.json`, carry every live cross-reference forward. Leave historical records alone. |
+| **Doc contracts** | `.groundwork/skills/operating-contract.md` + the `groundwork-writer` skill | A published `docs/*.md` (outside `docs/bets/`) carrying a `## Summary for Downstream` section, or a code-coupled doc missing `last_reviewed` / `source_of_truth` frontmatter → graduate each still-binding Key Decision / Binding Constraint into a `docs/architecture/decisions/` ADR (or confirm it already lives in the body), strip the section, and stamp the drift-tracking frontmatter so `groundwork-check` can see the doc. |
+| **Naming** | The `groundwork-design-system` skill; the structural-design principle (`code-structure`); the published package name `groundwork-method`; the current install layout (hidden methodology skills live at `.groundwork/skills/`) | `docs/ux-design.md` or a `hexagonal-architecture.md` present → rename to `docs/design-system.md` / `code-structure.md` and carry every live cross-reference forward; remove the orphaned old file. A project-owned script, CI step, or doc invoking `npx groundwork ` (trailing space + subcommand) → rewrite to `npx groundwork-method ` — flags and arguments unchanged, lockfiles and any unrelated tool that merely contains the word untouched. A project-owned doc, script, or CI step referencing the relocated hidden-skills path `.agents/groundwork/skills/` → rewrite the prefix to `.groundwork/skills/`, the rest of the path unchanged — the move is real and these references dangle. Leave the user-owned `config.toml` (never written) and historical records alone. |
+| **Surfaces registry** | `.groundwork/skills/templates/surfaces.md` (its `version` field) + the `groundwork-surface-activation` skill | No `docs/surfaces.md` / `.groundwork/surfaces.json` on a multi-surface product → bootstrap the registry and capability ledger via `groundwork-surface-activation`. A runner-less `dev.config.json` whose surfaces/sidecars are invisible to `./dev` → register them as runners, without touching the db/jaeger compose. |
+| **Docs site** | The `docs-site` generator (`.groundwork/config/generators.json`) | A docs site behind the current generator — no `app/brand.css`, unordered nav, unrendered `mermaid`, a redirect instead of a landing page → for a generator-produced site, **regenerate** through the worker's `regenerate` recipe with its recorded options; for a hand-built site, refactor in place to match the generator's output (brand projection, the mermaid remark transform, `docs/meta.json` ordering, the two-audience landing hero). Keep the unbranded fallback intact: a project with no `brand-tokens.json` stays on the stock theme. |
+| **Next.js token layer** | The Next.js app generator (`.groundwork/config/generators.json`) | A Next.js app with a hardcoded `globals.css` and no per-app `brand.css` / token-conformance gate → regenerate the token layer from `brand-tokens.json` via the worker's `regenerate` recipe, reconcile any hand-edited `globals.css`, and add the conformance test. |
+
+Generator-owned families (**Docs site**, **Next.js token layer**) advance through the
+worker's `regenerate` recipe — the index names them so one framing covers every family, and
+does not duplicate the generator's reconcile steps. The prose families advance through the
+worker's relocate / rename / graduate / restructure recipes.
+
+---
+
+## Bookkeeping — Phase A items, exact, every item
+
+This contract is what keeps `update`, `check`, and future sessions honest about brief-lane
+work. (Phase B needs none — detect-first re-derives a family's state from its artifacts
+every run.) The driver records it as part of each item's commit, reading the worker's `FILES`
+report for what landed. After each brief item is committed (or checked off as done / n-a):
+
+- **Brief:** set the item's `status` to `"done"` in `.groundwork/cache/upgrade-brief.json`.
+- **Manifest** (`tier2-merge` and `tier1-custom` items): in
+  `.groundwork/config/manifest.json`, set the file's entry to the merged reality — `hash` =
+  SHA-256 of the file now on disk, `base` = SHA-256 of the `incoming` package content the
+  worker merged against, `version` = the brief's `to`. (Compute with `shasum -a 256 <file>`.)
+  This is what stops the same merge being queued forever.
+- **Manifest** (`regenerate` items): set `generated[<artifact>].version` to the brief's
+  `to`, and record the `options` used if the entry had none.
+
+Include the bookkeeping edits in the item's commit.
+
+When every brief item is done, delete the brief and the staged payloads
+(`.groundwork/cache/upgrade-brief.json`, `.groundwork/cache/upgrade/`) — cache lifecycle
+rules — in a final tidy commit. Then close by naming the version the project now stands at
+and confirming Phase B is reconciled, and suggest `npx groundwork-method check` as the
+proof.