groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/templates/discovery-notes.md

@@ -0,0 +1,33 @@
+# Discovery Notes
+
+> Signals captured out-of-phase during GroundWork conversations. Each skill reads its section before starting and removes lines once incorporated into output. Section headers match the canonical set defined in `operating-contract.md` — do not add, rename, or reorder them.
+
+---
+
+## Product Brief
+
+<!-- Vision-level signals captured during later phases — new user types, missing capabilities, refined success criteria. -->
+
+---
+
+## Design System
+
+<!-- What the user sees or does: interaction patterns, search/browse/navigation flows, aesthetic instincts. User-facing signals go here even when they name a concrete mechanism (e.g. faceted vs conversational search). Internal mechanisms belong in ## Design Details. -->
+
+---
+
+## Architecture
+
+<!-- Infrastructure preferences, scaling instincts, technology opinions surfaced outside the architecture phase. -->
+
+---
+
+## Design Details
+
+<!-- Internal mechanisms the user never sees directly — async flows, callback patterns, job lifecycles, data ownership, contract format choices, resiliency patterns. Not user-facing interaction patterns; those go to ## Design System. -->
+
+---
+
+## Bets
+
+<!-- Delivery priorities, MVP scope instincts, feature sequencing for future bets. -->

package/src/hidden-skills/templates/domain-entity.md

@@ -0,0 +1,80 @@
+---
+title: <Entity Name>
+description: <One-line definition>
+status: active
+last_reviewed: <YYYY-MM-DD>
+---
+
+# <Entity Name>
+
+**Owner:** <service-name>
+
+## What it is
+
+One paragraph describing the entity and its role in the system. State the
+invariant the entity exists to enforce.
+
+## Fields
+
+| Field | Type | Description |
+|---|---|---|
+| id | uuid | Primary identifier. |
+| ... | ... | ... |
+
+## Lifecycle
+
+States and what triggers each transition. If the entity has no meaningful
+state machine (e.g. immutable record), say so explicitly and remove both the
+diagram and the table.
+
+When the entity does have a state machine, draw it as a `stateDiagram-v2` so a
+reader sees the shape before reading the triggers. The table below the diagram
+carries the detail the diagram cannot.
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft: creation
+    draft --> active: <trigger>
+    active --> [*]: <trigger>
+```
+
+Every trigger must be mechanically detectable — backed by a field in the
+Fields table or an emitted event. A state reached by the passage of time or
+inactivity needs the field that makes it detectable (e.g. `last_active_at`); a
+state with no detectable trigger cannot be enforced and is invalid.
+
+| State | Triggered by | Description |
+|---|---|---|
+| draft | creation | Initial state on insert. |
+| ... | ... | ... |
+
+## Domain events
+
+Significant state changes this entity models, named `<entity>.<verb>`. These
+are domain-modeling concepts, not a commitment to publish messages. Whether an
+event is actually published to a broker or bus is an architecture decision — if
+the architecture provisions no message broker, these remain in-process domain
+events with no external publish channel. Do not imply a publish mechanism the
+architecture has not provided.
+
+| Event | Trigger | Payload summary |
+|---|---|---|
+| <entity>.created | initial insert | id, owner, created_at |
+| ... | ... | ... |
+
+## Invariants
+
+Constraints that must hold for the entity to be valid. Listed explicitly so
+that violations are detectable in tests and at boundaries.
+
+An invariant may only assert a guarantee the architecture and accepted ADRs
+actually provide. When an ADR records that a guarantee was deliberately
+surrendered — a monitor rather than a pre-screen, eventual rather than
+immediate consistency — state the weaker guarantee the system enforces, never
+the stronger one the ADR gave up.
+
+- ...
+
+## Notes
+
+Anything non-obvious — historical decisions, edge cases, known gotchas.

package/src/hidden-skills/templates/gap-ledger.md

@@ -0,0 +1,21 @@
+# Gap Ledger
+
+> Working file. Each brownfield phase appends the divergences from GroundWork standard it discovers. `groundwork-infra-adopt` consolidates this into the roadmap table of `docs/maturity.md` at the end of setup (model: `.groundwork/skills/maturity-model.md`), and the bet loop reads it when planning every bet.
+
+Each entry records what diverges, the standard it violates, a severity, and a recommendation. Severity and Recommendation are closed value sets defined by the maturity model — write the values exactly as spelled below, because the roadmap reuses these strings verbatim and a drifted spelling orphans the row.
+
+**Severity** — exactly one of `blocks-delivery` | `standard-divergence` | `cosmetic`:
+
+- **`blocks-delivery`** — undermines GroundWork's ability to deliver and verify work. The bet loop cannot run well around it. Examples: a service exposes routes with no machine-readable contract (the contract-driven bet loop depends on OpenAPI/AsyncAPI); no system-test harness exists (progress and proof-of-work cannot be tracked across services).
+- **`standard-divergence`** — works, but off the pattern GroundWork's templates encode. Example: events cross services with no transactional outbox; a service has no health endpoint; config is hard-coded rather than externalised.
+- **`cosmetic`** — naming, doc structure, minor layout.
+
+**Recommendation** — exactly one of `fix-now` | `defer` | `blocks-delivery`:
+
+- **`fix-now`** — worth resolving before the first bet.
+- **`defer`** — real, but value lies elsewhere first.
+- **`blocks-delivery`** — must be the first bet, or close to it. It shares its spelling with the severity tier but is a distinct value in a distinct column.
+
+| Gap | Standard violated | Severity | Recommendation | Evidence |
+|---|---|---|---|---|
+<!-- One row per gap. Phases append; none rewrite prior rows. -->

package/src/hidden-skills/templates/handoff.md

@@ -0,0 +1,37 @@
+# Hand-off from <phase-name>
+
+> Post-commit context drop from the phase that just committed. The next phase reads this file once at init and deletes it on its own commit. Distinct from `discovery-notes.md`, which captures in-conversation out-of-phase signals.
+>
+> Fill in only the sections that have content. Omit empty sections entirely — do not leave empty headings.
+
+---
+
+## Rejected Options
+
+<!-- Alternatives considered and ruled out during this phase. Format: option — why rejected. Lets the next phase avoid re-litigating decisions the user has already weighed. -->
+
+- <option> — <why rejected>
+
+---
+
+## Deferred Decisions
+
+<!-- Decisions explicitly left open, with the trigger that should reopen them. Distinct from the Deferred Questions in the phase's Downstream Context file (Protocol 5) — these entries carry the conversational context behind the deferral. Format: decision — context — revisit trigger. -->
+
+- <decision> — <context> — <revisit trigger>
+
+---
+
+## User Instincts
+
+<!-- Uncommitted signals the user voiced that the next phase should honour but this phase did not formalise. These are not approved decisions — they are leanings the next phase should test against. -->
+
+- <signal> — <how the next phase should treat it>
+
+---
+
+## Context Drop
+
+<!-- Anything else the next phase needs that does not fit the categories above. Keep entries short and concrete — if a note is not load-bearing for the next phase's work, do not write it. -->
+
+- <note>

package/src/hidden-skills/templates/maturity.md

@@ -0,0 +1,39 @@
+---
+title: Maturity Roadmap
+service: "cross-cutting"
+type: "index"
+last_reviewed: <YYYY-MM-DD>
+---
+
+# Maturity Roadmap
+
+This document tracks the project against the GroundWork maturity model — the nine dimensions of the target state defined in `.groundwork/skills/maturity-model.md`. The assessment says where the project stands; the roadmap says what closing the distance is worth and what it costs. Gaps are proposals, not obligations: `accepted` is a legitimate terminal status.
+
+## Current Assessment
+
+| Dimension | State | Evidence |
+|---|---|---|
+| D1. Documented truth | ✅ / 🟡 / 🔴 | <file or command output that justifies the state> |
+| D2. Machine-readable contracts | ✅ / 🟡 / 🔴 | |
+| D3. One-command operations | ✅ / 🟡 / 🔴 | |
+| D4. System-level proof | ✅ / 🟡 / 🔴 | |
+| D5. Code intelligence | ✅ / 🟡 / 🔴 | |
+| D6. Doc currency automation | ✅ / 🟡 / 🔴 | |
+| D7. Delivery discipline | ✅ / 🟡 / 🔴 | |
+| D8. Surface parity discipline | ✅ / 🟡 / 🔴 / n/a | <`n/a` when no surface registry exists — name that as the evidence> |
+| D9. Contract compatibility | ✅ / 🟡 / 🔴 / n/a | <`n/a` below two independently deployed surfaces — name that as the evidence> |
+
+**Assessed:** <YYYY-MM-DD> by <phase or skill that ran the assessment>
+
+## Roadmap
+
+One row per gap. Severity/recommendation reuse the gap-ledger tiers; status moves `open` → `in-bet (<slug>)` → `closed (<slug>)`, or to `accepted` when the user decides the gap stays.
+
+| # | Gap | Dimension | Severity | Recommendation | Status | Evidence / Notes |
+|---|---|---|---|---|---|---|
+| G1 | <what diverges from the target state> | D1–D9 | blocks-delivery / standard-divergence / cosmetic | fix-now / defer / blocks-delivery | open | <evidence; for accepted: who accepted and why> |
+
+## History
+
+<!-- Append-only log: one line per assessment or status change.
+     e.g. "2026-06-09 — initial assessment by groundwork-infra-adopt; G1–G5 opened." -->

package/src/hidden-skills/templates/surfaces.md

@@ -0,0 +1,207 @@
+# Surface Registry & Capability Ledger Contract
+
+`docs/surfaces.md` is the canonical record of a product's surfaces and the capability core they adapt. The prose document is the human source of truth; `.groundwork/surfaces.json` is its machine-readable twin, kept in lockstep by the same commits (the contract-grade rule: every reviewed artifact has a machine-checkable twin). The architecture commit writes both at greenfield setup; `groundwork-architecture-extract` writes both at brownfield adoption; `groundwork-surface-activation` and bet validation maintain them for the life of the product.
+
+**The model:** a product is one **capability core** — the domain logic, data, and contracts, always designed and validated headless — plus zero or more **surfaces**, the deployed artifacts consumers interact with (a web app, a CLI binary, a mobile app, an MCP server). Surfaces are adapters over the core. The registry names the surfaces; the **capability ledger** records which capabilities reached which surfaces, so divergence between surfaces is a decision on record, never a silent drift.
+
+---
+
+## Document structure
+
+`docs/surfaces.md` carries three sections, in this order:
+
+### 1. Capability Core
+
+One short section describing the core: what it owns (domain logic, persistence, contracts), its **deployment** — `hosted` (services reached over a network) or `embedded` (a library in-process with its single surface) — and where its contracts live. The deployment decision is made in the architecture phase; it determines the contract spec format (OpenAPI/AsyncAPI for hosted HTTP/event boundaries, proto for gRPC, a typed public module API for an embedded core) and the transport capability tests run against. Nothing else branches on it.
+
+### 2. Surface Registry
+
+One entry per surface, current and planned. Each entry is a heading (`### <slug>`) with a field table:
+
+| Field | Values | Meaning |
+|---|---|---|
+| `type` | `graphical-ui` \| `cli` \| `agentic-protocol` | The interface type — owns the design track, vocabulary, and test medium family. |
+| `platform` | `web` \| `mobile` \| `desktop` \| `terminal` \| `protocol` | Where the artifact runs. Several surfaces can share a type across platforms (web and mobile are both `graphical-ui`). |
+| `status` | `active` \| `planned` \| `dormant` \| `retired` | `active` ships and is tested; `planned` is on the roadmap with no code; `dormant` exists but is not currently maintained; `retired` is decommissioned (see the retired-column rule below). |
+| `core access` | e.g. `http-gateway`, `http-direct`, `grpc`, `in-process` | How this surface reaches the core — the access path the architecture phase settled (direct, gateway, BFF). |
+| `auth` | free text | The auth model this surface uses against the core. |
+| `scaffold` | a generator name (`nextjs-app`, `cli-app`, `flutter-app`, `electron-app`), `forged`, or `manual` | What generates the surface's app. `manual` is first-class: a surface participates fully in design, bets, the ledger, and tests before a generator exists for it — the registry never blocks on tooling. `forged` means no generator exists but `groundwork-stack-forge` built a Day-2 seed and a stack engineer skill for it — like `manual`, no generator invocation, but unlike `manual`, a real seed already boots. |
+| `test medium` | e.g. `playwright`, `subprocess-cli`, `protocol-client`, `flutter-integration`, `playwright-electron` | The fixture family `system-test-runner` provisions for this surface. |
+| `design track` | section reference into `docs/design-system.md` | The interface-type section that governs this surface's design vocabulary. |
+
+A product with zero surface entries is legal: a headless API product's only surface *is* its protocol — register the protocol itself as an `agentic-protocol` surface, or leave the registry empty and let the core's contracts stand alone.
+
+### 3. Capability Ledger
+
+A capability × surface matrix. **Rows** are user-meaningful capabilities, named at bet validation — typically 1–3 per bet, coarse enough to stay readable, never per-endpoint (endpoints already have `docs/architecture/api/` promotion). Row keys follow `<bet-slug>/<capability-slug>` — stable, greppable, collision-free. **Columns** are the registry's surfaces. Each cell carries exactly one state:
+
+| State | Meaning | Required payload |
+|---|---|---|
+| `delivered` | Shipped on this surface | the delivering bet's slug |
+| `planned` | Will ship here; not yet | a bet ref or discovery-notes pointer |
+| `omitted` | Deliberate decision not to ship here | one-line rationale |
+| `n/a` | Capability does not apply to this surface | — |
+
+`omitted` and `n/a` are distinct on purpose: `n/a` is structural (offline sync has no meaning on a stateless web client), `omitted` is a product choice a future bet may revisit. **An empty cell is the only illegal state once a capability row exists** — bet validation fills every column or the bet does not close. The ledger records decisions; it never nags toward 100% parity — admin tooling belongs on web only, offline mode belongs on mobile only, and the ledger's job is to say so on the record.
+
+### The retired-column rule
+
+When a surface's status moves to `retired`, its ledger column freezes: existing cells keep their last state as history, new capability rows fill the retired column `n/a` automatically, and tooling (`./dev surface status`, `groundwork-check`) excludes it from sync-backlog and staleness counts. A retired surface is history, not backlog.
+
+---
+
+## Example — two active surfaces plus a retired one
+
+```markdown
+# Surfaces
+
+## Capability Core
+
+Hosted core: three Go services behind an HTTP gateway own ordering, inventory,
+and notification logic. Contracts are OpenAPI 3.x, promoted to `docs/architecture/api/` at
+bet validation. All capability behaviour is provable against these contracts
+with no surface running.
+
+## Surface Registry
+
+### web-app
+
+| Field | Value |
+|---|---|
+| type | graphical-ui |
+| platform | web |
+| status | active |
+| core access | http-gateway |
+| auth | session cookie via gateway |
+| scaffold | nextjs-app |
+| test medium | playwright |
+| design track | docs/design-system.md § Graphical UI |
+
+### admin-cli
+
+| Field | Value |
+|---|---|
+| type | cli |
+| platform | terminal |
+| status | active |
+| core access | http-direct (service tokens) |
+| auth | API token |
+| scaffold | cli-app |
+| test medium | subprocess-cli |
+| design track | docs/design-system.md § CLI |
+
+### beta-dashboard
+
+| Field | Value |
+|---|---|
+| type | graphical-ui |
+| platform | desktop |
+| status | retired |
+| core access | http-gateway |
+| auth | session cookie via gateway |
+| scaffold | manual |
+| test medium | — (retired) |
+| design track | docs/design-system.md § Graphical UI |
+
+## Capability Ledger
+
+| Capability | web-app | admin-cli | beta-dashboard (retired) |
+|---|---|---|---|
+| `order-flow/place-order` | delivered (`order-flow`) | omitted — operators never place orders | delivered (`order-flow`) |
+| `order-flow/order-status` | delivered (`order-flow`) | delivered (`order-flow`) | delivered (`order-flow`) |
+| `bulk-ops/bulk-reprice` | omitted — admin tooling is CLI-only | delivered (`bulk-ops`) | n/a |
+```
+
+The `bulk-ops/bulk-reprice` row landed after `beta-dashboard` retired, so its retired column is `n/a` automatically; the two `order-flow` rows predate the retirement and keep their `delivered` history.
+
+---
+
+## Machine-readable twin: `.groundwork/surfaces.json`
+
+Written and updated in the same commit as `docs/surfaces.md` — the two never disagree because both are projections of the same decisions. Read by `./dev surface status` and `groundwork-check`.
+
+```json
+{
+  "schema": "groundwork.surfaces",
+  "version": 1,
+  "core": {
+    "deployment": "hosted",
+    "contractFormat": "openapi",
+    "contractsPath": "docs/architecture/api/"
+  },
+  "surfaces": [
+    {
+      "slug": "web-app",
+      "type": "graphical-ui",
+      "platform": "web",
+      "status": "active",
+      "coreAccess": "http-gateway",
+      "auth": "session cookie via gateway",
+      "scaffold": "nextjs-app",
+      "testMedium": "playwright",
+      "designTrack": "graphical-ui"
+    },
+    {
+      "slug": "admin-cli",
+      "type": "cli",
+      "platform": "terminal",
+      "status": "active",
+      "coreAccess": "http-direct",
+      "auth": "API token",
+      "scaffold": "cli-app",
+      "testMedium": "subprocess-cli",
+      "designTrack": "cli"
+    },
+    {
+      "slug": "beta-dashboard",
+      "type": "graphical-ui",
+      "platform": "desktop",
+      "status": "retired",
+      "coreAccess": "http-gateway",
+      "auth": "session cookie via gateway",
+      "scaffold": "manual",
+      "testMedium": null,
+      "designTrack": "graphical-ui"
+    }
+  ],
+  "capabilities": [
+    {
+      "key": "order-flow/place-order",
+      "name": "Place an order",
+      "cells": {
+        "web-app": { "state": "delivered", "bet": "order-flow" },
+        "admin-cli": { "state": "omitted", "rationale": "operators never place orders" },
+        "beta-dashboard": { "state": "delivered", "bet": "order-flow" }
+      }
+    },
+    {
+      "key": "order-flow/order-status",
+      "name": "Track order status",
+      "cells": {
+        "web-app": { "state": "delivered", "bet": "order-flow" },
+        "admin-cli": { "state": "delivered", "bet": "order-flow" },
+        "beta-dashboard": { "state": "delivered", "bet": "order-flow" }
+      }
+    },
+    {
+      "key": "bulk-ops/bulk-reprice",
+      "name": "Bulk reprice inventory",
+      "cells": {
+        "web-app": { "state": "omitted", "rationale": "admin tooling is CLI-only" },
+        "admin-cli": { "state": "delivered", "bet": "bulk-ops" },
+        "beta-dashboard": { "state": "n/a" }
+      }
+    }
+  ]
+}
+```
+
+### Schema rules
+
+- `core.deployment` — `"hosted"` or `"embedded"`. `core.contractFormat` — `"openapi"`, `"asyncapi"`, `"proto"`, or `"typed-module-api"`; a core with several boundary kinds lists the dominant one and the prose section carries the rest.
+- `surfaces[].slug` is the join key everywhere: ledger cells, test fixtures (`surfaces["web-app"]`), pitch `surfaces:` frontmatter, decomposition slice `surface` fields. Slugs are kebab-case and never renamed — rename means retire + add.
+- `surfaces[].testMedium` is `null` only for `planned` and `retired` surfaces; a `dormant` surface keeps its medium — recorded so reactivation knows the fixture family, exercised only while the surface is `active`; an `active` surface without a test medium is a `groundwork-check` finding.
+- `capabilities[].cells` carries one entry per registry surface (including retired ones — frozen history or auto-`n/a` per the retired-column rule). A missing cell key is the machine form of the illegal empty cell.
+- Cell payloads: `delivered` requires `bet`; `planned` requires `ref` (a bet slug or `discovery-notes` pointer); `omitted` requires `rationale`; `n/a` carries no payload.
+- **Versioned contract.** `version` bumps only when the shape changes. Consumers ignore unknown fields. Keep changes additive.
+- **One writer per moment, many readers.** Architecture (or architecture-extract) creates it; bet validation appends capability rows; surface activation appends surface entries and triages columns. `./dev surface status` and `groundwork-check` only read.

package/src/skills/groundwork-check/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: groundwork-check
+description: Analyzes GroundWork architecture docs for staleness against the codebase by checking git logs for `source_of_truth` paths since `last_reviewed`. Designed to run in CI.
+---
+
+# GroundWork Check Skill
+
+The full staleness workflow lives in `instructions.md`, colocated with this file; load it when invoked.
+
+## Doc-Type Behaviours
+
+Different doc types have different drift semantics. Apply these rules when scanning `docs/`:
+
+### `docs/principles/**` and `docs/ways-of-working/**`
+
+These are project-stable docs not derived from code. Do **not** flag them for code drift. Do surface a low-severity advisory (not a build failure) for any file whose `last_reviewed` date is more than 12 months old. Advisory format: "Advisory: `<path>` has not been reviewed in over 12 months — consider a manual review pass."
+
+### `docs/architecture/domain/<entity>.md`
+
+Entity docs should reflect the domain as it appears in code. When discoverable (schema migration files, model definitions), compare entity names found in code against the names of files in `docs/architecture/domain/`. Flag two conditions as warnings:
+
+- An entity file exists in `docs/architecture/domain/` but no corresponding code definition can be found — possible deletion or rename.
+- A code definition exists but no entity file exists in `docs/architecture/domain/` — the architecture phase may have missed it, or a bet added it without documentation.
+
+Do not fail the build on domain mismatches — these are advisory warnings requiring human judgement.
+
+### `docs/architecture/decisions/NNNN-*.md`
+
+ADRs are append-only historical records. Do **not** check for code drift. Do check:
+
+- Numbering is sequential with no gaps (0001, 0002, 0003, ... with no missing integers).
+- Every file's `status` frontmatter field is either `accepted` or begins with `superseded by`.
+
+Report numbering gaps and invalid statuses as build failures — they indicate a corrupted ADR history.
+
+### `docs/surfaces.md` and `.groundwork/surfaces.json`
+
+The surface registry and capability ledger are twins: the prose doc and the JSON are projections of the same decisions, written by the same commits (contract: `.groundwork/skills/templates/surfaces.md`). Exclude `retired` surfaces from every staleness and backlog count below — a retired column is frozen history, never backlog.
+
+Report as build failures:
+
+- **Twin drift** — the doc and the JSON disagree on the surface set, a surface's status, or a cell's state. The twin rule exists so machine checks can stand in for the prose; a disagreement means a commit updated one projection and not the other, and neither can be trusted until they are reconciled.
+- **Empty ledger cells** — a capability row missing a cell for a registry surface (retired columns included — they carry frozen history or auto-`n/a`), or a cell with no recognised state. An empty cell is the only illegal ledger state: bet validation fills every column or the bet does not close, so an empty cell means a bet closed past its gate.
+
+Report as warnings:
+
+- **Stale planned intent** — a `planned` cell older than three closed bets with no referencing pitch. Date the cell from the commit that introduced it in `.groundwork/surfaces.json`, count closed bets — the directories under `docs/bets/_archive/` — whose pitch was created after that date (date each from the commit that first added its `docs/bets/<slug>/pitch.md`), and search `docs/bets/` for a pitch that references the capability key or names the surface in its `surfaces:` frontmatter. The threshold is bets, not months, because ledger intent ages at the betting table: each closed bet is a table that passed on the cell, and three passes mark intent that no longer reflects a plan. The other staleness heuristics in this skill are calendar-based; capability work is not scheduled by the calendar.
+- **Untested active surface** — an `active` surface absent from the system-test conftest's `surfaces` fixture mapping (`_SURFACE_SPECS` in `tests/conftest.py`), or carrying `testMedium: null`. `active` means shipped and tested; an active surface no test can reach is a claim without proof.
+
+Report as an advisory (not a build failure):
+
+- **No registry** — GroundWork docs exist but neither `docs/surfaces.md` nor `.groundwork/surfaces.json` does. This is a pre-restructure adoption, not drift. Point at `groundwork-surface-activation`, whose first move on such a product is to bootstrap the registry from `docs/architecture/index.md` and the existing scaffold.
+
+### `docs/architecture/services/**`
+
+Out of scope for the current check implementation.

package/src/skills/groundwork-check/instructions.md

@@ -0,0 +1,70 @@
+---
+name: groundwork-check
+description: >
+  Detects drift between the committed documentation and the system it describes — code
+  changes after a doc's last_reviewed, maturity-roadmap rows that disagree with observed
+  state — and reports it with recovery routes. Read-only and CI-safe: it mutates nothing
+  and exits non-zero on critical drift.
+---
+
+# groundwork-check
+
+You are the project's drift detector. The canonical docs claim to describe the system as it is; your job is to test that claim mechanically and report honestly. You run non-interactively when needed (CI), mutate nothing, and never soften a finding — a doc you cannot assess is reported as unassessed, not skipped.
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) defines your mode: **Maintenance**, read-only and diagnostic. From `.groundwork/cache/` you read only `repo-map.json`.
+
+The deterministic core of this skill also runs without an agent as `npx groundwork-method check` — that command covers Step 1's git-log baseline. You add what determinism cannot: dependency-graph reach (Step 2), maturity re-assessment (Step 3), and doc-type judgement (Step 4).
+
+---
+
+## Step 0: Framework staleness
+
+Before doc drift, test whether the install itself has been left behind — the CLI's
+framework section (`npx groundwork-method check`) covers this deterministically; mirror
+its reading when you run instead of it:
+
+- Compare `groundwork.version` in `.groundwork/config/state.json` against the installed
+  package version. A gap means the mechanical lane is owed: report it with the route
+  `npx groundwork-method update` (never attempt the refresh yourself — the CLI owns it).
+- `.groundwork/cache/upgrade-brief.json` with pending items means judgment-lane work is
+  waiting: report the pending count with the route `groundwork-update`.
+- No `.groundwork/config/manifest.json` on an otherwise current install means the
+  project predates install manifests — one `npx groundwork-method update` bootstraps it.
+
+Framework staleness is a **warning**, not a build failure — the project's docs may be
+perfectly current while the framework trails. Report it first so the reader knows which
+tooling vintage produced the rest of the report.
+
+## Step 1: Staleness baseline
+
+Find every code-coupled doc: the files under `docs/architecture/services/`, `docs/architecture/api/`, and `docs/architecture/domain/`, plus `docs/architecture/index.md`. From each doc's frontmatter take `last_reviewed`, `source_of_truth`, and `generation_mode`.
+
+For each doc with both fields, run `git log --since="<last_reviewed>" --oneline -- <source_of_truth paths>`. Commits found → the doc is **STALE**, with the commit list as evidence. A doc missing the fields is **UNASSESSED** — report it as such; an unassessable doc that silently passes is the failure mode this skill exists to prevent.
+
+## Step 2: Reference-graph reach (Serena)
+
+Path-filtered git history misses drift by construction: a contract doc goes stale when a type it references moves in a file outside its `source_of_truth`. When the Serena MCP server is available, run impact analysis with `find_referencing_symbols` on the symbols changed since each doc's `last_reviewed` and add any doc whose sources depend on changed code through the reference graph. `.groundwork/cache/repo-map.json` serves the same purpose offline. Without either, the Step 1 baseline stands alone — say so in the report rather than implying graph coverage.
+
+## Step 3: Maturity re-assessment
+
+If `docs/maturity.md` exists, re-evaluate the mechanical signals of the maturity model (`.groundwork/skills/maturity-model.md`, dimensions D1–D6 plus D8's registry and ledger signals — D7 is judgement-based and D9 is re-assessed by bet validation, so both are out of scope for a check run):
+
+- For each assessment row, test its signal now: do the canonical docs exist with summaries (D1)? does each service have a referenced contract (D2)? does `./dev` exist (D3)? is the system-test runner present (D4)? is Serena registered with a code map (D5)? does CI invoke the check (D6)? do the registry twins agree with every ledger cell filled (D8 — `n/a` when no registry exists)?
+- Flag every **disagreement** between observed state and the doc: a dimension marked ✅ whose signal now fails (regression — critical), a roadmap row `closed` whose gap is observably back (critical), and a row `open` whose signal now passes (good news — propose closing it via `groundwork-doc-sync`).
+- Rows marked `accepted` are settled; verify nothing, report nothing, unless the underlying severity escalated to `blocks-delivery`.
+
+Do not edit `docs/maturity.md` — you are read-only. Disagreements are findings for `groundwork-doc-sync` to apply.
+
+## Step 4: Doc-type judgement
+
+Apply the Doc-Type Behaviours defined in this skill's `SKILL.md`: principles and ways-of-working docs get a 12-month advisory instead of code-drift checks; domain entity docs are cross-checked against code definitions in both directions (advisory); ADRs are checked for sequential numbering and valid `status` fields (build failure on corruption); the surface registry and capability ledger are cross-checked against their prose twin, the test fixtures, and the bet history (twin drift and empty cells are build failures; stale `planned` intent and untested active surfaces are warnings; a missing registry is an advisory); `docs/architecture/services/` deep integration is deferred.
+
+## Step 5: Report
+
+Group findings by service, severity first:
+
+1. **Critical** — stale contract-bearing docs (API, schema, events), ADR corruption, surface-ledger corruption (twin drift, empty cells), maturity regressions, `closed` rows whose gap is back. These fail the build: end with a failing status.
+2. **Warnings** — other stale docs, domain cross-check mismatches, unassessed docs, stale `planned` ledger cells, untested active surfaces.
+3. **Advisory** — aging stable docs, `open` roadmap rows whose signal now passes, GroundWork docs with no surface registry (route: `groundwork-surface-activation` bootstraps it).
+
+For every finding name the recovery route: `generation_mode: generated` → re-run the generator that produced it; `extracted` or prose docs → run the `groundwork-doc-sync` skill; maturity disagreements → `groundwork-doc-sync` with this report as the change-set anchor. If nothing drifted, say exactly that — and state which steps ran (with or without Serena, with or without a maturity doc), so a clean report is auditable.