@tiphys/kernel 0.0.0 → 0.1.0

package/checklists/plan-review.yaml

@@ -0,0 +1,103 @@
+# THE ADVERSARIAL PLAN-REVIEW CHECKLIST (kernel plan M3, M3-P7 step 2).
+#
+# Run against a PLAN, before any of it is dispatched. The three canonical
+# probes are R-026b, R-027 and R-028a, and each one is written to be
+# unanswerable without opening something: R-027 carries the process document's
+# own zero-amount-rows illustration, and R-028a names the artifact that counts
+# as proof so a testability claim cannot be admired instead of tested.
+kind: checklist
+id: plan-review
+applies-to: >-
+  a plan document before dispatch, read adversarially: the reviewer is looking
+  for the phase that cannot be built as written, not for reasons to approve.
+
+probes:
+  # R-026b. Hidden dependencies and semantic coupling ABOVE the file-overlap
+  # floor. File overlap is what the M5 pre-pass computes mechanically; this
+  # probe is the part no pre-pass reaches.
+  - id: hidden-dependency-above-file-overlap
+    probe: >-
+      Which phases share MEANING rather than files? Two phases with disjoint
+      file lists still collide when one renames a key the other reads, changes
+      a value's vocabulary, moves an ordering another relies on, or changes
+      what a shared registry row means. The file-overlap pre-pass computes the
+      floor and cannot see any of those. Name each pair you found, the shared
+      concept, and the phase whose assumption breaks; then name the pairs you
+      examined and cleared, because a list of collisions with no stated scope
+      is indistinguishable from a search that looked in the wrong place.
+    applies-to: plan-structure
+    evidence-required: true
+
+  - id: grounding-names-a-real-artifact
+    probe: >-
+      Does each phase's `grounding` name artifacts that will EXIST when it
+      starts, and does its `blocked-by` follow from that rather than from
+      habit? A `blocked-by` naming a phase whose artifacts the grounding never
+      mentions is an ordering habit serialising work that could run in
+      parallel; the reverse, a grounding consuming a phase the `blocked-by`
+      does not name, is a phase that will be dispatched before its inputs
+      exist. Check both directions per phase and say which you found.
+    applies-to: plan-structure
+    evidence-required: true
+
+  # R-027. Probe every fix shape for THE STATE THAT CAN NO LONGER EXIT, with
+  # the process document's own illustration carried in the probe text so the
+  # question cannot be answered from the phrase alone.
+  - id: fix-shape-state-that-cannot-exit
+    probe: >-
+      For every fix this plan proposes, what state does it create that can no
+      longer be exited? The process document's own illustration: a repair that
+      writes rows with a ZERO amount leaves records that are structurally
+      valid, that every later query counts, and that no reconciliation can
+      distinguish from real ones, so the system can enter that state and never
+      leave it. Walk each fix and name the state, the transition INTO it, and
+      the transition OUT of it. A fix with no stated exit is the finding.
+    applies-to: fix-shapes
+    evidence-required: true
+
+  - id: fix-shape-partial-application
+    probe: >-
+      What does each fix leave behind if it is interrupted halfway? Name the
+      point of no return in each one, and whether re-running it from the start
+      is safe. A fix that is only correct when it completes is a fix that has
+      not been designed for the case it exists to handle.
+    applies-to: fix-shapes
+    evidence-required: true
+
+  # R-028a. TEST THE TESTABILITY CLAIMS. The accepted evidence is the M2-P2
+  # red-witness harness's own evidence file, not the plan's assertion that
+  # something is testable.
+  - id: testability-claim-tested
+    probe: >-
+      For every claim in this plan that something is testable, guarded or
+      witnessed, what is the accepted proof? The harness's captured evidence
+      file (`witness-records.json`, whose per-member `runs[].exitCode` and
+      `failedNamedTests` record what actually ran) is the proof; the plan's
+      own sentence is not. Where no such file can exist yet because the
+      behaviour is not built, say so in those words and mark the claim as
+      owed, rather than letting an untested assertion pass as a tested one.
+    applies-to: testability
+    evidence-required: true
+
+  - id: acceptance-criterion-is-falsifiable
+    probe: >-
+      Is each acceptance criterion FALSIFIABLE? "Works correctly" is banned;
+      the register is a command, its exit code and a count ("node --test exits
+      0 and reports N tests, N greater than zero"). Quote every criterion that
+      names no command, no observable output and no count, and propose the
+      falsifiable form. A criterion nobody can fail is a criterion nobody has
+      to meet.
+    applies-to: testability
+    evidence-required: true
+
+  - id: hazard-class-is-not-the-criteria-reworded
+    probe: >-
+      Does each phase's declared hazard class name something its own
+      acceptance criteria CANNOT reach? T-007 records a phase meeting fifteen
+      of fifteen executed criteria while live-locking every supervision
+      command. A hazard class that is the criteria list reworded reproduces
+      that failure while appearing to fix it. For each class, name the
+      criterion that reaches it or state that none does and name the
+      instrument that does.
+    applies-to: plan-structure
+    evidence-required: true

package/dist/bin/tiphys.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/tiphys.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { EX_USAGE, run } from "../src/cli.js";
+function singleLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+try {
+    process.exitCode = await run(process.argv.slice(2));
+}
+catch (error) {
+    const usage = error?.usage === true;
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`tiphys: ${singleLine(message)}\n`);
+    process.exitCode = usage ? EX_USAGE : 1;
+}

package/dist/src/brief.d.ts

@@ -0,0 +1,32 @@
+import type { Fleet } from "./fleet.ts";
+/**
+ * Brief assembly (kernel plan v1, M1-P4 step 2; R-033b, R-083b).
+ *
+ * The brief for a task is written once, at spawn, to tasks/<id>/brief.md:
+ * the operator's brief file verbatim, followed by the fleet's
+ * environment-warnings file verbatim when the fleet has one. The
+ * warnings file is <fleet>/warnings.md (fleet root, tracked content, not
+ * the ignored state/ area). When no warnings file exists, brief.md is
+ * byte-identical to the brief file.
+ *
+ * Verbatim means verbatim: no heading, no banner, no rewriting. A brief
+ * is the durable instruction an implementer is judged against, and a
+ * kernel that edits it makes the audit trail lie. The only byte this
+ * module may add is a single newline between the two documents when the
+ * brief does not already end in one.
+ */
+/** The fleet's environment-warnings file, appended to every brief. */
+export declare const WARNINGS_FILE = "warnings.md";
+export declare function warningsPath(fleet: Fleet): string;
+export type BriefResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Assemble tasks/<id>/brief.md from briefFile. Returns the written path.
+ * The task directory must already exist.
+ */
+export declare function assembleBrief(fleet: Fleet, taskId: string, briefFile: string): BriefResult;

package/dist/src/brief.js

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { briefPath } from "./task.js";
+/**
+ * Brief assembly (kernel plan v1, M1-P4 step 2; R-033b, R-083b).
+ *
+ * The brief for a task is written once, at spawn, to tasks/<id>/brief.md:
+ * the operator's brief file verbatim, followed by the fleet's
+ * environment-warnings file verbatim when the fleet has one. The
+ * warnings file is <fleet>/warnings.md (fleet root, tracked content, not
+ * the ignored state/ area). When no warnings file exists, brief.md is
+ * byte-identical to the brief file.
+ *
+ * Verbatim means verbatim: no heading, no banner, no rewriting. A brief
+ * is the durable instruction an implementer is judged against, and a
+ * kernel that edits it makes the audit trail lie. The only byte this
+ * module may add is a single newline between the two documents when the
+ * brief does not already end in one.
+ */
+/** The fleet's environment-warnings file, appended to every brief. */
+export const WARNINGS_FILE = "warnings.md";
+export function warningsPath(fleet) {
+    return join(fleet.root, WARNINGS_FILE);
+}
+/**
+ * Assemble tasks/<id>/brief.md from briefFile. Returns the written path.
+ * The task directory must already exist.
+ */
+export function assembleBrief(fleet, taskId, briefFile) {
+    let brief;
+    try {
+        brief = readFileSync(briefFile, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `cannot read brief file ${briefFile}: ${error.message}`,
+        };
+    }
+    let content = brief;
+    const warnings = warningsPath(fleet);
+    if (existsSync(warnings)) {
+        let warningsText;
+        try {
+            warningsText = readFileSync(warnings, "utf8");
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: `cannot read fleet warnings file ${warnings}: ${error.message}`,
+            };
+        }
+        const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+        content = `${content}${separator}${warningsText}`;
+    }
+    const target = briefPath(fleet, taskId);
+    writeFileSync(target, content);
+    return { ok: true, value: target };
+}

package/dist/src/checklists.d.ts

@@ -0,0 +1,169 @@
+/**
+ * READING AND RESOLVING REVIEW CHECKLISTS (kernel plan M3, M3-P7 steps 2 to
+ * 5; R-054, T-001).
+ *
+ * `checklists/` ships at the package root beside `gate-registry.yaml`,
+ * `assurance-modes.yaml` and `schemas/`. This module locates it, decodes a
+ * checklist, merges a per-phase extra probe file into it, and orders the
+ * result under a declared framing. It answers one question: WHICH PROBES, IN
+ * WHICH ORDER, does this reviewer answer.
+ *
+ * NO VALIDATION HAPPENS HERE, deliberately, and this is the same split
+ * `src/modes.ts` documents: `tiphys validate --type checklist` decides whether
+ * a document is well formed, and duplicating its rules in a reader would
+ * produce a second opinion to keep in sync. The COMMAND validates before it
+ * serves (`src/commands/checklist.ts`), which is where the M3-P3 fix round put
+ * that duty after shipping a reader that printed without checking.
+ *
+ * THE MERGE FAILURES ARE FAILURES HERE AND NOT WARNINGS. An extra file
+ * reusing a canonical probe id is a COLLISION and names both sources; an
+ * extra probe missing `evidence-required` is a refusal; and, added in fix
+ * round 2, an extra file DECLARING A FRAMING is a refusal, because framings
+ * are read from the canonical checklist only and the entry point was
+ * previously dropped without a word. Last-wins and silent-drop are the same
+ * dangerous state seen from two sides: the phase's own hazard class names "an
+ * extra-probe merge that silently overrides a canonical probe instead of
+ * colliding", and a silent anything is how a per-phase file quietly diverges
+ * from the standing checklist.
+ *
+ * ORDERING IS BY SCOPE AND FILE POSITION, NEVER BY PROBE ID. A framing names
+ * `applies-to` scopes; probes in a named scope lead, scope by scope, and
+ * inside one scope the FILE ORDER decides. That is what makes CLAUDE.md's
+ * "the reviewer's FIRST check is item 3" falsifiable: move the probe later in
+ * the file and the resolved head changes. A framing that named probe ids
+ * would pin the head wherever the probe sat, which is the hazard class's
+ * "ordering expressed as a comment rather than as position" one level up.
+ */
+/** The shipped directory's basename, at the package root. */
+export declare const CHECKLISTS_DIRNAME = "checklists";
+/** One probe as the document declares it. */
+export interface Probe {
+    id: string;
+    probe: string;
+    appliesTo: string;
+    evidenceRequired: boolean;
+    verifiesGate?: string;
+    /** Where this probe came from, for the collision message. */
+    source: string;
+}
+/** One declared entry point into the same probe list. */
+export interface Framing {
+    id: string;
+    entryPoint: string;
+    ordersProbes: string[];
+}
+export interface Checklist {
+    id: string;
+    appliesTo: string;
+    probes: Probe[];
+    framings: Framing[];
+    /** The decoded document, for the validator to see unaltered. */
+    raw: unknown;
+    /** The file this was read from. */
+    path: string;
+}
+type Read<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The shipped `checklists/` directory, found by walking up from this module. */
+export declare function checklistsDirectory(): string;
+/** Every checklist id the shipped directory declares, by filename, sorted. */
+export declare function shippedChecklistIds(): string[];
+/**
+ * Project a decoded checklist document into the shape the resolver uses.
+ *
+ * FIELDS ABSENT FROM THE DOCUMENT STAY ABSENT rather than becoming defaults,
+ * with one exception stated here so it is not a surprise: `evidence-required`
+ * is projected as `false` when it is absent, and the CALLER is what refuses
+ * such a probe. Defaulting it to `true` would let a probe missing the field
+ * merge in as though it carried the stronger obligation, which is R-054's
+ * second named failure passing silently.
+ */
+export declare function projectChecklist(document: unknown, path: string, source: string): Read<Checklist>;
+/**
+ * Read a checklist document from an explicit path.
+ *
+ * The path is OPERATOR-SUPPLIED (D-M3-27), so it is classified before it is
+ * opened rather than opened and hoped about: a named pipe at `--extra` is a
+ * reported refusal, never a command that blocks forever.
+ */
+export declare function readChecklistFile(path: string, source: string): Read<Checklist>;
+/** Read a shipped checklist by id, or say which ids exist. */
+export declare function readShippedChecklist(id: string): Read<Checklist>;
+export interface MergeProblem {
+    /** The probe id at fault. */
+    probe: string;
+    reason: string;
+}
+/**
+ * Merge an extra probe file into a canonical checklist.
+ *
+ * BOTH FAILURES ARE COLLECTED RATHER THAN THROWN AT THE FIRST, so an author
+ * fixing an extra file sees every problem in one run instead of one per
+ * invocation.
+ */
+export declare function mergeExtraProbes(canonical: Checklist, extra: Checklist): {
+    probes: Probe[];
+    problems: MergeProblem[];
+};
+/**
+ * An extra file may not declare a framing, and saying so is a REFUSAL.
+ *
+ * M3-P7 FIX ROUND 2, H-2 MEMBER 2. `resolveChecklist` reads
+ * `request.checklist.framings` and only that, so a framing declared in an
+ * `--extra` file was neither merged nor mentioned: the run exited 0 with an
+ * empty stderr and the author's entry point was gone. That is a SILENT NO-OP
+ * on R-054's own use case, and the extra file validates as a full checklist
+ * document, so declaring a framing in one is the natural thing to try.
+ *
+ * BOTH SHAPES ARE REFUSED, colliding and not, because the mechanism is the
+ * same one: the extra document's framings are never read. Refusing only the
+ * COLLIDING one would fix the instance the review constructed and leave the
+ * mechanism, which is exactly the fix-round failure CLAUDE.md's contract
+ * exists against. The two get different messages because the consequences
+ * differ: a collision is also the shape that would let a per-phase file
+ * shadow a standing entry point if the merge were ever added, and the
+ * message says which document wins today.
+ *
+ * IT IS A REFUSAL RATHER THAN A MERGE. Merging extra framings would be a new
+ * capability, and nothing asks for one; what was wrong was the silence.
+ * Nothing depends on the old behaviour: `framings` is not in the checklist
+ * schema's `required`, so an extra file that declares none is unaffected.
+ */
+export declare function extraFramingRefusals(canonical: Checklist, extra: Checklist): string[];
+/**
+ * Order probes under a framing.
+ *
+ * Probes whose `applies-to` scope is named by the framing come first, scope
+ * by scope in the framing's order, and inside a scope in FILE ORDER. Every
+ * probe in no named scope follows, also in file order. NOTHING IS DROPPED: a
+ * framing changes what a reviewer reads first and never what they read at
+ * all, because a framing that filtered would let an entry point silently
+ * retire a probe.
+ */
+export declare function orderUnderFraming(probes: readonly Probe[], framing: Framing): Probe[];
+export interface ResolveRequest {
+    checklist: Checklist;
+    extra?: Checklist;
+    framingId?: string;
+}
+export interface Resolution {
+    probes: Probe[];
+    framing?: Framing;
+}
+export type ResolveOutcome = {
+    ok: true;
+    value: Resolution;
+} | {
+    ok: false;
+    reasons: string[];
+};
+/** Merge, then order. The two failures above and an unknown framing are refusals. */
+export declare function resolveChecklist(request: ResolveRequest): ResolveOutcome;
+/** The resolved list as lines, the framing's entry point at the head. */
+export declare function renderResolution(checklist: Checklist, resolution: Resolution): string[];
+export {};