@tiphys/kernel 0.0.0 → 0.2.0

package/templates/work-history.example.yaml

@@ -0,0 +1,185 @@
+# Tiphys work history, worked example.
+#
+# FILLED WITH REAL CONTENT FROM THIS REPOSITORY (kernel plan M3, M3-P4 step 4):
+# this is M3-P4's own record, in the machine-readable form the contract
+# defines. The prose work history at delivery/work-history/m3-p4.md is the
+# same phase's record in the form this repository's own process uses; the two
+# are kept in step deliberately, because a template nobody fills is a template
+# nobody can tell has drifted.
+#
+# THE claims[], fix-round[] AND gate-evidence[] SECTIONS BELOW ARE THE REPORT
+# SCHEMA'S OWN DEFINITIONS, reached by $ref rather than restated, so the
+# honesty contract has one definition and not two that can drift.
+
+kind: work-history
+phase: M3-P4
+
+prompt: |
+  You are the IMPLEMENTER for M3-P4 in the Tiphys kernel repository. You do
+  not open pull requests and you do not merge. You implement, commit, push,
+  and hand back. Your full brief is at the dispatch brief path; read it FIRST
+  and follow it. It carries ten lessons M3-P3 paid ten rounds for, and they
+  are repeated there rather than left to CLAUDE.md because a brief that only
+  says "read CLAUDE.md" is how they get skipped.
+
+files-touched:
+  - schemas/report.schema.json
+  - schemas/final-report.schema.json
+  - schemas/work-history.schema.json
+  - templates/report.example.yaml
+  - templates/final-report.example.yaml
+  - templates/work-history.example.yaml
+  - templates/warnings.md
+  - test/report-contract.test.ts
+  - test/work-history.test.ts
+  - test/fixtures/wrapper-capture.counts.json
+  - test/fixtures/wrapper-capture.stdout.txt
+  - test/fixtures/wrapper-capture.invocation.json
+  - src/validate.ts
+  - src/checks.ts
+  - src/commands/validate.ts
+  - delivery/requirements/clause-map.json
+  - test/behaviors.json
+  - delivery/work-history/m3-p4.md
+
+per-step-commits:
+  - sha: "9fd800a"
+    subject: "M3-P4: open the work history beacon"
+  - sha: "b1ddc1b"
+    subject: "M3-P4: record the misplaced beacon commit, and the report schema first draft"
+
+key-decisions:
+  - decision: >-
+      Add a declared COMPANION_TABLE beside the type table and an optional
+      companions argument to compileSchema, rather than bundling the shared
+      definitions into the work-history document at load time.
+    why: >-
+      The plan requires the two schemas to resolve to the SAME definition
+      object rather than to two equal ones. Bundling would satisfy that by a
+      caching accident; a declared companion satisfies it because there is one
+      physical definition and the second document points at it. It also keeps
+      the property DR-0013 clause 4 protects: the set of documents a schema
+      may reach is declared in one auditable place and is never derived from
+      the reference itself.
+  - decision: >-
+      Record the pre-existing RangeError in collectUnits rather than fix it.
+    why: >-
+      Its red witness would have to live in test/checks.test.ts, which is not
+      on this phase's declaration, and a fix with no witness is the shape the
+      red-witness rule exists to forbid. It is re-measured at this head so the
+      record is a measurement rather than an inherited claim.
+  - decision: >-
+      Express the universal-quantifier rule as a two-branch oneOf rather than
+      the if/then the criterion's letter names.
+    why: >-
+      One object level carries one if/then, the finding object already spends
+      it on T-004's source-pinned coupling, and allOf is outside the declared
+      authoring vocabulary. Declared as a deviation rather than done quietly.
+
+verification-first:
+  - finding: >-
+      compileSchema builds a fresh Ajv per document and registers nothing
+      beside it, and makeAjv withholds loadSchema on purpose, so a $ref that
+      leaves the document fails compilation. Shipping the plan's cross-document
+      $ref without a change to the compile path would fail acceptance
+      criterion 1 on this phase's own example.
+    contradicts-plan: true
+    stopped-and-reported: >-
+      Reported in delivery/work-history/m3-p4.md as VF-1 before any schema was
+      authored, with the decision and its reasoning recorded above rather than
+      taken silently.
+  - finding: >-
+      The M2-P6 coverage checker exposes checkFindingOutcomeParity as a
+      function and its CLI accepts only --result, --evidence and --config, so
+      there is no flag that reaches finding-to-outcome parity mode.
+    contradicts-plan: false
+
+deviations:
+  - plan-clause: M3-P4 acceptance criterion 2(e)
+    why: >-
+      The criterion calls for an if/then over a pattern on the same object;
+      the object's one if/then slot is spent on T-004's coupling and allOf is
+      outside the declared authoring vocabulary, so the rule is a two-branch
+      oneOf. It remains Kind A and is witnessed by removing and restoring
+      oneOf.
+  - plan-clause: M3-P4 acceptance criterion 4
+    why: >-
+      The criterion says the M2-P6 coverage checker is RUN in
+      finding-to-outcome parity mode with an exit code on both arms. That mode
+      has no CLI flag and src/gates/coverage.ts is not on this phase's
+      declaration, so the registered test invokes the exported checker in a
+      subprocess. The checker itself is unmodified and the exit code is a real
+      process exit code.
+
+gate-evidence:
+  - gate: suite
+    result: green
+    wrapper-exit-code: 0
+    discovered: 507
+    passed: 505
+    failed: 0
+    skipped: 2
+    todo: 0
+    did-not-run: 0
+
+claims:
+  - id: W-1
+    kind: open-question
+    statement: >-
+      I did not find a way to express "this array is empty" in the declared
+      authoring vocabulary, so the rule that a report with no findings must
+      carry a no-findings-statement is not schema-enforced.
+
+  - id: W-2
+    kind: coverage
+    statement: >-
+      Registering report.schema.json as a companion is what makes the
+      work-history schema compile; without it the compilation fails closed.
+    settled-by:
+      executed-construction:
+        command: >-
+          node --input-type=module -e "import {compileSchema} from
+          './src/validate.ts'; import {readFileSync} from 'node:fs'; const s =
+          JSON.parse(readFileSync('schemas/work-history.schema.json','utf8'));
+          const r = compileSchema(s); console.log(r.ok ? 'compiled' : r.reason);"
+        exit-code: 0
+        output: |
+          INVALID # schema reference report.schema.json#/$defs/gateResult does not resolve
+
+fix-round:
+  - mechanism: >-
+      A schema document compiled without the sibling documents its references
+      reach, so a reference that leaves the document fails closed at
+      compilation rather than resolving.
+    derivation:
+      command: "grep -rn 'compileSchema(\\|validateInstance(\\|validateToLines(' src/ bin/ | grep -v '^src/validate.ts:'"
+      output: |
+        src/gates/run.ts:361:  const diagnostics = formatDiagnostics(validateInstance(schema, decoded.value));
+        src/gates/validate.ts:524:  return validateInstance(schema, instance) as Diagnostic[];
+        src/gates/validate.ts:528:export function validateToLines(
+        src/commands/mode.ts:125:  const lines = formatDiagnostics(validateInstance(loadTypeSchema(MODES_TYPE), read.raw));
+        src/commands/validate.ts:273:  const diagnostics = validateInstance(
+        src/commands/status.ts:127:  const diagnostics = validateInstance(loadTypeSchema("status-line"), record);
+    not-covered: >-
+      The search covered src/ and bin/ only. It did NOT cover test/, where the
+      same functions are reached through a computed dynamic import and a
+      literal grep would find the import rather than the call; it did not cover
+      scripts/, which reaches the validator only through src/gates/result.ts
+      and compiles no schema of its own; and it did not cover dist/, which is
+      generated and never committed.
+
+environment-warnings:
+  - warning: >-
+      A checkout whose node_modules predates M3-P3 fails npm run build at
+      build:runtime-deps, because commonmark is a dependency added by that
+      phase and the copy step reads its package.json directly.
+    evidence: >-
+      npm run build exited 1 with ENOENT on node_modules/commonmark/package.json;
+      npm ci then npm run build exited 0.
+  - warning: >-
+      This container's default toolchain is node v22.22.2, below the declared
+      engine floor, so EBADENGINE warnings appear on every npm operation and
+      two floor-gated tests skip.
+    evidence: >-
+      node --version printed v22.22.2 in the shell that ran the suite, and the
+      captured wrapper run reports 507 reported, 505 pass, 2 skipped.

package/tuition/README.md

@@ -0,0 +1,76 @@
+# tuition/
+
+The tuition feed: one document per failure mode a delivery paid for, and the
+mechanism index projected out of them.
+
+**`tuition/mechanism-index.yaml` is the index. Read it before you use a
+mechanism.** It is GENERATED by `tiphys tuition index` from the `mechanisms[]`
+field of the entries beside it, so a rule is recorded once, in the entry that
+paid for it. Do not edit it by hand; `tiphys tuition index --check` exits
+nonzero on any drift and names the mechanism and the entry it came from. It
+supersedes the interim markdown table this repository kept at its root until
+M3-P8, which was deleted rather than kept for reference, because two indexes is
+the state T-005 exists to prevent and a file kept for reference is a file
+someone will edit. Git history keeps it losslessly, and a verbatim capture of
+it lives at test/fixtures/mechanisms-interim.md:1 as the independent source a
+registered test uses to prove no row was dropped.
+
+## What is here
+
+| Path | What it is |
+|---|---|
+| `T-nnn.yaml` | one tuition entry, validated by `schemas/tuition.schema.json` |
+| `mechanism-index.yaml` | the generated projection, validated by `schemas/mechanism-index.schema.json` |
+
+Two layers, deliberately. The INDEX is the read layer: dense, consulted at
+every dispatch. The ENTRIES are the archive layer: longer, read when a rule is
+disputed.
+
+## The commands
+
+```
+tiphys validate --type tuition --context . tuition/T-005.yaml
+tiphys tuition add --file <entry>        # validate, then file it under its id
+tiphys tuition list [--kernel-relevant]  # id, date, target count
+tiphys tuition index [--check]           # regenerate, or fail on drift
+```
+
+`add` writes with an exclusive create, so an id already in the feed is a loud
+refusal rather than an overwrite. A `T-nnn` id is never renumbered and never
+reused after retirement, and this feed shares that one id space with the
+delivering project's own log.
+
+## Two rules that are not negotiable
+
+**A rule with no citation is not a rule.** Every `mechanisms[]` entry requires
+a non-empty `evidence[]`, and the schema rejects one without it. That is
+T-005's checkability rule as a validation failure rather than as advice.
+
+**An entry that claims kernel relevance and proposes no change to any kernel
+artifact is not tuition, it is an anecdote.** `kernel-relevant: true` requires
+at least one `structural-consequence`, each carrying the artifact it targets
+and whether the change is `proposed`, `applied` or `ticketed`.
+
+## R-070: a pipeline flaw is fixed immediately
+
+**When the flaw is in the DELIVERY PROCESS rather than in the product, the fix
+is a hotfix promoted to next in queue, not a backlog item.** A process defect
+keeps charging rent: every phase dispatched between discovering it and fixing
+it pays for it again, which is why deferring it is more expensive than it
+looks. File the tuition entry when you discover it, not at the end, and carry
+the fix in the same queue position as a production defect.
+
+The orchestrator's half of this rule (who promotes, and what happens to work
+already in flight) is stated in the orchestrator brief shipped by M3-P9, whose
+clause id is reserved here as `hotfix-promotion`. The checkable half that
+exists today is the retention check below.
+
+## R-098: the retention duty
+
+A project charter declares `retention` paths for its work histories, its
+evidence and its tuition. `tiphys doctor` reads them and reports `CHECK
+retention`: a declared path that is absent, or that is git-ignored in the fleet
+or the project repository, is a FAIL naming the path, because evidence that is
+ignored is evidence that will not survive the next clone. A fleet whose charter
+declares no retention at all is a WARN under the generic profile and a FAIL
+under `--for full`, never a silent pass.

package/tuition/T-001.yaml

@@ -0,0 +1,48 @@
+# T-001: cross-model review caught findings that survived three same-model
+# rounds. Promoted from the delivering project's own log by M3-P8; the
+# long-form account stays there.
+kind: tuition
+version: 1
+id: T-001
+project: tiphys-kernel
+date: 2026-08-04
+stage: planning, before any implementation dispatch
+kernel-relevant: true
+what-happened: >-
+  The kernel plan went through three adversarial review rounds plus one
+  targeted verification, all by the same model family, producing 28 applied
+  findings. An external review by a different model family then found two
+  genuine defects that had survived every internal round: lease renewal was
+  never required to fail after expiry, so an expired-but-alive holder racing a
+  legitimate takeover could produce dual mutation; and fleet initialization
+  assumed a configured git identity, which a clean cloud environment does not
+  have. A second data point arrived the same day, with decorrelation in place:
+  two clean-room reviews of one head, given deliberately different starting
+  questions, found different defects, and the hazard-framed one surfaced two
+  highs the criteria walk did not raise at all.
+lesson:
+  - >-
+      Same-family reviewers share blind spots, and the deterministic verifier
+      layer does not cover design-level races or environment assumptions at
+      planning time.
+  - >-
+      The narrower lesson is not "use two models". It is that two reviews with
+      different STARTING QUESTIONS find different things, and model diversity
+      makes that difference harder to collapse.
+structural-consequence:
+  - target: role-model-config.yaml
+    status: applied
+    change: >-
+      The role-to-model binding carries a review-model-family field, so which
+      family produced a review is configuration rather than a dispatch habit.
+  - target: checklists/clean-room.yaml
+    status: ticketed
+    change: >-
+      The review checklists must vary the ENTRY POINT rather than only the
+      reviewer, so the two contracts of a dual review start from different
+      questions by construction.
+    record: delivery/plan/kernel-plan-m3.md, M3-P7 step 3
+evidence:
+  - delivery/review/plan-review-r4-external.md, the external review with its verdict and findings
+  - delivery/review/plan-review-r1.md, delivery/review/plan-review-r2.md and delivery/review/plan-review-r3.md, the internal rounds that missed both defects
+  - delivery/review/clean-room-m1-p4.md and delivery/review/clean-room-m1-p4-second.md, the first dual review with two framings

package/tuition/T-002.yaml

@@ -0,0 +1,51 @@
+# T-002: agent death mid fix round, and salvage exercised for real. Promoted
+# from the delivering project's own log by M3-P8.
+kind: tuition
+version: 1
+id: T-002
+project: tiphys-kernel
+date: 2026-08-04
+stage: M1-P3 fix round (session lock and worktree pool)
+kernel-relevant: true
+what-happened: >-
+  An implementer hit a provider usage limit part way through a fix round and
+  stopped, leaving uncommitted work in its worktree and no turn-end record.
+  The stop was clean and quiet: nothing crashed, nothing timed out, and no exit
+  code said anything had gone wrong. The work was salvaged by hand into a
+  commit marked WIP-UNREVIEWED, which is the discipline the process document
+  mandates and which nothing in the system detects or performs.
+lesson:
+  - >-
+      Agent death from a provider limit is a distinct failure class from a crash
+      or a timeout, and it looks exactly like an ordinary completion to anything
+      keyed on process exit.
+  - >-
+      A missing turn-end record must never be read as success. Task open, no
+      turn-end, worktree dirty is the abandoned-task state and deserves its own
+      wake reason rather than being discovered later.
+  - >-
+      Salvage is currently manual. Detection belongs with the watcher and the
+      liveness guard, because a rule that depends on somebody noticing is the
+      thing that failed here.
+structural-consequence:
+  - target: src/teardown.ts
+    status: applied
+    change: >-
+      teardown --salvage commits a dirty worktree under a fixed
+      WIP-UNREVIEWED prefix, so the audit trail of a salvage is uniform rather
+      than per-incident.
+  - target: src/watcher.ts
+    status: applied
+    change: >-
+      The watcher treats an open task with no turn-end record as a wake
+      condition with its own reason line, so the human is told rather than
+      finding out afterwards.
+  - target: roles/implementer.md
+    status: applied
+    change: >-
+      The R-081b clause makes incremental, committed output an obligation of
+      the dispatched agent, so a death leaves a partial result rather than
+      nothing.
+evidence:
+  - delivery/work-history/m1-p3.md, fix-round section, with the measured salvage state
+  - delivery/intake/orchestrated-delivery-process.md section 6, the salvage discipline

package/tuition/T-003.yaml

@@ -0,0 +1,100 @@
+# T-003: a fix round for low-severity findings introduced two high-severity
+# defects. Promoted from the delivering project's own log by M3-P8.
+kind: tuition
+version: 1
+id: T-003
+project: tiphys-kernel
+date: 2026-08-04
+stage: M1-P3 (session lock and worktree pool), after clean-room APPROVE
+kernel-relevant: true
+what-happened: >-
+  A fix round addressing four LOW findings introduced two HIGH defects. One
+  gave a worktree destroy the authority to force-delete a branch, justified by
+  a component scheduled for a later phase that would refuse first. The other
+  narrowed a git contention matcher using hand-written example strings chosen
+  to match the new pattern, so real racing-git messages fell outside it. The
+  round's own tests were green and worthless for both: the destroy test
+  destroyed a branch still at its base commit, so no data could be lost, and
+  the concurrency test never advanced the upstream, so no ref transaction was
+  ever opened. The work history then stated as measured fact a universal claim
+  that concealed the second defect from the next reader.
+lesson:
+  - >-
+      A fix round is not lower risk than the work it fixes, and it receives less
+      scrutiny. The severity of the findings being fixed says nothing about the
+      severity of the defects the fixes can introduce.
+  - >-
+      Tests written alongside a fix test the fix, not the behaviour the fix
+      endangers. A test must be red against the DANGEROUS state, not merely
+      against the absence of the feature.
+  - >-
+      An unfalsified universal claim in a work history is worse than no claim:
+      the document whose purpose is to let a reviewer trust the round is what
+      hid the defect.
+mechanisms:
+  - mechanism: Lease compare-and-swap
+    rule: >-
+      Liveness is lease freshness, never pid, process probing or signals
+      (constraint C-2). Expiry does not block a release, but it DOES block a
+      renew and it DOES block teardown's holdership check, which fails closed.
+    siblings:
+      - src/lock.ts
+      - src/task.ts
+    evidence:
+      - src/lock.ts
+      - checkHoldership in src/task.ts
+      - CR-680 in delivery/review/clean-room-m1-p6-round3-hazard.md
+  - mechanism: Append-only log
+    rule: >-
+      Never read current state from the tail of a log (constraint C-1).
+      Currency comes from `meta.json` and turn-end files only.
+    siblings:
+      - src/task.ts
+    evidence:
+      - plan v1 section 3, C-1 (FM-052)
+  - mechanism: Worktree removal and force branch delete
+    rule: >-
+      Resolve, evaluate, then apply. No policy decision may be taken after a
+      destructive action has begun, and destructive authority is never
+      inherited from a component that does not exist yet.
+    siblings:
+      - src/pool.ts
+      - src/teardown.ts
+    machine-readable-form:
+      path: gates.manifest.json
+      key: destructiveCommands
+    evidence:
+      - delivery/review/verification-m1-p3-fix-round.md V-1 and V-3
+  - mechanism: Classifying another program's errors
+    rule: >-
+      Derive the signature from REAL captured output under forced conditions,
+      never from hand-written examples chosen to match the implementation. 312
+      captured contention failures, every one of the dropped shape.
+    siblings:
+      - src/pool.ts
+    evidence:
+      - V-2 in delivery/review/verification-m1-p3-fix-round.md
+      - CLAUDE.md environment warning 10
+structural-consequence:
+  - target: assurance-modes.yaml
+    status: applied
+    change: >-
+      Full mode carries a fix-round-verification stage, so an independent
+      verification of a fix round is a declared pipeline stage rather than
+      orchestrator discretion.
+  - target: schemas/report.schema.json
+    status: applied
+    change: >-
+      The shared claims[] contract makes a universal claim carry the executed
+      construction that could have falsified it, or be restated as an open
+      question.
+  - target: gates.manifest.json
+    status: applied
+    change: >-
+      The destructiveCommands list names every command that can destroy work,
+      which is the machine-readable view of this entry's destructive-operation
+      rule and the list the derived-class rule consumes.
+evidence:
+  - delivery/review/verification-m1-p3-fix-round.md, findings V-1 and V-2 with the unrefuted candidates
+  - delivery/review/clean-room-m1-p3.md, the APPROVE and the four LOW findings that triggered the round
+  - delivery/work-history/m1-p3.md, the round's own record including the claim named above

package/tuition/T-004.yaml

@@ -0,0 +1,52 @@
+# T-004: verification lenses sharing one worktree can manufacture a phantom
+# defect. Promoted from the delivering project's own log by M3-P8.
+kind: tuition
+version: 1
+id: T-004
+project: tiphys-kernel
+date: 2026-08-04
+stage: M1-P3 verification and the investigation that followed it
+kernel-relevant: true
+what-happened: >-
+  Two verification lenses ran against the same worktree. One was running a
+  disciplined sabotage window (copy, mutate, measure, restore) while the other
+  ran tests. The second lens observed a failure that came from the first lens's
+  mutation and reported it as a defect. By the time anyone inspected the tree it
+  was byte-clean, so the evidence of contamination was gone while the finding
+  survived, and closing it took two multi-hour investigations.
+lesson:
+  - >-
+      Shared mutable ground turns one lens's experiment into another lens's
+      discovery, and the contamination erases itself while the finding remains.
+  - >-
+      The dispatch instruction was the defect. The briefs PERMITTED isolation
+      rather than REQUIRING it, and permitting is not requiring.
+  - >-
+      A test run is only evidence if you can prove what it ran. A run that
+      cannot name what it executed is an anecdote.
+mechanisms:
+  - mechanism: Shared worktree
+    rule: >-
+      A verification lens works in its OWN clone, never in a tree another agent
+      is editing, and a run that cannot pin the source it ran against is not
+      evidence and must label itself so.
+    siblings:
+      - src/pool.ts
+    evidence:
+      - delivery/verification/u2-race-flake-investigation.md, the U-2 phantom and the four hypotheses each run in a private clone
+      - delivery/review/verification-m1-p3-fix-round.md, the round whose lenses shared a tree
+structural-consequence:
+  - target: schemas/report.schema.json
+    status: applied
+    change: >-
+      A report declares the source it ran against, so a finding produced by a
+      run that cannot pin its source is labelled unpinned rather than inherited
+      as fact.
+  - target: roles/investigator.md
+    status: applied
+    change: >-
+      The investigator brief requires a private clone and a reproduction, so
+      isolation is a role obligation rather than a dispatch-time permission.
+evidence:
+  - delivery/verification/u2-race-flake-investigation.md, the whole investigation
+  - delivery/review/verification-m1-p3-fix-round.md, the run that produced the phantom

package/tuition/T-005.yaml

@@ -0,0 +1,72 @@
+# T-005: a lesson the codebase had already paid for did not reach the next
+# phase that needed it. Promoted from the delivering project's own log by
+# M3-P8; the long-form account stays there.
+kind: tuition
+version: 1
+id: T-005
+project: tiphys-kernel
+date: 2026-08-05
+stage: M1-P5 (watcher and liveness guard), first dual review
+kernel-relevant: true
+what-happened: >-
+  M1-P3 established, in a multi-hour investigation, that a claim file which
+  cannot be taken must fail loudly and name the stuck file. Two phases later
+  M1-P5 implemented the same claim-file pattern for the watcher's seen state
+  and absorbed the timeout silently. A stranded claim file then made every
+  subsequent watcher pass report that there was nothing to surface, for a
+  genuinely pending signal, while the beacon kept advancing so the liveness
+  guard reported the fleet healthy throughout. It was the most severe defect
+  found in M1. The implementer had read the plan, the agent-rules file, the
+  constraint list, the environment warnings and three prior work histories,
+  and none of them carried the rule: it lived in the M1-P3 source and in an
+  investigation report filed under the mystery it solved rather than under the
+  mechanism it constrained.
+lesson:
+  - >-
+      A lesson attached to a component does not travel to the next component
+      that needs it. Documents organised by phase, by incident or by environment
+      each fail this for their own reason, and none of them is carelessness.
+  - >-
+      The missing artifact is an index from MECHANISM to RULE, so an implementer
+      reaching for a claim file, a lease, an append-only log or a destructive
+      git operation can ask what the project already learned and get an answer.
+  - >-
+      That index is a PROJECTION of the tuition feed rather than a second thing
+      to maintain, because two copies of a rule is the state that produced this
+      defect in the first place.
+mechanisms:
+  - mechanism: Claim file (mutual exclusion by O_EXCL)
+    rule: >-
+      A claim that cannot be taken must fail LOUDLY and name the stuck file. A
+      silent timeout is indistinguishable from an absence of contention. There
+      are now THREE claim-file users (the lock, the watcher seen-state, and
+      M2-P1's evidence-directory run claim); the next one reads `src/lock.ts`
+      first, and the M2-P1 instance is the worked example of doing that and
+      stating the one difference (no expiry, because an evidence directory must
+      not have a lease that lapses).
+    siblings:
+      - src/lock.ts
+      - src/watch.ts
+      - src/gates/run.ts
+    evidence:
+      - delivery/verification/u2-race-flake-investigation.md D-3
+      - delivery/tuition/T-005, the silent reimplementation two phases later that became M1's most severe defect
+structural-consequence:
+  - target: tuition/mechanism-index.yaml
+    status: applied
+    change: >-
+      The mechanism index exists and is generated by `tiphys tuition index` as
+      a projection of every tuition entry's mechanisms[] field, so a rule is
+      recorded once and read from one place.
+  - target: roles/implementer.md
+    status: applied
+    change: >-
+      The mandated reading list names the mechanism index, and the
+      `mechanism-lookup` and `mechanism-sibling` clauses require an implementer
+      to look up every mechanism it is about to use and to record the siblings
+      when it establishes a rule.
+evidence:
+  - delivery/verification/u2-race-flake-investigation.md, defect D-3 and the structural-fix section
+  - delivery/review/clean-room-m1-p5-second.md, finding 1, with the reproduction
+  - delivery/work-history/m1-p5.md, fix-round section
+  - delivery/intake/orchestrated-delivery-v1.md section 9, the tuition flow

package/tuition/T-006.yaml

@@ -0,0 +1,81 @@
+# T-006: claimed impossibilities and claimed safety nets, written without
+# execution. Promoted from the delivering project's own log by M3-P8.
+kind: tuition
+version: 1
+id: T-006
+project: tiphys-kernel
+date: 2026-08-05
+stage: M1-P5 (watcher and liveness guard), across its fix rounds
+kernel-relevant: true
+what-happened: >-
+  Three times in one phase, a work history stated something about the world
+  that had never been executed: an arm that "cannot be forced", a case another
+  guard "already catches", a path that "recovers anyway". Each was written by an
+  implementer who had done real work, and each survived into a document a
+  reviewer was expected to trust. The orchestrator then did the same thing the
+  same day, reporting a remote as unreachable on the strength of a read
+  operation that says nothing about write access.
+lesson:
+  - >-
+      An impossibility claim, a coverage claim or a remedy claim must carry the
+      executed construction, or be restated as an open question.
+  - >-
+      The honest restatement costs nothing and is more useful: "I did not find a
+      way to force this arm" is true and invites the next reader to try, where
+      "this arm cannot be forced here" is false and closes the question.
+  - >-
+      A reminder does not survive a busy session. The mechanism is a grep over
+      the work history before it is submitted.
+mechanisms:
+  - mechanism: Reading a path whose type is not established
+    rule: >-
+      lstat the link, stat what it resolves to, open ONLY a regular file. A
+      block is not an exception, so try/catch does not touch it.
+    siblings:
+      - src/task.ts
+      - src/lock.ts
+      - src/pool.ts
+      - src/brief.ts
+      - src/hooks.ts
+    evidence:
+      - CR-520 and the four M1-P5 rounds
+      - delivery/verification/cr-520-orchestrator-reproduction.md
+  - mechanism: Atomic file replacement
+    rule: >-
+      Stage under a name no other pass can collide with. A fixed
+      `${path}.stage` lets two concurrent passes share one temporary; the loser
+      dies on ENOENT after advancing its seen state, dropping a signal in a
+      protocol whose rule is duplicate-rather-than-drop.
+    siblings:
+      - src/lock.ts
+      - src/watch.ts
+    evidence:
+      - M1-P5 round 4, verified pre-existing against a pristine build
+  - mechanism: Verifying access to a remote
+    rule: >-
+      `git push --dry-run` authenticates against receive-pack and updates no
+      ref. `clone` and `ls-remote` are READ operations and witness nothing
+      about write access.
+    evidence:
+      - delivery/tuition/T-006-unexecuted-claims-about-the-world.md, the orchestrator's own instance
+structural-consequence:
+  - target: schemas/work-history.schema.json
+    status: applied
+    change: >-
+      The shared claims[] section requires an executed construction beside any
+      impossibility, coverage or remedy claim, so the claim and its settlement
+      travel together.
+  - target: schemas/report.schema.json
+    status: applied
+    change: >-
+      The same claims[] definition is shared by the report contract, so a
+      review making an unexecuted claim is subject to the same rule as the work
+      it reviews.
+  - target: roles/implementer.md
+    status: applied
+    change: >-
+      The claim-grep clause carries the grep command verbatim, so hunting these
+      claims is a command rather than a habit.
+evidence:
+  - delivery/work-history/m1-p5.md, the three claims and their fix rounds
+  - delivery/review/clean-room-m1-p5-round4-hazard.md, the review that named the pattern