diff --git a/design/20-contract.md b/design/20-contract.md index 5cad3da..582c306 100644 --- a/design/20-contract.md +++ b/design/20-contract.md @@ -22,95 +22,6 @@ kind-internal signatures remain in their respective blocks. Core reason codes and validation errors are owned by Core Specification. Each kind adds only its registered reason-code vocabulary. -## Design-state mechanics - -This section is infrastructure for `tools/Test-DesignState.ps1` (installed from AgentKit), not -part of the game engine's own contract. It exists so the checker's two closed lists — the -artifact globs and the divergence classes — have somewhere to be read from in this repository, -matching every other repository the kit is installed into. - -### Artifacts of a unit kind - -A design-state record's kind determines which glob it must be found under. This repository has -adopted only the `WorkRef` record kind (`design/state-index.md`), so the `Unit`/`Invariant`/ -`Contract`/`Decision`/`Question` kinds below have no records of their own yet — the glob still -has to be readable so `GlobDisagreement` can compare it against the tree. - -| Kind | Glob | Excluded | -|---|---|---| -| command | `skills/*/SKILL.md` | — | -| script | `tools/*.ps1` | `*.Tests.ps1` | -| document | `design/*.md`, `templates/design/*.md`, `*.md`, `.claude/COMPANIONS.md`, `.github/ISSUE_TEMPLATE/*.md`, `codex/PROFILES.md` | `design/FROZEN.md`, `CLAUDE.md` | -| invariant | not a tree path | — | -| component | none in this repository | — | - -The `command` row matches nothing here: this repository's skills carry `SKILL-local.md`, not the -literal `SKILL.md` leaf the glob requires, so the empty set on both sides is agreement, not a gap. -The `component` row is empty for the same reason the `Unit`/`Contract`/`Decision`/`Question` kinds -are: this repository has not adopted a record kind for it, so declaring no pattern here is the -correct statement of that fact rather than an omission. - -### The divergence classes - -`Test-DesignState.ps1` raises every finding as one of a fixed set of classes. The three tiers -below are that checker's own arrays, restated here because `ClassListDisagreement` compares this -table against them. - -**Blocking.** - -| Class | Raised when | -|---|---| -| `UnresolvedId` | A reference names a record id that has no record. | -| `AnchorMissing` | A record's anchor does not resolve to a real file or heading. | -| `OwnerMismatch` | A record's declared owner disagrees with what the artifact itself states. | -| `UnrecordedArtifact` | A tracked-kind artifact in the tree has no record for it. | -| `ProjectionStale` | A generated projection disagrees with the records it was built from. | -| `RegionMalformed` | A marked region's start/end markers are missing or unbalanced. | -| `IdCollision` | Two records share the same id. | -| `DecisionAnchorAmbiguous` | A decision's anchor could resolve to more than one site. | -| `LogEntryUnrecorded` | A decision-log entry has no matching record. | -| `EnforcementUnevidenced` | An invariant's enforcement claim has no evidence that it runs. | -| `ClosureOverBudget` | A record's one-hop closure exceeds the byte budget. | -| `ClassListDisagreement` | This table disagrees with the checker's own class arrays. | -| `GlobDisagreement` | The glob table above disagrees with the checker's own enumeration for that kind. | -| `HeadingCollision` | Two headings in the same document normalize to the same anchor. | -| `RecordPairMalformed` | A paired record is missing its counterpart or fails to parse. | -| `HalfStatusMismatch` | A paired record's two halves disagree on status. | -| `HalfOverlap` | A paired record's two halves cover overlapping scope. | -| `SiteAmbiguous` | A record's site could resolve to more than one location. | -| `SiteOutOfReach` | A record's site falls outside anywhere that record kind may point. | -| `SiteContradictsLive` | A record's site disagrees with what is actually live in the tree. | -| `DecisionUnplaced` | A decision has no site recorded at all. | -| `SupersessionCycle` | A chain of decision supersessions loops back on itself. | - -**Reported, never blocking.** - -| Class | Raised when | -|---|---| -| `MirrorStale` | The work mirror lags behind the tracker it mirrors. | -| `WorkStateDivergence` | A work-mirror record disagrees with the live state of the work it mirrors. | -| `PinAncestry` | A pinned reference's ancestry cannot be walked to confirm what it claims to descend from. | -| `SemanticDisagreement` | Two records appear to state the same thing in conflicting words — a judgement call, not a structural one. | -| `LiveAlreadyStated` | A decision's terms already stand at a heading with no site naming it. | - -**Could not evaluate.** - -| `DesignStateFailure` | Raised when | Caller does | -|---|---|---| -| `StateSetAbsent` | `design/state/` is missing or holds no records of the kind being checked. | Skips that check rather than failing it. | -| `RecordUnparseable` | A record file exists but does not parse as its declared shape. | Reports the offending text verbatim. | -| `TrackerUnavailable` | The issue tracker could not be reached to compare against. | Skips the comparison. | -| `ShallowCheckout` | The checkout is too shallow for a check that needs history. | Skips that check. | -| `ProjectorFailed` | The projection generator itself failed to run. | Skips projection-staleness checks. | -| `ContractListUnreadable` | One of this contract's own canonical lists (this class table, the glob table, or the invariants table) could not be parsed. | Skips whatever comparison depends on that list — read-and-disagrees is a finding, cannot-read is not. | - -### The freeze - -While `design/FROZEN.md` exists, every blocking class above is downgraded to reported, the count -downgraded is stated, and the marker's `Frozen because` and `Lifts when` are reproduced verbatim. -A freeze permits known staleness; it does not permit a checker that could not run, so a -`CouldNotEvaluate` result stands regardless of whether a freeze is in effect. - ## Invariants Statements that must hold at all times, each written so it could become an assertion. This @@ -207,28 +118,6 @@ defeat it (§9.1). never replay inputs. *Enforced by the type — neither is a declared envelope field, which is why `RecordIdSource` is a second port rather than a widening of `IdSource`.* -**C1–C20 above are this contract's asserted set. The empty table below does not contradict -them**, and reading it as "no invariants" would be exactly backwards. The two are different -kinds of thing. C1–C20 are *prose statements*, written so each could become an assertion, and -they are what this document asserts. The table is a *projection of `Invariant` records* under -`design/state/` — machine-readable records with an `Owner`, an `Enforcement` and an `Evidence` -list, which `tools/Update-DesignProjection.ps1` renders into the marked region below and rewrites -on every `/track` run. - -This repository has no `Invariant` records. It adopted the work mirror and its index -(`design/state-index.md`) and no other record kind, per `AGENTS.md`, *Writing a design-state -record*, so the table renders its header and nothing else and will keep doing so until that -changes. The region exists so the projector has the target its own contract names, rather than -refusing a seventh region forever and leaving a standing failure that a real one cannot be told -apart from. - -Do not hand-write a row here — anything between the two markers is discarded on the next run. To -give an invariant a row, write it a record; to state one, write it as a C-number above. - - -| | Statement | Held by | Enforcement | Evidence | -|---|---|---|---|---| - ## Unresolved diff --git a/design/90-decisions.md b/design/90-decisions.md index 8891110..c65dc93 100644 --- a/design/90-decisions.md +++ b/design/90-decisions.md @@ -2217,3 +2217,9 @@ Context: The kit's `v2026.10.07` ships thirteen commands (`interview`, `design`, Chosen: Delete the 14 `SKILL-local.md` files and the three kit-owned `tools/*.ps1` copies (`Test-DesignDrift.ps1` and its test, `Test-CIWorkflow.Tests.ps1`). Rewrite `CLAUDE.md`'s Design Freeze and Agent Kit sections and `AGENTS.md`'s design-state section to the current command set. The freeze stays, as a manual convention: `design/FROZEN.md` is written and lifted by hand. `design/state/` and `design/state-index.md` stay in place, orphaned, until a separate decision retires them. Rejected: **Leave the docs as written** — they point readers at commands that do not exist. **Retire the freeze with the commands that enforced it** — the reasoning for it (no fixed point while implementation is the bottleneck) still holds and a marker costs nothing. **Delete `design/state/` now** — that is a decision about the tracker mirror, not a transcription, and `design/20-contract.md`'s Design-state mechanics section names it. **Edit `design/20-contract.md` here** — it carries the same stale references (`Test-DesignState.ps1`, `Update-DesignProjection.ps1`, `/track`) and belongs to a `/agentkit:align` pass, not an install. Reversibility: cheap. The deletions and the prose are one revert of this change. + +### 2026-10-07 — Remove the design-state mechanics and invariants projection from the contract +Context: `/agentkit:align` after the `v2026.10.07` kit sync. `20-contract.md` carried a *Design-state mechanics* section (artifact globs, divergence classes, the freeze downgrade) for `Test-DesignState.ps1`, and an empty invariants projection table rendered by `Update-DesignProjection.ps1` on `/track`. Neither tool exists any more (`tools/` holds only `host-smoke`), so nothing reads or regenerates either. +Chosen: Delete both from `20-contract.md`; C1–C20 stay as the asserted invariant set. `design/state/` and `design/state-index.md` are left in place; retiring them stays a separate decision, as recorded 2026-10-07. The freeze convention lives in `CLAUDE.md`. +Rejected: A tombstone paragraph — the 2026-10-07 kit-sync entry already records why. Retiring `design/state/` in the same change — a larger diff, and `AGENTS.md` still documents the mirror. +Reversibility: cheap. One revert restores the text. diff --git a/docs/docs/guide.md b/docs/docs/guide.md index 62c85d8..9af3828 100644 --- a/docs/docs/guide.md +++ b/docs/docs/guide.md @@ -3,7 +3,7 @@ sidebar_position: 1 sidebar_label: Developer Guide --- - + > Generated from `design/` by `/make-human-docs`. Do not edit by hand — edit the > design docs and regenerate. `/reconcile` reports when this has gone stale.