@tiphys/kernel 0.0.0 → 0.2.0

package/tuition/T-007.yaml

@@ -0,0 +1,56 @@
+# T-007: a phase met fifteen of fifteen executed acceptance criteria and still
+# live-locked every supervision command. Promoted by M3-P8.
+kind: tuition
+version: 1
+id: T-007
+project: tiphys-kernel
+date: 2026-08-05
+stage: M1-P5 (watcher and liveness guard), third dual review
+kernel-relevant: true
+what-happened: >-
+  Every one of a phase's fifteen acceptance criteria was walked and met, and the
+  delivered component still blocked forever on a named pipe at a path it read,
+  taking every supervision command with it. Two reviews ran on one head: the
+  criteria walk approved, and the hazard-framed review, given the question "what
+  can block, what can be lost, what can never exit", found the defect. The two
+  agreed on every mechanical fact; they disagreed on the verdict because they
+  were asking different questions.
+lesson:
+  - >-
+      Acceptance criteria inherit the blind spots of whoever wrote them, so a
+      criteria walk cannot find a defect the criteria could not express. "All
+      criteria met" is one input, never a terminal green.
+  - >-
+      A code phase needs two review CONTRACTS, not two reviewers, and the second
+      one must be a declared artifact rather than something the dispatch prompt
+      is trusted to remember.
+  - >-
+      The hazard question is derivable from the component's nature, which means
+      it belongs in the plan rather than in a prompt.
+structural-consequence:
+  - target: schemas/plan.schema.json
+    status: applied
+    change: >-
+      A phase declares its hazard-classes[] beside its acceptance criteria, so
+      the second review contract is derived from the plan rather than improvised
+      per dispatch.
+  - target: assurance-modes.yaml
+    status: applied
+    change: >-
+      review-contracts[] are declared per mode, so a mode says how many
+      contracts a review round carries and what each one asks.
+  - target: roles/clean-room-reviewer.md
+    status: applied
+    change: >-
+      The brief carries a review-contract field, so a reviewer knows which
+      contract it is executing and a hazard contract cannot be silently
+      dropped.
+  - target: checklists/hazard-review.yaml
+    status: ticketed
+    change: >-
+      The hazard contract gets its own checklist, so the second contract has
+      probes rather than only a framing.
+    record: delivery/plan/kernel-plan-m3.md, M3-P7
+evidence:
+  - delivery/review/clean-room-m1-p5-third-hazard.md and delivery/review/clean-room-m1-p5-third-criteria.md, the two verdicts on one head
+  - delivery/review/arbitration-m1-p5-third-round.md, the arbitration

package/tuition/T-008.yaml

@@ -0,0 +1,111 @@
+# T-008: the orchestrator supervised two agents with no beacon and no guard,
+# and lost nine hours. Promoted by M3-P8.
+kind: tuition
+version: 1
+id: T-008
+project: tiphys-kernel
+date: 2026-08-06
+stage: M1-P6, fifth review pass
+kernel-relevant: true
+what-happened: >-
+  Two review agents died within minutes of dispatch and the orchestrator did not
+  notice for nine hours and eleven minutes, while answering the owner and
+  dispatching other work throughout. Its supervision was "wait for a completion
+  notification", which is process liveness: a dead process sends no
+  notification, and no notification is indistinguishable from work in progress.
+  The first watchdog written after the incident then tested whether the report
+  file EXISTED, so it fired two minutes in, reported success, and said nothing.
+lesson:
+  - >-
+      Supervision is a freshness watchdog armed in the same turn as the
+      dispatch, never a wait for a completion notification.
+  - >-
+      Every dispatched agent writes its output incrementally, so its artifact's
+      mtime is a beacon and a death leaves a salvageable partial result.
+  - >-
+      A guard whose condition does not test the property that matters is green
+      and worthless, which is the red-witness rule one level up.
+mechanisms:
+  - mechanism: Supervising a dispatched agent
+    rule: >-
+      Supervision is a FRESHNESS watchdog armed in the same turn as the
+      dispatch, never a wait for a completion notification and never a probe of
+      process liveness (constraint C-2). The watchdog must test freshness, never
+      existence and never completion, must watch the union of the paths the
+      agent actually writes (measured, not predicted), and must exclude the
+      supervisor's own trees, because a watchdog that cannot go red is worse
+      than none.
+    siblings:
+      - src/watcher.ts
+      - src/liveness.ts
+    evidence:
+      - delivery/tuition/T-008-the-orchestrator-had-no-beacon.md, nine hours and eleven minutes measured
+      - delivery/tuition/T-014-the-watchdog-watched-the-wrong-place-six-times.md, six wrong applications of the same rule in one session
+  - mechanism: Parsing another program's reporter output
+    rule: >-
+      PIN the format as a controlled input rather than widening the parse. A
+      format-agnostic regex is a union of formats known on the day, and the
+      default already differs between the two toolchains this project runs.
+    siblings:
+      - src/gates/suite.ts
+    evidence:
+      - M1-P6 floor defect
+      - "`NODE_OPTIONS=--test-reporter=tap` scoped to the child"
+  - mechanism: Deciding what another program will do by pattern-matching the text of a file it consumes
+    rule: >-
+      A regex over a file and the consuming program's evaluation of that file
+      are DIFFERENT FUNCTIONS, so every finding is another input where they
+      differ, and rounds close instances forever. Three tiers instead, each
+      labelled by what enforces it: execute the extractable part against stubs;
+      PIN the accepted shapes and fail closed on anything else, never widen the
+      pattern; and where a denylist is unavoidable, DERIVE it by walking the
+      consuming program's closed documented vocabulary once, publishing the
+      walk. Name what remains unguarded rather than chasing it.
+    siblings:
+      - test/exit-test-local.test.ts
+      - test/m2-exit-test.test.ts
+    evidence:
+      - Four M1-P6 rounds, CR-640, CR-661, CR-681, CR-720 to CR-725
+      - the derived walk found two members no reviewer had named (`working-directory`, a custom `shell` template)
+      - "the widen-the-regex approach produced a guard that both missed real defangs and rejected `needs: [test, lint]`, an edit that STRENGTHENS the guarded property"
+  - mechanism: Asserting a CI step is wired
+    rule: >-
+      Assert BEHAVIOUR, not text. A text assertion catches deletion and misses
+      defanging. Extract the step and execute it against stubs. A witness for a
+      class must redden under at least two structurally different members.
+    siblings:
+      - test/exit-test-local.test.ts
+      - test/m2-exit-test.test.ts
+      - test/implementer-brief.test.ts
+    evidence:
+      - CR-640, CR-661, CR-681
+      - delivery/verification/cr-661-orchestrator-reproduction.md
+  - mechanism: A guard's own failure path
+    rule: >-
+      A guard whose correctness depends on a crash is not a guard. Make the
+      success path total, so removing the explicit failure is visible.
+    siblings:
+      - test/exit-test-local.test.ts
+    evidence:
+      - M1-P6 fix round 2, the D3 defang the implementer caught in its own fix
+structural-consequence:
+  - target: roles/implementer.md
+    status: applied
+    change: >-
+      The incremental-output and beacon-is-not-a-claim clauses make the beacon
+      an obligation of the dispatched agent and forbid reading its existence as
+      progress.
+  - target: roles/clean-room-reviewer.md
+    status: applied
+    change: >-
+      The same two clauses bind review agents, which is the half of the dispatch
+      contract this incident actually needed.
+  - target: AGENTS.md
+    status: ticketed
+    change: >-
+      The orchestrator's supervision section states the watchdog rule and the
+      three questions a dispatch turn answers in writing before arming one.
+    record: delivery/plan/kernel-plan-m3.md, M3-P9
+evidence:
+  - delivery/tuition/T-008-the-orchestrator-had-no-beacon.md, the measured nine hours and eleven minutes
+  - delivery/work-history/m1-p6.md, the phase running while the two agents were dead

package/tuition/T-009.yaml

@@ -0,0 +1,50 @@
+# T-009: main was red for four hours and twenty-one minutes while every pull
+# request check was green. Promoted by M3-P8.
+kind: tuition
+version: 1
+id: T-009
+project: tiphys-kernel
+date: 2026-08-07
+stage: M2 tail
+kernel-relevant: true
+what-happened: >-
+  The CI workflow fires on two events and they run different bundles: the pull
+  request event runs the strong bundle with a phase id derived from the head
+  ref, and a push to the default branch runs a main bundle with no phase. A
+  defect on the arm only one event takes was invisible to the other, so the
+  default branch stayed red across five consecutive push runs while every pull
+  request check was green, and four more merges landed on it. The owner
+  surfaced it, not the process.
+lesson:
+  - >-
+      A gate result is evidence only for the configuration it ran under. "CI is
+      green" is never a complete sentence: the complete sentence names the event
+      and the head sha.
+  - >-
+      A merge is not complete until the post-merge run on the new head is
+      observed to completion. Not the check on the branch: the run whose head
+      sha is the new tip.
+  - >-
+      Where behaviour forks on the CI event, BOTH arms need a witness. One
+      witnessed arm and one unwitnessed arm is the exact shape that broke here,
+      and the unwitnessed one is the one that broke.
+structural-consequence:
+  - target: schemas/report.schema.json
+    status: applied
+    change: >-
+      A reported gate result carries the event and the head it ran under, so a
+      green cannot be quoted outside the configuration that produced it.
+  - target: gate-registry.yaml
+    status: applied
+    change: >-
+      Every gate declares the CI events it runs on, so the two arms are data a
+      reader can compare rather than a property of a workflow file.
+  - target: AGENTS.md
+    status: ticketed
+    change: >-
+      The orchestrator's merge duty includes observing the post-merge run on the
+      new head before the phase is closed.
+    record: delivery/plan/kernel-plan-m3.md, M3-P9
+evidence:
+  - delivery/tuition/T-009-green-on-the-wrong-event.md, the five red push runs and the four merges
+  - delivery/work-history/m2-p9.md, the exit-test harness the incident ran through

package/tuition/T-015.yaml

@@ -0,0 +1,36 @@
+# T-015: a citation into a newest-at-top file rots on every append. Promoted
+# by M3-P8.
+kind: tuition
+version: 1
+id: T-015
+project: tiphys-kernel
+date: 2026-08-12
+stage: orchestrator paperwork, across one branch
+kernel-relevant: true
+what-happened: >-
+  A document that grows at the TOP moves every line below the insertion point.
+  A citation of the form path:line into such a file is therefore correct when
+  written and wrong after the next append, and it fails silently: the line still
+  exists, so the citation resolves, and it now points at something else. Four
+  instances were found in one branch, every one of them by re-running the check
+  after the final edit rather than by reading.
+lesson:
+  - >-
+      A positional citation into an append-at-top document decays on every
+      append, and the decayed form RESOLVES, so nothing reddens.
+  - >-
+      Prefer citing something that does not move, and where the positional
+      citation is the right one anyway, resolve it after the final edit and not
+      before.
+  - >-
+      The check that catches this is a re-run, not a reading.
+structural-consequence:
+  - target: gate-registry.yaml
+    status: proposed
+    change: >-
+      The citations gate's document globs reach only the delivery tree today.
+      Extending them to root-level authored files would put this region under
+      the same check as everything else; the change belongs to the phase that
+      owns the registry rather than to this record.
+evidence:
+  - delivery/tuition/T-015-a-citation-into-a-newest-at-top-file-rots-on-every-append.md, the four instances and the measurement

package/tuition/T-016.yaml

@@ -0,0 +1,36 @@
+# T-016: an acknowledged alarm says nothing new when the state actually
+# changes. Promoted by M3-P8.
+kind: tuition
+version: 1
+id: T-016
+project: tiphys-kernel
+date: 2026-08-12
+stage: orchestrator supervision, one session
+kernel-relevant: true
+what-happened: >-
+  A staleness alarm fired, was checked, and was correctly judged a false
+  positive against a live agent. The alarm kept reporting the same condition in
+  the same words afterwards, so when the underlying state actually changed there
+  was nothing new to notice: the message for "still quiet and known healthy" and
+  the message for "was alive when last checked, is not now" were identical. An
+  acknowledged alarm that repeats itself is a silence with extra steps.
+lesson:
+  - >-
+      A guard should report a TRANSITION, not a level. Only the transition is
+      worth waking someone for.
+  - >-
+      An acknowledged alarm should be latched with the state it was acknowledged
+      AT, and re-fire when the state CHANGES from that, in different words.
+  - >-
+      The liveness signal has to be part of the guard rather than a separate
+      manual step, because a guard that cannot see what the operator saw cannot
+      tell the two states apart.
+structural-consequence:
+  - target: src/liveness.ts
+    status: proposed
+    change: >-
+      The guard's verdict should carry the transition rather than the level, and
+      an acknowledged verdict should be latched at the state it was acknowledged
+      at, so the next report differs when the state does.
+evidence:
+  - delivery/tuition/T-016-an-acknowledged-alarm-says-nothing-new-when-the-state-changes.md, the session it was measured in

package/tuition/T-017.yaml

@@ -0,0 +1,46 @@
+# T-017: the beacon instruction asks for a habit, and habits do not survive a
+# working agent. Promoted by M3-P8.
+kind: tuition
+version: 1
+id: T-017
+project: tiphys-kernel
+date: 2026-08-12
+stage: dispatch contract, four instances in one session
+kernel-relevant: true
+what-happened: >-
+  The dispatch contract tells every agent to create its work history early and
+  append as it works, because the file's mtime is the beacon its supervisor
+  watches. Four times in one session an agent working hard went quiet for long
+  enough to read as possibly dead, twice with the same number of minutes, because
+  "append as you work" names no moment at which to append. A second, sharper
+  instance came from fusing two acts in one instruction: an agent told to commit
+  and push on every append pushed six times, cancelling five in-flight CI runs
+  and leaving the critical-path branch with no completed evidence for two hours.
+lesson:
+  - >-
+      An instruction that asks for a habit names no moment. A per-action trigger
+      ("append after each command whose output you will cite, before running the
+      next one") names one, which is a fact about the two texts rather than a
+      prediction that rewording will hold.
+  - >-
+      Committing locally satisfies durability; pushing is a separate act that
+      cancels in-flight CI, and fusing them into one instruction is how an
+      obedient agent destroys its own evidence.
+  - >-
+      The watcher should be able to distinguish "alive and not appending" from
+      "possibly dead", which is a distinction that belongs in the guard rather
+      than in one session's scripts.
+structural-consequence:
+  - target: roles/implementer.md
+    status: applied
+    change: >-
+      The incremental-output clause carries the per-action trigger rather than
+      the habit, so the brief names a moment at which to append.
+  - target: src/watcher.ts
+    status: proposed
+    change: >-
+      The guard cannot today tell "alive and not appending" from "possibly
+      dead"; carrying the agent's own liveness signal rather than only mtimes is
+      what would separate them.
+evidence:
+  - delivery/tuition/T-017-the-beacon-instruction-asks-for-a-habit.md, the four instances and the postscript on the fused instruction

package/tuition/T-018.yaml

@@ -0,0 +1,84 @@
+# T-018: two checks that catch the same input make each other unwitnessable.
+# Promoted by M3-P8, which also carries this entry's mechanism into the index.
+kind: tuition
+version: 1
+id: T-018
+project: tiphys-kernel
+date: 2026-08-12
+stage: M3-P6 fix round 2 (the brief drift check)
+kernel-relevant: true
+what-happened: >-
+  A red-witness member mutated one of two checks that reject the same input.
+  Neither check is individually necessary, so the mutation left the other one
+  covering the arm and no named test could reach the mutated line. The harness
+  correctly reported that nothing reddened, and the instruction derived from
+  reading that message literally ("write a test that reaches this line") was
+  impossible to satisfy. The round tried the instructed fix first, watched it
+  stay red, and then read the runner. The same phase's reviews found the wider
+  version of the same shape: a check that renders an artifact and compares the
+  artifact to that rendering can only see drift BETWEEN the two, so a narrowing
+  INSIDE the loop is a fixed point of it and is silent.
+lesson:
+  - >-
+      Redundancy that cannot be observed is indistinguishable from dead code. A
+      line can be un-reddenable not because no test exercises the feature, but
+      because a second line in front of it rejects every input that would reach
+      it.
+  - >-
+      Reordering does not dissolve it; it only changes which of the two is
+      shadowed.
+  - >-
+      A gate message that names a line is naming a symptom. The reading is the
+      part that has to be earned, and the wrong reading was tried first here.
+mechanisms:
+  - mechanism: Checking a generated artifact against its own generator
+    rule: >-
+      A check that renders an artifact and then compares the artifact to that
+      rendering can only see drift BETWEEN the two, so any narrowing INSIDE the
+      loop is a fixed point of it and is silent. Three seats can choose what
+      gets compared and all three have now been occupied by a real finding: the
+      MODE, when it is read out of the artifact being audited; the UNIT COUNT,
+      when the generator computes it; and the SELECTION, inside the generator
+      itself. Two rules follow. A CHECK WHOSE SUBJECT IS SELECTED BY A VALUE
+      READ FROM THE ARTIFACT IT AUDITS CAN BE SILENTLY NARROWED BY EDITING THAT
+      ARTIFACT, so pin the subject OUTSIDE the artifact and refuse a
+      disagreement in every mode, `--write` included, because `--write` is the
+      command that launders a narrowing into the shipped bytes. And A UNIT COUNT
+      THAT DOES NOT MEASURE WHAT WAS COMPARED CANNOT MAKE THE VACUITY GUARD
+      FIRE, so count the rows actually compared and never add a mode-independent
+      term, which gives the count a floor it can never fall below. Closing the
+      third seat needs a SECOND, INDEPENDENT statement of what the artifact must
+      contain, derived from the AUTHORITY and never routed through the
+      generator; nothing that calls the generator can close it. Make that
+      statement SET EQUALITY AND FIELD PRESENCE, not containment: dropping rows
+      and dropping a column from rows that all survive are structurally
+      different members, and each is invisible to the assertion that catches the
+      other. State it in two places that fail independently, and derive per item
+      at run time rather than pinning a count, because these registries are
+      append-only.
+    siblings:
+      - scripts/check-brief-drift.mjs
+      - scripts/render-agent-rules-gates.mjs
+      - src/roles.ts
+      - test/implementer-brief.test.ts
+    evidence:
+      - CV-1 and contract A finding 3 in delivery/review/clean-room-m3-p6-criteria.md, two clean-room contracts reaching the mode seat from different directions on one head
+      - DV-1 in delivery/review/verification-m3-p6-fix-round.md, the selection seat, silent to the whole suite and to every gate in the PR bundle
+      - "M3-P6 fix round 2 measured `scripts/render-agent-rules-gates.mjs` carrying the same defect UNFIXED: its rowCount is registry-derived, so the check reports 15 gates over a CLAUDE.md block holding 13, with the suite green"
+structural-consequence:
+  - target: scripts/check-brief-drift.mjs
+    status: applied
+    change: >-
+      The drift check pins its subject outside the artifact it audits and counts
+      the rows actually compared, so a narrowing inside the loop cannot be
+      silent.
+  - target: test/implementer-brief.test.ts
+    status: applied
+    change: >-
+      A second, independent statement of what the brief must contain is derived
+      from the authority rather than from the generator, and it asserts set
+      equality and field presence rather than containment.
+evidence:
+  - delivery/tuition/T-018-two-checks-catching-the-same-input-make-each-other-unwitnessable.md, the round's account and the correction
+  - delivery/review/verification-m3-p6-fix-round.md, the delta verification that found the selection seat
+  - delivery/work-history/m3-p6.md, the round that tried the instructed fix first

package/tuition/T-021.yaml

@@ -0,0 +1,40 @@
+# T-021: MIGRATION TICKET, not an incident. Plan v1 section 11 item 7 parked
+# two L1 enforcement items for the tuition flow to carry; this is the first.
+# Recorded here at M3-P8 and executed post-M3.
+kind: tuition
+version: 1
+id: T-021
+project: tiphys-kernel
+date: 2026-08-12
+stage: M3-P8, recorded as a migration ticket
+kernel-relevant: true
+what-happened: >-
+  Plan v1 decision D-9 places "a review is never skipped" in Layer 1, meaning
+  enforced by the substrate rather than by an agent obeying a brief. The
+  substrate half is branch protection whose required checks depend on the
+  delivery mode: full mode requires the review gates, local-only mode cannot
+  require a pull request at all. None of it is built. Today the rule lives in
+  the orchestrator's brief and in the gate registry's applicability, which is
+  Layer 2: it holds while every agent obeys, and it has no floor under it if one
+  does not. This entry exists so the gap is a tracked artifact rather than a
+  sentence in a plan nobody re-reads.
+lesson:
+  - >-
+      A rule enforced only by a brief is enforced by whoever is reading the
+      brief. Recording the intended enforcement layer next to the rule is what
+      makes the gap visible.
+  - >-
+      Mode-awareness is the hard half. A protection rule that assumes a pull
+      request breaks local-only mode, so the enforcement has to be derived from
+      the charter's delivery mode rather than fixed.
+structural-consequence:
+  - target: gate-registry.yaml
+    status: ticketed
+    change: >-
+      Mode-aware branch-protection enforcement of the never-skipped review, so
+      the rule has a Layer 1 floor rather than living only in a brief. Executed
+      post-M3, per plan v1 section 11 item 7.
+    record: delivery/plan/kernel-plan-v1.md section 11 item 7 (D-9)
+evidence:
+  - delivery/plan/kernel-plan-v1.md, section 11 item 7, which parks both L1 items for the tuition flow to carry
+  - delivery/decisions/DR-0012-delegated-merge-authority.md, the delegation this rule protects

package/tuition/T-022.yaml

@@ -0,0 +1,36 @@
+# T-022: MIGRATION TICKET, not an incident. The second of the two L1 items plan
+# v1 section 11 item 7 parked for this moment. Recorded at M3-P8, executed
+# post-M3.
+kind: tuition
+version: 1
+id: T-022
+project: tiphys-kernel
+date: 2026-08-12
+stage: M3-P8, recorded as a migration ticket
+kernel-relevant: true
+what-happened: >-
+  Plan v1 decision D-10 places "validate before you push" in Layer 1: a push
+  that has not been through the validator is refused by the substrate, not by
+  the agent remembering. Nothing enforces it today. The validator exists as of
+  M3-P1 and the gates run in CI, which means the failure is caught AFTER the
+  push rather than before it, and the cost of that ordering is a red run, a
+  cancelled bundle and a round trip for something a pre-push check would have
+  named in a second.
+lesson:
+  - >-
+      A check that runs after the act it was supposed to prevent is a report,
+      not an enforcement.
+  - >-
+      The pre-validation check must be derivable from the same registry CI uses,
+      or it becomes a second list that drifts from the first.
+structural-consequence:
+  - target: gate-registry.yaml
+    status: ticketed
+    change: >-
+      A pre-push validation check derived from the registry's local-only mode,
+      so the same declarations drive both the pre-push refusal and the CI
+      bundle. Executed post-M3, per plan v1 section 11 item 7.
+    record: delivery/plan/kernel-plan-v1.md section 11 item 7 (D-10)
+evidence:
+  - delivery/plan/kernel-plan-v1.md, section 11 item 7, which parks both L1 items for the tuition flow to carry
+  - delivery/work-history/m3-p1.md, the validator this check would call