Skip to content

Wire Design Contract Checker lenses into a structural registry - #261

Merged
joshft merged 4 commits into
mainfrom
feature/design-contract-lens-sync
Jul 11, 2026
Merged

Wire Design Contract Checker lenses into a structural registry#261
joshft merged 4 commits into
mainfrom
feature/design-contract-lens-sync

Conversation

@joshft

@joshft joshft commented Jul 11, 2026

Copy link
Copy Markdown
Owner

Summary

Closes the DA-001 / AP-036 gap: the eight documented /creview-spec Design Contract Checker lenses (from postmortems PMB-013 to PMB-020) existed only as CLAUDE.md prose and never reached the enforcing agent — a "corrective-action described but not implemented" instance in the contract mechanism itself. This makes the lens set a first-class, structurally-enforced artifact.

  • New agents/design-contract-lenses.tsv — the single source of truth (SSOT) for the 8 PMB-derived lenses (DCL-001 cardinality through DCL-008 mechanism-capability-mismatch).
  • agents/review-spec-design-contract.md expanded with a ## PMB-derived lenses section — one DCL-tagged, condition-bearing bullet per registry row (keyword + {BLOCKING,flag} directive + {when,if} condition + body floor), plus a template/runbook intro. The generic lens is retained.
  • tests/test-design-contract-lens-sync.sh binds registry to agent by set-equality (completeness + no-orphans), validates registry well-formedness (15-case malformed-fixture rejection suite), enforces the anti-gaming body floor over the live registry (not a hard-coded seed), and self-scans to prevent re-coupling to CLAUDE.md.
  • skills/cpostmortem/SKILL.md Step 3 convention: a PMB documenting a new Design Contract Checker lens must add a registry row.
  • ABS-050 architecture entry — a new primary-SSOT abstraction (opposite authority direction to the ABS-047 sole-writer family: here the registry is the source of truth and the agent is derived from it).

The registry is source-only (sync.sh mirrors only agents/*.md); user installs receive the lens bodies inline in the shipped agent .md.

Incidental fix (separate commit)

A pre-existing, unrelated date-drift in tests/test-cross-feature-intel.sh: a hardcoded PMB-001 fixture date (2026-04-10) crossed the intel script's 90-day recency window on ~2026-07-09, so any CI run after that date silently filtered the "audit" entry and reddened INV-016e. Fixed by generating the fixture dates relative to today (date -d 'N days ago') so they never drift again — fittingly, the exact bound-drift class the new DCL-001/DCL-007 lenses guard against.

Test plan

  • tests/test-design-contract-lens-sync.sh73 assertions, all pass (set-equality via two shared-regex extractors, 8 anchored seed rows, live-registry substance loop, 15-case malformed-registry rejection suite, PRH-001 self-scan whitelist, mirror parity, source-only find-check, plus test-the-test cases proving the two extractor scopes differ and the rejection branches are live).
  • Full test suite green (112 test files).
  • sync.sh verify clean; shellcheck --severity=warning clean.

QA findings

  • 2 QA rounds — independent Claude review + codex (GPT-5.5) cross-model review. Codex found (and later confirmed resolved): DCL-004/DCL-005 lens-body narrowing vs. their source PMBs, and INV-005 substance checks iterating only the hard-coded seed array. All fixed.
  • 3 mini-audit lenses (seed-completeness-vs-postmortems, lens-body-anti-gaming, test-the-test-rejection-coverage) — converged, no CRITICAL/HIGH; independently re-derived the 8-lens set from postmortems and confirmed 1:1 registry mapping.
  • 1 verification-phase HIGH (CV-001) from codex — the PRH-001 self-scan whitelist matched grep + the single-quoted needle without pinning the trailing file argument, so a prohibited grep '<needle>' CLAUDE.md (reading CLAUDE.md) would have passed. Tightened to strip the needle and reject any residual guidance-file token, with 3 new test-the-test assertions.
  • Surfaced (optional follow-up): MA-001 LOW (the exactly-once uniqueness leg has no dedicated duplicate-token negative fixture — exercised indirectly).

Verification status

PASS — all 13 rules (INV-001..010, PRH-001/002, BND-001) satisfied with real-file evidence and live test enforcement; codex cross-model verification confirmed convergence with no BLOCKING/HIGH outstanding.

joshft added 4 commits July 10, 2026 18:05
The INV-016 workflow-effectiveness fixture used hardcoded absolute dates
(2026-04-10/-21/-27). PMB-001's 2026-04-10 crossed the intel script's
90-day recency window on ~2026-07-09, so any CI run after that date
silently filtered the audit entry and reddened INV-016e. Generate the
fixture dates relative to today so they never drift again.

Pre-existing bug, unrelated to the design-contract-lens-sync feature this
branch implements; fixed here to keep the branch's CI green.
Add agents/design-contract-lenses.tsv as the single source of truth for the
eight PMB-derived Design Contract Checker lenses (DCL-001..008), expand
agents/review-spec-design-contract.md with a DCL-tagged, condition-bearing
bullet per lens, and bind registry<->agent by set-equality in
tests/test-design-contract-lens-sync.sh so a documented lens can never again
exist only as CLAUDE.md prose. This closes the DA-001/AP-036 gap where PMB-017's
authoring-affordance lens was documented but wired to neither the agent nor the
original seed.

Also add the /cpostmortem Step-3 convention note (a PMB documenting a new lens
must add a registry row), sync both distribution mirrors, add the registry path
and lens keywords to the typos ignore-list, and bump the test-file count to 112.
Document agents/design-contract-lenses.tsv as a new primary-SSOT abstraction:
the registry is the source of truth and the review-spec-design-contract agent
is derived from it via set-equality (opposite authority direction to the
ABS-047 sole-writer family, DD-005). Index line in .correctless/ARCHITECTURE.md,
full body in docs/architecture/abstractions.md (fragmented-doc layout).
Feature doc (docs/features/), AGENT_CONTEXT.md ABS-050 entry, workflow-history
and dev-journal entries, and the /cverify verification report.
@joshft
joshft merged commit 54787be into main Jul 11, 2026
6 checks passed
@joshft
joshft deleted the feature/design-contract-lens-sync branch July 11, 2026 03:41
joshft added a commit that referenced this pull request Jul 11, 2026
After PR #261 (design-contract-lens-sync) closed the DA-001 gap, capture the
generalized convention: a prose-documented enforcement addition to an agent must
ship with a structural SSOT registry + set-equality test in the same feature, or
it is AP-036 by construction (documented but never reaching the enforcer).
Human-approved post-merge.
joshft added a commit that referenced this pull request Jul 11, 2026
Minor release: /cchores protected-file affordance (#255), Design Contract
Checker lens registry (#261), sanctioned meta sole-writer (#246),
InstructionsLoaded/PAT-001 (#221), plus fixes for the affordance capability
probe (#264), audit-trail/workflow-gate repo attribution (#244, #243),
two ARG_MAX overflows (#212, #211), and the workflow-gate fail-open (#208).

Bumps .claude-plugin/marketplace.json plugins[0].version 3.1.1 -> 3.2.0 so
the plugin cache picks up the affordance and its capability-probe fix.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant