Skip to content

Align — drop the retired design-state mechanics from the contract #559

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
The-Running-Dev merged 1 commit into from
Oct 7, 2026
Merged

Align — drop the retired design-state mechanics from the contract #559

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 0 additions & 111 deletions design/20-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

<!-- invariants:start -->
| | Statement | Held by | Enforcement | Evidence |
|---|---|---|---|---|
<!-- invariants:end -->

## Unresolved

Expand Down
6 changes: 6 additions & 0 deletions design/90-decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion docs/docs/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ sidebar_position: 1
sidebar_label: Developer Guide
---

<!-- design-digest: b887fe2c4a8cf79343b17c1fd73dbd688aecf0d32e375e31a61dfc14ff673b64 -->
<!-- design-digest: 38764ed43bde96faf963b60289a6dd595a9f6bff2d4c783edda8bccf7d5fa9c3 -->

> 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.
Expand Down
Loading