@tiphys/kernel 0.0.0 → 0.1.0

package/schemas/verdict.schema.json

@@ -0,0 +1,289 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/verdict.schema.json",
+  "title": "Tiphys clean-room review verdict",
+  "$comment": "R-053, R-057b, R-060, T-001, T-007. Kernel plan M3, M3-P7 steps 6 and 6a. THE OUTPUT OF A CLEAN-ROOM REVIEW, and the document that decides what a review is ALLOWED TO SAY. THE HAZARD THIS DOCUMENT EXISTS AGAINST is the phase's own last item: a verdict that admits APPROVE alongside an unaddressed hazard class. WHAT IT REACHES. (1) APPROVE beside a finding the review itself ranked high or critical, which is a review saying yes while recording a reason to say no, and is how a fix round gets skipped; the root `if`/`then` inverts it into the form the closed vocabulary can carry (schemas/README.md has no `not`): a set CONTAINING such a finding must carry the FIX-ROUND-NEEDED verdict. Stated deliberately WIDER than criterion 4(a), which names `high` alone: `critical` outranks it, and a rule that stopped at `high` would let the worse finding through. (2) A finding with no `concrete-fix`, on EVERY finding rather than on high ones, because a low finding with no proposed edit is a remark. (3) A verdict with no `produced-by` or no `framing`: DR-0012 condition 1 compares two reviews of one head on family AND entry point, and neither comparison is reachable from inside one document, so what is bought here is that neither field can be absent. (4) T-007's `review-contract`, and `hazard-classes-addressed[]` required exactly when the contract is `hazard`, through the `oneOf`. WHAT IT CANNOT REACH, each with its instrument. (a) Whether `criteria[]` covers every acceptance criterion of the phase: that is a comparison against a DIFFERENT document and is the Kind B check `verdict-criteria-complete`. (b) Same for `deviations-judged[]` against the work history's `deviations[]` (M3R-005), check `verdict-deviations-judged`. (c) Same for `hazard-classes-addressed[]` against the plan phase's `hazard-classes[]`, check `verdict-hazard-classes-addressed`. (d) Whether a `cleared-because` statement is true, or whether `met: true` was earned; those are the reviewer's judgement and no keyword reaches them. (e) ADDED IN FIX ROUND 2, and it is INTRA-document rather than cross-document, which is why it was missed: whether `hazard-classes-addressed[].finding` names a finding this document actually declares. It is the check `verdict-finding-references-resolve`, and what it protects is rule (1) above, which reads `findings[]` alone and is therefore blind to a finding recorded one field away.",
+  "description": "A clean-room review verdict: the decision, the findings behind it, and the three completeness arrays that say what the review actually walked.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "phase",
+    "verdict",
+    "produced-by",
+    "framing",
+    "review-contract",
+    "findings",
+    "criteria",
+    "deviations-judged"
+  ],
+  "properties": {
+    "kind": {
+      "$comment": "R-016's discriminator, so `tiphys validate --type auto` resolves this document without being told (M3R-001).",
+      "type": "string",
+      "const": "verdict"
+    },
+    "phase": {
+      "$comment": "The plan phase this review is OF. Not decoration: it is the join key all three Kind B checks use to select the phase in `plan.yaml` and to confirm `work-history.yaml` is the right one. A verdict that named no phase would make every cross-document completeness rule unimplementable, which is the same reason the checklist probe carries `verifies-gate`.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "verdict": {
+      "$comment": "R-060's closed vocabulary, exactly two values. A third value such as 'approve with comments' is the shape that lets a fix round be skipped by wording, so the enum is the whole point of the field.",
+      "type": "string",
+      "enum": ["APPROVE", "FIX-ROUND-NEEDED"]
+    },
+    "produced-by": {
+      "$comment": "T-001: record in the review header which model family produced it. DR-0012 condition 1 requires the two clean-room reviews of one head to differ here, and that comparison is between two documents.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "framing": {
+      "$comment": "Step 6: which entry point this review was given, naming a `framings[].id` of the checklist it ran. T-001's second lesson is that decorrelation comes from the STARTING QUESTION rather than only from the reviewer, so a verdict that does not record its framing cannot be checked for decorrelation at all.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "review-contract": {
+      "$comment": "T-007, step 6a. Which of the two review CONTRACTS produced this verdict, mirroring the field the role brief carries (M3-P6). `scripts/check-dual-review.mjs` can then check contract distinctness alongside model-family and framing distinctness, which is T-007's point: the phase that met fifteen of fifteen criteria and live-locked every supervision command was caught by a reviewer that differed in its BRIEF, not in its model.",
+      "type": "string",
+      "enum": ["criteria", "hazard"]
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/finding"
+      }
+    },
+    "criteria": {
+      "$comment": "R-053: each acceptance criterion quoted, with file:line evidence and a met-or-not-met verdict. One entry per criterion; that it is EVERY criterion is Kind B.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/criterionWalk"
+      }
+    },
+    "deviations-judged": {
+      "$comment": "R-057b, and M3R-005 is why it is an ARRAY rather than a probe question. 'Each declared deviation judged against the plan's intent by the reviewer, never assumed by the implementer' has exactly the same completeness shape as criteria coverage, and revision 0 had left it as a bare probe, so a reviewer could silently skip judging one of three declared deviations and every criterion still passed. Empty is legitimate: a phase can declare no deviation.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/deviationJudgement"
+      }
+    },
+    "hazard-classes-addressed": {
+      "$comment": "T-007, step 6a. Required exactly when `review-contract` is `hazard`, by the `oneOf` below. One entry per class declared by the referenced plan phase; that it is EVERY class is Kind B, check `verdict-hazard-classes-addressed`, which has the shape `verdict-criteria-complete` has for criteria and for the same reason.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/hazardClassAddressed"
+      }
+    }
+  },
+  "if": {
+    "$comment": "THE DANGEROUS INSTANCE, criterion 4(a), inverted into the closed vocabulary's reach. The rule wanted is APPROVE implies no high finding, and the direct spelling needs `not`, which schemas/README.md does not permit. `contains` matches the NON-empty case, which is the polarity that works here: a set that CONTAINS a finding the review itself ranked high or critical is a set whose verdict must be FIX-ROUND-NEEDED. `type: array` is restated inside because ajv 8.20.0 under `strict: true` refuses `contains` in a subschema that has not declared its type at the same level.",
+    "properties": {
+      "findings": {
+        "type": "array",
+        "contains": {
+          "type": "object",
+          "required": ["severity"],
+          "properties": {
+            "severity": {
+              "type": "string",
+              "enum": ["high", "critical"]
+            }
+          }
+        }
+      }
+    }
+  },
+  "then": {
+    "$comment": "So APPROVE beside a high or critical finding fails HERE, naming the verdict field. Restated in `properties` at this level because a bare `enum` under a name ajv cannot see declared is a compilation error under strictTypes.",
+    "properties": {
+      "verdict": {
+        "type": "string",
+        "enum": ["FIX-ROUND-NEEDED"]
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "$comment": "Branch A, the criteria contract. `hazard-classes-addressed` is not required, and criterion 4e asserts a `criteria` verdict is unaffected by the hazard completeness check as well, so the rule applies exactly where the contract applies and nowhere else.",
+      "properties": {
+        "review-contract": {
+          "type": "string",
+          "const": "criteria"
+        }
+      }
+    },
+    {
+      "$comment": "Branch B, the hazard contract (T-007). `review-contract` and `hazard-classes-addressed` are BOTH restated in a sibling `properties` here, which is not redundancy: measured against ajv 8.20.0 under this validator's `strict: true`, a `required` naming a property not declared in `properties` at the same level fails COMPILATION under strictRequired. The two branches are discriminated by a `const` on one field, so exactly one can ever match and `oneOf` is an exclusive choice rather than an ambiguity.",
+      "required": ["hazard-classes-addressed"],
+      "properties": {
+        "review-contract": {
+          "type": "string",
+          "const": "hazard"
+        },
+        "hazard-classes-addressed": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "finding": {
+      "$comment": "R-060: severity-ranked, a concrete fix each. Ranked low < medium < high < critical, the same four names schemas/finding.schema.json and schemas/plan.schema.json use, so the kernel carries one severity vocabulary rather than three.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "severity", "evidence", "concrete-fix"],
+      "properties": {
+        "id": {
+          "$comment": "The stable id the arbitration and the fix round cite. CLAUDE.md owns the scheme (CR-nnn for a clean-room finding on a PR); this schema does not pick one.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "evidence": {
+          "$comment": "Evidence beats assertion: exit codes, counts, paths with line numbers, captured output. `minItems: 1` because a finding with no evidence is an opinion, and this repository treats a claim with no verifiable artifact behind it as unknown.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        },
+        "concrete-fix": {
+          "$comment": "Criterion 4(b) names a FIX-ROUND-NEEDED finding with no concrete fix as the dangerous instance. Required on EVERY finding regardless of verdict or severity, which is deliberately stronger: a review made of remarks is the empty review with extra steps. DR-0027 sharpens what a fix should say, since a finding that cannot name the shipped behaviour at risk has found nothing worth a round.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "analysis": {
+          "$comment": "The argument behind one finding, which is not enumerable and therefore lives inside a field rather than becoming structure (section 1.5). Optional, non-empty when present.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "criterionWalk": {
+      "$comment": "R-053, one acceptance criterion walked.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "quote", "evidence", "met"],
+      "properties": {
+        "id": {
+          "$comment": "The `acceptance[].id` of the criterion in the referenced plan phase. This is the join key `verdict-criteria-complete` compares; a walk keyed only by its quoted text could not be compared to anything without matching prose.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "quote": {
+          "$comment": "R-053 says QUOTED, so the reviewer has read the criterion rather than the id. The schema cannot check that the quote matches the plan's text; it can require that something was quoted.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        },
+        "met": {
+          "type": "boolean"
+        }
+      }
+    },
+    "deviationJudgement": {
+      "$comment": "R-057b, one declared deviation judged.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["deviation", "serves-plan-intent", "reasoning"],
+      "properties": {
+        "deviation": {
+          "$comment": "The work history's `deviations[].plan-clause`, verbatim. The join key `verdict-deviations-judged` compares.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "serves-plan-intent": {
+          "$comment": "The REVIEWER's judgement, which is the half R-057b insists is never the implementer's. A boolean, so a deviation cannot be waved through in prose that reads as approval without being one.",
+          "type": "boolean"
+        },
+        "reasoning": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "hazardClassAddressed": {
+      "$comment": "T-007, step 6a: one declared hazard class, probed, and either a finding it produced or a statement clearing it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["class-id", "probed"],
+      "properties": {
+        "class-id": {
+          "$comment": "The `hazard-classes[].id` of the referenced plan phase, the join key `verdict-hazard-classes-addressed` compares.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "probed": {
+          "$comment": "What the reviewer actually DID against this class. The hazard checklist's canonical probes each name a construction rather than asking a bare question (a real mkfifo, a forced concurrency, a killed process mid-write, a destroy on a branch carrying committed unpushed work), and this is where that construction is recorded.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "finding": {
+          "$comment": "The `findings[].id` this class produced, when it produced one. THE ONLY INTRA-DOCUMENT ID REFERENCE IN ANY SHIPPED SCHEMA, and resolving it is the Kind B check `verdict-finding-references-resolve` rather than a keyword: matching one array's entry against another array's ids is not a keyword property under any DR-0013 option. It is not decoration. The escalation rule at the root of this document reads `findings[]` and nothing else, so a class recorded as having produced a finding that never reaches `findings[]` is an APPROVE the rule cannot see past; measured before the check, that document validated at exit 0.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "cleared-because": {
+          "$comment": "The statement clearing the class, when the probe produced no finding. Step 6a asks for EITHER a finding reference OR this, and the `oneOf` below is that either.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      },
+      "oneOf": [
+        {
+          "$comment": "Branch A: the class produced a finding. `finding` is restated in a sibling `properties` for the strictRequired reason recorded on the root `oneOf`.",
+          "required": ["finding"],
+          "properties": {
+            "finding": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S"
+            }
+          }
+        },
+        {
+          "$comment": "Branch B: the class was cleared and the reviewer says why. An entry carrying BOTH matches both branches and is therefore invalid, which is deliberate: a class both cleared and found is a contradiction and the reader cannot tell which the review meant.",
+          "required": ["cleared-because"],
+          "properties": {
+            "cleared-because": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/work-history.schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/work-history.schema.json",
+  "title": "Tiphys work history",
+  "$comment": "R-035, R-052a, R-083a. Kernel plan M3, M3-P4 step 3. THE WORK HISTORY IS THE ARTIFACT A LATER REVIEWER TRUSTS and the one CLAUDE.md says must never be softened, which is why `claims[]`, `fix-round[]` and `gate-evidence[]` are the REPORT SCHEMA'S OWN DEFINITIONS reached by $ref into report.schema.json rather than restated here. A shared definition is not a convenience: two independently-drifting copies of the honesty contract is the drift hole M3-P2 closes for gates and M3-P3 closes for mode ids, and a registered test asserts that both documents resolve to the SAME definition object rather than to two equal ones. THE SHARING IS OF KEYWORDS ONLY, AND THAT WAS ONCE A HOLE: a derived check is registered per artifact TYPE and reads a type-specific KEY, so a Kind B rule written against a shared `$def` does not follow the `$ref` here (M3-P4 round-1 finding CR-001). Every shared `$def` in report.schema.json now states whether a derived check guards it, the one that is guarded declares this type in `alsoTypes`, and test/report-contract.test.ts derives the relation from the schemas so a stale claim reddens rather than reassures. HOW THE $ref RESOLVES: the reference is RELATIVE, so it resolves against this document's $id to https://tiphys.dev/schemas/report.schema.json and matches that document's own $id. Nothing is fetched. `src/commands/validate.ts` declares report.schema.json as this type's COMPANION and registers it with the same compiler before this document is compiled, which is a named, in-directory, shipped-schema registration and not the remote loading DR-0013 clause 4 withholds. R-083a's ACCUMULATION HALF is `environment-warnings[]`; its template half is templates/warnings.md.",
+  "description": "One document per phase branch. The prompt verbatim, what was touched, what was decided and why, what was verified before any code was written, every deviation, the gate evidence, the claims made and how each was settled, and the environment warnings the phase accumulated.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "phase",
+    "prompt",
+    "files-touched",
+    "per-step-commits",
+    "key-decisions",
+    "verification-first",
+    "deviations",
+    "gate-evidence",
+    "claims",
+    "environment-warnings"
+  ],
+  "properties": {
+    "kind": {
+      "description": "The artifact type, so `tiphys validate --type auto` resolves this document without being told.",
+      "type": "string",
+      "const": "work-history"
+    },
+    "phase": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "prompt": {
+      "$comment": "R-052a: VERBATIM. A block scalar, and the schema cannot tell verbatim from paraphrased; what it can do is refuse an empty or whitespace-only one.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "files-touched": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "pattern": "\\S" }
+    },
+    "per-step-commits": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sha", "subject"],
+        "properties": {
+          "sha": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+          "subject": { "type": "string", "minLength": 1, "pattern": "\\S" }
+        }
+      }
+    },
+    "key-decisions": {
+      "$comment": "R-052a: the WHY that is invisible in the diff. `why` is required, so a decision cannot be recorded as a bare fact.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["decision", "why"],
+        "properties": {
+          "decision": { "type": "string", "minLength": 1, "pattern": "\\S" },
+          "why": { "type": "string", "minLength": 1, "pattern": "\\S" }
+        }
+      }
+    },
+    "verification-first": {
+      "$comment": "R-035, D-M3-03. Findings written BEFORE any code, recorded verbatim. `contradicts-plan` is a REQUIRED boolean, so the question is answered rather than skipped, and a `true` drags a `stopped-and-reported` reference with it: the whole point of R-035 is that a finding contradicting the plan is escalated rather than implemented around, and a record that says it contradicted the plan while naming no escalation is the shape that rule exists to forbid. RESIDUE, STATED HERE BECAUSE THE FIX ROUND 2 ENUMERATION FOUND IT AND NOTHING ELSE ON THIS BRANCH RECORDS IT: this is CR-002's mechanism in boolean form. The `if` keys off A VALUE THE AUTHOR CHOOSES, and the `false` branch owed NOTHING, so a finding that DOES contradict the plan and is recorded as `contradicts-plan: false` escaped the escalation reference entirely. FIX ROUND 2 WROTE HERE THAT NO KEYWORD AND NO DERIVED CHECK COULD REACH IT, on the ground that deciding whether a finding contradicts the plan is a reading of two documents in prose. THAT SENTENCE WAS FALSE AND IS CORRECTED RATHER THAN QUIETLY DELETED, because it is the exact shape this whole schema exists to refuse: the round-2 delta verifier refuted it by CONSTRUCTION (finding DV-002), and the reason it was wrong is that the second document is not outside this one at all, since `finding` is prose carried in the same object. The `false` branch of `$defs/verificationFirst`'s `oneOf` now narrows that prose; see its own comment for the token list and for what it still does not reach. The required boolean makes the question unskippable and the pattern prices the most obvious lies, and NEITHER makes the answer true; M3-P7's clean-room checklist is where that is checked.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/verificationFirst" }
+    },
+    "deviations": {
+      "$comment": "R-057a, the same shape the report carries.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["plan-clause", "why"],
+        "properties": {
+          "plan-clause": { "type": "string", "minLength": 1, "pattern": "\\S" },
+          "why": { "type": "string", "minLength": 1, "pattern": "\\S" }
+        }
+      }
+    },
+    "gate-evidence": {
+      "$comment": "R-049, R-086. THE REPORT SCHEMA'S gate-results DEFINITION, by $ref, not a copy of it. THE KEY IS DIFFERENT HERE (`gate-evidence`, not `gate-results`) AND THAT DIFFERENCE IS LOAD-BEARING: the derived check `report-parity-arithmetic` guards this definition, and a check registered for one type reading one hard-coded key was blind on this document even though the keywords were shared, so a work history claiming 9999 tests discovered and 1 passed validated while the identical counts in a report did not (M3-P4 round-1 finding CR-001). src/checks.ts now enumerates the key per type in `GATE_RESULT_SITES` and the check declares `alsoTypes: [work-history]`.",
+      "type": "array",
+      "items": { "$ref": "report.schema.json#/$defs/gateResult" }
+    },
+    "claims": {
+      "$comment": "T-006, D-M3-30. THE REPORT SCHEMA'S claims DEFINITION, by $ref, not a copy of it.",
+      "type": "array",
+      "items": { "$ref": "report.schema.json#/$defs/claim" }
+    },
+    "fix-round": {
+      "$comment": "CLAUDE.md's fix-round contract, D-M3-30. THE REPORT SCHEMA'S fix-round DEFINITION, by $ref, not a copy of it. An ARRAY here and a single object in the report, because a phase branch carries many rounds and one report answers one of them; the ELEMENT is the same definition in both. Optional, because a phase with no fix round has none to record.",
+      "type": "array",
+      "items": { "$ref": "report.schema.json#/$defs/fixRound" }
+    },
+    "environment-warnings": {
+      "$comment": "R-083a's ACCUMULATION HALF. Its template half is templates/warnings.md, which src/brief.ts appends verbatim to every brief. A warning recorded here without evidence is still a warning, so `evidence` is optional and `warning` is not; making evidence mandatory would price an honest note out of the record, which is this phase's own worst hazard one size down.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["warning"],
+        "properties": {
+          "warning": { "type": "string", "minLength": 1, "pattern": "\\S" },
+          "evidence": { "type": "string", "minLength": 1, "pattern": "\\S" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "verificationFirst": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["finding", "contradicts-plan"],
+      "properties": {
+        "finding": {
+          "$comment": "Recorded VERBATIM (R-035).",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "contradicts-plan": { "type": "boolean" },
+        "stopped-and-reported": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "plan-language-note": {
+          "$comment": "M3-P4 FIX ROUND 4, FINDING DV3-002. Declared here as well as in the branch that requires it, because this object sets `additionalProperties: false` and a field absent from THIS block is refused before any branch is reached. A DECLARED RESIDUE, MEASURED RATHER THAN ASSUMED: the third `oneOf` branch below is the only one that REQUIRES this field, and the first branch (`contradicts-plan: true`) sets no `additionalProperties`, so a `true` record carrying this note validates and nothing refuses it. Making that a rejection means giving branch 1 an `additionalProperties: false` and restating every property of this object inside it, which is a change to the branch each `contradicts-plan: true` witness names; it was not worth that, and it is written down here instead of being left for a reader to find.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      },
+      "if": {
+        "$comment": "Kind A, both sides on the SAME object, so the escalation cannot be satisfied by a reference recorded elsewhere in the document.",
+        "type": "object",
+        "required": ["contradicts-plan"],
+        "properties": { "contradicts-plan": { "const": true } }
+      },
+      "then": {
+        "type": "object",
+        "required": ["stopped-and-reported"],
+        "properties": {
+          "stopped-and-reported": { "type": "string", "minLength": 1, "pattern": "\\S" }
+        }
+      },
+      "oneOf": [
+        {
+          "$comment": "THE `contradicts-plan: true` BRANCH, which adds nothing: the escalation obligation is the `if`/`then` above and is deliberately left there rather than moved, so every witness registered against it keeps naming the keyword that does the work. This branch exists to make the two branches disjoint. Its own `required` is what makes an ABSENT `contradicts-plan` fall to the branch below instead of matching both, which is why the two branches are not symmetric.",
+          "type": "object",
+          "required": ["contradicts-plan"],
+          "properties": { "contradicts-plan": { "const": true } }
+        },
+        {
+          "$comment": "M3-P4 FIX ROUND 3, FINDING DV-002. Round 2 wrote that this site was `Unreachable by keyword or check` and the round-2 delta verifier REFUTED THAT BY BUILDING THE THING, using this phase's own remedy one definition over. The correction matters more than the fix: the argument round 2 gave for the whole class was that each open site `compares a document to something that is not in any document`, and that is FALSE HERE. `finding` is prose recorded verbatim (R-035) and it is IN THIS DOCUMENT, so the branch is content-discriminated in exactly the sense this phase's own converse table defines, and the negative-lookahead `pattern` that narrowed `#/$defs/claim`'s `open-question` statement narrows it too. WHAT IT REFUSES: a finding whose own prose names a divergence FROM THE PLAN while the boolean beside it says there is none, by eight tokens (`contradict* the plan`, `contrary to the plan`, `conflict* with the plan`, `diverg* from the plan`, `deviat* from the plan`, `at odds with the plan`, `inconsistent with the plan`, `the plan is wrong`), each written case-insensitively for the same reason as report.schema.json's `$defs/universalQuantifier`. EVERY TOKEN NAMES THE PLAN, and that is the whole design: a bare `contradicts` would refuse `the two schema comments contradict each other`, and `the plan requires` would refuse `the plan requires a deviations section and the M2 schemas already model one`, both of which are honest findings that do not contradict anything. Pricing those out is this phase's own worst hazard and the reason the token list is narrow rather than long. THE SENTENCE THAT USED TO STAND HERE, `EVERY TOKEN NAMES THE PLAN, AND THAT IS THE WHOLE DESIGN`, WAS THE ROUND-3 DEFECT AND IS CORRECTED RATHER THAN DELETED: naming the plan is what an ASSERTION of divergence and a DENIAL of one have in common, so the tokens caught both, and the denial is the plainest sentence a `contradicts-plan: false` record carries. Round 4 derived four of them against the shipped template and recorded their exit codes in delivery/work-history/m3-p4.md (finding DV3-002); `This does not contradict the plan; I checked section 2.3 first` is the first. R-035 records the finding VERBATIM, so rewording it was never available and the record was unwritable rather than merely awkward. THE BRANCH BELOW IS THE REPAIR: prose carrying a token is still writable, with the author declaring in `plan-language-note` why the sentence is not the assertion the token looks like. A LIST OF PERMITTED NEGATIONS WAS CONSIDERED AND REFUSED, because English negates, quotes and hedges these eight tokens in open-endedly many ways and any such list would be the same underived universal one level up, which is the mechanism the round-3 arbitration ruled on. RESIDUE, STATED RATHER THAN LEFT TO BE FOUND: neutral prose over a real contradiction still passes, exactly as `$defs/universalQuantifier` still passes an unlisted universal; `the plans` in the plural escapes the word boundary; a token split across a line break escapes the literal space, which is a residue this pattern SHARES with the two shipped patterns in report.schema.json rather than one it introduces; and nothing here can tell a true `plan-language-note` from a false one. The pattern narrows the escape; it does not seal it, and I did not find a way to make the marker TRUE by schema alone here. What checks the answer against the world is M3-P7's clean-room checklist.",
+          "type": "object",
+          "properties": {
+            "contradicts-plan": { "const": false },
+            "finding": {
+              "type": "string",
+              "pattern": "^(?:(?!\\b([Cc][Oo][Nn][Tt][Rr][Aa][Dd][Ii][Cc][Tt][A-Za-z]* [Tt][Hh][Ee] [Pp][Ll][Aa][Nn]|[Cc][Oo][Nn][Tt][Rr][Aa][Rr][Yy] [Tt][Oo] [Tt][Hh][Ee] [Pp][Ll][Aa][Nn]|[Cc][Oo][Nn][Ff][Ll][Ii][Cc][Tt][A-Za-z]* [Ww][Ii][Tt][Hh] [Tt][Hh][Ee] [Pp][Ll][Aa][Nn]|[Dd][Ii][Vv][Ee][Rr][Gg][A-Za-z]* [Ff][Rr][Oo][Mm] [Tt][Hh][Ee] [Pp][Ll][Aa][Nn]|[Dd][Ee][Vv][Ii][Aa][Tt][A-Za-z]* [Ff][Rr][Oo][Mm] [Tt][Hh][Ee] [Pp][Ll][Aa][Nn]|[Aa][Tt] [Oo][Dd][Dd][Ss] [Ww][Ii][Tt][Hh] [Tt][Hh][Ee] [Pp][Ll][Aa][Nn]|[Ii][Nn][Cc][Oo][Nn][Ss][Ii][Ss][Tt][Ee][Nn][Tt] [Ww][Ii][Tt][Hh] [Tt][Hh][Ee] [Pp][Ll][Aa][Nn]|[Tt][Hh][Ee] [Pp][Ll][Aa][Nn] [Ii][Ss] [Ww][Rr][Oo][Nn][Gg])\\b)[\\s\\S])*$"
+            }
+          }
+        },
+        {
+          "$comment": "M3-P4 FIX ROUND 4, FINDING DV3-002. THE `contradicts-plan: false` RECORD WHOSE VERBATIM PROSE CARRIES ONE OF THE EIGHT TOKENS, WITH THE AUTHOR SAYING WHY IT IS NOT THE ASSERTION THE TOKEN LOOKS LIKE. The sibling branch above is unchanged and stays the cheap path: prose free of the tokens owes nothing. WHAT THIS BRANCH COSTS: one short string, where the sibling alone cost the author the record. CARRYING `plan-language-note` WITH TOKEN-FREE PROSE IS A REJECTION, by the exactly-one rule of `oneOf`, which is the same discipline `schemas/final-report.schema.json`'s `$defs/enumerableSection` applies to `none: true` over real entries: an exception marker declared where the exception does not apply is a misdeclaration. WHAT IT DOES NOT REACH, measured rather than argued: the note is prose, so the round wrote the assertion `This contradicts the plan section 2.3` beside the note `I say it does not` and measured exit 0, which is in delivery/work-history/m3-p4.md with the rest. This raises the price of the lie from zero to a sentence a reviewer reads; it does not detect the lie, and M3-P7's clean-room checklist is where it is detected.",
+          "type": "object",
+          "required": ["contradicts-plan", "plan-language-note"],
+          "properties": {
+            "contradicts-plan": { "const": false },
+            "plan-language-note": { "type": "string", "minLength": 1, "pattern": "\\S" }
+          }
+        }
+      ]
+    }
+  }
+}

package/templates/charter.example.yaml

@@ -0,0 +1,54 @@
+# A minimal Tiphys project charter that validates against
+# schemas/charter.schema.json. Kernel plan M3, M3-P1 step 7.
+kind: charter
+identity:
+  name: example-service
+  repo: git@github.com:example/example-service.git
+  kernel-version-pin: 0.1.0
+# The mode ids are assurance-modes.yaml's, and the charter schema's enum is
+# held equal to them by the derived check charter-mode-enum-matches-modes.
+# This template said `standard` until M3-P3, which is a value no mode
+# definition has ever carried.
+delivery-mode: full
+assurance-tier: full
+yolo-permissions:
+  enabled: false
+  scope: []
+irreversible-decisions:
+  stack: Node 26, TypeScript, Postgres 16
+  language: TypeScript
+  framework: Fastify
+  core-data-model: >-
+    One tenant per organization; every row carries tenant_id and every query
+    is scoped by it.
+  tenancy: shared database, row-level tenant scoping
+  auth: OIDC through the organization's identity provider, no local passwords
+  deployment-topology: single region, one managed container service
+product-intent: |
+  A service that ingests supplier catalogues, normalizes them, and exposes one
+  search endpoint. Success is that a buyer finds the right part in one query.
+  Not in scope: pricing, ordering, or anything that writes to a supplier.
+constraints:
+  - No customer data leaves the region.
+  - The search endpoint answers in under 300ms at the 95th percentile.
+escalation-contract:
+  # The two DEFAULT stop-for entries. The second one is what makes turning
+  # verification off an owner decision instead of an implementer's edit
+  # (delivery/verification/release-verification-interface.md section 4.1).
+  # This is a default that is SHIPPED, not a rule anyone is proved to obey.
+  stop-for:
+    - any irreversible choice the charter is silent on
+    - a change from a declared release verification to `none`
+  route: >-
+    The orchestrator raises a decision record and notifies the owner
+    asynchronously; work on the affected phase stops.
+release-verification:
+  # RESERVED, NOT DESIGNED (DR-0014, D-M3-29). See the schema's $comment.
+  mode: reserved
+  note: >-
+    The real shape of this field is settled by the first real project charter
+    at M4's pilot. Until then a project declares reserved and says why.
+retention:
+  work-history: delivery/work-history/
+  evidence: delivery/evidence/
+  tuition: delivery/tuition/

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