Skip to content

Mechanically reconcile designated primitive projections #2

Description

@raylei50653

Status

Design / intent only. This issue declares a decision object and its boundary. It does
not authorize an implementation PR, and it explicitly does not decide whether the resulting
check becomes blocking CI.

Motivating evidence

Review of 93b9729 (PR #1)
found four hand-written surfaces that had drifted from the primitives they summarize, on
a repository whose subject is that summaries drift:

# surface drift
1 MODEL.md §2 still stated the pre-two-mode identity rule — claims required pre-first-byte, reconstruction described as simply not a binding
2 docs/primitives/02-identity.md carried a superseded status note ("ADR 021 is proposed; that the fix landed is not claimed") after docs/evolution/ had already been corrected
3 README.md + docs/primitives/README.md claimed four of five primitives were transcriptions and only 05 went beyond the lab; 01 does too, and says so on its own page
4 the PR body still described docs/evolution/retracted/ after the branch had moved to failures/

The one mechanically checked invariant did not drift. check_mainline_concurrency.py
has been correct on every commit since it was written.

All four were found by human review. That is the measure of how much of this model is
currently mechanical, and it is the reason to file this rather than to assume the discipline
holds.

Honest scope of the fix

Of the four, this proposal would have caught 2 — items 1 and 3, which are designated
projections of a primitive's invariant. Item 2 is a stale status claim inside a primitive
body, and item 4 lives on GitHub, not in the tree. Neither is in scope, and widening the
proposal to cover them is how it becomes a governance suite.

Decision object

Which model projections are worth mechanical reconciliation, and against which owner?

Distinct from PR #1's decision object (template → reference model repositioning), which is
closed. This one is admissible but was deliberately not folded into the PR that discovered
it — next admissible unit ≠ next task
(primitive 04).

Proposed shape

Owner. A primitive's invariant is owned by its own file, in a fixed form:

> **Invariant.**

No separate YAML or JSON truth file. Introducing one to prevent
primitive → MODEL → README drift would produce YAML → primitive → MODEL → README
one more owner than the problem had.

Designated projections. Exactly three, each carrying an explicit machine-readable marker:

docs/primitives/<NN>-*.md      ← canonical owner
        ↓
MODEL.md
docs/primitives/README.md
README.md

Acceptance

A primitive invariant has one owner in docs/primitives/<NN>.md. Every designated
projection must either match that invariant or explicitly stop projecting it.

The check protects projection equality, not markdown style. A projection that drops a
primitive entirely is a legal outcome; a projection that silently states a different
invariant is not.

Non-goals

✗  evolution narrative reconciliation
✗  failure status reconciliation
✗  link checking or provenance-grade checking
✗  reference-realization/ checking (frozen exhibit — never checked)
✗  arbitrary prose or style linting
✗  any blocking-CI decision — not settled by this issue

Blocking CI is a separate question

mechanizable ≠ should block development
(primitive 04).

The check ships as an executable check first. It earns blocking status only after it shows:

  • low false-positive rate,
  • a stable projection surface,
  • direct failure recovery (the fix is obvious from the message),
  • and no drift into answering questions outside its own scope — the failure mode recorded in
    failures/03
    and saccade#334.

Not authorized by this issue

  • Implementing the checker.
  • Adding it to any hook or CI workflow.
  • Adding markers to the designated projections.
  • Any change under reference-realization/.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TLxS1LJjyJiivQKNhCR5xe

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions