@windyroad/architect 1.1.0 → 1.1.1-preview.1386

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "1.1.0"
+  "version": "1.1.1"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wr-architect",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Architecture decision enforcement for AI coding agents",
   "author": {
     "name": "Windy Road Technology",

package/hooks/codex-agent-completion.mjs

@@ -5,10 +5,13 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameS
 import { dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CLOSE_TOOLS, SPAWN_TOOLS, WAIT_TOOLS, completionTarget, response } from "./lib/codex-completion-input.mjs";
+import { CLOSE_TOOLS, SPAWN_TOOLS, WAIT_TOOLS, completionTarget, response, reviewerDispatch, reviewerInstructionsMatch, clearGeneralReview } from "./lib/codex-completion-input.mjs";
 
 const hookDir = dirname(fileURLToPath(import.meta.url));
 const role = "wr-architect:agent";
+function reviewerInstructions(candidate) {
+  return candidate === role ? readFileSync(join(hookDir, "..", "agents", "agent.md"), "utf8") : null;
+}
 const ttlText = process.env.REVIEW_TTL ?? "3600";
 const ttl = Number(ttlText) * 1000;
 
@@ -112,24 +115,30 @@ function rememberNative(input) {
 }
 
 function remember(input) {
-  if (existsSync(nativePath(input.session_id))) return;
+  const dispatch = reviewerDispatch(input, reviewerInstructions);
   reapTransport();
   const result = response(input);
   const target = normalizeTarget(result.agent_id ?? result.task_name);
   if (!target) return;
+  if (!dispatch?.reviewerTransport && existsSync(nativePath(input.session_id))) {
+    clearGeneralReview(input, role, target, { state: statePath(input.session_id, target),
+      registration: registrationPath(input.session_id, target), receipt: receiptPath(input.session_id, target) });
+    return;
+  }
   mkdirSync(riskDir(input.session_id), { recursive: true });
   clear(input.session_id, target);
-  if (input.tool_input?.agent_type !== role) return;
+  if (!dispatch) return;
   const bound = checkout(input.cwd || process.cwd());
   const hash = bound && policyHash(bound.root);
   if (!bound || !hash) return diagnostic(bound ? "policy-hash-failed" : "invalid-spawn-checkout", input);
-  const registered = { parentSession: input.session_id, role, target, ...bound, policyHash: hash, createdAt: Date.now() };
+  const registered = { parentSession: input.session_id, role, target, reviewerTransport: dispatch.reviewerTransport, reviewerInstructionsHash: dispatch.reviewerInstructionsHash, ...bound, policyHash: hash, createdAt: Date.now() };
   writeFileSync(statePath(input.session_id, target), JSON.stringify(registered), { mode: 0o600 });
   mkdirSync(transportDir(), { recursive: true, mode: 0o700 });
   writeFileSync(registrationPath(input.session_id, target), JSON.stringify(registered), { mode: 0o600 });
 }
 
 function valid(registered, input, target, age) {
+  if (!reviewerInstructionsMatch(registered, reviewerInstructions)) return diagnostic("reviewer-instructions-changed", input), false;
   if (registered.role !== role || registered.target !== target) return diagnostic("registration-mismatch", input), false;
   if (!Number.isFinite(age) || age < 0) return diagnostic("invalid-registration-age", input), false;
   if (age >= ttl) return diagnostic("stale-registration", input), false;
@@ -159,7 +168,6 @@ function writeMarker(input, registered, target, output, completedAt, claim, done
 }
 
 function complete(input, rawTarget, output) {
-  if (existsSync(nativePath(input.session_id))) return;
   const target = completionTarget(rawTarget, riskDir(input.session_id), "codex-architect-");
   if (!target || typeof output !== "string" || !output) return;
   const state = statePath(input.session_id, target);
@@ -167,6 +175,7 @@ function complete(input, rawTarget, output) {
   let registered, age;
   try { registered = JSON.parse(readFileSync(state, "utf8")); age = Date.now() - statSync(state).mtimeMs; }
   catch { return diagnostic("malformed-registration", input); }
+  if (existsSync(nativePath(input.session_id)) && registered.reviewerTransport !== "general") return;
   if (!valid(registered, input, target, age)) {
     rmSync(state, { force: true });
     rmSync(registrationPath(registered.parentSession || input.session_id, target), { force: true });
@@ -220,7 +229,7 @@ function consume(input) {
     let pending;
     try { pending = JSON.parse(readFileSync(path, "utf8")); } catch { diagnostic("malformed-receipt", input); continue; }
     if (pending.parentSession !== input.session_id || pending.role !== role) continue;
-    if (existsSync(nativePath(input.session_id)) && pending.source !== "subagent-start") continue;
+    if (existsSync(nativePath(input.session_id)) && pending.source !== "subagent-start" && pending.reviewerTransport !== "general") continue;
     if (!valid(pending, input, pending.target, Date.now() - pending.completedAt)) continue;
     const claim = `${path}.claim`;
     try { writeFileSync(claim, "", { flag: "wx", mode: 0o600 }); }

package/hooks/lib/codex-completion-input.mjs

@@ -1,4 +1,59 @@
-import { readdirSync } from "node:fs";
+import { readdirSync, readFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function reviewerFallbackPrompt(role, instructions, request) {
+  return `WR_REVIEWER_FALLBACK: ${role}\n<reviewer-instructions>\n${instructions}</reviewer-instructions>\n\n${request}`;
+}
+
+// A general reviewer is identified by the installed contract actually supplied
+// at dispatch, never by its task name or its returned verdict.
+export function reviewerDispatch(input, loadInstructions) {
+  const options = input.tool_input || {};
+  const prompt = options.message ?? options.prompt ?? "";
+  const named = options.agent_type;
+  try {
+    if (named && named !== "default") {
+      return loadInstructions(named) ? { role: named, prompt } : null;
+    }
+    if (options.fork_turns !== "none" || typeof prompt !== "string") return null;
+    const role = prompt.match(/^WR_REVIEWER_FALLBACK: ([a-z0-9-]+:[a-z0-9-]+)\n/)?.[1];
+    if (!role) return null;
+    const instructions = loadInstructions(role);
+    if (!instructions) return null;
+    const prefix = `WR_REVIEWER_FALLBACK: ${role}\n<reviewer-instructions>\n${instructions}</reviewer-instructions>\n\n`;
+    if (!prompt.startsWith(prefix) || !prompt.slice(prefix.length).trim()) return null;
+    return { role, prompt: prompt.slice(prefix.length), reviewerTransport: "general",
+      reviewerInstructionsHash: createHash("sha256").update(instructions).digest("hex") };
+  } catch { return null; }
+}
+
+export function reviewerInstructionsMatch(registered, loadInstructions) {
+  if (registered.reviewerTransport === undefined) return true;
+  if (registered.reviewerTransport !== "general") return false;
+  try {
+    const instructions = loadInstructions(registered.role);
+    return Boolean(instructions && registered.reviewerInstructionsHash ===
+      createHash("sha256").update(instructions).digest("hex"));
+  } catch { return false; }
+}
+
+// Native replay claims share a target key with legacy receipts. In native mode
+// invalidate only a demonstrably owned general registration, never its claims.
+export function clearGeneralReview(input, role, target, paths) {
+  const owned = value => value.reviewerTransport === "general" && value.role === role &&
+    value.parentSession === input.session_id && value.target === target;
+  try {
+    if (!owned(JSON.parse(readFileSync(paths.registration, "utf8")))) return false;
+  } catch { return false; }
+  rmSync(paths.state, { force: true });
+  rmSync(paths.registration, { force: true });
+  try {
+    if (owned(JSON.parse(readFileSync(paths.receipt, "utf8")))) rmSync(paths.receipt, { force: true });
+  } catch { /* No pending general receipt to invalidate. */ }
+  return true;
+}
 
 // Resolve only this session's state files, including completed claims so an
 // ambiguous short name cannot consume a different reviewer after delivery.
@@ -63,3 +118,14 @@ export function parsedResponse(value) {
 export function response(input) {
   return parsedResponse(input?.tool_response);
 }
+
+// This only prepares a prompt. Hooks independently verify their own installed
+// instruction source before registering or accepting a general review.
+if (process.argv[2] === "--fallback-prompt" && process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (process.argv[2] !== "--fallback-prompt" || process.argv.length !== 5) {
+    console.error("Usage: codex-completion-input.mjs --fallback-prompt <role> <installed-agent.md> < request.txt");
+    process.exitCode = 1;
+  } else {
+    process.stdout.write(reviewerFallbackPrompt(process.argv[3], readFileSync(process.argv[4], "utf8"), readFileSync(0, "utf8")));
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "1.1.0",
+  "version": "1.1.1-preview.1386",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"

package/skills/capture-adr/SKILL.md

@@ -12,7 +12,14 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 > that token with the absolute path before running a bundled script; never
 > search the adopter repository or rely on a `wr-architect-*` command being
 > on `PATH`. Spawn the installed `wr-architect:agent` custom agent with the
-> native Codex subagent tool, wait for it, and close the same agent.
+> native Codex subagent tool when available. Otherwise start an independent
+> general/default subagent with `fork_turns: "none"`. Prepare its message with
+> `node "<architect-plugin-root>/hooks/lib/codex-completion-input.mjs" --fallback-prompt wr-architect:agent "<architect-plugin-root>/agents/agent.md" < request.txt`.
+> Pass that output verbatim, preserve read-only scope, wait, and call
+> `interrupt_agent` once on the completed child. For cognitive review, supply
+> the complete installed `agents/cog-a11y.md`, rubric and ADR to an independent
+> general reviewer if its named reviewer is unavailable. A FAIL requires
+> remediation, not fallback; never write markers or claim unverified completion.
 
 
 # Capture ADR Skill

package/skills/create-adr/SKILL.md

@@ -12,7 +12,14 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input, Agent
 > that token with the absolute path before running a bundled script; never
 > search the adopter repository or rely on a `wr-architect-*` command being
 > on `PATH`. Spawn the installed `wr-architect:agent` custom agent with the
-> native Codex subagent tool, wait for it, and close the same agent.
+> native Codex subagent tool when available. Otherwise start an independent
+> general/default subagent with `fork_turns: "none"`. Prepare its message with
+> `node "<architect-plugin-root>/hooks/lib/codex-completion-input.mjs" --fallback-prompt wr-architect:agent "<architect-plugin-root>/agents/agent.md" < request.txt`.
+> Pass that output verbatim, preserve read-only scope, wait, and call
+> `interrupt_agent` once on the completed child. For cognitive review, supply
+> the complete installed `agents/cog-a11y.md`, rubric and ADR to an independent
+> general reviewer if its named reviewer is unavailable. A FAIL requires
+> remediation, not fallback; never write markers or claim unverified completion.
 
 
 # Architecture Decision Record Generator

package/skills/review-decisions/SKILL.md

@@ -12,7 +12,14 @@ allowed-tools: Read, Glob, Grep, Bash, Edit, request_user_input, Agent
 > that token with the absolute path before running a bundled script; never
 > search the adopter repository or rely on a `wr-architect-*` command being
 > on `PATH`. Spawn the installed `wr-architect:agent` custom agent with the
-> native Codex subagent tool, wait for it, and close the same agent.
+> native Codex subagent tool when available. Otherwise start an independent
+> general/default subagent with `fork_turns: "none"`. Prepare its message with
+> `node "<architect-plugin-root>/hooks/lib/codex-completion-input.mjs" --fallback-prompt wr-architect:agent "<architect-plugin-root>/agents/agent.md" < request.txt`.
+> Pass that output verbatim, preserve read-only scope, wait, and call
+> `interrupt_agent` once on the completed child. For cognitive review, supply
+> the complete installed `agents/cog-a11y.md`, rubric and ADR to an independent
+> general reviewer if its named reviewer is unavailable. A FAIL requires
+> remediation, not fallback; never write markers or claim unverified completion.
 
 
 # Review Decisions — human-oversight drain

package/skills/review-design/SKILL.md

@@ -12,7 +12,14 @@ allowed-tools: Read, Glob, Grep, Bash, request_user_input, Skill
 > that token with the absolute path before running a bundled script; never
 > search the adopter repository or rely on a `wr-architect-*` command being
 > on `PATH`. Spawn the installed `wr-architect:agent` custom agent with the
-> native Codex subagent tool, wait for it, and close the same agent.
+> native Codex subagent tool when available. Otherwise start an independent
+> general/default subagent with `fork_turns: "none"`. Prepare its message with
+> `node "<architect-plugin-root>/hooks/lib/codex-completion-input.mjs" --fallback-prompt wr-architect:agent "<architect-plugin-root>/agents/agent.md" < request.txt`.
+> Pass that output verbatim, preserve read-only scope, wait, and call
+> `interrupt_agent` once on the completed child. For cognitive review, supply
+> the complete installed `agents/cog-a11y.md`, rubric and ADR to an independent
+> general reviewer if its named reviewer is unavailable. A FAIL requires
+> remediation, not fallback; never write markers or claim unverified completion.
 
 
 # Architecture Compliance Review Skill
@@ -110,7 +117,7 @@ agent: wr-architect:agent
 prompt: <constructed review prompt from step 4>
 ```
 
-The Codex installer generates `.codex/agents/wr-architect-agent.toml` from the installed plugin's `agents/agent.md` and registers the exact identity `wr-architect:agent`. SessionStart repairs the user-scoped registration when needed. Adopter projects do not need to ship their own agent configuration. Restart Codex if that exact identity is not visible; do not substitute the built-in `default` agent because the review marker consumes the architect identity. The repo-local `.codex/agents/wr-architect.toml`, kept in sync from `<architect-plugin-root>/agents/agent.md` by `scripts/sync-codex-agents.mjs`, remains the short-name `wr-architect` alias for source-repo dogfooding.
+The Codex installer generates `.codex/agents/wr-architect-agent.toml` from the installed plugin's `agents/agent.md` and registers the exact identity `wr-architect:agent`. SessionStart repairs the user-scoped registration when needed. Adopter projects do not need to ship their own agent configuration. Prefer that named reviewer. If it is unavailable, or the native tool cannot select named reviewers, use an independent general/default subagent with `fork_turns: "none"`. Prepare its message with `node "<architect-plugin-root>/hooks/lib/codex-completion-input.mjs" --fallback-prompt wr-architect:agent "<architect-plugin-root>/agents/agent.md" < request.txt`, where `request.txt` contains the original review request and `<architect-plugin-root>` is the installed plugin root. Pass the output verbatim. Preserve read-only scope, wait for completion, then call `interrupt_agent` once on that child. The normal hook verifies the installed instructions and completed review before recording a result. A substantive FAIL still requires remediation; never write a marker manually. The repo-local `.codex/agents/wr-architect.toml`, kept in sync from `<architect-plugin-root>/agents/agent.md` by `scripts/sync-codex-agents.mjs`, remains the short-name `wr-architect` alias for source-repo dogfooding.
 
 Wait for the agent to complete.