zob-harness 0.2.0 → 0.3.1

package/.pi/extensions/zob-switch/src/settings.ts

@@ -0,0 +1,25 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { SETTINGS_PATH } from "./paths.js";
+
+export type JsonObject = Record<string, unknown>;
+
+export function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+export async function readSettings(cwd: string): Promise<JsonObject> {
+  const raw = await readFile(join(cwd, SETTINGS_PATH), "utf8");
+  const parsed = JSON.parse(raw) as unknown;
+  if (!isObject(parsed)) throw new Error(`${SETTINGS_PATH} must contain a JSON object`);
+  return parsed;
+}
+
+export async function writeSettings(cwd: string, settings: JsonObject): Promise<void> {
+  await writeFile(join(cwd, SETTINGS_PATH), `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}

package/.pi/extensions/zob-switch/src/snapshot.ts

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { SNAPSHOT_PATH } from "./paths.js";
+import { isObject } from "./settings.js";
+import type { JsonObject } from "./settings.js";
+
+export type Snapshot = {
+  schema: "zob.harness-switch.settings-snapshot.v1";
+  savedAt: string;
+  settings: JsonObject;
+};
+
+export async function writeSnapshot(cwd: string, settings: JsonObject): Promise<void> {
+  const snapshot: Snapshot = {
+    schema: "zob.harness-switch.settings-snapshot.v1",
+    savedAt: new Date().toISOString(),
+    settings,
+  };
+  const snapshotPath = join(cwd, SNAPSHOT_PATH);
+  await mkdir(dirname(snapshotPath), { recursive: true });
+  await writeFile(snapshotPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+}
+
+export async function readSnapshot(cwd: string): Promise<Snapshot | null> {
+  const snapshotPath = join(cwd, SNAPSHOT_PATH);
+  if (!existsSync(snapshotPath)) return null;
+  const parsed = JSON.parse(await readFile(snapshotPath, "utf8")) as unknown;
+  if (!isObject(parsed) || parsed.schema !== "zob.harness-switch.settings-snapshot.v1" || !isObject(parsed.settings)) {
+    throw new Error(`${SNAPSHOT_PATH} is not a valid ZOB switch snapshot`);
+  }
+  return parsed as Snapshot;
+}

package/.pi/extensions/zob-switch/src/state.ts

@@ -0,0 +1,57 @@
+import { HARNESS_EXTENSION, SWITCH_EXTENSION, ZOB_PROMPTS, ZOB_SKILLS } from "./paths.js";
+import { asStringArray } from "./settings.js";
+import type { JsonObject } from "./settings.js";
+
+function uniqueWithRequiredFirst(values: string[], requiredFirst: string[]): string[] {
+  const result: string[] = [];
+  for (const value of [...requiredFirst, ...values]) {
+    if (!result.includes(value)) result.push(value);
+  }
+  return result;
+}
+
+function withoutValues(values: string[], remove: string[]): string[] {
+  return values.filter((value) => !remove.includes(value));
+}
+
+export function hasValue(settings: JsonObject, key: "extensions" | "prompts" | "skills", value: string): boolean {
+  return asStringArray(settings[key]).includes(value);
+}
+
+export function buildOffSettings(current: JsonObject): JsonObject {
+  return {
+    ...current,
+    extensions: uniqueWithRequiredFirst(withoutValues(asStringArray(current.extensions), [HARNESS_EXTENSION]), [SWITCH_EXTENSION]),
+    prompts: withoutValues(asStringArray(current.prompts), [ZOB_PROMPTS]),
+    skills: withoutValues(asStringArray(current.skills), [ZOB_SKILLS]),
+  };
+}
+
+export function buildOnSettings(base: JsonObject, usedSnapshot: boolean): JsonObject {
+  return {
+    ...base,
+    extensions: uniqueWithRequiredFirst(asStringArray(base.extensions), [SWITCH_EXTENSION, HARNESS_EXTENSION]),
+    prompts: usedSnapshot ? asStringArray(base.prompts) : uniqueWithRequiredFirst(asStringArray(base.prompts), [ZOB_PROMPTS]),
+    skills: usedSnapshot ? asStringArray(base.skills) : uniqueWithRequiredFirst(asStringArray(base.skills), [ZOB_SKILLS]),
+  };
+}
+
+export function statusFor(settings: JsonObject, snapshotPresent: boolean): string {
+  const switchConfigured = hasValue(settings, "extensions", SWITCH_EXTENSION);
+  const harnessConfigured = hasValue(settings, "extensions", HARNESS_EXTENSION);
+  const promptsConfigured = hasValue(settings, "prompts", ZOB_PROMPTS);
+  const skillsConfigured = hasValue(settings, "skills", ZOB_SKILLS);
+  const state = switchConfigured && harnessConfigured && promptsConfigured && skillsConfigured
+    ? "on"
+    : switchConfigured && !harnessConfigured && !promptsConfigured && !skillsConfigured
+      ? "off"
+      : "partial";
+  return [
+    `ZOB Harness switch: ${state}`,
+    `switch extension: ${switchConfigured ? "configured" : "missing"}`,
+    `harness extension: ${harnessConfigured ? "configured" : "missing"}`,
+    `prompts: ${promptsConfigured ? "configured" : "missing"}`,
+    `skills: ${skillsConfigured ? "configured" : "missing"}`,
+    `snapshot: ${snapshotPresent ? "present" : "missing"}`,
+  ].join("\n");
+}

package/.pi/factories/agentic-spec-team/README.md

@@ -0,0 +1,35 @@
+# Agentic Spec Team Factory
+
+Status: **v1 scaffold**.
+
+This factory describes the repeatable checkpoint backbone for the Agentic Spec Team workflow. The actual v1 launch surface is `scripts/spec-run.mjs` plus run-scoped ZTeam agents. The factory keeps the process evidence-first, human-question-gated, and oracle-reviewed.
+
+## Safe entrypoints
+
+```bash
+npm run spec-run -- init --mission "..." --source docs/ --source data/export.csv
+npm run spec-run:auto-pilot -- --mission-file specs/mission.md --source docs/ --source mockups/
+```
+
+## What it does
+
+- Defines map/reduce/validate stages for source intake, data/domain/UX analysis, spec synthesis, BDD, handoff, and oracle review.
+- Requires traceability from source/answer/assumption to requirement, criteria, task, and oracle check.
+- Treats raw sources as `citation_only` or `context_only` until explicitly approved otherwise.
+- Blocks completion on open blocking questions.
+- Requires final oracle PASS with `no_ship=false`.
+
+## What it does not do in v1
+
+- No runtime `/spec-run` extension command.
+- No external durable write/import/sync.
+- No automatic answer invention for business decisions.
+- No closing tmux on timeout/WARN/FAIL/no_ship=true.
+
+## Local validators
+
+```bash
+node scripts/spec-run.mjs validate <run_id>
+node scripts/agentic-spec-team/validate-run.mjs <run_id>
+node scripts/agentic-spec-team/validate-traceability.mjs <run_id>
+```

package/.pi/factories/agentic-spec-team/batch-manifest.json

@@ -0,0 +1,11 @@
+{
+  "factory": "agentic-spec-team",
+  "mode": "batch",
+  "items": [
+    {
+      "id": "agentic-spec-docs-batch",
+      "path": "docs/",
+      "mission": "Analyze ZOB docs as source material for a detailed agentic spec team operating model."
+    }
+  ]
+}

package/.pi/factories/agentic-spec-team/example-agentic-spec-manifest.json

@@ -0,0 +1,19 @@
+{
+  "schema": "zob.agentic-spec-manifest.v1",
+  "name": "billing-redesign",
+  "mission": "Produce a detailed, testable billing redesign implementation spec from approved docs, data exports, mockups, and owner notes.",
+  "sources": [
+    { "path": "docs/billing-brief.md", "type": "doc", "policy": "citation_only" },
+    { "path": "data/billing-export.csv", "type": "data", "policy": "citation_only" },
+    { "path": "mockups/billing-flow/", "type": "mockups", "policy": "context_only" }
+  ],
+  "human_question_policy": {
+    "interlocutor": "spec-chief",
+    "blocking_questions_stop_auto_pilot": true
+  },
+  "completion_gate": {
+    "traceability_required": true,
+    "oracle_required": true,
+    "no_ship_must_be_false": true
+  }
+}

package/.pi/factories/agentic-spec-team/factory.json

@@ -0,0 +1,98 @@
+{
+  "name": "agentic-spec-team",
+  "version": "0.1.0",
+  "description": "Evidence-first ZOB workflow for producing detailed implementation specs from missions plus docs/data/mockups through a run-scoped agent team.",
+  "status": "v1-scaffold",
+  "autoPromotion": false,
+  "manualPromotionRequired": true,
+  "defaultMode": "smoke",
+  "agenticModel": {
+    "controlPlane": "spec-chief-led-zteam-plus-deterministic-cli",
+    "runtimeExtensionV1": false,
+    "humanInterlocutor": "spec-chief",
+    "traceabilityRequired": true,
+    "oracleRequired": true
+  },
+  "requiredStages": [
+    "manifest_loaded",
+    "source_registered",
+    "analysis_ready",
+    "clarification_closed",
+    "spec_synthesized",
+    "acceptance_ready",
+    "workgraph_ready",
+    "oracle_passed",
+    "sentinel"
+  ],
+  "expectedArtifacts": [
+    "run-manifest.json",
+    "source-register.json",
+    "source-register.md",
+    "questions.md",
+    "answers.md",
+    "validation/traceability-matrix.json",
+    "validation/traceability-matrix.md",
+    "spec/mission-spec.md",
+    "validation/acceptance-criteria.md",
+    "handoff/workgraph.md",
+    "oracle/final-oracle-review.json",
+    "final-report.json",
+    "status.json"
+  ],
+  "noShipBlockers": [
+    "secret-like source path or sensitive raw data persisted without approval",
+    "blocking human question open",
+    "requirement without source, answer, assumption, or decision support",
+    "acceptance criterion not mapped to requirement",
+    "task not mapped to acceptance criterion",
+    "contradiction hidden without decision",
+    "final oracle missing or no_ship=true",
+    "auto-pilot closes tmux on timeout/WARN/FAIL/no_ship=true"
+  ],
+  "stages": [
+    {
+      "name": "source-intake",
+      "type": "map",
+      "agent": "explore",
+      "outputContract": "explore.v1",
+      "requiredTools": ["read", "grep", "find", "ls"],
+      "expectedOutcome": "Inventory approved sources, sensitivity, freshness, owners, contradictions, and open questions with citations.",
+      "mustDo": ["Use only explicit sources from run-manifest.json.", "Assign stable source IDs.", "Flag secret-like or sensitive sources.", "Write source quality gaps."],
+      "mustNotDo": ["No broad filesystem scan.", "No secrets.", "No source mutation.", "No external durable writes."],
+      "context": "Agentic Spec Team run {run.id}; source intake stage."
+    },
+    {
+      "name": "specialized-analysis",
+      "type": "map",
+      "agent": "explore",
+      "outputContract": "explore.v1",
+      "requiredTools": ["read", "grep", "find", "ls"],
+      "expectedOutcome": "Produce data/domain/UX analysis artifacts and candidate traceability rows.",
+      "mustDo": ["Cite source refs for each finding.", "Separate facts from assumptions.", "Propose questions to spec-chief when blocked."],
+      "mustNotDo": ["No invented business decisions.", "No direct human questions except through spec-chief.", "No edits outside the run directory."],
+      "context": "Agentic Spec Team run {run.id}; data/domain/UX analysis."
+    },
+    {
+      "name": "spec-synthesis",
+      "type": "reduce",
+      "agent": "specifier",
+      "outputContract": "spec.v1",
+      "requiredTools": ["read", "grep", "find", "ls"],
+      "expectedOutcome": "Synthesize mission spec, requirements, acceptance criteria, BDD, and workgraph from cited analysis artifacts.",
+      "mustDo": ["Every requirement must be traceable.", "List non-functional requirements and edge cases.", "Map implementation tasks to acceptance criteria."],
+      "mustNotDo": ["No unsupported requirements.", "No hidden contradictions.", "No open blocking questions."],
+      "context": "Agentic Spec Team run {run.id}; spec synthesis."
+    },
+    {
+      "name": "oracle-validation",
+      "type": "validate",
+      "agent": "oracle",
+      "outputContract": "oracle.v1",
+      "requiredTools": ["read", "grep", "find", "ls"],
+      "expectedOutcome": "Validate source-to-requirement-to-task traceability, question closure, sensitive data posture, and final no-ship status.",
+      "mustDo": ["Fail if traceability is incomplete.", "Fail if blocking questions remain open.", "Fail if final-report PASS/no_ship=false is unsupported."],
+      "mustNotDo": ["No patches.", "No commits.", "No external writes.", "No approval of unsupported specs."],
+      "context": "Agentic Spec Team run {run.id}; final oracle gate."
+    }
+  ]
+}

package/.pi/factories/agentic-spec-team/pilot-manifest.json

@@ -0,0 +1,11 @@
+{
+  "factory": "agentic-spec-team",
+  "mode": "pilot",
+  "items": [
+    {
+      "id": "agentic-spec-readme-pilot",
+      "path": "README.md",
+      "mission": "Produce a cited internal spec for how the Agentic Spec Team should be used from this repository."
+    }
+  ]
+}

package/.pi/factories/agentic-spec-team/schemas/final-report.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "zob.agentic-spec.final-report.schema.v1",
+  "type": "object",
+  "required": ["schema", "run_id", "status", "no_ship", "verdict"],
+  "properties": {
+    "schema": { "const": "agentic-spec.final-report.v1" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["pass", "blocked", "fail", "warn"] },
+    "verdict": { "enum": ["PASS", "WARN", "FAIL"] },
+    "no_ship": { "type": "boolean" },
+    "evidence_refs": { "type": "array", "items": { "type": "string" } },
+    "blocking_issues": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/.pi/factories/agentic-spec-team/schemas/manifest.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "zob.agentic-spec.manifest.schema.v1",
+  "type": "object",
+  "required": ["schema", "name", "mission", "sources", "completion_gate"],
+  "properties": {
+    "schema": { "const": "zob.agentic-spec-manifest.v1" },
+    "name": { "type": "string", "minLength": 1 },
+    "mission": { "type": "string", "minLength": 1 },
+    "sources": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["path"], "properties": { "path": { "type": "string", "minLength": 1 }, "type": { "type": "string" }, "policy": { "enum": ["citation_only", "context_only", "safe_to_copy"] } } } },
+    "human_question_policy": { "type": "object" },
+    "completion_gate": { "type": "object" }
+  }
+}

package/.pi/factories/agentic-spec-team/schemas/question.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "zob.agentic-spec.question.schema.v1",
+  "type": "object",
+  "required": ["schema", "question_id", "status", "blocking", "question"],
+  "properties": {
+    "schema": { "const": "agentic-spec.question.v1" },
+    "question_id": { "type": "string", "pattern": "^Q-[0-9]{3,}$" },
+    "status": { "enum": ["open", "answered", "closed", "withdrawn"] },
+    "blocking": { "type": "boolean" },
+    "origin_agent": { "type": "string" },
+    "concerns": { "type": "array", "items": { "type": "string" } },
+    "source_refs": { "type": "array", "items": { "type": "string" } },
+    "question": { "type": "string", "minLength": 1 },
+    "options": { "type": "array" },
+    "recommended_option": { "type": ["string", "null"] }
+  }
+}

package/.pi/factories/agentic-spec-team/schemas/source-register.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "zob.agentic-spec.source-register.schema.v1",
+  "type": "object",
+  "required": ["schema", "run_id", "sources"],
+  "properties": {
+    "schema": { "const": "agentic-spec.source-register.v1" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "sources": { "type": "array", "items": { "type": "object", "required": ["source_id", "path", "exists", "policy"], "properties": { "source_id": { "type": "string" }, "path": { "type": "string" }, "exists": { "type": "boolean" }, "kind": { "type": "string" }, "policy": { "type": "string" }, "sensitivity": { "type": "string" } } } }
+  }
+}

package/.pi/factories/agentic-spec-team/schemas/traceability.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "zob.agentic-spec.traceability.schema.v1",
+  "type": "object",
+  "required": ["schema", "run_id", "rows"],
+  "properties": {
+    "schema": { "const": "agentic-spec.traceability.v1" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "rows": { "type": "array", "items": { "type": "object", "required": ["requirement_id", "support_ref", "acceptance_criteria_refs", "task_refs", "oracle_check_ref"], "properties": { "requirement_id": { "type": "string" }, "support_ref": { "type": "string" }, "acceptance_criteria_refs": { "type": "array", "items": { "type": "string" } }, "task_refs": { "type": "array", "items": { "type": "string" } }, "oracle_check_ref": { "type": "string" } } } }
+  }
+}

package/.pi/factories/agentic-spec-team/smoke-manifest.json

@@ -0,0 +1,11 @@
+{
+  "factory": "agentic-spec-team",
+  "mode": "smoke",
+  "items": [
+    {
+      "id": "agentic-spec-skill-smoke",
+      "path": ".pi/skills/zob-agentic-spec-team/SKILL.md",
+      "mission": "Validate that the Agentic Spec Team scaffold describes a safe evidence-first spec workflow."
+    }
+  ]
+}

package/.pi/skills/zob-agentic-spec-team/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: zob-agentic-spec-team
+description: Use when launching, running, reviewing, or extending the Agentic Spec Team workflow that turns missions plus docs/data/mockups into evidence-first implementation specs.
+---
+# ZOB Agentic Spec Team Skill
+
+## Purpose
+
+Use this skill to run a reusable ZOB-native spec production workflow. It ingests a mission plus explicit source paths, coordinates a run-scoped ZTeam, asks the human only through `spec-chief`, and produces a detailed, testable, traceable implementation spec.
+
+V1 packaging is composite and deliberately **not** a runtime extension. It is a specialized Agent Factory pattern:
+
+```text
+Skill = rules and operating contract
+Factory = repeatable checkpoints, sentinels, validators
+ZTeam/ZAgents = run-scoped human-facing team
+CLI = scriptable entrypoint and tmux automation
+Coms = parent-visible async asks, blockers, evidence refs, and oracle/no-ship routing
+```
+
+Use the generic `examples/agent-factory-tmux-comms/` pattern for a smaller teaching version of the same shape.
+
+## Entry points
+
+```bash
+npm run spec-run -- init --mission "..." --source docs/ --source data/export.csv --name billing-redesign
+npm run spec-run:auto-pilot -- --mission-file specs/mission.md --source docs/ --source mockups/
+```
+
+Run artifacts are written under:
+
+```text
+reports/agentic-spec-runs/<run_id>/
+```
+
+## Team roles
+
+- `spec-chief` — sole human interlocutor, run coordinator, blocker owner.
+- `source-intake-steward` — inventories sources, sensitivity, freshness, contradictions.
+- `data-profile-analyst` — profiles CSV/XLS/structured data and writes dictionaries.
+- `domain-modeler` — extracts entities, states, rules, glossary, assumptions.
+- `ux-flow-analyst` — maps mockups/screens/user journeys and UI state matrix.
+- `spec-writer` — writes mission spec, requirements, slices, contracts.
+- `bdd-writer` — writes acceptance criteria and Gherkin/data-driven examples.
+- `planner-handoff-writer` — produces workgraph, implementation tasks, agent prompts.
+- `spec-oracle` — validates traceability, open questions, safety, and no-ship.
+
+## Required artifacts
+
+```text
+run-manifest.json
+source-register.json/source-register.md
+questions.jsonl/questions.md
+answers.jsonl/answers.md
+analysis/data-profile.json
+analysis/data-dictionary.md
+analysis/domain-model.md
+analysis/business-rules.md
+analysis/ux-flows.md
+spec/mission-spec.md
+spec/functional-requirements.md
+spec/non-functional-requirements.md
+validation/acceptance-criteria.md
+validation/bdd-scenarios.feature.md
+validation/traceability-matrix.json
+validation/traceability-matrix.md
+handoff/workgraph.md
+handoff/implementation-tasks.md
+oracle/final-oracle-review.json
+final-report.json
+status.json
+```
+
+## Traceability rule
+
+Every requirement must map to at least one of:
+
+```text
+source_ref | owner_answer | explicit_assumption | decision_ref
+```
+
+The traceability matrix must connect:
+
+```text
+source_ref -> extracted_fact/answer/assumption -> requirement -> acceptance_criteria -> task -> oracle_check
+```
+
+No requirement may be accepted if it is unsupported or if the supporting source is known to be stale/contradictory without an explicit assumption or decision.
+
+## Human question loop
+
+`spec-chief` is the only role that asks the owner questions. Other agents propose questions to `spec-chief`; they do not directly ask the human unless explicitly instructed.
+
+Question shape:
+
+```json
+{
+  "schema": "agentic-spec.question.v1",
+  "question_id": "Q-001",
+  "status": "open",
+  "blocking": true,
+  "origin_agent": "domain-modeler",
+  "concerns": ["REQ-014", "AC-022"],
+  "source_refs": ["SRC-003"],
+  "question": "Which billing rule wins?",
+  "options": [{ "id": "A", "label": "Invoice date wins" }],
+  "recommended_option": "A"
+}
+```
+
+If a blocking question is open, auto-pilot must return `blocked/no_ship=true` and point to `questions.md`. It must not invent answers.
+
+Answers may be recorded with:
+
+```bash
+npm run spec-run -- answer <run_id> Q-001 --text "..." --answered-by owner
+npm run spec-run -- resume <run_id>
+```
+
+## No-ship blockers
+
+- secret-like paths or sensitive raw data are read/persisted without explicit approval;
+- source content is treated as `safe_to_copy` instead of citation/context evidence;
+- any requirement lacks source/answer/assumption/decision support;
+- acceptance criteria are not mapped to requirements;
+- implementation tasks are not mapped to acceptance criteria;
+- blocking questions remain open;
+- contradictions are hidden or collapsed without decision;
+- ZPeer transient messages are treated as durable evidence without artifact refs;
+- auto-pilot closes tmux on timeout, WARN, FAIL, or `no_ship=true`;
+- final oracle is missing or does not PASS with `no_ship=false`.
+
+## V1 vs V2
+
+V1 uses `.pi/skills`, `.pi/factories`, `.pi/zagents`, `.pi/zteams`, and `scripts/spec-run.mjs`.
+
+V2 may add a runtime `/spec-run` extension command only after the script/team/factory workflow is stable and validated.
+
+## Validation
+
+Minimum parent validation for scaffold changes:
+
+```bash
+npm run check
+node scripts/spec-run.mjs --help
+node scripts/spec-run.mjs init --name smoke --mission "smoke spec" --source README.md
+node scripts/spec-run.mjs validate <run_id>
+```

package/.pi/skills/zob-coms-safety/SKILL.md

@@ -30,6 +30,17 @@ ZOB coms live transport may be transient, but ZOB audit must stay metadata-only.
 - No silent fallback from required live delivery to append-only success.
 - No token/secret logging.
 
+## Tmux Agent Factory safety
+
+For tmux-backed ZAgent teams:
+
+- Tmux is a local launch/observation surface, not the durable source of truth.
+- Startup kickoff files are allowed when they stay bounded and avoid secrets/raw private dumps; post-start pane paste is not reliable proof of delivery.
+- Pane capture may be useful for live diagnosis, but do not persist captured prompt/output bodies into ledgers, reports, Mission Control, or skills.
+- Supervisors/watchdogs must be bounded and local-only; they may detect stale windows or nudge a specific owed-response agent only with hash/body-free durable records.
+- Team communication must remain parent-visible. Prefer one `control` room with lanes/tags/artifact sections unless a bounded owner-approved route exists.
+- Completion still requires artifacts, validation evidence, and oracle/no-ship review when applicable; an active tmux session or chat reply is not completion evidence.
+
 ## Goal Room and owner-pool safety
 
 For parallel owner micro-worker pools:
@@ -48,6 +59,8 @@ No-ship if:
 - live send succeeds while receiver is absent/stale/offline;
 - await treats timeout/stale/offline as success;
 - hidden worker-to-worker free chat works outside a typed parent-visible Goal Room;
+- tmux pane paste/capture is treated as reliable durable communication or completion evidence;
+- a supervisor/watchdog nudges indefinitely, starts broad work, or stores raw pane bodies;
 - a non-owner writes owned paths instead of sending an owner request;
 - a worker applies or merges directly into the main workspace;
 - network starts without explicit auth/locality policy;

package/.pi/skills/zob-coms-v2-live/SKILL.md

@@ -35,6 +35,17 @@ Use this skill when:
 - Do not bypass topology guards.
 - Do not enable network transport without explicit auth/locality policy.
 
+## Tmux/ZAgent communication pattern
+
+For tmux-backed Agent Factory teams:
+
+- Treat each tmux window as a local Pi/ZAgent session with its own identity and room membership.
+- Use tmux only to start, attach, inspect status, or close the local session; do not use pane paste as the primary communication transport.
+- Prefer startup files (`pi @chief-kickoff.md`, `pi @worker-kickoff.md`) for initial instructions so Pi receives one bounded message block.
+- Use async ZPeer/Goal Room-style asks for normal coordination; do not block in polling loops after sending a non-blocking ask.
+- Keep messages short and actionable with `CONTEXT`, `ASK`, `EVIDENCE`, `URGENCY`, and `BLOCKER` fields.
+- When a reply affects scope, ownership, merge readiness, oracle status, or completion, mirror only body-free metadata/artifact refs into durable records.
+
 ## Expected pattern
 
 ```text

package/.pi/skills/zob-factory/SKILL.md

@@ -17,6 +17,19 @@ Use when the task is repeated, batchable, or should become a reusable system rat
 5. Pilot: 10 items max with bounded concurrency.
 6. Batch: only after pilot sentinel and oracle gate.
 
+## Agent Factory shape
+
+Some factories produce not only code or reports, but a supervised team workflow. Treat these as **Agent Factories**. A safe Agent Factory defines:
+
+- ZAgent roles, prompts, default modes, and allowed authority;
+- ZTeam topology, aliases, rooms, entry agent, and `parentVisible` communication policy;
+- optional manual tmux launcher with start/attach/status/close only;
+- startup kickoff templates or rendered kickoff files passed as `pi @kickoff.md`;
+- run artifacts such as `run-manifest.json`, workgraph/status/iteration logs, readiness or kickoff-dispatch records;
+- validation and oracle/no-ship gates before completion claims.
+
+Do not treat launching a tmux team as factory success. Success comes from evidence artifacts, validators, and oracle review.
+
 ## Required artifacts
 
 - `manifest.json`
@@ -26,3 +39,11 @@ Use when the task is repeated, batchable, or should become a reusable system rat
 - `validation.json`
 - phase sentinel (`SMOKE_PASSED.sentinel`, `PILOT_PASSED.sentinel`, or `BATCH_PASSED.sentinel`)
 - `DONE.sentinel` only after validation passes
+
+For Agent Factories, also prefer:
+
+- team manifest or generated run-scoped team manifest
+- kickoff templates or rendered startup kickoff files
+- `autonomous-workgraph.md` / `autonomous-status.md` / `iteration-log.md`
+- `kickoff-dispatch.json` or equivalent body-free startup proof
+- communication protocol and no-ship policy

package/.pi/skills/zob-harness/SKILL.md

@@ -9,12 +9,26 @@ description: Use when working inside the ZOB Pi harness, designing agentic workf
 Use this skill for any task involving:
 - Pi extensions, prompt templates, skills, or agent definitions.
 - Multi-agent delegation workflows.
+- Agent Factory design: ZAgents, ZTeams, tmux launchers, kickoff files, visible coms, workgraphs, and oracle gates.
 - Safety gates and damage-control policy.
 - Software-factory design from repeated manual workflows.
 - Runtime tool/command routing via `.pi/capabilities/zob-public-runtime-capabilities.json`.
 
 For routing behavior, load `zob-tool-router` before non-trivial or tool-ambiguous work. For compaction/recovery behavior, load `zob-compaction-policy` before changing compaction hooks or resuming from a compacted long-running goal. For domain behavior, load the domain skill named by the registry instead of inlining details here: `zob-goal-todo-tree`, `zob-coms-v2-live`, `zob-coms-safety`, `zob-mission-control-coms`, `zob-autonomous-runtime`, `zob-factory`, `zob-sandbox`, `zob-oracle`, or `zob-spec` as applicable.
 
+## Agent Factory posture
+
+Treat ZOB as a governed Agent Factory when the owner wants persistent local agent roles rather than one transient assistant. An Agent Factory may include:
+
+- ZAgent role definitions and prompts;
+- ZTeam topology, rooms, aliases, entry agent, and communication policy;
+- optional tmux launchers for manual local startup/attach/status/close;
+- startup kickoff files passed as `pi @kickoff.md`, not post-start pane paste as the primary transport;
+- run artifacts such as `run-manifest.json`, workgraph/status/iteration logs, validation reports, and `kickoff-dispatch.json`;
+- oracle/no-ship gates before completion claims.
+
+Communication is a core deliverable. Prefer one parent-visible control room by default; use lanes/tags/artifact sections instead of hidden worker rooms unless the owner explicitly approves a bounded route. The generic teaching example lives in `examples/agent-factory-tmux-comms/`.
+
 ## Operating model
 
 1. Classify the task as one of: `explore`, `plan`, `implement`, `oracle`, `factory`, `orchestrator`.