@tiphys/kernel 0.0.0 → 0.2.0

package/gates.manifest.json

@@ -0,0 +1,257 @@
+{
+  "note": "This is the KERNEL'S OWN manifest and is repository-local by construction: gate commands invoke bin/tiphys.ts, which npm pack does not ship (files is [\"dist\"]). In CI the RUNNER is the compiled entry (dist/bin/tiphys.js, per kernel plan M2 step 9) while this gate is the source entry, so the runner resolves dist/src/gates/schemas and the gate resolves src/gates/schemas. Both copies are therefore exercised on every CI run, the runner's by its manifest load and record ingest and the gate's by self-check. Recorded here rather than left ambiguous (CR-813).",
+  "version": 1,
+  "gates": [
+    {
+      "id": "manifest-self-check",
+      "command": [
+        "node",
+        "bin/tiphys.ts",
+        "gates",
+        "self-check",
+        "--manifest",
+        "gates.manifest.json"
+      ],
+      "unitLabel": "schema documents validated",
+      "applicability": "required"
+    },
+    {
+      "id": "coverage",
+      "command": [
+        "node",
+        "src/gates/coverage.ts"
+      ],
+      "unitLabel": "finding ids checked",
+      "applicability": "required",
+      "precondition": {
+        "id": "coverage-inventory-exists",
+        "kind": "file-exists",
+        "path": "delivery/requirements/migration-table.md"
+      }
+    },
+    {
+      "id": "credential-scrub",
+      "command": [
+        "node",
+        "src/gates/credentials.ts",
+        "credential-scrub"
+      ],
+      "unitLabel": "credential sources probed",
+      "applicability": "required"
+    },
+    {
+      "id": "credential-token",
+      "command": [
+        "node",
+        "src/gates/credentials.ts",
+        "credential-token"
+      ],
+      "unitLabel": "tokens probed",
+      "applicability": "conditional",
+      "precondition": {
+        "id": "implementer-token-present-owner-action-a-3",
+        "kind": "command-exit-zero",
+        "command": [
+          "node",
+          "-e",
+          "process.exit(process.env.TIPHYS_IMPLEMENTER_TOKEN === undefined ? 1 : 0)"
+        ]
+      }
+    },
+    {
+      "id": "suite",
+      "command": [
+        "node",
+        "src/gates/suite.ts",
+        "--pin-root",
+        "src",
+        "--pin-root",
+        "bin",
+        "--pin-root",
+        "test"
+      ],
+      "unitLabel": "tests reported",
+      "applicability": "required",
+      "parameters": [
+        "base"
+      ]
+    },
+    {
+      "id": "citations",
+      "command": [
+        "node",
+        "src/gates/citations.ts"
+      ],
+      "unitLabel": "citations resolved",
+      "applicability": "required",
+      "precondition": {
+        "id": "citations-diff-touches-documents",
+        "kind": "diff-touches",
+        "paths": [
+          "delivery/plan/",
+          "delivery/verification/",
+          "delivery/decisions/",
+          "delivery/tuition/",
+          "delivery/requirements/",
+          "delivery/STATE.md"
+        ]
+      }
+    },
+    {
+      "id": "scope",
+      "command": [
+        "node",
+        "src/gates/scope.ts",
+        "--declarations",
+        "delivery/plan/phase-declarations"
+      ],
+      "unitLabel": "changed paths audited",
+      "applicability": "required",
+      "parameters": [
+        "base",
+        "head"
+      ],
+      "precondition": {
+        "id": "scope-branch-is-a-phase-branch",
+        "kind": "branch-matches",
+        "pattern": "claude/m[0-9]+-p[0-9]+-.*"
+      }
+    },
+    {
+      "id": "deploy",
+      "command": [
+        "node",
+        "src/gates/deploy.ts"
+      ],
+      "unitLabel": "release verifications satisfied",
+      "applicability": "conditional",
+      "precondition": {
+        "id": "deploy-release-verification-declared (an unmet result here is STRUCTURAL in any pre-merge bundle, not local to this repository: release verification runs post-merge against a commit that exists only once the merge has happened; kernel plan M2 section 1.4, investigation observation O-3)",
+        "kind": "file-exists",
+        "path": "release-verification.json"
+      }
+    },
+    {
+      "id": "migrations",
+      "command": [
+        "node",
+        "src/gates/migrations.ts"
+      ],
+      "unitLabel": "migrations compared",
+      "applicability": "conditional",
+      "precondition": {
+        "id": "migrations-release-verification-declared (an unmet result here is STRUCTURAL in any pre-merge bundle, not local to this repository: release verification runs post-merge against a commit that exists only once the merge has happened; kernel plan M2 section 1.4, investigation observation O-3)",
+        "kind": "file-exists",
+        "path": "release-verification.json"
+      }
+    },
+    {
+      "id": "clause-map",
+      "command": [
+        "node",
+        "scripts/check-clause-map.mjs"
+      ],
+      "unitLabel": "clause-map rows checked",
+      "applicability": "required"
+    },
+    {
+      "id": "red-witness",
+      "command": [
+        "node",
+        "src/gates/red-witness.ts"
+      ],
+      "unitLabel": "witnesses evaluated",
+      "applicability": "required",
+      "parameters": [
+        "base",
+        "head"
+      ],
+      "precondition": {
+        "id": "red-witness-diff",
+        "kind": "diff-touches",
+        "paths": [
+          "src/",
+          "bin/",
+          "plugin/"
+        ]
+      }
+    },
+    {
+      "id": "brief-drift",
+      "command": [
+        "node",
+        "scripts/check-brief-drift.mjs",
+        "--check"
+      ],
+      "unitLabel": "generated brief gate rows compared",
+      "applicability": "required"
+    },
+    {
+      "id": "typecheck",
+      "command": [
+        "node",
+        "src/gates/gate-classes.ts",
+        "typecheck",
+        "--project",
+        "tsconfig.src.json",
+        "--project",
+        "tsconfig.test.json",
+        "--project",
+        "plugin/tsconfig.json"
+      ],
+      "unitLabel": "source files type-checked",
+      "applicability": "required"
+    },
+    {
+      "id": "gate-classes",
+      "command": [
+        "node",
+        "src/gates/gate-classes.ts",
+        "gate-classes",
+        "--declarations",
+        "delivery/plan/phase-declarations",
+        "--registry",
+        "gate-registry.yaml"
+      ],
+      "unitLabel": "declared gate classes checked",
+      "applicability": "required",
+      "parameters": [
+        "phase"
+      ],
+      "precondition": {
+        "id": "gate-classes-branch-is-a-phase-branch",
+        "kind": "branch-matches",
+        "pattern": "claude/m[0-9]+-p[0-9]+-.*"
+      }
+    },
+    {
+      "id": "merge-preconditions",
+      "command": [
+        "node",
+        "src/gates/merge-preconditions.ts"
+      ],
+      "unitLabel": "merge preconditions evaluated",
+      "applicability": "conditional",
+      "parameters": [
+        "head",
+        "phase"
+      ],
+      "precondition": {
+        "id": "merge-preconditions-verdicts-present",
+        "kind": "command-exit-zero",
+        "command": [
+          "node",
+          "scripts/check-dual-review.mjs",
+          "--precondition",
+          "."
+        ]
+      }
+    }
+  ],
+  "destructiveCommands": [
+    "pool destroy",
+    "teardown",
+    "src/pool.ts",
+    "src/teardown.ts"
+  ]
+}

package/package.json

@@ -1,7 +1,76 @@
 {
   "name": "@tiphys/kernel",
-  "version": "0.0.0",
-  "description": "Placeholder. Reserved for the Tiphys delivery-process kernel. Do not install.",
+  "version": "0.2.0",
+  "description": "Tiphys kernel: the fleet orchestration toolbelt, delivered as an npm package.",
+  "type": "module",
   "license": "Apache-2.0",
-  "private": false
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThomasHendrickx/tiphys-ai-helmsman.git"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "bin": {
+    "tiphys": "dist/bin/tiphys.js"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/node_modules",
+    "LICENSE",
+    "AGENTS.md",
+    "gate-registry.yaml",
+    "gates.manifest.json",
+    "assurance-modes.yaml",
+    "checklists",
+    "role-model-config.yaml",
+    "roles",
+    "schemas",
+    "templates",
+    "tuition"
+  ],
+  "workspaces": [
+    "plugin"
+  ],
+  "overrides": {
+    "@tiphys/kernel": "file:."
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.src.json tsconfig.test.json plugin/tsconfig.json && npm run build:schemas && npm run build:runtime-deps",
+    "build:schemas": "node --input-type=module -e \"import { cpSync } from 'node:fs'; cpSync('src/gates/schemas', 'dist/src/gates/schemas', { recursive: true });\"",
+    "build:runtime-deps": "node --input-type=module -e \"import { cpSync, readFileSync } from 'node:fs'; const lock = JSON.parse(readFileSync('node_modules/.package-lock.json', 'utf8')); for (const [path, entry] of Object.entries(lock.packages ?? {})) { if (!path.startsWith('node_modules/') || entry?.dev === true || entry?.link === true) continue; cpSync(path, 'dist/' + path, { recursive: true }); }\"",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "gate:suite": "node src/gates/suite.ts --pin-root src --pin-root bin --pin-root test",
+    "prepack": "npm run build",
+    "gate:license": "node scripts/license-gate.mjs",
+    "prepublishOnly": "node scripts/license-gate.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.2",
+    "typescript": "7.0.2"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "commonmark": "0.31.2",
+    "yaml": "2.9.0"
+  },
+  "tiphys": {
+    "licenseAllowlist": [
+      "Apache-2.0",
+      "MIT",
+      "ISC",
+      "BSD-2-Clause",
+      "BSD-3-Clause"
+    ],
+    "thirdPartyCode": []
+  }
 }

package/role-model-config.yaml

@@ -0,0 +1,88 @@
+# THE KERNEL'S ROLE-TO-MODEL DEFAULTS (kernel plan M3, M3-P3; R-075).
+#
+# R-075, from process doc section 5: "Model tier per risk: strongest model for
+# money-path/architecture phases, investigations, and all reviews; cheaper tier
+# for mechanical phases (a measurement script, copy)."
+#
+# CONFIGURATION ONLY. M3 ships the data and no resolver. Binding is done by the
+# harness adapter (blueprint section 6) and the charter override is L4, which
+# lands at M4. DR-0010, which asks whether any judgment-layer fan-out should
+# target the harness's native orchestration primitive, is `status: open` with
+# "no action required before M4", so nothing here targets a harness, names an
+# executor, or names a model: a tier and a family POLICY, and nothing else.
+#
+# WHY A TIER AND NOT A MODEL. A model id in a versioned kernel artifact goes
+# stale in weeks and puts a vendor's product name inside the package. The
+# adapter maps tier to model at M4, where the mapping can change without a
+# kernel release.
+
+kind: role-model-config
+version: 1
+
+roles:
+  - role: orchestrator
+    tier: strongest
+    charter-override: allowed
+    rationale: >-
+      Arbitrates between disagreeing reviews with evidence (DR-0012 condition
+      6), decides what reaches the owner (DR-0016), and holds delegated merge
+      authority. Every one of those is a judgment call on the money path.
+
+  - role: investigator
+    tier: strongest
+    charter-override: allowed
+    rationale: >-
+      R-075 names investigations explicitly. The role's output is a root-cause
+      verdict with a runnable repro (R-015a), and a wrong verdict sends a whole
+      fix round at the wrong mechanism, which is the dominant cost shape the
+      fix-round contract was written after measuring.
+
+  - role: plan-writer
+    tier: strongest
+    charter-override: allowed
+    rationale: >-
+      R-075 names architecture phases. The plan is what every later phase is
+      measured against, and plan v1's binding rule is that what is not written
+      there is not being made.
+
+  - role: adversarial-plan-reviewer
+    tier: strongest
+    charter-override: allowed
+    # T-001: an external review on a different model family found two genuine
+    # defects that had survived three same-family internal rounds plus one
+    # targeted verification. The record's own ask was "at minimum, a
+    # charter-level option to route one review round of a full-mode plan
+    # through a different family"; this is that option, as a policy.
+    review-model-family: must-differ-from-previous-round
+    rationale: >-
+      R-075 puts all reviews at the strongest tier, and T-001 is the recorded
+      miss that made same-family review rounds a known blind spot.
+
+  - role: implementer
+    tier: cheaper
+    # R-075 IS PHASE-CLASS SCOPED FOR THIS ROLE, so a flat tier would drop half
+    # of it. The default is the mechanical case the rule names ("a measurement
+    # script, copy"); the classes below are where the same rule raises it.
+    # Nothing in M3 classifies a phase, and no resolver reads this field.
+    strongest-for:
+      - money-path
+      - architecture
+    charter-override: allowed
+    rationale: >-
+      R-075 puts mechanical phases at the cheaper tier and money-path and
+      architecture phases at the strongest one, so the implementer is the one
+      role whose tier is a function of the phase rather than of the role.
+
+  - role: clean-room-reviewer
+    tier: strongest
+    charter-override: allowed
+    # DR-0012 condition 1: two independent clean-room reviews of the same head,
+    # produced on different model families. That is a constraint between the
+    # two SIBLING reviews of one pull request, which is a different axis from
+    # T-007's two review CONTRACTS in assurance-modes.yaml; full mode requires
+    # both and they are not the same rule.
+    review-model-family: must-differ-from-sibling-review
+    rationale: >-
+      R-075 puts all reviews at the strongest tier. This is also the role
+      DR-0012 made the signature on every merge, so cheapening it would
+      cheapen the merge condition itself.

package/roles/README.md

@@ -0,0 +1,128 @@
+# roles/
+
+The kernel's role briefs. One markdown file per role of blueprint section 6,
+each carrying YAML frontmatter validated by `schemas/role-brief.schema.json`,
+plus `_shared-dispatch-contract.md`, which is not a brief and is included by
+all of them.
+
+Delivered by M3-P5 (investigator, plan writer, adversarial plan reviewer) and
+M3-P6 (implementer, clean-room reviewer). The orchestrator's brief is
+`AGENTS.md` at the repository root and uses the same frontmatter schema with
+`role: orchestrator` (M3-P9).
+
+## Why markdown and not a structured document
+
+Section 1.5 of the M3 plan grants role briefs a JUSTIFIED EXCEPTION to the
+lintable-schema-first rule. A brief is instruction prose addressed to a
+reasoning agent, and its effect comes from argument, ordering and emphasis,
+which have no field decomposition that preserves them: splitting a brief into
+fields produces either one giant string field, which is structure that carries
+nothing, or a set of fragments no agent reads as an argument. The frontmatter
+carries everything that IS enumerable and is schema-validated. The reason is
+not that markdown is easier.
+
+## The three mechanical contracts
+
+A brief is prose, and three things about it are checked by machine.
+
+### 1. Frontmatter
+
+The file OPENS with a `---` fence, and a second `---` closes the block. The
+enclosed YAML validates against `schemas/role-brief.schema.json`:
+
+```
+tiphys validate --type role-brief roles/investigator.md
+```
+
+The body is not schema-parsed. A `---` in the middle of a document is a
+horizontal rule and is not a frontmatter fence: only the block at the top of
+the file is read as frontmatter.
+
+### 2. The include
+
+A line whose entire content is
+
+```
+$include: _shared-dispatch-contract.md
+```
+
+is replaced by that file's text, resolved against `roles/` (the directory the
+including brief is in). Includes are ONE LEVEL DEEP: an include inside an
+included file is refused by name, because a nested include would be a second
+place the shared text could come from and the point of the shared block is
+that there is exactly one.
+
+`_shared-dispatch-contract.md` exists because M3-P5's three briefs and
+M3-P6's two carry the same two dispatch-contract clauses. Five independently
+editable copies of one rule drift into five different rules; one copy cannot.
+A phase that needs the shared text CHANGED escalates rather than editing it,
+because the same edit changes every brief that includes it.
+
+### 3. The clause round trip
+
+Every id in the frontmatter's `clauses[]` must occur EXACTLY ONCE as a body
+heading anchor of the include-expanded body, and every anchor must be declared
+in `clauses[]`. Both directions are checked by
+`tiphys validate --type role-brief`, and a violation exits nonzero naming the
+clause id.
+
+An anchor is a markdown heading of the form
+
+```
+## clause <clause-id>: <title>
+```
+
+The word `clause` is the marker and the title is optional. The form is
+explicit on purpose: an anchor rule that guessed, such as "a heading whose
+text looks like an identifier", would classify ordinary headings like
+`## Scope` as anchors and redden every brief that has one.
+
+What the round trip buys is that a clause id cannot be a LABEL WITH NOTHING
+BEHIND IT. `scripts/check-clause-map.mjs` asks only whether the id occurs
+somewhere in the file, so without this check a brief could satisfy the clause
+map by listing ids in its frontmatter and writing no text at all.
+
+What it does NOT buy, stated so nobody reads it as more: it proves PRESENCE
+and never content. Whether the text under `## clause R-004` says what R-004
+says, or the opposite of it, is judgment, and the M3-P5 plan section records
+that no criterion reaches the general case.
+
+## Mandated reading
+
+`mandated-reading[]` is an ORDERED list of paths, resolved against the
+INSTALLED KERNEL ROOT (the directory holding `roles/`), not against the
+current working directory. `tiphys brief compose` checks every one of them
+before it emits anything and exits nonzero naming the first that does not
+resolve.
+
+The paths are established with `classifyEntry` and are NEVER OPENED by the
+check, so a missing path and a named pipe are two different reported failures
+rather than one hang (D-M3-27). That distinction is not pedantry: a mandated
+reading entry pointing at a FIFO would otherwise block `brief compose` forever
+with no output and no exit code.
+
+Because these paths resolve against the kernel root, a brief may only mandate
+reading that the kernel SHIPS. `package.json`'s `files` entry is the list of
+what that is.
+
+## Composition
+
+```
+tiphys brief compose --role plan-writer \
+  --phase templates/plan.example.yaml --phase-id M9-P1 [--out brief.md]
+```
+
+The composed brief contains, in order: a frontmatter-driven header carrying
+the resolved mandated-reading list, the brief body with includes expanded, the
+named phase rendered from the plan instance, and the fleet warnings file when
+one is present in the current working directory.
+
+The rendered phase is a COMPLETE projection: every required field of
+`schemas/plan.schema.json`'s phase definition is rendered under its own
+heading. The renderer's field list is hand-written in `src/roles.ts` and the
+test that guards it reads the schema, so adding a required phase field reddens
+that test until the renderer is extended, rather than silently shrinking every
+brief.
+
+What composition writes is what `tiphys spawn --brief` consumes. `src/brief.ts`
+remains the assembly spawn performs at launch and is unchanged.

package/roles/_shared-dispatch-contract.md

@@ -0,0 +1,87 @@
+# The dispatch contract
+
+THE ONE COPY. Every role brief in `roles/` and `AGENTS.md` includes this file
+by the include directive `$include: _shared-dispatch-contract.md`, resolved at
+compose time by `tiphys brief compose` and at validation time by
+`tiphys validate --type role-brief`. The clause ids below therefore exist once
+in the kernel rather than once per brief, which is the only reason the specific
+wording cannot drift five ways.
+
+Changing the text below changes every brief that includes it. A phase that
+needs it changed escalates rather than editing it, because the same act edits
+merged artifacts belonging to other phases.
+
+This file has no frontmatter of its own and is not a role brief. It is never
+composed on its own and is never validated as a role brief.
+
+## clause incremental-output: create the artifact in the first minutes, append as you go
+
+Create your output artifact within the FIRST MINUTES of work, before the work
+is done, and append to it as you go. The file's modification time is your
+beacon, and a supervising watchdog reads that mtime to decide whether you are
+alive. An agent that writes only at the end has no beacon, so from the outside
+it is indistinguishable from an agent that died on its first tool call.
+
+Write what you just tried, the command you ran, what it printed, what you
+concluded, and what you are about to do next. Do not save the write-up for the
+end and do not polish it as you go.
+
+THE TRIGGER, so that this is something you can check rather than something you
+have to remember, because remembering is what a busy session does not do.
+Append at whichever of these comes first: before you run a command you expect
+to take more than a minute, write down what you are about to run and why; after
+any command whose output you will cite, paste that output then rather than
+later; at every conclusion you reach, including the ones you go on to discard.
+The self-check is one line and you can run it against yourself at any moment:
+if you cannot say which tool call your last append followed, you are already
+behind, so stop and write.
+
+Two things this buys that a final write-up cannot. A death mid-round leaves a
+PARTIAL RESULT rather than nothing, which is the difference between salvage and
+total loss. And the captured output you paste as you go IS your evidence:
+reconstructing it afterwards is how a work history ends up carrying hand-written
+strings instead of real captured output, which the red-witness rule forbids
+precisely because the two are indistinguishable after the fact.
+
+Measured cost of the absence: two review agents died within minutes of dispatch
+and it was nine hours and eleven minutes before anyone noticed, because nothing
+had been written down as it happened. That is the largest single waste this
+project has recorded, and the entire loss was wall clock.
+
+WHAT A STALE BEACON COSTS, which the watchdog sentence above implies and does
+not state. Staleness is measured against a threshold the supervisor sets and
+not one you agree to, and a stale beacon is read as a DEAD AGENT, because from
+the outside those two are the same observation. The supervisor is then entitled
+to interrupt you, to dispatch a replacement, and to salvage your artifact as it
+stands and continue from that. What you had not written down is not handed
+over; it is lost, and the work is redone without it. The consequence lands on
+the round rather than on you, which is why it is worth more to you to write
+than to finish the thought first.
+
+AND THE HONEST LIMIT OF THIS CLAUSE. Nothing here forces the append. This is a
+rule you follow, and what the kernel adds is to make the absence VISIBLE and
+the consequence real, not to make the omission impossible. The teeth are the
+watchdog, which is the supervisor's half in the clause below, so a dispatch
+made without one leaves this clause with none. If you are the one dispatching,
+arm it in the same turn.
+
+## clause beacon-is-not-a-claim: the artifact is the report, and the guard tests freshness
+
+Do not report progress by asserting it. "Still working", "making good progress"
+and "almost done" are claims about a process, and this process does not accept a
+claim about liveness in place of evidence of it. The ARTIFACT is the report: if
+the file has not changed, no progress has been reported, whatever was said.
+
+This is one half of a rule written from two ends. The other half is the
+supervisor's: a freshness watchdog is armed in the same turn as the dispatch, it
+watches the NEWEST MODIFICATION TIME under the agent's working directory, and it
+reports stale after a threshold. It must test FRESHNESS, never existence and
+never completion. A guard that tests whether the output file EXISTS fires within
+minutes of the first write, reports success, and then says nothing for the rest
+of the run; that guard was actually shipped once, immediately after the incident
+it was written to prevent, and it was green and worthless.
+
+The two halves need each other. A watchdog watching freshness needs something
+freshening, which is the clause above; and an agent freshening a file needs
+something watching, which is the supervisor's duty. Neither half alone reaches
+the failure.