zob-harness 0.2.0 → 0.3.0

package/.pi/zagents/spec-chief.json

@@ -0,0 +1,21 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "spec-chief",
+  "team": "agentic-spec-run",
+  "role": "orchestrator",
+  "alias": "spec_chief",
+  "description": "Lead for one Agentic Spec Team run; sole human interlocutor and owner of questions, blockers, traceability posture, and final report readiness.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "orchestrator",
+  "defaultRoom": "spec-control",
+  "activeRoom": "spec-control",
+  "rooms": [{ "id": "spec-control", "alias": "spec_chief", "role": "lead", "active": true }],
+  "allowedTools": ["read", "bash", "write", "edit", "zpeer_ask"],
+  "allowedPaths": ["AGENTS.md", "README.md", "docs/", "specs/", "scripts/spec-run.mjs", "scripts/agentic-spec-team/", "reports/agentic-spec-runs/", ".pi/skills/zob-agentic-spec-team/", ".pi/factories/agentic-spec-team/", ".pi/zagents/", ".pi/zteams/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "approvalGates": { "externalAccess": "human", "externalWrite": "human+oracle", "commitOrPush": "human" },
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/spec-oracle.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "spec-oracle",
+  "team": "agentic-spec-run",
+  "role": "oracle",
+  "alias": "spec_oracle",
+  "description": "Skeptically validates source traceability, open questions, sensitive data posture, testability, handoff readiness, and no-ship status.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "oracle",
+  "defaultRoom": "oracle",
+  "activeRoom": "oracle",
+  "rooms": [{ "id": "spec-control", "alias": "spec_oracle", "role": "oracle", "active": true }, { "id": "oracle", "alias": "spec_oracle", "role": "oracle", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "oracle"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/spec-writer.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "spec-writer",
+  "team": "agentic-spec-run",
+  "role": "spec-writing",
+  "alias": "spec_writer",
+  "description": "Synthesizes mission spec, feature slices, functional/non-functional requirements, and API/data contracts from traced evidence.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "implement",
+  "defaultRoom": "writing",
+  "activeRoom": "writing",
+  "rooms": [{ "id": "spec-control", "alias": "spec_writer", "role": "member", "active": true }, { "id": "writing", "alias": "spec_writer", "role": "writer", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "writing"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/ux-flow-analyst.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "ux-flow-analyst",
+  "team": "agentic-spec-run",
+  "role": "ux-analysis",
+  "alias": "ux_flow",
+  "description": "Maps mockups, screens, user journeys, UI states, roles, permissions, and UX edge cases into cited artifacts.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "explore",
+  "defaultRoom": "ux",
+  "activeRoom": "ux",
+  "rooms": [{ "id": "spec-control", "alias": "ux_flow", "role": "member", "active": true }, { "id": "ux", "alias": "ux_flow", "role": "analyst", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "ux"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zteams/agentic-spec-run.json

@@ -0,0 +1,42 @@
+{
+  "schema": "zob.zteam.v1",
+  "id": "agentic-spec-run",
+  "description": "Temporary run-scoped Agentic Spec Team for turning explicit sources plus mission text into a traceable implementation spec.",
+  "defaultRoom": "spec-control",
+  "activeRoom": "spec-control",
+  "rooms": [
+    { "id": "spec-control", "role": "coordination", "active": true },
+    { "id": "intake", "role": "source-intake", "active": true },
+    { "id": "data", "role": "data-analysis", "active": true },
+    { "id": "domain", "role": "domain-modeling", "active": true },
+    { "id": "ux", "role": "ux-analysis", "active": true },
+    { "id": "writing", "role": "spec-writing", "active": true },
+    { "id": "validation", "role": "acceptance-bdd", "active": true },
+    { "id": "handoff", "role": "implementation-handoff", "active": true },
+    { "id": "oracle", "role": "final-review", "active": true }
+  ],
+  "agents": [
+    { "id": "spec-chief", "alias": "spec_chief", "rooms": [{ "id": "spec-control", "alias": "spec_chief", "role": "lead", "active": true }] },
+    { "id": "source-intake-steward", "alias": "source_intake", "rooms": [{ "id": "spec-control", "alias": "source_intake", "role": "member", "active": true }, { "id": "intake", "alias": "source_intake", "role": "steward", "active": true }] },
+    { "id": "data-profile-analyst", "alias": "data_profile", "rooms": [{ "id": "spec-control", "alias": "data_profile", "role": "member", "active": true }, { "id": "data", "alias": "data_profile", "role": "analyst", "active": true }] },
+    { "id": "domain-modeler", "alias": "domain_modeler", "rooms": [{ "id": "spec-control", "alias": "domain_modeler", "role": "member", "active": true }, { "id": "domain", "alias": "domain_modeler", "role": "modeler", "active": true }] },
+    { "id": "ux-flow-analyst", "alias": "ux_flow", "rooms": [{ "id": "spec-control", "alias": "ux_flow", "role": "member", "active": true }, { "id": "ux", "alias": "ux_flow", "role": "analyst", "active": true }] },
+    { "id": "spec-writer", "alias": "spec_writer", "rooms": [{ "id": "spec-control", "alias": "spec_writer", "role": "member", "active": true }, { "id": "writing", "alias": "spec_writer", "role": "writer", "active": true }] },
+    { "id": "bdd-writer", "alias": "bdd_writer", "rooms": [{ "id": "spec-control", "alias": "bdd_writer", "role": "member", "active": true }, { "id": "validation", "alias": "bdd_writer", "role": "acceptance", "active": true }] },
+    { "id": "planner-handoff-writer", "alias": "handoff_writer", "rooms": [{ "id": "spec-control", "alias": "handoff_writer", "role": "member", "active": true }, { "id": "handoff", "alias": "handoff_writer", "role": "planner", "active": true }] },
+    { "id": "spec-oracle", "alias": "spec_oracle", "rooms": [{ "id": "spec-control", "alias": "spec_oracle", "role": "oracle", "active": true }, { "id": "oracle", "alias": "spec_oracle", "role": "oracle", "active": true }] }
+  ],
+  "communicationPolicy": {
+    "zpeerContact": true,
+    "allowedRooms": ["spec-control", "intake", "data", "domain", "ux", "writing", "validation", "handoff", "oracle"],
+    "parentVisible": true,
+    "hiddenPeerChat": false,
+    "bodyStored": false
+  },
+  "metadata": {
+    "entryAgent": "spec-chief",
+    "temporaryRunTeam": true,
+    "humanInterlocutor": "spec-chief",
+    "closePolicy": "close only after final-report/status PASS no_ship=false"
+  }
+}

package/.pi/zteams/agentic-spec-run.tmux.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="/Users/cgarrot/zob/zob-harness"
+ENTRY_AGENT="spec-chief"
+PI_BIN="/Users/cgarrot/.nvm/versions/node/v24.14.0/bin/pi"
+AGENTS=(
+  "spec-chief"
+  "source-intake-steward"
+  "data-profile-analyst"
+  "domain-modeler"
+  "ux-flow-analyst"
+  "spec-writer"
+  "bdd-writer"
+  "planner-handoff-writer"
+  "spec-oracle"
+)
+
+require_tmux() {
+  command -v tmux >/dev/null 2>&1 || { echo "tmux is required" >&2; exit 1; }
+}
+
+safe_token() {
+  printf '%s' "${1:-}" | tr -c 'A-Za-z0-9_-' '-' | sed 's/^-*//; s/-*$//; s/--*/-/g' | cut -c1-120
+}
+
+session_name() {
+  local run_id="$(safe_token "${1:-}")"
+  [ -n "$run_id" ] || { echo "missing run_id" >&2; exit 2; }
+  printf 'agentic-spec-run-%s' "$run_id"
+}
+
+is_known_agent() {
+  local candidate="${1:-}"
+  local agent
+  for agent in "${AGENTS[@]}"; do
+    [ "$agent" = "$candidate" ] && return 0
+  done
+  return 1
+}
+
+resolve_agent() {
+  local requested="${1:-$ENTRY_AGENT}"
+  if ! is_known_agent "$requested"; then
+    echo "Unknown run agent/window: $requested" >&2
+    printf 'Known agents:\n' >&2
+    printf '  %s\n' "${AGENTS[@]}" >&2
+    exit 2
+  fi
+  printf '%s' "$requested"
+}
+
+session_exists() {
+  local session="$1"
+  tmux has-session -t "$session" 2>/dev/null
+}
+
+start_detached() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  cd "$PROJECT_DIR"
+
+  if session_exists "$session"; then
+    echo "session already running: $session"
+    return 0
+  fi
+
+  local first="${AGENTS[0]}"
+  tmux new-session -d -s "$session" -n "$first" -c "$PROJECT_DIR"
+  tmux send-keys -t "$session:$first" "cd '$PROJECT_DIR' && unset npm_config_prefix && AGENTIC_SPEC_RUN_ID='$run_id' ZOB_ZAGENT_ID=$first '$PI_BIN'" C-m
+
+  local agent
+  for agent in "${AGENTS[@]:1}"; do
+    tmux new-window -t "$session" -n "$agent" -c "$PROJECT_DIR"
+    tmux send-keys -t "$session:$agent" "cd '$PROJECT_DIR' && unset npm_config_prefix && AGENTIC_SPEC_RUN_ID='$run_id' ZOB_ZAGENT_ID=$agent '$PI_BIN'" C-m
+  done
+
+  tmux select-window -t "$session:$ENTRY_AGENT"
+  echo "session started detached: $session"
+}
+
+attach() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  local agent="$(resolve_agent "${2:-$ENTRY_AGENT}")"
+  if ! session_exists "$session"; then
+    echo "session not running: $session" >&2
+    echo "Run: $0 start-detached $run_id" >&2
+    exit 1
+  fi
+  tmux select-window -t "$session:$agent"
+  tmux attach -t "$session:$agent"
+}
+
+status() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  if session_exists "$session"; then
+    tmux list-windows -t "$session" -F '#{window_index}: #{window_name} #{pane_current_command} active=#{window_active} panes=#{window_panes}'
+  else
+    echo "session not running: $session"
+  fi
+}
+
+close() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  if session_exists "$session"; then
+    tmux kill-session -t "$session"
+    echo "session closed: $session"
+  else
+    echo "session not running: $session"
+  fi
+}
+
+list_agents() {
+  printf 'entry: %s\n' "$ENTRY_AGENT"
+  printf 'agents:\n'
+  printf '  %s\n' "${AGENTS[@]}"
+}
+
+case "${1:-}" in
+  start|start-detached) start_detached "${2:-}" ;;
+  attach|window) attach "${2:-}" "${3:-$ENTRY_AGENT}" ;;
+  status) status "${2:-}" ;;
+  close) close "${2:-}" ;;
+  list) list_agents ;;
+  session-name) session_name "${2:-}" ;;
+  *) echo "Usage: $0 start-detached <run_id>|status <run_id>|attach <run_id> [agent]|close <run_id>|list|session-name <run_id>" >&2; exit 2 ;;
+esac

package/SOURCE_INDEX.md

@@ -35,7 +35,7 @@ See `scripts/README.md` for the script surface map.
 
 These are intentionally local/generated and should not be committed by default:
 
-- `docs/` — legacy/internal docs for now; future curated docs should be recreated intentionally.
+- `docs/` — curated architecture/refactor docs plus local/generated planning docs; classify generated reports separately before commit.
 - `plans/` — captured planning artifacts.
 - `reports/` — generated reports and evidence.
 - `.pi/tmp/`, `.pi/logs/`, `.pi/sessions/`, `.pi/agent-sessions/` — runtime local state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zob-harness",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A governed, human-controlled Pi harness for contract-driven agentic engineering, safety gates, specialist delegation, and software-factory workflows.",
   "license": "MIT",
@@ -46,6 +46,7 @@
     ".pi/factories/factory-forge",
     ".pi/factories/opencode-pattern-canonizer",
     ".pi/factories/project-dna",
+    ".pi/factories/agentic-spec-team",
     ".pi/factories/roadmap-smoke-lots",
     ".pi/git-policy.json",
     ".pi/mission-control/zob_coms_transport.json",
@@ -57,7 +58,11 @@
     ".pi/settings.json",
     ".pi/skills",
     ".pi/teams",
+    ".pi/zagents",
+    ".pi/zteams",
     "scripts/README.md",
+    "scripts/spec-run.mjs",
+    "scripts/agentic-spec-team",
     "scripts/autonomy",
     "scripts/compute-profile",
     "scripts/git-ops",
@@ -79,6 +84,9 @@
     "pi": "pi",
     "pi:explore": "pi --no-extensions -e ./.pi/extensions/zob-harness/index.ts --tools read,grep,find,ls,delegate_agent --append-system-prompt 'Start in ZOB explore mode.'",
     "pi:check": "pi --offline --no-session --no-extensions -e ./.pi/extensions/zob-harness/index.ts -p 'Reply exactly: zob-harness-ok'",
+    "spec-run": "node scripts/spec-run.mjs",
+    "spec-run:auto-pilot": "node scripts/spec-run.mjs auto-pilot",
+    "validate:agentic-spec-team": "node scripts/agentic-spec-team/validate-run.mjs",
     "check": "tsc --noEmit --pretty false",
     "check:ci": "npm run check -- --pretty false",
     "smoke:path-policy": "node scripts/path-policy/validate-smoke.mjs",

package/scripts/README.md

@@ -13,7 +13,7 @@ These script families are intended to be part of the normal tracked repo workflo
 - `scripts/model-catalog/` — local model catalog/economy validators.
 - `scripts/package-surface/` — package.json script/file surface validation.
 - `scripts/path-policy/` — path safety smoke checks.
-- `scripts/project-dna/` — ProjectDNA scaffold/scan/query smoke helpers.
+- `scripts/project-dna/` — ProjectDNA scaffold/scan/query smoke helpers; canonical helpers are grouped in subfolders with top-level compatibility CLI shims.
 - `scripts/worker-pool/` — worker-pool metadata/static checks.
 - `scripts/start-pi.sh` — local Pi startup helper.
 

package/scripts/agentic-spec-team/validate-bdd.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const run = process.argv[2];
+const runDir = (run || "").startsWith("reports/") ? run : `reports/agentic-spec-runs/${run || ""}`;
+const criteria = join(runDir, "validation/acceptance-criteria.md");
+const bdd = join(runDir, "validation/bdd-scenarios.feature.md");
+const errors = [];
+if (!existsSync(criteria)) errors.push(`missing ${criteria}`);
+if (!existsSync(bdd)) errors.push(`missing ${bdd}`);
+if (existsSync(bdd) && !/Given|When|Then/u.test(readFileSync(bdd, "utf8"))) errors.push("BDD scenarios should include Given/When/Then");
+console.log(JSON.stringify({ schema: "agentic-spec.validate-bdd-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, errors }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/agentic-spec-team/validate-final-report.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const run = process.argv[2];
+const runDir = (run || "").startsWith("reports/") ? run : `reports/agentic-spec-runs/${run || ""}`;
+const file = join(runDir, "final-report.json");
+const errors = [];
+if (!existsSync(file)) errors.push(`missing ${file}`);
+let value = null;
+if (!errors.length) value = JSON.parse(readFileSync(file, "utf8"));
+if (value && value.schema !== "agentic-spec.final-report.v1") errors.push("schema mismatch");
+if (value && !(value.status === "pass" && value.verdict === "PASS" && value.no_ship === false)) errors.push("final report must be status=pass verdict=PASS no_ship=false");
+console.log(JSON.stringify({ schema: "agentic-spec.validate-final-report-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, errors }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/agentic-spec-team/validate-manifest.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const run = process.argv[2];
+const runDir = (run || "").startsWith("reports/") ? run : `reports/agentic-spec-runs/${run || ""}`;
+const file = join(runDir, "run-manifest.json");
+const errors = [];
+if (!existsSync(file)) errors.push(`missing ${file}`);
+let manifest = null;
+if (!errors.length) manifest = JSON.parse(readFileSync(file, "utf8"));
+if (manifest && manifest.schema !== "agentic-spec-run.manifest.v1") errors.push("schema mismatch");
+if (manifest && (!manifest.mission || !manifest.source_count)) errors.push("mission and source_count are required");
+console.log(JSON.stringify({ schema: "agentic-spec.validate-manifest-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, errors }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/agentic-spec-team/validate-oracle-ready.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+const run = process.argv[2];
+const checks = ["validate-run.mjs", "validate-question-loop.mjs", "validate-traceability.mjs"];
+const results = checks.map((script) => {
+  const res = spawnSync(process.execPath, [`scripts/agentic-spec-team/${script}`, run], { encoding: "utf8", cwd: process.cwd() });
+  let parsed = null;
+  try { parsed = JSON.parse(res.stdout); } catch {}
+  return { script, status: res.status, parsed };
+});
+const errors = results.filter((r) => r.status !== 0).map((r) => `${r.script} failed`);
+console.log(JSON.stringify({ schema: "agentic-spec.validate-oracle-ready-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, errors, results }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/agentic-spec-team/validate-question-loop.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const run = process.argv[2];
+const runDir = (run || "").startsWith("reports/") ? run : `reports/agentic-spec-runs/${run || ""}`;
+const file = join(runDir, "questions.jsonl");
+const errors = [];
+const rows = existsSync(file) ? readFileSync(file, "utf8").split(/\n/u).filter(Boolean).map((line) => JSON.parse(line)) : [];
+for (const q of rows) {
+  if (!q.question_id || q.schema !== "agentic-spec.question.v1") errors.push(`invalid question: ${JSON.stringify(q)}`);
+}
+const openBlocking = rows.filter((q) => q.blocking === true && !["answered", "closed", "withdrawn"].includes(q.status));
+if (openBlocking.length) errors.push(`open blocking questions: ${openBlocking.map((q) => q.question_id).join(", ")}`);
+console.log(JSON.stringify({ schema: "agentic-spec.validate-question-loop-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, open_blocking_questions: openBlocking.map((q) => q.question_id), errors }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/agentic-spec-team/validate-run.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+const target = process.argv[2];
+if (!target || process.argv.includes("--help")) {
+  console.log(JSON.stringify({ schema: "agentic-spec.validate-run-help.v1", usage: "node scripts/agentic-spec-team/validate-run.mjs <run_id|run_dir>" }, null, 2));
+  process.exit(target ? 0 : 1);
+}
+const result = spawnSync(process.execPath, ["scripts/spec-run.mjs", "validate", target], { encoding: "utf8", cwd: process.cwd() });
+process.stdout.write(result.stdout || "");
+process.stderr.write(result.stderr || "");
+process.exitCode = result.status ?? 1;

package/scripts/agentic-spec-team/validate-source-register.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const run = process.argv[2];
+const runDir = (run || "").startsWith("reports/") ? run : `reports/agentic-spec-runs/${run || ""}`;
+const file = join(runDir, "source-register.json");
+const errors = [];
+if (!existsSync(file)) errors.push(`missing ${file}`);
+let value = null;
+if (!errors.length) value = JSON.parse(readFileSync(file, "utf8"));
+if (value && value.schema !== "agentic-spec.source-register.v1") errors.push("schema mismatch");
+if (value && (!Array.isArray(value.sources) || value.sources.length < 1)) errors.push("sources must be non-empty");
+for (const source of value?.sources || []) {
+  if (!source.source_id || !source.path || !source.policy) errors.push(`invalid source row: ${JSON.stringify(source)}`);
+}
+console.log(JSON.stringify({ schema: "agentic-spec.validate-source-register-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, errors }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/agentic-spec-team/validate-traceability.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const run = process.argv[2];
+const runDir = (run || "").startsWith("reports/") ? run : `reports/agentic-spec-runs/${run || ""}`;
+const file = join(runDir, "validation/traceability-matrix.json");
+const errors = [];
+if (!existsSync(file)) errors.push(`missing ${file}`);
+let value = null;
+if (!errors.length) value = JSON.parse(readFileSync(file, "utf8"));
+if (value && value.schema !== "agentic-spec.traceability.v1") errors.push("schema mismatch");
+if (value && !Array.isArray(value.rows)) errors.push("rows must be an array");
+for (const row of value?.rows || []) {
+  if (!row.requirement_id || !row.support_ref) errors.push(`row missing requirement/support: ${JSON.stringify(row)}`);
+  if (!Array.isArray(row.acceptance_criteria_refs) || row.acceptance_criteria_refs.length < 1) errors.push(`row missing acceptance criteria: ${row.requirement_id}`);
+  if (!Array.isArray(row.task_refs) || row.task_refs.length < 1) errors.push(`row missing task refs: ${row.requirement_id}`);
+  if (!row.oracle_check_ref) errors.push(`row missing oracle check: ${row.requirement_id}`);
+}
+console.log(JSON.stringify({ schema: "agentic-spec.validate-traceability-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, errors }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/agentic-spec-team/validate-workgraph.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const run = process.argv[2];
+const runDir = (run || "").startsWith("reports/") ? run : `reports/agentic-spec-runs/${run || ""}`;
+const workgraph = join(runDir, "handoff/workgraph.md");
+const tasks = join(runDir, "handoff/implementation-tasks.md");
+const errors = [];
+if (!existsSync(workgraph)) errors.push(`missing ${workgraph}`);
+if (!existsSync(tasks)) errors.push(`missing ${tasks}`);
+if (existsSync(tasks) && !/REQ-|AC-|TASK-/u.test(readFileSync(tasks, "utf8"))) errors.push("tasks should cite requirement/acceptance/task ids");
+console.log(JSON.stringify({ schema: "agentic-spec.validate-workgraph-result.v1", status: errors.length ? "fail" : "pass", no_ship: errors.length > 0, errors }, null, 2));
+process.exitCode = errors.length ? 1 : 0;

package/scripts/autonomy/mission-readiness-secret-smoke.mjs

@@ -7,9 +7,9 @@ const repoRoot = process.cwd();
 const runtimeRoot = join(repoRoot, "reports/benchmarks/coding-agent-benchmark/live-dokploy-pilot-v3/autonomy-secret-smoke-runtime");
 
 const sourceFiles = [
-  ".pi/extensions/zob-harness/src/interactive-autonomy.ts",
-  ".pi/extensions/zob-harness/src/utils/hashing.ts",
-  ".pi/extensions/zob-harness/src/utils/records.ts",
+  ".pi/extensions/zob-harness/src/domains/autonomy/interactive-autonomy.ts",
+  ".pi/extensions/zob-harness/src/core/utils/hashing.ts",
+  ".pi/extensions/zob-harness/src/core/utils/records.ts",
 ];
 
 mkdirSync(runtimeRoot, { recursive: true });
@@ -33,10 +33,10 @@ for (const sourceFile of sourceFiles) {
   writeFileSync(outputPath, transpiled.outputText, "utf8");
 }
 
-const { DEFAULT_INTERACTIVE_AUTONOMY_POLICY, scoreMissionReadiness } = await import(pathToFileURL(join(runtimeRoot, "interactive-autonomy.js")).href);
+const { DEFAULT_INTERACTIVE_AUTONOMY_POLICY, scoreMissionReadiness } = await import(pathToFileURL(join(runtimeRoot, "domains", "autonomy", "interactive-autonomy.js")).href);
 
 const generatedAt = "2026-05-31T00:00:00.000Z";
-const negativeDenylistPrompt = `Fix V3 autonomy readiness in .pi/extensions/zob-harness/src/interactive-autonomy.ts.
+const negativeDenylistPrompt = `Fix V3 autonomy readiness in .pi/extensions/zob-harness/src/domains/autonomy/interactive-autonomy.ts.
 Acceptance criteria: validate with npm run check -- --pretty false and a deterministic smoke.
 MUST NOT: Do not read .env/key files, ~/.ssh, or ~/.aws.
 Deliver evidence and keep safety gates enabled.`;

package/scripts/git-ops/commit-policy-smoke.mjs

@@ -31,14 +31,14 @@ const policy = JSON.parse(readText(".pi/git-policy.json"));
 const capabilities = JSON.parse(readText(".pi/capabilities/zob-public-runtime-capabilities.json"));
 const damageRules = JSON.parse(readText(".pi/damage-control-rules.json"));
 const skill = readText(".pi/skills/zob-commit/SKILL.md");
-const gitOps = readText(".pi/extensions/zob-harness/src/git-ops.ts");
+const gitOps = readText(".pi/extensions/zob-harness/src/domains/git/git-ops.ts");
 const commands = readText(".pi/extensions/zob-harness/src/runtime/commands.ts");
 const events = readText(".pi/extensions/zob-harness/src/runtime/events.ts");
 const toolsZcommit = readText(".pi/extensions/zob-harness/src/runtime/tools-zcommit.ts");
 const runtime = readText(".pi/extensions/zob-harness/src/runtime/zobHarness.ts");
 const state = readText(".pi/extensions/zob-harness/src/runtime/state.ts");
-const goalTodos = readText(".pi/extensions/zob-harness/src/goal-todos.ts");
-const goalRuntime = readText(".pi/extensions/zob-harness/src/goal-runtime.ts");
+const goalTodos = readText(".pi/extensions/zob-harness/src/domains/goal/goal-todos.ts");
+const goalRuntime = readText(".pi/extensions/zob-harness/src/runtime/goal-runtime.ts");
 const toolsDelegation = readText(".pi/extensions/zob-harness/src/runtime/tools-delegation.ts");
 
 const allowedZcommitCommands = [
@@ -173,7 +173,8 @@ assertIncludes(gitOps, "zcommitFileContentHash", "git-ops.ts child dirty delta c
 assertIncludes(gitOps, "hardForbiddenZcommitPatterns", "git-ops.ts policy/hard forbidden path filter");
 assertIncludes(gitOps, "...Object.keys(runtime.ownedPathRefs ?? {})", "git-ops.ts retains explicit owned path refs for legacy/adopt metadata");
 assertNotIncludes(gitOps, "dirtyFiles.map", "git-ops.ts must not blindly map all dirty files into ownership refs");
-assertIncludes(gitOps, '["diff", "--cached", "--name-only", "-z"]', "git-ops.ts cached index inspection");
+assertIncludes(gitOps, '["diff", "--cached", "--no-renames", "--name-only", "-z"]', "git-ops.ts cached index inspection must be stable for delete+add rehomes");
+assertIncludes(gitOps, '["diff", "--cached", "--no-renames", "--binary", "--", ...paths]', "git-ops.ts cached patch capture must avoid rename-collapsed rehomes");
 assertIncludes(gitOps, '["diff", "--cached", "--check"]', "git-ops.ts cached diff verification");
 assertIncludes(gitOps, "sameStringSet(stagedAfterAdd, eligiblePaths)", "git-ops.ts staged path allowlist verification");
 assertIncludes(gitOps, "commitMessageArgs", "git-ops.ts Conventional Commit path");

package/scripts/goal-todo/child-goal-ref-smoke.mjs

@@ -39,9 +39,9 @@ for (const file of listTsFiles(srcRoot)) {
   writeFileSync(out, outputText);
 }
 
-const goalTodos = await import(pathToFileURL(join(outRoot, "goal-todos.js")).href);
+const goalTodos = await import(pathToFileURL(join(outRoot, "domains", "goal", "goal-todos.js")).href);
 const modeIntent = await import(pathToFileURL(join(outRoot, "runtime", "mode-intent.js")).href);
-const modelAvailability = await import(pathToFileURL(join(outRoot, "model-availability.js")).href);
+const modelAvailability = await import(pathToFileURL(join(outRoot, "domains", "models", "model-availability.js")).href);
 const toolsDelegationSource = readFileSync(join(srcRoot, "runtime", "tools-delegation.ts"), "utf8");
 assert(!toolsDelegationSource.includes("childGoalTodoErrors"), "delegation runtime must not reference stale childGoalTodoErrors symbol");
 assert(toolsDelegationSource.includes("...childGoalResolution.errors"), "delegation preflight must include structured childGoalResolution.errors");

package/scripts/path-policy/validate-smoke.mjs

@@ -39,9 +39,9 @@ for (const file of listTsFiles(srcRoot)) {
   writeFileSync(out, outputText);
 }
 
-const safety = await import(pathToFileURL(join(outRoot, "safety.js")).href);
-const paths = await import(pathToFileURL(join(outRoot, "utils", "paths.js")).href);
-const adaptive = await import(pathToFileURL(join(outRoot, "orchestration", "adaptive-delegation.js")).href);
+const safety = await import(pathToFileURL(join(outRoot, "domains", "governance", "safety.js")).href);
+const paths = await import(pathToFileURL(join(outRoot, "core", "utils", "paths.js")).href);
+const adaptive = await import(pathToFileURL(join(outRoot, "domains", "orchestration", "adaptive-delegation.js")).href);
 
 const invalidAllowedPaths = ["docs/../", "docs/../src", "./docs/../", "a/../../b"];
 for (const candidate of invalidAllowedPaths) {

package/scripts/project-dna/AGENTS.md

@@ -0,0 +1,39 @@
+# ProjectDNA Script Guardrails
+
+Scope: `scripts/project-dna/` contains ProjectDNA scaffold, scan, workflow, query, sample, benchmark, oracle, and validation helpers.
+
+## Structure
+
+Canonical scripts live in grouped subfolders:
+
+- `scan/` — scanner and scan-artifact validation.
+- `workflow/` — agentic workflow planning and validation.
+- `emit/` — ontology and golden-case emission helpers.
+- `query/` — context query and query-steward helpers.
+- `sample/` — sample-spec, quarantine sample generation, and sample validation.
+- `capsules/` — pointer capsule builders.
+- `benchmark/` — deterministic benchmark smoke helpers.
+- `oracle/` — structural oracle review helpers.
+- `validation/` — scaffold, ontology, golden-case, and 5/5 posture validators.
+
+Top-level `*.mjs` entries are compatibility shims for existing `package.json` commands and direct CLI paths. Keep those paths stable unless package refs and downstream callers are intentionally migrated.
+
+## Invariants
+
+- Split-only changes: move code, do not change script logic, CLI args, output paths, status strings, report schemas, or validation semantics.
+- Preserve read/write posture: ProjectDNA scans are read-only for source projects; generated outputs stay under approved quarantine/report locations.
+- Do not read secrets or traverse forbidden/generated folders such as `.env`, `.git`, `node_modules`, `dist`, `build`, or runtime ledgers.
+- Keep package command behavior stable; prefer compatibility shims over package script churn.
+- Do not introduce network calls or external knowledge-backend imports/writes without explicit approval.
+
+## Validation ladder
+
+After structural edits, run:
+
+```bash
+npm run validate:script-surface
+npm run validate:project-dna
+npm run check -- --pretty false
+```
+
+Run targeted ProjectDNA smokes only when their report-output paths are approved for the current task.