@akagilnc/pi-workflow-roles 0.1.1751

package/dist/work-subject-identity.js

@@ -0,0 +1,53 @@
+import { resolve } from "node:path";
+import {
+  physicalPathIdentity,
+  physicallyContainedIn,
+  resolveActivationLedgerHome
+} from "./activation-ledger-topology.js";
+function issueRoot(value) {
+  const normalized = value.replaceAll("\\", "/");
+  const marker = ".ak/work/issues/";
+  const index = normalized.indexOf(marker);
+  if (index < 0) return void 0;
+  const issue = normalized.slice(index + marker.length).split("/")[0]?.split("#")[0];
+  return issue === void 0 || issue === "" ? void 0 : normalized.slice(0, index + marker.length) + issue;
+}
+function workIdentityFromCwd(cwd) {
+  const resolvedCwd = resolve(cwd, ".");
+  const cwdIssue = issueRoot(resolvedCwd);
+  if (cwdIssue !== void 0) return cwdIssue;
+  if (resolvedCwd.includes("/.ak/work/")) return resolvedCwd;
+  return void 0;
+}
+function isMachineLedgerSessionPath(sessionPath) {
+  return physicallyContainedIn(resolveActivationLedgerHome(), sessionPath);
+}
+function subjectPath(sessionDir, cwd = process.cwd()) {
+  if (sessionDir === "") {
+    return workIdentityFromCwd(cwd) ?? resolve(cwd, ".ak/work");
+  }
+  const resolvedSession = resolve(cwd, sessionDir || ".ak/work");
+  if (isMachineLedgerSessionPath(resolvedSession)) {
+    return workIdentityFromCwd(cwd) ?? resolve(cwd, ".ak/work");
+  }
+  const issue = issueRoot(resolvedSession);
+  if (issue !== void 0) return issue;
+  const runsMarker = "/runs/";
+  const runsIndex = resolvedSession.indexOf(runsMarker);
+  if (runsIndex >= 0) {
+    return resolvedSession.slice(0, runsIndex);
+  }
+  return resolvedSession;
+}
+function workSubjectKeyFromProjectRoot(projectRoot) {
+  return subjectPath("", projectRoot);
+}
+function workSubjectKeysEqual(left, right) {
+  return physicalPathIdentity(left) === physicalPathIdentity(right);
+}
+export {
+  issueRoot,
+  subjectPath,
+  workSubjectKeyFromProjectRoot,
+  workSubjectKeysEqual
+};

package/extensions/role-runtime.ts

@@ -0,0 +1,303 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+import { loadDoctorCase } from "../src/doctor-evidence.ts";
+import { loadAdmittedJudgeRequest } from "../src/public-cli/invocation.ts";
+
+import {
+  buildSessionContext,
+  convertToLlm,
+  serializeConversation,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Message } from "@earendil-works/pi-ai";
+
+import { createGhCollectorGitHubTransport } from "../src/collector-github.ts";
+import { createReviewerAgentRunner } from "../src/reviewer-agent.ts";
+import { createReviewerPinnedGitReader } from "../src/reviewer-dispatch.ts";
+import { createPiReviewerAuditor } from "../src/reviewer-auditor.ts";
+import { createPiDoctorAuditor } from "../src/doctor-auditor.ts";
+import {
+  createNativeNavigatorSessionFactory,
+  createNavigatorAttendance,
+  navigatorUnavailableError,
+  navigatorSessionDirectory,
+  navigatorSubjectKey,
+  navigatorSubjectKeyForInput,
+  registerNavigatorModelCommand,
+  subjectPath,
+  type NavigatorSubjectProvenance,
+  type NavigatorTargetRole,
+} from "../src/navigator-attendance.ts";
+import { loadCanonicalSkillBinding as loadHomeCanonicalSkillBinding } from "../src/canonical-skill-binding.ts";
+import { loadPackagedCanonicalSkillBinding } from "../src/package-resources/method-skill-binding.ts";
+import { JUDGE_OUTPUT_TOOL_NAME } from "../src/package-contracts/judge-output.ts";
+import {
+  createProductionMergerGitState,
+  createRoleRuntimeExtension,
+  ROLE_FLAG,
+} from "../src/role-runtime.ts";
+import {
+  packagedRoleInputFlag,
+  packagedRoleMetadata,
+} from "../src/packaged-role-registry.ts";
+import { createPiJudgeAuditor } from "../src/judge-auditor.ts";
+const extensionPath = fileURLToPath(import.meta.url);
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const judgeSoulPath = fileURLToPath(new URL("../souls/judge.md", import.meta.url));
+const fixerSoulPath = fileURLToPath(new URL("../souls/fixer.md", import.meta.url));
+const coderSoulPath = fileURLToPath(new URL("../souls/coder.md", import.meta.url));
+const reviewerSoulPath = fileURLToPath(new URL("../souls/reviewer.md", import.meta.url));
+const collectorSoulPath = fileURLToPath(new URL("../souls/collector.md", import.meta.url));
+const doctorSoulPath = fileURLToPath(new URL("../souls/doctor.md", import.meta.url));
+const navigatorSoulPath = fileURLToPath(new URL("../souls/navigator.md", import.meta.url));
+const navigatorRoutePlaybookPath = fileURLToPath(new URL("../resources/navigator-route-playbook.md", import.meta.url));
+const mergerSoulPath = fileURLToPath(new URL("../souls/merger.md", import.meta.url));
+
+function navigatorInputReference(pi: ExtensionAPI, role: string): string | undefined {
+  const name = packagedRoleInputFlag(role);
+  const value = name === undefined ? undefined : pi.getFlag(name);
+  return typeof value === "string" && value !== "" ? resolve(value) : undefined;
+}
+
+// Cold `pi -e <extension> --help` must cover installed-package process startup under CI load.
+// This bound is process-startup budget only — not settlement-to-visible presentation latency.
+export const NAVIGATOR_LIVE_HELP_TIMEOUT_MS = 30_000;
+
+/**
+ * Subprocess live help (disk-reread via fresh pi -e). Kept for cold-install proofs.
+ * Production Navigator prepare must not call this on the post-role grace path — under
+ * concurrent CI load each role's pi --help alone can exceed the accepted 3s grace.
+ */
+export async function loadNavigatorRoleHelp(
+  pi: Pick<ExtensionAPI, "exec">,
+  extensionPath: string,
+  cwd: string,
+  role: NavigatorTargetRole,
+): Promise<string> {
+  const result = await pi.exec("pi", ["--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files", "-e", extensionPath, "--ak-role", role, "--help"], { cwd, timeout: NAVIGATOR_LIVE_HELP_TIMEOUT_MS });
+  if (result.killed) {
+    throw new Error(`live help unavailable for ${role}: process did not settle`, { cause: result });
+  }
+  if (result.code !== 0) throw new Error(`live help unavailable for ${role}: process exited with code ${result.code}`, { cause: result });
+  return result.stdout || result.stderr;
+}
+
+/**
+ * In-process role help for Navigator prepare. Same loaded package/module the role
+ * is already running — no child pi. Public command surface is ak-role (ADR 0052).
+ */
+export function formatInProcessNavigatorRoleHelp(role: NavigatorTargetRole): string {
+  const metadata = packagedRoleMetadata(role);
+  const lines = [
+    `Usage: ak-role ${role}`,
+    ROLE_FLAG.definition.description,
+  ];
+  if (metadata?.inputFlag !== undefined) {
+    lines.push(`  --${metadata.inputFlag} <value>    ${role} input material`);
+  }
+  if (metadata?.phaseFlag !== undefined) {
+    lines.push(
+      `  --${metadata.phaseFlag} <value>    ${role} phase: ${(metadata.phases.filter((p) => p !== null) as string[]).join(" | ")}`,
+    );
+  }
+  lines.push(`Public next-command form: ak-role ${role}`);
+  return lines.join("\n");
+}
+
+/**
+ * Role-input document bytes win verbatim over work-root file authority when non-empty.
+ * Absent or whitespace-only input yields to fileAuthority; neither remains undefined.
+ */
+export function resolveNavigatorAuthorityMaterial(
+  roleInput: string | undefined,
+  fileAuthority: string | undefined,
+): string | undefined {
+  if (roleInput !== undefined && roleInput.trim() !== "") return roleInput;
+  if (fileAuthority !== undefined && fileAuthority.trim() !== "") return fileAuthority;
+  return undefined;
+}
+
+
+function projectJudgeTranscriptForAudit(messages: Message[]): Message[] {
+  return messages.map((message) => {
+    if (message.role !== "assistant") return message;
+    return {
+      ...message,
+      content: message.content.map((part) => {
+        if (part.type !== "toolCall" || part.name !== JUDGE_OUTPUT_TOOL_NAME) {
+          return part;
+        }
+        const { evidence: _evidence, ...adjudicativeArguments } = part.arguments;
+        return { ...part, arguments: adjudicativeArguments };
+      }),
+    };
+  });
+}
+
+export function transcriptFromContext(ctx: ExtensionContext): string {
+  const context = buildSessionContext(
+    [...ctx.sessionManager.getEntries()],
+    ctx.sessionManager.getLeafId(),
+  );
+  return serializeConversation(
+    projectJudgeTranscriptForAudit(convertToLlm(context.messages)),
+  );
+}
+
+export async function loadNavigatorWorkContext(
+  pi: Pick<ExtensionAPI, "getFlag">,
+  options: { context: ExtensionContext; role: string },
+): Promise<{ subjectKey: string; subject: string; authority: string; subjectProvenance: NavigatorSubjectProvenance }> {
+  const reference = navigatorInputReference(pi as ExtensionAPI, options.role);
+  const input = reference === undefined || options.role === "doctor" ? undefined : await readFile(reference, "utf8");
+  const subjectRoot = subjectPath(reference ?? options.context.sessionManager.getSessionDir(), options.context.cwd);
+  let subjectKey = reference === undefined
+    ? subjectRoot
+    : navigatorSubjectKeyForInput(subjectRoot, reference, options.context.cwd);
+  let subject = input ?? `work subject: ${subjectKey}`;
+  let subjectProvenance: NavigatorSubjectProvenance = input === undefined ? "placeholder" : "role_input";
+  if (options.role === "doctor" && reference !== undefined) {
+    const patient = await loadDoctorCase(reference);
+    subject = JSON.stringify({ identity: patient.identity, cost: patient.cost });
+    subjectProvenance = "role_input";
+  }
+  // Public ak-role run: admitted request is the typed Navigator work-context source.
+  // Classification failure here stays source=context (distinct from model/session/transport).
+  const publicRunDir = process.env.AK_ROLE_RUN_DIR;
+  if (
+    options.role === "judge" &&
+    typeof publicRunDir === "string" &&
+    publicRunDir.trim() !== ""
+  ) {
+    let admitted;
+    try {
+      admitted = await loadAdmittedJudgeRequest(publicRunDir);
+    } catch (error) {
+      throw navigatorUnavailableError("context", error);
+    }
+    if (admitted === undefined) {
+      throw navigatorUnavailableError(
+        "context",
+        new Error("public Judge admitted request was missing or malformed"),
+      );
+    }
+    if (!admitted.instructionEmpty && admitted.instruction.trim() !== "") {
+      const prose = admitted.instruction;
+      subjectProvenance = "role_input";
+      subject = prose;
+      subjectKey = navigatorSubjectKey(subjectRoot, prose, subjectProvenance);
+      return { subjectKey, subject, authority: prose, subjectProvenance };
+    }
+    // Structurally empty public request: placeholder work context, no invented task.
+    return {
+      subjectKey: subjectRoot,
+      subject: `work subject: ${subjectRoot}`,
+      authority: "",
+      subjectProvenance: "placeholder",
+    };
+  }
+  // True short-circuit: non-whitespace role-input is authority verbatim.
+  // Do not probe work-root authority files once input already supplies material.
+  if (input !== undefined && input.trim() !== "") {
+    return { subjectKey, subject, authority: input, subjectProvenance };
+  }
+  const workRoot = subjectRoot.includes("/.ak/work/") ? subjectRoot : undefined;
+  const authorityFiles = workRoot === undefined ? [] : [
+    resolve(workRoot, "authority.md"),
+    resolve(workRoot, "authority.txt"),
+    resolve(workRoot, "design-v2/owner-direction.md"),
+  ];
+  let authorityMaterial: string | undefined;
+  for (const path of authorityFiles) {
+    try {
+      const content = await readFile(path, "utf8");
+      if (content.trim() !== "") {
+        authorityMaterial = content;
+        break;
+      }
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT")) throw error;
+    }
+  }
+  // Absent or whitespace-only input yields to the existing file fallback.
+  const authority = resolveNavigatorAuthorityMaterial(input, authorityMaterial);
+  if (authority === undefined) {
+    // Bare developer seams (judge -p, etc.) supply the prompt only at
+    // before_agent_start. session_start absence is a soft placeholder, not a
+    // permanent context poison — prepare still fails honestly if nothing arrives.
+    return {
+      subjectKey: subjectRoot,
+      subject: `work subject: ${subjectRoot}`,
+      authority: "",
+      subjectProvenance: "placeholder",
+    };
+  }
+  return { subjectKey, subject, authority, subjectProvenance };
+}
+
+export default function roleRuntime(pi: ExtensionAPI): void {
+  const reviewerAgent = createReviewerAgentRunner();
+  registerNavigatorModelCommand(pi);
+  const navigatorSessionFactory = createNativeNavigatorSessionFactory();
+  createRoleRuntimeExtension({
+    loadJudgeSoul: () => readFile(judgeSoulPath, "utf8"),
+    loadFixerSoul: () => readFile(fixerSoulPath, "utf8"),
+    loadFixPacket: (path) => readFile(path, "utf8"),
+    loadCoderSoul: () => readFile(coderSoulPath, "utf8"),
+    loadCoderTask: (path) => readFile(path, "utf8"),
+    loadReviewerSoul: () => readFile(reviewerSoulPath, "utf8"),
+    createReviewerPinnedGitReader: () => createReviewerPinnedGitReader(),
+    loadCollectorSoul: () => readFile(collectorSoulPath, "utf8"),
+    createCollectorTransport: () => createGhCollectorGitHubTransport(),
+    collectorPackageExtensionPath: extensionPath,
+    loadDoctorSoul: () => readFile(doctorSoulPath, "utf8"),
+    loadDoctorCase,
+    auditDoctorCompliance: createPiDoctorAuditor(),
+    loadNavigatorWorkContext: (options) => loadNavigatorWorkContext(pi, options),
+    createNavigatorAttendance: (options) => {
+      const sessionDir = navigatorSessionDirectory(options.context, options.subjectKey);
+      return createNavigatorAttendance({
+        context: options.context,
+        role: options.role,
+        phase: options.phase,
+        subjectKey: options.subjectKey,
+        sessionDir,
+        sessionDirectory: (subjectKey) => navigatorSessionDirectory(options.context, subjectKey),
+        subject: options.subject,
+        authority: options.authority,
+        invocationId: options.invocationId,
+        loadSoul: () => readFile(navigatorSoulPath, "utf8"),
+        loadRoutePlaybook: () => readFile(navigatorRoutePlaybookPath, "utf8"),
+        // In-process help: subprocess pi --help is reserved for cold-install proofs.
+        // N child pi processes cannot fit the accepted 3s post-role grace under CI load.
+        loadRoleHelp: async (role) => formatInProcessNavigatorRoleHelp(role),
+        createSession: navigatorSessionFactory,
+        contextError: options.contextError,
+        onEvent: options.onEvent,
+      });
+    },
+    loadMergerSoul: () => readFile(mergerSoulPath, "utf8"),
+    loadMergerInput: async (path) => JSON.parse(await readFile(path, "utf8")),
+    createMergerGitState: (repositoryRoot) =>
+      createProductionMergerGitState(repositoryRoot),
+    async loadCanonicalSkillBinding(name) {
+      // Coder TDD (#109) and Reviewer code-review (#111) are package-owned.
+      // Optional Fixer diagnosing-bugs is available via --skill without this binding.
+      if (name === "tdd") {
+        return loadPackagedCanonicalSkillBinding(packageRoot, "tdd");
+      }
+      if (name === "code-review") {
+        return loadPackagedCanonicalSkillBinding(packageRoot, "code-review");
+      }
+      return loadHomeCanonicalSkillBinding(name);
+    },
+    runReviewerDispatch: (dispatch, options) => reviewerAgent.run(dispatch, options),
+    shutdownReviewerAgent: () => reviewerAgent.shutdown(),
+    transcriptFromContext,
+    auditSoulCompliance: createPiJudgeAuditor(),
+    auditReviewerCompliance: createPiReviewerAuditor(),
+  })(pi);
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@akagilnc/pi-workflow-roles",
+  "version": "0.1.1751",
+  "description": "Soul-bound workflow roles for Pi",
+  "type": "module",
+  "license": "Apache-2.0",
+  "keywords": [
+    "pi-package"
+  ],
+  "bin": {
+    "ak-role": "./dist/public-cli/main.js"
+  },
+  "files": [
+    "dist",
+    "extensions",
+    "scripts/generate-tool-execution-observation-schema.ts",
+    "scripts/build-package.mjs",
+    "src",
+    "souls",
+    "schemas",
+    "packets",
+    "resources",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "tsx scripts/generate-tool-execution-observation-schema.ts && tsc -p tsconfig.build.json && node scripts/build-package.mjs",
+    "prepack": "npm run build",
+    "test": "pnpm run test:all",
+    "test:fast": "node --import tsx --test test/unit/**/*.test.ts test/contract/**/*.test.ts",
+    "test:integration": "node --import tsx --test test/unit/**/*.test.ts test/contract/**/*.test.ts test/integration/**/*.test.ts",
+    "test:all": "node scripts/run-test-all.mjs",
+    "test:adjudication": "node --import tsx --test test/adjudication/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": []
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "packageManager": "pnpm@11.20.0",
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@types/node": "latest",
+    "esbuild": "^0.28.1",
+    "tsx": "latest",
+    "typebox": "1.3.8",
+    "typescript": "latest"
+  }
+}

package/packets/fixer-prerequisites.json

@@ -0,0 +1,6 @@
+[
+  {
+    "id": "owner.choice",
+    "requirement": "The controlling owner decision required before this repair exists."
+  }
+]

package/packets/fixer-repair.md

@@ -0,0 +1,5 @@
+# Fixer repair instructions
+
+Repair and verify the caller-assigned findings. Treat this document as opaque prose: its headings and wording have no machine semantics.
+
+Search the authorized scope for every same-pattern occurrence, preserve unrelated behavior, run the required checks, and report each finding class through the typed Fixer output.

package/packets/judge-apply.md

@@ -0,0 +1,77 @@
+# Apply evidence packet (contributor template)
+
+This file is a **repository-contributor template** for a manually supplied Apply
+(executable-proof) artifact. The filename identifies an **evidence burden**, not
+a verdict, phase flag, transition, or required predecessor/successor.
+
+Selection, composition, and use are **caller-owned** (ADR 0010). Apply posture
+semantics remain solely in `souls/judge.md`. Git commit identity owns the code
+snapshot and any reviewed range. This template creates no receipt envelope,
+audit, runtime enforcement, trust tier, production hook, or package surface.
+
+## Sealed upstream identities
+
+Digests seal **artifact-byte identity only**. They do not prove truth,
+acceptance, or freshness.
+
+| Artifact | Repository-relative path | SHA-256 of exact bytes |
+| --- | --- | --- |
+| Authority materials | | |
+| Plan materials | | |
+
+## Target and range identity
+
+| Kind | Full SHA | Meaning |
+| --- | --- | --- |
+| **Target commit** (required for code/apply facts) | | Complete snapshot under claim |
+| **Range base** (only if a range is claimed) | | Base snapshot from which the reviewed delta starts |
+| **Range target** (only if a range is claimed) | | Target snapshot at which that delta ends |
+
+Distinguish carefully:
+
+- **path + SHA-256** → exact bytes of a named artifact
+- **full target commit SHA** → complete code snapshot under claim
+- **full base + target SHAs** → identify only the reviewed delta (not a commit-set membership rule or range syntax)
+- **tests / seam / boundary observations** → behavioral evidence
+
+None of these alone proves truth or acceptance.
+
+## Construction evidence
+
+### Live code and tests
+
+| Claim | Evidence (path, command, or observation) | Binds to target SHA? |
+| --- | --- | --- |
+| | | yes/no |
+
+Use `file:line` **only where applicable** to a concrete claim. Do not invent
+blanket line citations.
+
+### Real production-seam evidence
+
+| Seam / module owner | How the claim crosses the real seam | Result |
+| --- | --- | --- |
+| | | |
+
+### Boundary evidence
+
+| Boundary condition | How it was actually reached | Result |
+| --- | --- | --- |
+| | | |
+
+### Guardrail triad (only when adding or approving a guardrail)
+
+Complete this section **only** if the change adds or approves a guardrail;
+otherwise record `N/A — no guardrail added or approved` with disposition.
+
+| Question | Answer |
+| --- | --- |
+| 1. Which real, reproducible failure proves this guardrail is needed? | |
+| 2. Which seam owns the invariant it protects? | |
+| 3. Why is deleting or simplifying the root cause insufficient for this failure class? | |
+
+## Explicit non-claims
+
+- Filename is not a verdict and does not imply Apply convergence.
+- This template does not define or alter role receipts, Soul audit, or runtime gates.
+- Instantiation does not route work to any role or require a successor packet.

package/packets/judge-authority.md

@@ -0,0 +1,64 @@
+# Authority evidence packet (contributor template)
+
+This file is a **repository-contributor template** for a manually supplied
+Authority-evidence artifact. The filename identifies an **evidence burden**, not
+a verdict, phase flag, transition, or required predecessor/successor.
+
+Selection, composition, and use are **caller-owned** (ADR 0010). This template
+does not restate or amend Judge law in `souls/judge.md`. It creates no routing,
+next-role, package memory, resume semantics, timeout budget, or trust tier.
+
+## Identity seal
+
+Every supplied artifact is identified by:
+
+| Field | Value |
+| --- | --- |
+| Repository-relative path | |
+| SHA-256 of exact bytes | |
+
+A digest seals **identity only**. It does not prove truth, acceptance, or
+freshness. Judge independently checks claims against the supplied current
+target. This packet does **not** require Apply-level executable proof.
+
+## Authority items
+
+Record each item the contributor wants examined under the Authority burden.
+Do not invent Apply fixtures, blanket `file:line` demands, or implementation
+recipes here.
+
+### Clauses
+
+| ID | Clause | Notes |
+| --- | --- | --- |
+| A1 | | |
+
+### Decisions
+
+| ID | Decision | 陛下 | Notes |
+| --- | --- | --- | --- |
+| D1 | | | |
+
+### Counterexamples
+
+| ID | Counterexample | Why it matters |
+| --- | --- | --- |
+| C1 | | |
+
+### Boundaries
+
+| ID | In-scope / out-of-scope boundary |
+| --- | --- |
+| B1 | |
+
+### Unresolved 陛下 choices
+
+| ID | Open choice | Options | Blocking? |
+| --- | --- | --- | --- |
+| U1 | | | |
+
+## Explicit non-claims
+
+- Filename is not a verdict and does not imply convergence.
+- Instantiation does not start, order, or require any role call.
+- No mechanical schema/runtime enforcement is claimed by this template.

package/packets/judge-plan.md

@@ -0,0 +1,55 @@
+# Plan evidence packet (contributor template)
+
+This file is a **repository-contributor template** for a manually supplied Plan
+(construction-readiness) artifact. The filename identifies an **evidence
+burden**, not a verdict, phase flag, transition, or required
+predecessor/successor.
+
+Selection, composition, and use are **caller-owned** (ADR 0010). Plan posture
+semantics remain solely in `souls/judge.md`. This template does not restate or
+amend that law. It creates no routing, topology, role-order, package memory, or
+proof that construction occurred.
+
+## Sealed authority identity
+
+Bind the authority materials this plan consumes. Digests seal identity only—not
+truth, acceptance, or freshness.
+
+| Artifact | Repository-relative path | SHA-256 of exact bytes |
+| --- | --- | --- |
+| Authority packet / inputs | | |
+
+## Planned changes — five readiness facts
+
+For **each** proposed change, record exactly these five facts. Do not demand
+fixture pseudocode or blanket `file:line` here.
+
+### Change P1
+
+| Fact | Content |
+| --- | --- |
+| **Behavior** | Observable requirement or defect addressed |
+| **Owner** | Deep module / seam that owns the behavior |
+| **Red** | Counterexample that must fail before the fix |
+| **Green** | Observable result that proves the fix |
+| **Scope** | What deliberately stays unchanged |
+
+### Change P2
+
+| Fact | Content |
+| --- | --- |
+| **Behavior** | |
+| **Owner** | |
+| **Red** | |
+| **Green** | |
+| **Scope** | |
+
+Add P3… as needed. Every planned change must be reconcilable to the sealed
+authority identity above and must carry all five facts.
+
+## Explicit non-claims
+
+- Filename is not a verdict and does not authorize or prove Apply success.
+- This packet does not claim construction already happened.
+- No orchestration, next-role, or stage-machine semantics arise from this file.
+- No mechanical schema/runtime enforcement is claimed by this template.

package/packets/judge-review.md

@@ -0,0 +1,49 @@
+# Review evidence packet (contributor template)
+
+This file is a **repository-contributor template** for a manually supplied
+Review (finding-adjudication) artifact. The filename identifies an **evidence
+burden**, not a verdict, phase flag, transition, or required
+predecessor/successor.
+
+Selection, composition, and use are **caller-owned** (ADR 0010). This template
+records adjudication evidence only. It does **not** define Reviewer protocol,
+alter Reviewer method/audit, or alter Collector ledger semantics. Judge Review
+posture meaning remains in `souls/judge.md`. No generic Reviewer/Collector
+provider law is introduced (ADR 0011).
+
+## Sealed authority identity
+
+| Artifact | Repository-relative path | SHA-256 of exact bytes |
+| --- | --- | --- |
+| Authority materials | | |
+
+A digest seals identity only—not truth, acceptance, or freshness.
+
+## Fixed reviewed range
+
+Every finding and disposition in this packet concerns **one immutable range**
+and current target facts. A changed target or range requires a **new**
+artifact/digest; do not silently mutate this packet.
+
+| Field | Full SHA |
+| --- | --- |
+| Range base commit | |
+| Range target commit | |
+| Current target facts bind to | |
+
+## Findings and dispositions
+
+Bind each independent finding to sealed authority, the fixed range above, and
+current facts. Every finding needs an explicit disposition.
+
+| Finding ID | Claim | Authority binding | Evidence on current target/range | Disposition | Disposition evidence |
+| --- | --- | --- | --- | --- | --- |
+| F1 | | | | sustained / rejected / deferred / other | |
+
+## Explicit non-claims
+
+- Filename is not a verdict and does not imply Review convergence.
+- This packet defines no required review order, repetition count, or return path
+  to any role.
+- No routing, next-role, stage machine, or provider-universal protocol arises here.
+- No mechanical schema/runtime enforcement is claimed by this template.