@tiphys/kernel 0.0.0 → 0.1.0

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

package/tuition/mechanism-index.yaml

@@ -0,0 +1,256 @@
+# THE MECHANISM INDEX (kernel plan M3; T-005, D-M3-23).
+#
+# GENERATED BY `tiphys tuition index`. DO NOT EDIT THIS FILE. It is a
+# PROJECTION of the `mechanisms[]` field of every entry in the tuition feed
+# beside it, so a rule is recorded once, in the entry that paid for it, and
+# read from here. `tiphys tuition index --check` compares this file against a
+# fresh projection and exits nonzero on any drift, which is what stops the two
+# from becoming two sources.
+#
+# READ THE ROW BEFORE YOU USE THE MECHANISM. Every rule here was paid for with
+# a defect, a fix round, or an investigation, which is why `evidence` is a
+# required field with at least one entry: a rule with no citation is not a
+# rule.
+#
+# WHY THIS FILE EXISTS AT ALL. T-005 records a rule M1-P3 paid for in a
+# multi-hour investigation that did not reach M1-P5, which reimplemented the
+# same claim-file mechanism silently and produced the most severe defect found
+# in that milestone. The implementer there had read the plan, the agent-rules
+# file, the constraint list, the accumulated environment warnings and three
+# work histories. None of them carried the rule, because a rule about a
+# MECHANISM has no home in a set of documents organised by phase. This is that
+# home, and the obligation to consult it is the `mechanism-lookup` clause in
+# roles/implementer.md.
+#
+# `key` IS DERIVED FROM `name`, NOT INVENTED: lowercase, every run of
+# characters outside [a-z0-9] collapsed to one hyphen, ends trimmed.
+
+kind: mechanism-index
+version: 1
+
+mechanisms:
+  - key: a-guard-s-own-failure-path
+    name: 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
+
+  - key: append-only-log
+    name: 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)
+
+  - key: asserting-a-ci-step-is-wired
+    name: 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
+
+  - key: atomic-file-replacement
+    name: 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
+
+  - key: checking-a-generated-artifact-against-its-own-generator
+    name: 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"
+
+  - key: claim-file-mutual-exclusion-by-o-excl
+    name: 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
+
+  - key: classifying-another-program-s-errors
+    name: 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
+
+  - key: deciding-what-another-program-will-do-by-pattern-matching-the-text-of-a-file-it-consumes
+    name: 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"
+
+  - key: lease-compare-and-swap
+    name: 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
+
+  - key: parsing-another-program-s-reporter-output
+    name: 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"
+
+  - key: reading-a-path-whose-type-is-not-established
+    name: 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
+
+  - key: shared-worktree
+    name: 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
+
+  - key: supervising-a-dispatched-agent
+    name: 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
+
+  - key: verifying-access-to-a-remote
+    name: 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
+
+  - key: worktree-removal-and-force-branch-delete
+    name: 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