@tiphys/kernel 0.0.0 → 0.2.0

package/schemas/verdict.schema.json

@@ -0,0 +1,295 @@
+{
+  "$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",
+    "head",
+    "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"
+    },
+    "head": {
+      "$comment": "M4-P10, discharging DR-0012 condition 1's head clause (delivery/decisions/DR-0012-delegated-merge-authority.md:22): two independent clean-room reviews exist FOR THE CURRENT HEAD. WHY IT IS REQUIRED RATHER THAN OPTIONAL, decided here because the plan left the choice open and the migration cost is not zero. Before this field the only thing scoping a set of verdicts to one head was the DIRECTORY the operator pointed the gate at, a convention recorded as a declared reading in delivery/work-history/m3-p9.md and enforced by nothing. An OPTIONAL head leaves that convention in place for every document that omits it, which is the whole existing population, so the gate would keep grouping by directory and the clause would stay asserted by a human while reading as checked. Required is the only spelling that removes the convention. WHY FORTY LOWERCASE HEX AND NOT AN ABBREVIATION. A short sha and a full sha are two spellings of ONE fact, and no canonical form reconciles them: nothing here can know that a seven-character value is a prefix of a forty-character sibling without resolving both against a repository this schema is never given. Two spellings of one head would then form two groups of one, which is the fail-open direction, because a group of one is never compared to anything. The pattern refuses the abbreviation at the document boundary instead. Case is refused here and ALSO folded downstream by the derived check's `establishField`, so the two layers agree rather than one relying on the other. WHAT IT DOES NOT BUY, stated rather than left to be found. Nothing here checks that the value names a commit that exists, or that it is the commit the reviewer actually read; the field makes the CLAIM explicit and comparable between two documents, it does not make it true. And a verdict cannot carry the sha of the commit that CONTAINS it, because committing the verdict changes the tree and therefore the sha. `head` names the commit that was REVIEWED, which is an ancestor of the commit carrying the verdict.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "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": "WIDENED TO `medium` BY M4-P10, AND THAT WIDENING IS THE POINT OF THE FIELD LIST BELOW. As shipped by M3-P7 this enum read [high, critical] while DR-0012 condition 2 (delivery/decisions/DR-0012-delegated-merge-authority.md:23) bars an unresolved finding at high OR MEDIUM. So a verdict reading APPROVE beside a finding the review itself ranked `medium` validated at exit 0, and the merge precondition the schema exists to carry was one severity wider than the schema. `low` is deliberately still mergeable, which is what that same line of DR-0012 says. 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": ["medium", "high", "critical"]
+            }
+          }
+        }
+      }
+    }
+  },
+  "then": {
+    "$comment": "So APPROVE beside a medium, high or critical finding fails HERE, naming the verdict field (widened from high by M4-P10). 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/schemas/write-bypass.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiphys.dev/schemas/write-bypass.schema.json",
+  "title": "Tiphys write-bypass declaration",
+  "$comment": "Kernel plan M4, M4-P9 (delivery/plan/kernel-plan-m4.md:1501), discharging M4-D-26. THE DOCUMENT IS THE CURRENT STATE AND IS REWRITTEN IN PLACE; the append-only evidence log beside it is a separate file that NO DECISION EVER READS, which is constraint C-1 made structural rather than promised. Reading the bypass state from the tail of that log is exactly what C-1 forbids, and a schema cannot forbid it, so the split is enforced by the decision function having no log parameter at all (plugin/src/hooks/project-write-block.ts). WHAT THIS DOCUMENT DOES REACH is the hazard the plan names first: a bypass with no expiry, so that the first infrastructure hotfix disables the project-write block permanently. `expiresAt` is REQUIRED and is an ABSOLUTE INSTANT, never a duration, so a bypass that never expires is unrepresentable rather than discouraged. WHAT IT CANNOT REACH, each with its instrument: (a) whether the expiry is in the future, which is a comparison against a clock and belongs to the reader (decideWrite takes `now` as a parameter for exactly that reason); (b) whether the listed paths lie inside the declared project, which compares sibling fields and is Kind B; (c) whether the declaration was written by an orchestrator rather than by an agent, which no document can establish about itself.",
+  "description": "What the orchestrator writes to <fleet>/write-bypass.json to permit a named, time-boxed set of working-tree writes in one project clone that the project-write block would otherwise refuse. A bypass is a FIRST-CLASS DECLARED ACT: it names the project, lists the paths explicitly, gives a reason, and expires at an instant it states.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "contractVersion",
+    "project",
+    "paths",
+    "reason",
+    "expiresAt",
+    "declaredBy",
+    "declaredAt"
+  ],
+  "properties": {
+    "kind": {
+      "$comment": "The artifact type, so `tiphys validate --type auto` resolves this document without being told, and so the ONE row in src/commands/validate.ts's TYPE_TABLE serves the `--type` table and the auto resolver at once (M3R-001).",
+      "type": "string",
+      "const": "write-bypass"
+    },
+    "contractVersion": {
+      "$comment": "A closed set rather than a minimum, for the reason every other shipped schema records: the authoring vocabulary has no `minimum` keyword.",
+      "type": "string",
+      "enum": ["1"]
+    },
+    "project": {
+      "$comment": "The ABSOLUTE path of the one project working tree this declaration is about. One declaration, one project: a bypass covering several projects at once is the shape that quietly becomes permanent, because the reason that justified it for the first stops being read for the rest.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^/"
+    },
+    "paths": {
+      "$comment": "THE EXPLICIT PATH LIST, and `minItems: 1` is what makes it explicit. An empty list would be a declaration that names a project and permits nothing, which reads as an off switch waiting for an edit. Each entry is absolute; the reader additionally requires each to lie inside `project`, which is a sibling-field comparison no keyword here reaches.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^/"
+      }
+    },
+    "reason": {
+      "$comment": "Why the hotfix could not go through the ordinary pipeline. Required because a bypass with no stated reason is indistinguishable, a week later, from a block that was simply switched off.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "expiresAt": {
+      "$comment": "THE ABSOLUTE EXPIRY INSTANT, and it is the single most load-bearing field in this document. The plan's hazard class opens with 'a bypass with no expiry, so the first hotfix disables the block permanently'; making this required is how that state stops being representable. It is an instant and never a duration, because a duration has to be added to something and the thing it would be added to is a clock this document has no way to read.",
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$"
+    },
+    "declaredBy": {
+      "$comment": "Who declared it, verbatim. A bypass is an act by a role, and the evidence log records the writes it permitted; this is the only field that says who is answerable for them.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "declaredAt": {
+      "$comment": "When it was declared. Paired with `expiresAt` it gives the window a reviewer reads, and it is what every refusal names when the declaration did not apply.",
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$"
+    }
+  }
+}

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/