@tiphys/kernel 0.0.0 → 0.2.0

package/templates/decision-record.example.yaml

@@ -0,0 +1,27 @@
+# A minimal Tiphys decision record that validates against
+# schemas/decision-record.schema.json. Kernel plan M3, M3-P1 step 7.
+kind: decision-record
+id: DR-0021
+project: example-service
+task: m9-planning
+question: >-
+  Does the importer retry a 429, and if so how many times, given that the
+  caller already retries at job level?
+options:
+  - label: Retry twice inside the importer
+    consequence: >-
+      Bounded total attempts at six when multiplied by the caller's three, and
+      the failure surfaces within one job.
+  - label: Do not retry inside the importer
+    consequence: >-
+      One rate-limited response fails the whole job, and the caller's retry
+      re-reads the entire catalogue.
+reversibility: reversible
+vetoable: false
+revert-cost: >-
+  One constant and one test; the change is behind no data migration.
+status: decided
+decided: Retry twice inside the importer (owner, 2026-08-08).
+date: 2026-08-08
+evidence:
+  - delivery/verification/importer-retry.md

package/templates/final-report.example.yaml

@@ -0,0 +1,80 @@
+# Tiphys final report, worked example.
+#
+# FILLED WITH REAL CONTENT FROM THIS REPOSITORY (kernel plan M3, M3-P4 step 4).
+# The findings below are the six the M3-P3 round-8 adversarial verification
+# raised, with the outcomes that verification recorded, at
+# delivery/review/verification-m3-p3-round-8.md:766.
+#
+# THE FINAL REPORT IS A PROJECTION, NOT A SUMMARY. Nothing here is authored:
+# every row is derived from a record that already exists, which is why the
+# document can be dense while the archive stays verbose.
+
+kind: final-report
+subject: M3-P3, assurance modes and role-to-model configuration, rounds 1 to 10
+
+inputs:
+  - V-1
+  - V-2
+  - V-3
+  - V-4
+  - V-5
+  - V-6
+
+input-findings:
+  - id: V-1
+    outcome: >-
+      CLOSED. 128 runs through the shipped CLI with byte-identical output,
+      flat growth to 3584 markers, a 23.4M-string language equivalence, and a
+      time witness red 2 of 2 on both members and green with 58x headroom.
+  - id: V-2
+    outcome: >-
+      CLOSED. The {0,2}, {0,3} and {0,4} mutants and three loop-bound mutants
+      were all killed; name, description, spec and fixture agree. Residual
+      W-3 is LOW.
+  - id: V-3
+    outcome: CLOSED. The replacement member reddens one test out of 505, was fourteen.
+  - id: V-4
+    outcome: CLOSED. Both sweeps re-run by the reviewer; exit codes and hits reproduce exactly.
+  - id: V-5
+    outcome: >-
+      OUT OF SCOPE by orchestrator decision in
+      delivery/review/arbitration-m3-p3-round-8.md; not re-measured and no
+      claim made.
+  - id: V-6
+    outcome: >-
+      CLOSED BY REMOVAL. git grep for both constants outside delivery/
+      returns nothing at exit 1, and the derivation is stated in the true
+      form rather than as an impossibility.
+
+decisions-owed:
+  none: false
+  entries:
+    - id: todo-bucket
+      statement: >-
+        The report contract's gate-result count vocabulary has five fields and
+        the M2-P3 wrapper reports six buckets; a run with todo greater than
+        zero cannot be recorded without breaking parity. Whether to add the
+        field or to state the gap is a plan question, not an implementer one.
+      owner: orchestrator
+
+owner-verification:
+  none: false
+  entries:
+    - id: A-4
+      statement: >-
+        The npm publish credential is an owner action; no agent in this
+        container holds it and no gate can stand in for it.
+      owner: owner
+
+infrastructure-left:
+  none: true
+
+out-of-band:
+  none: false
+  entries:
+    - id: beacon-branch-correction
+      statement: >-
+        The M3-P4 beacon commit landed on local main and was moved onto the
+        phase branch by the orchestrator with git branch -f; no file content
+        changed and nothing was pushed while HEAD was wrong.
+      owner: orchestrator

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.