Skip to content

docs: FAMILY.md v2 — member classes, and clause 7 stated per class - #83

Merged
chaoz23 merged 1 commit into
mainfrom
family/contract-v2
Aug 20, 2026
Merged

chaoz23 merged 1 commit into
mainfrom
family/contract-v2

Conversation

@chaoz23

@chaoz23 chaoz23 commented Aug 19, 2026

Copy link
Copy Markdown
Owner

Resolves #80. This is a contract decision, so it is a PR rather than a push — the call is reviewable before it binds anything.

The problem

FAMILY.md v1 opened by saying it "describes the contract the family already implements." The audit found that false of clause 7: 2 of 4 D&D members ship no --pipe, and 1 ships no MCP server. The family's canonical contract overstated its own conformance — the same doc-truth defect these tools exist to catch, in the document that defines them.

The decision

The obvious fixes were both wrong. Marking clause 7 aspirational gives up on surfaces that genuinely should exist. Doing all the work means building --pipe and an MCP server for table-kit, which is transport plus a session ledger — --pipe is one-query-in / one-verdict-out, and that shape has no honest meaning for a thing that records a session. You'd get a surface built to satisfy a table.

So v2 states clause 7 per member class:

Surface verdict transport adjacent
SKILL.md, tool.json, llms.txt, --schema flag ✅ ✅ ✅
--pipe ✅ — —
MCP server ✅ — —
  • verdict — srdcheck, charactercheck, dmcheck. Every clause.
  • transport — table-kit. Clauses 1 and 3 bind it where it emits a verdict (its own coverage/QC), not elsewhere.
  • adjacent — inkcheck, loudcheck. Clauses 2–6, different domains, outside the D&D choreography and the honest lane.

That last class replaces v1's "recorded divergence" language. inkcheck and loudcheck were never breaking a rule — they were never in its scope, and describing them as an exception was the contract being imprecise about its own boundary.

What this does to the open issues

issue disposition
chaoz23/dmcheck#14 — no --pipe stays open — dmcheck is a verdict tool, the clause binds
chaoz23/table-kit#23 — --schema is a subcommand stays open — binds every class, and it's a small alias
chaoz23/table-kit#21 — no --pipe close as won't-fix if this merges
chaoz23/table-kit#22 — no MCP server close as won't-fix if this merges

I have not closed anything. If you'd rather table-kit ship both surfaces anyway, reject this PR and all four stay as work.

Also corrected in v2

  • Clause 1's honest lane was narrower than its own reference implementation. v1 said "outside the tool's codified jurisdiction"; srdcheck's refusal contract 1.1 also covers cannot answer from the evidence available (incomplete coverage), which is exactly what table-kit's qc/report exit-2 lane does too. Widened to match reality.
  • Usage errors must not share the honest lane's exit code, stated explicitly, with srdcheck's exit 3 as the precedent. This is the rule behind [DMC-010] Exit 2 is overloaded between the honest lane and argparse usage errors dmcheck#15 and the HONEST_LANE_OVERLOAD check.
  • Clause 7 gains a truth obligation for SKILL.md. Its acceptance test — "a fresh-context agent, given only this file, can produce a well-formed invocation" — checks invocability, and every member passed it while misstating its own exit contract. Claims must now be executable and executed, by scripts/family_conformance.py (feat: add a family conformance gate that executes documented exit contracts #82, merged).
  • The two open clause-7 gaps are named inline, so the document can't drift back into claiming a conformance it doesn't have.

Per clause 7's own versioning rule, this is a heading bump (v1 → v2) with a changelog entry.

🤖 Generated with Claude Code

v1 opened by claiming it "describes the contract the family already
implements". That was false of clause 7: two of four D&D members shipped no
--pipe and one shipped no MCP server. v2 fixes the claim rather than quietly
restating it.

The substantive change is member classes. Clause 7 bound every member to the
same six surfaces, which is wrong in a specific way: --pipe is
one-query-in/one-verdict-out, and table-kit is transport plus a session
ledger, so that shape has no honest meaning there. Same for an MCP server.
Requiring them anyway produces surfaces that exist to satisfy a table.

  verdict    (srdcheck, charactercheck, dmcheck)  every clause
  transport  (table-kit)                          clauses 1 and 3 only where
                                                  it emits a verdict; clause 7
                                                  minus --pipe and MCP
  adjacent   (inkcheck, loudcheck)                clauses 2-6; different
                                                  domains, outside the D&D
                                                  choreography and the honest
                                                  lane

That last class replaces v1's recorded exit-2 divergence. Those two tools were
not breaking a rule; they were never in its scope.

Also in v2:

- Clause 1's honest lane now includes "cannot answer from the evidence
  available" (incomplete coverage), which is what the reference implementation
  already does via refusal contract 1.1. v1's definition was narrower than its
  own reference.
- Clause 1 states explicitly that usage errors must not share the honest
  lane's exit code, with srdcheck's exit 3 as the precedent.
- Clause 7 adds the SKILL.md truth obligation. Its acceptance test checks
  invocability, and every member passed it while misstating its own exit
  contract, so the claims must now be executable and executed by
  scripts/family_conformance.py.
- The two open clause-7 gaps are named inline rather than left implied.

Closes #80

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.

FAMILY.md claims to describe what the family implements, but clause 7 is unimplemented

1 participant