Skip to content

Marks the family-reference agent sections - #214

Merged
johnnyt merged 1 commit into
mainfrom
st-i0qa-family-reference-sections
Aug 22, 2026
Merged

Marks the family-reference agent sections#214
johnnyt merged 1 commit into
mainfrom
st-i0qa-family-reference-sections

Conversation

@johnnyt

@johnnyt johnnyt commented Aug 22, 2026

Copy link
Copy Markdown
Member

Why

This repo is the de-facto reference for the family's agent-facing conventions,
but that status was implicit and the copies drift. Beads in the five sibling
repos currently say some version of "copy statifier-ex's, adapted down", which
is only safe if what to copy - and what not to - is written down here rather
than inferred by whoever reads the file next.

What

Adds docs/family-reference.md and points CLAUDE.md at it from two places:
the paragraph that already describes the .claude/wurk/ extension contract,
and the read-before-deciding list.

The doc marks each agent-facing section copy-verbatim, adapt-per-repo,
or not reference, and says what an adopter must change:

  • Agent authority - adapt-per-repo, and the worked example of why the
    distinction matters. This repo's grant is standing; statifier_persistence,
    statifier_oban and opentelemetry_statifier hold a consent-scoped grant.
    Copying verbatim in either direction would silently change a repo's
    authority level. What is common is the structure: the per-action table, the
    anti-inference paragraph, the two override paragraphs, the reversibility
    principle, and the closing widening line.
  • Beads that span repositories - adapt-per-repo.
  • Non-interactive shell commands - copy-verbatim.
  • The ExQuality block and the deps/ex_quality/usage-rules.md pointer -
    copy-verbatim; statifier-ui's copy is byte-identical today and that is the
    correct state.
  • The .claude/wurk/ extension mechanism - adapt-per-repo. The contract
    is the reference; the per-repo count of override files is not, and should
    not be levelled up to match.
  • The custom gate stages - not reference. The gate guard, the ADR guard,
    the ADR judge, the regression ratchet, and mix gate.check with its guard
    ledger stay out of scope for copying, so the scaffolds' "deliberately
    smaller than statifier-ex's gate" comments stand unreversed.
  • mix gate.verify - the one exception, adopted by px-591, sui-4py,
    sp-7cu, sob-ehl and ots-4l6. It adds no stage to .quality.exs, so the
    smaller-gate statement stays true; it reads nothing but ex_quality's own
    report; and without it the wurk pipeline reports attested: false and the
    commit skill refuses, which is a broken unattended commit path. The doc
    records that it is being extracted upstream into ex_quality (st-wgr0), so
    adopters should expect to collapse their copies later.

Notes

  • Docs only. gate.rb reports the carve-out (applicable: false, nothing
    under lib/, test/, config/, mix.exs, mix.lock), but
    mix quality --profile merge was run unconditionally per
    .claude/wurk/mr.md and is green across every stage. The ADR judge skipped
    cleanly - no file in this diff is in a judged ADR scope.
  • No changelog fragment: agent-facing documentation is invisible to anyone
    using the public API.
  • The consent-scoped exemplar is cited as statifier_persistence's
    CLAUDE.md on main plus its request numbers, deliberately not as a commit
    SHA - two SHAs written down earlier in this standardization pass were
    orphaned by non-fast-forward merges.
  • Nothing in the doc changes this repo's authority table or its gate.

Closes st-i0qa

Records which of this repo's agent-facing sections the sibling repos
copy, and whether each is copy-verbatim or adapt-per-repo, so their
standardization beads can cite a written record instead of saying
"copy statifier-ex's, adapted down".

The custom gate stages - the gate guard, the ADR guard, the ADR judge,
the regression ratchet, and gate.check with its guard ledger - are
marked out of scope for copying, so the scaffolds' deliberately
smaller gates stand. mix gate.verify is the one exception, on the
user's 2026-08-22 ruling: it adds no stage to .quality.exs, and a repo
without it has a broken unattended commit path.

The authority section is the worked example of adapt-per-repo. This
repo's grant is standing, three siblings' are consent-scoped, and
copying either way would silently change a repo's authority level.

Refs: st-i0qa
@johnnyt
johnnyt merged commit bebe1d0 into main Aug 22, 2026
1 check passed
@johnnyt
johnnyt deleted the st-i0qa-family-reference-sections branch August 22, 2026 05:26
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