@tiphys/kernel 0.0.0 → 0.1.0

package/templates/plan.example.yaml

@@ -0,0 +1,87 @@
+# A minimal Tiphys delivery plan that validates against schemas/plan.schema.json.
+# Kernel plan M3, M3-P1 step 7. It is a TEACHING instance: every required
+# field is present and carries a realistic value, so a plan writer copying it
+# starts from a shape the validator accepts.
+kind: plan
+status: approved
+baseline-commit: be84c6d
+binding-rule: >-
+  If it is not written here, it is not being made. Unanswered questions go to
+  the orchestrator.
+process-summary: >-
+  Orchestrated delivery: verified plan, adversarial plan review, one phase per
+  branch, clean-room review before merge, milestone exit tests as hard gates.
+standing-context: |
+  What previous runs bought: the fleet layout, the lease lock, the watcher and
+  the gate contract. What is already fixed: nothing ships without a red
+  witness. Deploy state: none, this is a library.
+report-code-disagreement:
+  - phase: M9-P1
+    claim: the report says the importer retries on a 429, and the code does not
+    verified: false
+phases:
+  - id: M9-P1
+    branch: claude/m9-p1-importer-retry
+    intent: Make the importer's retry behaviour match what the report claims.
+    grounding: >-
+      The importer is on main at be84c6d and has one call site. The report's
+      retry claim has not been confirmed against it.
+    severity: high
+    verified-root-cause: >-
+      To be established by step 1, which is why step 1 is verification-first
+      and the fill-in below is unfilled.
+    steps:
+      - kind: verification-first
+        text: >-
+          Confirm whether the importer retries a 429 at all, capture the
+          observed behaviour, and write it down before changing anything.
+      - text: Implement the retry the verification shows is missing.
+    files-to-touch:
+      - src/importer.ts
+      - test/importer.test.ts
+      - "`src/cli.ts` (edit only if step 4 requires it)"
+    extras:
+      - delivery/requirements/clause-map.json
+    acceptance:
+      - id: "1"
+        criterion: >-
+          node --test test/importer.test.ts exits 0 and reports 4 tests, 0
+          failing.
+      - id: "2"
+        criterion: >-
+          A staged 429 response is retried exactly twice and the third failure
+          propagates, asserted against captured server output.
+    hazard-classes:
+      - id: H1
+        statement: >-
+          A retry that masks a permanent failure, so a broken import reports
+          success after three attempts.
+        addressed-by: criterion 2
+      - id: H2
+        statement: >-
+          Retry storms under concurrent imports, which no state this milestone
+          reaches can produce.
+        addressed-by: "state-not-entered: M10"
+    migrations: none
+    conflicts-with: []
+    parallelizable: false
+    citations:
+      - R-012
+      - T-003
+    fill-in:
+      filled: false
+      root-cause: ""
+      fix-shape: ""
+      files: []
+decisions:
+  - id: D-1
+    statement: >-
+      The retry count is two rather than five, because the importer's caller
+      already has a job-level retry and five would multiply to twenty-five.
+open-questions:
+  - DR-0021
+parked:
+  - item: A circuit breaker in front of the importer.
+    reason: >-
+      No measured instance of the failure it prevents; building it now is the
+      shape risk 1 exists to stop.

package/templates/report.example.yaml

@@ -0,0 +1,236 @@
+# Tiphys report, worked example.
+#
+# FILLED WITH REAL CONTENT FROM THIS REPOSITORY, not with placeholders
+# (kernel plan M3, M3-P4 step 4 and the hazard row on authoring cost). The
+# hazard this phase cannot test is that an honest record might be more
+# expensive to write than a dishonest one; nothing here measures that ratio,
+# and the only thing the plan can do about it is pay the cost of one honest
+# record once, in the open, so a reader can see what it costs. This is that
+# record. Every command quoted below was run, and every exit code is the one
+# it returned.
+
+kind: report
+role: implementer
+task: >-
+  Deliver M3-P4: the report contract, the final-report shape, the work-history
+  contract and the environment-warnings template, so that every later role
+  brief has a validated output format to point at instead of describing one in
+  prose.
+verdict: >-
+  Delivered on the branch, with two residues stated rather than closed and one
+  declared deviation from criterion 2(e)'s letter.
+
+findings:
+  - id: VF-1
+    severity: high
+    source-pinned: true
+    pinned-evidence: origin/main at c7a7ce97e03fc0788c92b401de92f0f4a7b8ee0d
+    evidence:
+      - path: src/validate.ts
+        lines: "568"
+        note: >-
+          compileSchema built a fresh Ajv per document and registered nothing
+          beside it, so a reference leaving the document failed compilation.
+      - path: src/validate.ts
+        lines: "642"
+        note: >-
+          The reference is classified as remote or unresolved and either way
+          the compilation fails closed.
+    analysis: |
+      Plan step 3 requires the work-history schema to share the report
+      schema's claims and fix-round definitions by $ref rather than restating
+      them, and requires a registered test that both resolve to the same
+      definition object. As shipped at the merge base, no schema could reach
+      another document at all, so shipping the $ref without a change to the
+      compile path would have made `tiphys validate --type work-history` fail
+      on this phase's own example, which is acceptance criterion 1.
+    outcome: >-
+      Closed by a declared COMPANION_TABLE in src/commands/validate.ts and an
+      optional companions argument on compileSchema, so the set of documents a
+      schema may reach is declared in one auditable place rather than derived
+      from the reference.
+
+  - id: VF-2
+    severity: medium
+    source-pinned: false
+    evidence:
+      - path: src/gates/coverage.ts
+        lines: "599"
+        note: checkFindingOutcomeParity is an exported function.
+      - path: src/gates/coverage.ts
+        command: node src/gates/coverage.ts --help
+        exit-code: 64
+        note: >-
+          The gate CLI answers with its usage line, which accepts only
+          --result, --evidence and --config.
+
+    analysis: |
+      Acceptance criterion 4 asks for the M2-P6 coverage checker run in
+      finding-to-outcome parity mode against the final-report template, with
+      an exit code on both arms. The checker has no CLI flag that reaches that
+      mode, and src/gates/coverage.ts is not on this phase's declaration.
+    outcome: >-
+      Discharged by invoking the exported checker in a subprocess from the
+      registered test, so the exit code is a real process exit code and the
+      checker itself is unmodified.
+
+  - id: VF-3
+    severity: low
+    source-pinned: false
+    counter-experiment: >-
+      Removing minLength from the field and re-validating the whitespace-only
+      instance, which then passes, is the experiment that would falsify this.
+    evidence:
+      - path: schemas/report.schema.json
+        command: node bin/tiphys.ts validate --type report templates/report.example.yaml
+        exit-code: 0
+    analysis: |
+      Every field in these three schemas whose value is the point rather than
+      its presence carries minLength 1 and a non-whitespace pattern, because
+      required alone is satisfied by the empty string. The inventory of those
+      fields is written into the work history as a list, since which fields
+      were considered is a judgment made once at authoring time.
+    outcome: Closed; the field inventory is in delivery/work-history/m3-p4.md.
+
+claims:
+  - id: C-1
+    kind: open-question
+    statement: >-
+      I did not find a way to make a gate result record a todo bucket without
+      breaking the parity rule, because the plan's five-field count vocabulary
+      has no field for it.
+
+  - id: C-2
+    kind: impossibility
+    statement: >-
+      A relative $ref into a sibling schema cannot be compiled by this
+      validator unless the caller registers that sibling as a companion.
+    settled-by:
+      executed-construction:
+        command: >-
+          node --input-type=module -e "import {compileSchema} from
+          './src/validate.ts'; const s = JSON.parse(await
+          (await import('node:fs/promises')).readFile('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
+
+  - id: C-3
+    kind: coverage
+    statement: >-
+      The derived check report-parity-arithmetic reddens on a gate result
+      whose sum exceeds discovered, and not only on one where discovered
+      exceeds the sum.
+    settled-by:
+      executed-construction:
+        command: node --test --test-name-pattern "parity" test/report-contract.test.ts
+        exit-code: 0
+        output: |
+          # tests 2
+          # suites 0
+          # pass 2
+          # fail 0
+          # cancelled 0
+          # skipped 0
+          # todo 0
+
+  - id: C-4
+    kind: remedy
+    statement: >-
+      Registering report.schema.json as a companion makes the work-history
+      schema compile and its example validate.
+    settled-by:
+      executed-construction:
+        command: node bin/tiphys.ts validate --type work-history templates/work-history.example.yaml
+        exit-code: 0
+        output: |
+          (no output; the command exits 0 with nothing on either stream)
+
+  - id: C-5
+    kind: universal
+    statement: >-
+      Every field in these schemas whose value carries the meaning has both
+      minLength and a non-whitespace pattern.
+    settled-by:
+      counter-experiment: >-
+        The falsifying experiment is a grep for minLength without an adjacent
+        pattern in the three schema documents; it is recorded with its output
+        in delivery/work-history/m3-p4.md.
+
+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 three functions are called through a computed dynamic import and a
+    literal grep for the call would find the import rather than the call; it
+    did not cover scripts/, which reaches the validator only through
+    src/gates/result.ts and never compiles a schema of its own; and it did not
+    cover dist/, which is generated and is never committed. The six sites
+    listed are the ones a companion-needing schema could reach today, and only
+    src/commands/validate.ts:273 was changed, because it is the only one that
+    resolves a type through the type table.
+
+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 finding object already spends its one if/then slot on T-004's
+      source-pinned coupling, allOf is outside the declared authoring
+      vocabulary, and two independent conditional rules cannot share one slot,
+      so the universal-quantifier rule is expressed as a two-branch oneOf. It
+      remains Kind A and its guarding keyword is witnessed by removal and
+      restoration.
+
+honest-failures:
+  - cause: >-
+      The first copy of this phase's work history was created in the working
+      tree and not committed, and it disappeared within twenty-one minutes,
+      together with HEAD moving back to main.
+    exposure-window: >-
+      Twenty-one minutes, from the file's creation at 10:37 to the empty git
+      status at 10:58. Nothing was pushed in that window, so no branch outside
+      this container ever saw the misplaced commit.
+    structural-fix: >-
+      The beacon is committed in the same turn it is created, and the branch
+      is pushed early rather than at the end, so the beacon lives in git
+      rather than only in a working tree another process can reset.
+
+environmental-claims:
+  - claim: >-
+      The build fails at build:runtime-deps on a checkout whose node_modules
+      predates M3-P3, because commonmark is a new dependency.
+    evidence:
+      - path: package.json
+        command: npm run build
+        exit-code: 1
+        note: >-
+          Error ENOENT no such file or directory, open
+          node_modules/commonmark/package.json
+      - path: package-lock.json
+        command: npm ci
+        exit-code: 0
+        note: After npm ci the same build command exits 0.
+
+gate-results:
+  - gate: suite
+    result: green
+    wrapper-exit-code: 0
+    discovered: 507
+    passed: 505
+    failed: 0
+    skipped: 2
+    todo: 0
+    did-not-run: 0

package/templates/warnings.md

@@ -0,0 +1,74 @@
+# Environment warnings
+
+This is R-083a's template half; its accumulation half is the work-history
+schema's `environment-warnings[]`.
+
+Place this file at the fleet root as `warnings.md`. `tiphys spawn` appends it
+VERBATIM to every brief it assembles (`src/brief.ts`, R-083b), so what is
+written here is what every agent reads. No heading is added, no banner, no
+rewriting; the only byte the kernel may insert is one newline between the
+brief and this file.
+
+Markdown rather than YAML is a justified exception recorded in kernel plan M3
+section 1.5: the only consumer appends it into instruction prose, so a
+structured form would need a renderer whose sole output is the prose this file
+already holds.
+
+## What belongs here
+
+One entry per environment fact that has already cost someone time. Each entry
+states the fact, how it was MEASURED, and what to do instead. A warning with no
+measurement behind it is a rumour, and a brief full of rumours is skimmed.
+
+An entry is added the moment it is discovered, not at the end of a phase. The
+matching field in the work-history contract is `environment-warnings[]`
+(`schemas/work-history.schema.json`), which is the accumulation half of the
+same requirement this template is the template half of.
+
+## Entries, as they stand in this repository
+
+These are real and are kept here as the worked example rather than as
+placeholders. Replace them with your own project's; do not ship them unread.
+
+1. **Several node versions may be installed and which one you get depends on
+   how the shell was started.** Measured: a login shell resolved `node` to
+   v22.22.2, and a stripped environment (`env -i bash -c`, and some subagent
+   and hook contexts) resolved it to v20.20.2. Node 20 has no TypeScript type
+   stripping, so a TypeScript test suite fails there in a way that does not
+   look like a version problem. Check `node --version` in the shell that
+   actually runs the command, and prefer an absolute path or an explicit PATH
+   prefix over trusting the ambient one.
+
+2. **Running the suite without building first can silently skip tests while
+   still exiting 0.** Measured at one head on node v26.6.0: with `dist/` built,
+   504 tests, 504 pass, 0 skipped; with `dist/` removed, 504 tests, 495 pass,
+   9 skipped. Both runs exit 0. A skipped test is not a passing test, so quote
+   the SKIPPED count beside the pass count. The complete sentence names the
+   toolchain, the build state and the invocation, because the three axes skip
+   different tests and they compose.
+
+3. **`git checkout --` is destructive in a tree holding uncommitted work,
+   including when it names a single path.** An implementer used it to clean up
+   one probe file and lost four rounds of uncommitted edits, having read a
+   warning about it beforehand. There is no safe narrow form: commit, or copy
+   out of the tree, before experimenting.
+
+4. **A mutation harness killed by a timeout leaves the mutant installed.** A
+   modified source file is exactly what a mutation round expects to see, so the
+   one available signal is the one you have trained yourself to ignore. Restore
+   by copying from a pristine copy rather than from git, put the restore in a
+   shell `trap`, and print AND COMPARE a checksum on both sides.
+
+5. **Concurrent git operations against one clone contend on ref locks**, and
+   the real transient message names a ref rather than a lock file. Never derive
+   a retry signature from a hand-written example; capture real stderr under
+   forced contention.
+
+6. **A tool may be absent locally and present in CI.** Use a deterministic
+   PATH in tests rather than assuming either, and do not read an authenticated
+   API path and a git path as having the same authority: they can differ in one
+   container.
+
+7. **Tests that create scratch git repositories must set command-scoped
+   `GIT_AUTHOR_*` and `GIT_COMMITTER_*`**, because CI runners have no git
+   identity, and must never touch user or global configuration.

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.