@hyperdreamer/pi-webui 1.10.7 → 1.11.0-beta.10

package/optional-skills/deterministic-subagent-driven-development/references/state-machine.md

@@ -0,0 +1,177 @@
+# SDD State Machine Reference
+
+The reducer in `scripts/lib/state-machine.mjs` is the authority. This document
+describes it; it never redefines it. `TRANSITIONS` and `PHASES` are exported and
+the test suite asserts this table against them, so drift fails a test rather than
+misleading a reader.
+
+## Contents
+
+- [Two rules that shape everything](#two-rules-that-shape-everything)
+- [Canonical direction of truth](#canonical-direction-of-truth)
+- [Phases](#phases)
+- [Transitions](#transitions)
+- [Counters and their bounds](#counters-and-their-bounds)
+- [The finding ledger](#the-finding-ledger)
+- [Dispatch identity and the ambiguity window](#dispatch-identity-and-the-ambiguity-window)
+- [Recovery authority](#recovery-authority)
+
+## Two rules that shape everything
+
+**Recording a result and deciding what it means are separate transitions.** A
+`*-finished` event only pins a bounded artifact and a verdict. A separate,
+explicit controller event selects the next phase. A child's report can never
+choose the phase it leads to.
+
+**Nothing is inferred from absence.** Every branch a human would call a judgement
+call requires a persisted ruling naming a decision and a reason. The reducer never
+picks the agreeable option by default.
+
+Both rules come from measured failure, not taste. In the recorded baseline, both
+conditions on `post-compaction-illegal-transition` produced the correct phase
+token and then inverted the canonical-artifact rule and invented repair
+mechanisms. One minted a fabricated dispatch key.
+
+## Canonical direction of truth
+
+`state.json` is canonical. The progress ledger is an append-only audit trail
+**derived from it**. This direction is not negotiable.
+
+Authority for whether work actually happened is Git commits and artifacts on
+disk, inherited from the original SDD skill: trust the ledger and `git log` over
+your own recollection. A lost correlation between a dispatch and a session
+degrades to inspecting commits and reports, never to an unrecoverable run.
+
+## Phases
+
+30 phases. Six are terminal and accept no continuation event.
+
+| Group | Phases |
+| --- | --- |
+| Gates | `CAPABILITY_CHECK`, `PLAN_VALIDATE`, `PREFLIGHT_DECISION_REQUIRED`, `WORKSPACE_READY` |
+| Task loop | `IMPLEMENT_DISPATCH_INTENT`, `IMPLEMENT_RUNNING`, `IMPLEMENT_RESULT`, `CONTEXT_REQUIRED`, `CONCERN_DECISION_REQUIRED` |
+| Review loop | `TASK_REVIEW_DISPATCH_INTENT`, `TASK_REVIEW_RUNNING`, `TASK_REVIEW_DECISION` |
+| Fix loop | `FIX_DISPATCH_INTENT`, `FIX_RUNNING`, `REREVIEW_DISPATCH_INTENT`, `REREVIEW_RUNNING`, `TASK_COMPLETE` |
+| Final loop | `FINAL_REVIEW_DISPATCH_INTENT`, `FINAL_REVIEW_RUNNING`, `FINAL_FIX_DISPATCH_INTENT`, `FINAL_FIX_RUNNING`, `FINAL_REREVIEW_DISPATCH_INTENT`, `FINAL_REREVIEW_RUNNING` |
+| Ambiguity | `DISPATCH_AMBIGUOUS` |
+| Terminal | `CAPABILITY_BLOCKED`, `PLAN_INVALID`, `TASK_BLOCKED`, `DISPATCH_MISMATCH_BLOCKED`, `FINAL_BLOCKED`, `COMPLETE` |
+
+## Transitions
+
+61 registered `(phase, event)` pairs. Any pair absent from this table is an
+illegal transition.
+
+| Source | Event | Destination |
+| --- | --- | --- |
+| any nonterminal | `recovery-ruling-recorded` | same phase; requires reason and receipt |
+| `CAPABILITY_CHECK` | `capability-confirmed` | `PLAN_VALIDATE` |
+| `CAPABILITY_CHECK` | `capability-missing` | `CAPABILITY_BLOCKED` |
+| `PLAN_VALIDATE` | `plan-valid` | `PLAN_VALIDATE`, validation pinned |
+| `PLAN_VALIDATE` | `plan-invalid` / `plan-conflict` | `PLAN_INVALID` |
+| `PLAN_VALIDATE` | `preflight-clean` | `WORKSPACE_READY` |
+| `PLAN_VALIDATE` | `preflight-conflict` | `PREFLIGHT_DECISION_REQUIRED` |
+| `PREFLIGHT_DECISION_REQUIRED` | `preflight-approved` | `WORKSPACE_READY` |
+| `PREFLIGHT_DECISION_REQUIRED` | `preflight-rejected` | `FINAL_BLOCKED` |
+| `WORKSPACE_READY` | `implement-dispatch-intended` | `IMPLEMENT_DISPATCH_INTENT` |
+| any `*_DISPATCH_INTENT` | `dispatch-started` | matching `*_RUNNING` |
+| any `*_DISPATCH_INTENT` | `dispatch-mismatch` | `DISPATCH_MISMATCH_BLOCKED` |
+| any `*_DISPATCH_INTENT` | `dispatch-window-crossed` | `DISPATCH_AMBIGUOUS` |
+| `DISPATCH_AMBIGUOUS` | `dispatch-ruling-recorded` | the recorded intent's running phase (adopt) or intent phase (reissue) |
+| `IMPLEMENT_RUNNING` | `implementer-finished` | `IMPLEMENT_RESULT` |
+| `IMPLEMENT_RESULT` | `implementer-status-recorded` | status-pinned `IMPLEMENT_RESULT`, `CONTEXT_REQUIRED`, `CONCERN_DECISION_REQUIRED`, or `TASK_BLOCKED` |
+| status-pinned `IMPLEMENT_RESULT` | `task-review-dispatch-intended` | `TASK_REVIEW_DISPATCH_INTENT` |
+| `CONTEXT_REQUIRED` | `context-dispatch-intended` | `IMPLEMENT_DISPATCH_INTENT` |
+| `CONTEXT_REQUIRED` | `context-limit-reached` | `TASK_BLOCKED` |
+| `CONCERN_DECISION_REQUIRED` | `concern-ruling-recorded` | status-pinned `IMPLEMENT_RESULT` or `TASK_BLOCKED` |
+| `TASK_REVIEW_RUNNING` | `task-review-finished` | `TASK_REVIEW_DECISION` |
+| `TASK_REVIEW_DECISION` | `review-approved` | `TASK_COMPLETE` |
+| `TASK_REVIEW_DECISION` | `fix-dispatch-intended` | `FIX_DISPATCH_INTENT` |
+| `TASK_REVIEW_DECISION` | `review-blocked` | `TASK_BLOCKED` |
+| `FIX_RUNNING` | `rereview-dispatch-intended` | `REREVIEW_DISPATCH_INTENT` |
+| `FIX_RUNNING` | `fixer-blocked` | `TASK_BLOCKED` |
+| `REREVIEW_RUNNING` | `rereview-finished` | result-pinned `REREVIEW_RUNNING` |
+| result-pinned `REREVIEW_RUNNING` | `rereview-approved` | `TASK_COMPLETE` |
+| result-pinned `REREVIEW_RUNNING` | `task-park-ruling-recorded` | result-pinned `REREVIEW_RUNNING` |
+| result-pinned `REREVIEW_RUNNING` | `next-fix-dispatch-intended` | `FIX_DISPATCH_INTENT` |
+| result-pinned `REREVIEW_RUNNING` | `rereview-blocked` | `TASK_BLOCKED` |
+| `TASK_COMPLETE` | `next-task-ready` | `WORKSPACE_READY` at the next task |
+| `TASK_COMPLETE` | `final-review-dispatch-intended` | `FINAL_REVIEW_DISPATCH_INTENT` |
+| `FINAL_REVIEW_RUNNING` | `final-review-finished` | result-pinned `FINAL_REVIEW_RUNNING` |
+| result-pinned `FINAL_REVIEW_RUNNING` | `final-complete` | `COMPLETE` |
+| result-pinned `FINAL_REVIEW_RUNNING` | `final-fix-dispatch-intended` | `FINAL_FIX_DISPATCH_INTENT` |
+| result-pinned `FINAL_REVIEW_RUNNING` | `final-blocked` | `FINAL_BLOCKED` |
+| `FINAL_FIX_RUNNING` | `final-rereview-dispatch-intended` | `FINAL_REREVIEW_DISPATCH_INTENT` |
+| `FINAL_FIX_RUNNING` | `final-fixer-blocked` | `FINAL_BLOCKED` |
+| `FINAL_REREVIEW_RUNNING` | `final-rereview-finished` | result-pinned `FINAL_REREVIEW_RUNNING` |
+| result-pinned `FINAL_REREVIEW_RUNNING` | `final-complete` | `COMPLETE` |
+| result-pinned `FINAL_REREVIEW_RUNNING` | `final-park-ruling-recorded` | result-pinned `FINAL_REREVIEW_RUNNING` |
+| result-pinned `FINAL_REREVIEW_RUNNING` | `final-blocked` | `FINAL_BLOCKED` |
+
+Every `*-dispatch-intended` event carries a full dispatch intent and enters its
+named intent phase **before** any spawn. Task completion requires spec `PASS` and
+quality `APPROVED` together, with no open load-bearing finding.
+
+## Counters and their bounds
+
+| Field | Bound | Notes |
+| --- | --- | --- |
+| `contextAttempts` | 0–2 | A third `NEEDS_CONTEXT` must block. Never touches `fixRound`. |
+| `fixRound` | 0–5 | The fixer tier escalates one rung at round 4 and two at round 5. A load-bearing residual at round 5 blocks. |
+| `finalFixUsed` | one wave | A second final-fix wave is not legal. |
+| `revision` | +1 per transition | Exactly one increment, including recovery rulings. |
+| `recoveryRulings` | unbounded | Counted so interventions are visible in the audit trail. |
+
+`currentImplementerTier` is derived **only** from the immutable task index
+captured at initialization, never from a live re-parse.
+
+## The finding ledger
+
+Findings are keyed by immutable ID. Severity is recorded at report time and can
+never be re-reported at a different level, so a finding cannot be downgraded on
+its way to being dismissed.
+
+`Critical` and `Important` are load-bearing: they open a fix round and can never
+be parked. `Minor` is contestable and may be parked with a persisted ruling that
+names evidence.
+
+Reporting is additive and may grow the ledger. Adjudication is a set operation
+that may change dispositions but can neither add nor remove entries, which is the
+retention guarantee: no event can silently drop an open, deferred, or parked
+finding. Every disposition requires evidence.
+
+## Dispatch identity and the ambiguity window
+
+`dispatchKey` is controller-owned, composed as
+`<runId>:task-<n>:<role>:attempt-<n>[:round-<n>]`. It is **never** passed to
+`spawn_subsession`, which accepts only `{ prompt, cwd, tier }` and returns
+`{ sessionId, cwd }`.
+
+The runtime provides no deduplication, so the key buys **correlation, not
+idempotency**. A crash between the spawn call and the correlation write can orphan
+a child. That window cannot be closed from here; it can only be made visible.
+`DISPATCH_AMBIGUOUS` does exactly that, and leaving it requires an explicit
+ruling: `adopt` names an observed session id, `reissue` sends the stored prompt
+bytes and accepts a possible orphan. The reducer never picks.
+
+An intent stores the exact rendered prompt bytes, bounded at 384 KiB, before any
+session exists. Recovery reissues those bytes verbatim and never re-renders,
+because re-rendering couples recovery to renderer output.
+
+The typed `tier` selects the model. A leading `Model tier: <tier>` line is a
+human-readable echo with no control effect: absent is fine, and disagreement with
+the typed tier is reported as renderer/formula divergence.
+
+## Recovery authority
+
+`recovery-ruling-recorded` is legal in any nonterminal phase, never changes the
+phase, and requires both a reason and a receipt. It exists so an intervention
+appears in the audit trail instead of hiding.
+
+Terminal phases accept no continuation event. Recovery from a terminal phase is a
+human decision made outside the run.
+
+**Never hand-edit `state.json` or the progress ledger.** Every change goes through
+a transition so the revision, audit line, and validation all advance together. A
+hand-edited state is indistinguishable from a corrupted one, and the reducer is
+built to refuse exactly the kind of plausible-looking repair a stuck controller
+would otherwise invent.

package/optional-skills/deterministic-subagent-driven-development/scripts/lib/manifest.mjs

@@ -0,0 +1,258 @@
+/**
+ * Runtime ownership manifest for the optional deterministic SDD skill.
+ *
+ * The manifest answers two questions a consumer cannot otherwise answer: which
+ * package owns this skill, and whether the runtime tree on disk is the tree that
+ * was generated. It deliberately does not answer "is this up to date" -- that
+ * comparison belongs to an installer, which knows the installed version.
+ *
+ * The runtime list is explicit rather than globbed. A glob would silently absorb
+ * a new file into the shipped surface; an explicit list makes every addition a
+ * reviewed edit.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+/** Manifest schema version. Bump only for a breaking shape change. */
+export const MANIFEST_SCHEMA_VERSION = 1;
+
+/** Canonical skill name. Must match the `name` in `SKILL.md` frontmatter. */
+export const SKILL_NAME = "deterministic-subagent-driven-development";
+
+/** Distribution posture. `opt-in` means never auto-registered by the package. */
+export const DISTRIBUTION = "opt-in";
+
+/**
+ * Hash algorithm identifier.
+ *
+ * `sha256-path-nul-bytes-v1`: for each runtime file in sorted relative-path
+ * order, absorb the UTF-8 relative path, a NUL, the raw file bytes, and a NUL.
+ * The NUL delimiters make the encoding unambiguous: without them, a rename that
+ * shifted bytes between path and content could preserve the digest.
+ */
+export const RUNTIME_HASH_ALGORITHM = "sha256-path-nul-bytes-v1";
+
+/**
+ * Files that constitute the runtime skill, sorted.
+ *
+ * Excludes `evals/` and `tests/` by construction: those carry fake capability
+ * tools and adversarial prompts that must never reach a consumer's skill tree.
+ */
+export const RUNTIME_FILES = Object.freeze([
+  "SKILL.md",
+  "prompts/final-reviewer.md",
+  "prompts/implementer.md",
+  "prompts/re-reviewer.md",
+  "prompts/task-reviewer.md",
+  "references/capability-contract.md",
+  "references/plan-contract.md",
+  "references/state-machine.md",
+  "scripts/lib/manifest.mjs",
+  "scripts/lib/plan-policy.mjs",
+  "scripts/lib/prompt-renderer.mjs",
+  "scripts/lib/state-machine.mjs",
+  "scripts/lib/state-store.mjs",
+  "scripts/sdd-state",
+  "scripts/sdd-state.mjs",
+]);
+
+const SEMVER_PATTERN =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+
+/** Raised for any manifest validation or integrity failure. */
+export class ManifestError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ManifestError";
+  }
+}
+
+/**
+ * Reject a runtime entry that is absolute, traverses upward, duplicates another,
+ * or names excluded development evidence.
+ *
+ * Validation runs before any hashing so a rejected list never produces a digest.
+ */
+export function assertRuntimeList(runtimeFiles) {
+  if (!Array.isArray(runtimeFiles) || runtimeFiles.length === 0) {
+    throw new ManifestError("runtime file list must be a non-empty array");
+  }
+
+  const seen = new Set();
+  for (const entry of runtimeFiles) {
+    if (typeof entry !== "string" || entry.length === 0) {
+      throw new ManifestError("runtime entries must be non-empty strings");
+    }
+    if (isAbsolute(entry) || entry.startsWith("/")) {
+      throw new ManifestError(`runtime entry must be relative: ${entry}`);
+    }
+    if (entry.includes("\\")) {
+      throw new ManifestError(`runtime entry must use forward slashes: ${entry}`);
+    }
+    const segments = entry.split("/");
+    if (segments.includes("..") || segments.includes(".") || segments.includes("")) {
+      throw new ManifestError(`runtime entry must be a normalized path: ${entry}`);
+    }
+    if (entry.startsWith("evals/") || entry.startsWith("tests/")) {
+      throw new ManifestError(`runtime entry must not ship development evidence: ${entry}`);
+    }
+    if (seen.has(entry)) {
+      throw new ManifestError(`duplicate runtime entry: ${entry}`);
+    }
+    seen.add(entry);
+  }
+
+  const sorted = [...runtimeFiles].sort();
+  if (sorted.some((entry, index) => entry !== runtimeFiles[index])) {
+    throw new ManifestError("runtime file list must be sorted");
+  }
+  return sorted;
+}
+
+/**
+ * Resolve a runtime entry against the source root.
+ *
+ * There is no second escape check here on purpose. `assertRuntimeList` runs first
+ * on every path into this module and rejects absolute paths, backslashes, and any
+ * `..` segment, so a validated entry cannot escape. A redundant guard here would
+ * be unreachable, and an unreachable guard is worse than none: no test can pin it,
+ * so it silently rots while implying a protection it never performs.
+ *
+ * Symlinks are a separate matter and deliberately not handled: the runtime list is
+ * a frozen constant in this file, not caller input, so there is no untrusted path
+ * by which a runtime entry could become a link out of the tree.
+ */
+function resolveInside(sourceRoot, relativePath) {
+  return join(resolve(sourceRoot), relativePath);
+}
+
+/**
+ * Compute the runtime digest over the validated, sorted list.
+ *
+ * Missing files surface as a `ManifestError` rather than a raw ENOENT, because a
+ * manifest naming a file that does not exist is a manifest defect.
+ */
+export function computeRuntimeHash(sourceRoot, runtimeFiles = RUNTIME_FILES) {
+  const sorted = assertRuntimeList(runtimeFiles);
+  const hash = createHash("sha256");
+  for (const relativePath of sorted) {
+    const absolutePath = resolveInside(sourceRoot, relativePath);
+    let bytes;
+    try {
+      bytes = readFileSync(absolutePath);
+    } catch (cause) {
+      throw new ManifestError(`runtime file is missing: ${relativePath}`, { cause });
+    }
+    hash.update(Buffer.from(relativePath, "utf8"));
+    hash.update(Buffer.from([0]));
+    hash.update(bytes);
+    hash.update(Buffer.from([0]));
+  }
+  return hash.digest("hex");
+}
+
+/** Read the owning package's name and version, validating the version is semver. */
+function readSourcePackage(packageJsonPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  } catch (cause) {
+    throw new ManifestError(`cannot read package manifest: ${packageJsonPath}`, { cause });
+  }
+  if (typeof parsed.name !== "string" || parsed.name.length === 0) {
+    throw new ManifestError("package manifest has no name");
+  }
+  if (typeof parsed.version !== "string" || !SEMVER_PATTERN.test(parsed.version)) {
+    throw new ManifestError(`package version is not valid semver: ${String(parsed.version)}`);
+  }
+  return { name: parsed.name, version: parsed.version };
+}
+
+/** Build the manifest object without writing it. */
+export function buildManifest({ sourceRoot, packageJsonPath, runtimeFiles = RUNTIME_FILES }) {
+  const sorted = assertRuntimeList(runtimeFiles);
+  const sourcePackage = readSourcePackage(packageJsonPath);
+  // Hash last: a validation failure must never leave a digest to be trusted.
+  const runtimeHash = computeRuntimeHash(sourceRoot, sorted);
+  return {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    name: SKILL_NAME,
+    distribution: DISTRIBUTION,
+    sourcePackage,
+    runtimeHashAlgorithm: RUNTIME_HASH_ALGORITHM,
+    runtimeHash,
+    runtimeFiles: sorted,
+  };
+}
+
+/**
+ * Write the manifest atomically.
+ *
+ * The digest is computed fully before the first byte is written, and the file
+ * appears via `rename`, so a reader never observes a partial manifest or a
+ * placeholder digest. There is no intermediate sentinel hash to leak.
+ */
+export function writeManifest({ sourceRoot, packageJsonPath, outputPath, runtimeFiles }) {
+  const manifest = buildManifest({ sourceRoot, packageJsonPath, runtimeFiles });
+  const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
+  const temporaryPath = `${outputPath}.tmp-${process.pid.toString(36)}`;
+  writeFileSync(temporaryPath, serialized, { encoding: "utf8", mode: 0o644 });
+  renameSync(temporaryPath, outputPath);
+  return manifest;
+}
+
+/** Parse and structurally validate a manifest file. */
+export function readManifest(manifestPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (cause) {
+    throw new ManifestError(`cannot read manifest: ${manifestPath}`, { cause });
+  }
+  if (parsed.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+    throw new ManifestError(`unsupported manifest schema version: ${String(parsed.schemaVersion)}`);
+  }
+  if (parsed.name !== SKILL_NAME) {
+    throw new ManifestError(`unexpected skill name: ${String(parsed.name)}`);
+  }
+  if (parsed.distribution !== DISTRIBUTION) {
+    throw new ManifestError(`unexpected distribution: ${String(parsed.distribution)}`);
+  }
+  if (parsed.runtimeHashAlgorithm !== RUNTIME_HASH_ALGORITHM) {
+    throw new ManifestError(
+      `unsupported runtime hash algorithm: ${String(parsed.runtimeHashAlgorithm)}`,
+    );
+  }
+  if (typeof parsed.runtimeHash !== "string" || !/^[0-9a-f]{64}$/u.test(parsed.runtimeHash)) {
+    throw new ManifestError("runtime hash must be 64 lowercase hex characters");
+  }
+  assertRuntimeList(parsed.runtimeFiles);
+  return parsed;
+}
+
+/**
+ * Recompute the digest from the tree beside the manifest and compare.
+ *
+ * Returns the manifest and digest on success; throws on mismatch. The source root
+ * is the manifest's own directory, so verification cannot be pointed at a
+ * different tree by accident.
+ */
+export function verifyManifest(manifestPath, sourceRoot) {
+  const manifest = readManifest(manifestPath);
+  const actual = computeRuntimeHash(sourceRoot, manifest.runtimeFiles);
+  if (actual !== manifest.runtimeHash) {
+    throw new ManifestError(
+      `runtime hash mismatch: manifest records ${manifest.runtimeHash} but the tree hashes to ${actual}`,
+    );
+  }
+  return { manifest, runtimeHash: actual };
+}
+
+/** Absolute paths of the manifest's runtime files, for callers that copy the tree. */
+export function runtimeFilePaths(sourceRoot, runtimeFiles = RUNTIME_FILES) {
+  return assertRuntimeList(runtimeFiles).map((relativePath) =>
+    join(resolve(sourceRoot), relativePath),
+  );
+}