@hybridlabor-api/aos 4.1.0 → 4.2.0

package/.agents/agents.md

@@ -137,6 +137,83 @@ next. This file defines *what each agent is*, not *what calls what*.
 - **Output Artifacts**: `production_artifacts/04_release_report.md`
 - **Reads**: `state.artifacts.*`, `state.findings`, `state.approvals` · **Writes**: `state.gate`, `state.artifacts.report`, `state.phase: ship|done`
 
+---
+
+# Auxiliary agents
+
+The six below are **not** pipeline nodes — they are never in `.agents/nodes.json`,
+never invoked by the dispatcher, and never part of the seven-agent routing above.
+They are standalone specialists you reach for directly. They live here rather than
+only in `.claude/agents/` so the installer compiles them for every harness
+(Antigravity, OpenCode, Codex, Cursor, Roo) instead of leaving them Claude-Code-only.
+
+Ported from [affaan-m/ECC](https://github.com/affaan-m/ECC) (MIT) — see
+`THIRD_PARTY_NOTICES.md`.
+
+---
+
+## 🕳️ silent-failure-hunter
+- **Role**: Reviews code for silent failures, swallowed errors, bad fallbacks, and missing error propagation. Finds the bugs that never raise.
+- **Model**: sonnet
+- **Primary Skills**:
+  - `systematic-debugging`
+  - `debugger`
+  - `clean-code`
+- **Output Artifact**: findings returned inline (writes no file)
+
+---
+
+## 🛡️ security-reviewer
+- **Role**: Security vulnerability detection and remediation. Use after writing code that handles user input, authentication, API endpoints, or sensitive data. Flags secrets, SSRF, injection, unsafe crypto, and OWASP Top 10.
+- **Model**: sonnet
+- **Primary Skills**:
+  - `systematic-debugging`
+  - `clean-code`
+  - `api-design-principles`
+- **Output Artifact**: findings returned inline (writes no file)
+
+---
+
+## 🔧 go-build-resolver
+- **Role**: Resolves Go build, vet, and compilation errors with minimal changes. Use when Go builds fail — relevant to `bdb-synapse`, which ships a Go binary.
+- **Model**: sonnet
+- **Primary Skills**:
+  - `golang-pro`
+  - `go-concurrency-patterns`
+  - `systematic-debugging`
+- **Output Artifact**: edits the failing sources directly
+
+---
+
+## 🗄️ database-reviewer
+- **Role**: PostgreSQL specialist for query optimization, schema design, security, and performance. Use when writing SQL, creating migrations, or troubleshooting database performance.
+- **Model**: sonnet
+- **Primary Skills**:
+  - `postgres-best-practices`
+  - `database-design`
+  - `drizzle-orm-expert`
+- **Output Artifact**: findings returned inline (writes no file)
+
+---
+
+## 📦 opensource-forker
+- **Role**: Forks a project for open-sourcing — copies files, strips secrets and credentials, replaces internal references with placeholders, generates `.env.example`, cleans git history. Run before `opensource-sanitizer`.
+- **Model**: haiku
+- **Primary Skills**:
+  - `github-repo`
+  - `bash-linux`
+- **Output Artifact**: `FORK_REPORT.md`
+
+---
+
+## 🧼 opensource-sanitizer
+- **Role**: Verifies an open-source fork is fully sanitized before release. Scans for leaked secrets, PII, internal references, and dangerous files; emits PASS/FAIL/PASS-WITH-WARNINGS. Run after `opensource-forker`, before any public release.
+- **Model**: sonnet
+- **Primary Skills**:
+  - `github-repo`
+  - `bash-linux`
+- **Output Artifact**: `SANITIZATION_REPORT.md`
+
 ---
 ## 🔄 Context Boot Sequence
 Before executing any tasks, every agent MUST perform the following checks silently:

package/.agents/graph.md

@@ -33,6 +33,51 @@ before returning — this is what replaces "hand-off," and it's why a node
 never needs another node's reasoning: `goal` and prior artifacts are always
 read from the same typed record, not re-derived from a sibling's prose.
 
+## Mandatory Skill Injection
+
+`/startcycle-graph --skill=<name> <goal>` (repeatable: `--skill=a --skill=b
+<goal>`, quote a name containing spaces) forces a specific skill into this
+run — for the case where you have your own private skill (never part of
+`.agents/nodes.json`'s registry, and never touched by AOS's installer per
+its foreign-file conflict policy) that you need applied regardless of what
+the registry's own per-node allowlist would have reached for.
+
+- The dispatcher script (`startcycle-dispatch.mjs`) extracts every
+  `--skill=` flag from the invocation text before anything else runs, then
+  validates each name resolves to a real installed skill (a `SKILL.md`
+  under any harness's global skills directory — `~/.claude/skills/<name>/`,
+  `~/.agents/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, `~/.roo/skills/`,
+  all of which the installer writes — or this project's own `skills/` tree) via
+  a read-only lookup agent. **A name that doesn't resolve escalates
+  immediately** — same "never silently fall back or guess" posture as a
+  missing registry node id. This is a fail-fast check specifically so a
+  typo doesn't silently ship a run that never used the skill you asked for.
+  A flag written with an empty value (`--skill=` with nothing after it)
+  escalates for the same reason: it would otherwise inject nothing *and*
+  leave the literal `--skill=` glued to the goal text Architect reads.
+- The validated list is persisted to `state.mandatory_skills` (set by
+  Architect on the first write) and passed to every build node's prompt —
+  and Architect's own — as a **hard requirement, not a suggestion**,
+  layered on top of (never replacing) the registry's own per-node skill
+  allowlist.
+- **TechLead rejects a plan that ignores the mandate**, at the plan-approval
+  gate — one extra planning round instead of a wasted build cycle. Without
+  this the mandate is only caught downstream by Reviewer, i.e. after the
+  build nodes have already run against a plan that never accounted for it.
+- **Reviewer checks it was actually used, not just available.** An artifact
+  that shows no sign of applying a mandated skill's guidance is a
+  `contract_misread` finding (blocking), owned by whichever build node
+  should have applied it — the same precedence class as misreading the
+  plan itself, since an ignored `--skill` flag is exactly that.
+- Nodes that do **not** receive the mandate, deliberately: `shipping` (runs
+  mechanical gates — lint/typecheck/tests — and produces no artifact a skill
+  would shape).
+- `/startcycle` (the linear variant, no `state.json`) and
+  `/startcycle-graph-user` (throwaway, nothing persistent) support the same
+  `--skill=<name>` syntax — see each skill's own `SKILL.md` for how the
+  orchestrator threads it through without a durable state file to carry it
+  in.
+
 ## Nodes
 
 Seven, up from the original five — `Planner_Orchestrator` is split into

package/.agents/nodes.json

@@ -72,7 +72,8 @@
         "drizzle-orm-expert",
         "postgres-best-practices",
         "typescript-pro",
-        "python-pro"
+        "python-pro",
+        "bdbresilience"
       ],
       "instructions": "Implement the backend per the plan: DDD models, type-safe schemas, API routes, Clean Architecture. Write production_artifacts/02_backend_schema.md and the code."
     },
@@ -128,7 +129,8 @@
         "seo-audit",
         "wcag-audit-patterns",
         "github-repo",
-        "clean-code"
+        "clean-code",
+        "bdbresilience"
       ],
       "instructions": null
     }

package/.agents/state.schema.json

@@ -89,6 +89,12 @@
         "additionalProperties": false
       }
     },
+    "mandatory_skills": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Skill names the user required via /startcycle-graph's --skill=<name> flag (repeatable), validated to exist before the run proceeds. Empty when the user didn't ask for one. Build nodes (and Architect) are told to actually apply these, not just have them available; Reviewer checks the resulting artifacts for evidence they were used and flags a contract-misread finding if not. See .agents/graph.md's 'Mandatory Skill Injection' section."
+    },
     "needs_human": {
       "type": "boolean",
       "default": false,

package/.claude/workflows/startcycle-dispatch.mjs

@@ -81,6 +81,14 @@ const MAX_ITERATIONS = 3;
 // correct on the first draft.
 let iteration = 0;
 
+// Populated from a --skill=<name> flag (repeatable) in the invocation text --
+// see extractMandatorySkills() and .agents/graph.md's "Mandatory Skill
+// Injection" section. Empty when the user didn't ask for one. Module-level
+// like `iteration` above, for the same reason: skillsNote() and the Reviewer
+// prompt both need it and neither is in a position to thread it through as a
+// parameter without touching every call site.
+let mandatorySkills = [];
+
 // Every sequential (non-build-role) agent gets the same note: read the full
 // state, and explicitly set state.iteration to the dispatcher's current
 // count so the persisted file (which .claude/hooks/graph-gate.mjs reads)
@@ -149,11 +157,27 @@ function reviewerStateNote() {
 // Applies to every node, build and sequential alike.
 function skillsNote(node) {
   const skills = Array.isArray(node?.skills) ? node.skills : [];
-  if (skills.length === 0) return '';
-  return (
-    ` Use these skills for this work: ${skills.join(', ')}. ` +
-    'Do not reach for skills outside this list unless the task genuinely requires it.'
-  );
+  const parts = [];
+  if (skills.length > 0) {
+    parts.push(
+      ` Use these skills for this work: ${skills.join(', ')}. ` +
+      'Do not reach for skills outside this list unless the task genuinely requires it.'
+    );
+  }
+  // A --skill flag is a hard requirement from the user, not the registry's
+  // own suggested allowlist above -- it applies on top of, never instead of,
+  // that list. Only nodes that actually produce work get told to use it:
+  // build-role nodes, plus Architect (who should fold the skill's guidance
+  // into the plan itself, not just leave it for Build to discover cold).
+  // Reviewer gets a separate mention in its own prompt below, framed as a
+  // check rather than a use.
+  if (mandatorySkills.length > 0 && (node?.role === 'build' || node?.id === 'architect')) {
+    parts.push(
+      ` The user explicitly required this run to use the following skill(s), via /startcycle-graph's --skill flag: ${mandatorySkills.join(', ')}. ` +
+      "This is a hard requirement, not a suggestion -- actually apply the skill's guidance in your work, and name in your returned summary how each one was applied."
+    );
+  }
+  return parts.join('');
 }
 
 // "a", "a or b", "a, b, or c" -- used for NODE_NAMES, itself derived from the
@@ -297,13 +321,110 @@ const techleadNode = { id: 'techlead', ...registryNodes.techlead };
 const reviewerNode = { id: 'reviewer', ...registryNodes.reviewer };
 const shippingNode = { id: 'shipping', ...registryNodes.shipping };
 
-const goal = typeof args === 'string' ? args : args?.goal;
-if (!goal) {
+const rawGoal = typeof args === 'string' ? args : args?.goal;
+if (!rawGoal) {
   return escalate(
     'startcycle-graph needs a goal, e.g. "Run /startcycle-graph on: add OAuth login with Google" -- nothing was invoked.'
   );
 }
 
+// --skill=<name>, repeatable, extracted out of the raw goal text before
+// anything else sees it -- e.g. "--skill=my-custom-skill Add OAuth login"
+// becomes goal "Add OAuth login" plus one mandated skill name. This is the
+// mechanism for injecting a skill this script has never heard of (a user's
+// own private skill, never part of .agents/nodes.json's registry) -- see
+// .agents/graph.md's "Mandatory Skill Injection" section.
+function extractMandatorySkills(text) {
+  // The `|--skill=(?=\s|$)` alternative deliberately matches a flag with an
+  // EMPTY value ("--skill= add OAuth"). Without it, `\S+` simply fails to
+  // match, the flag falls through as ordinary prose, and the run proceeds
+  // with no skill injected AND the literal "--skill=" still glued to the
+  // goal text handed to Architect -- a silent no-op on a typo, which is the
+  // exact failure mode the validation below exists to prevent. Capturing it
+  // as an empty name instead routes it into `malformed` and escalates.
+  const flagPattern = /--skill=("[^"]+"|'[^']+'|\S+)|--skill=(?=\s|$)/g;
+  const skills = [];
+  let malformed = 0;
+  const goal = text
+    .replace(flagPattern, (_, val) => {
+      if (val === undefined) { malformed++; return ''; }
+      const unquoted =
+        (val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))
+          ? val.slice(1, -1)
+          : val;
+      if (unquoted.trim() === '') { malformed++; return ''; }
+      skills.push(unquoted);
+      return '';
+    })
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+  return { skills, goal, malformed };
+}
+
+const { skills: skillsFromFlags, goal, malformed } = extractMandatorySkills(rawGoal);
+if (malformed > 0) {
+  return await escalate(
+    `--skill was given with an empty value (${malformed} time(s)). Write --skill=<name>, e.g. --skill=my-custom-skill. ` +
+      'Refusing to proceed rather than silently running without the skill you asked for.'
+  );
+}
+if (!goal) {
+  return await escalate(
+    'startcycle-graph needs actual goal text, not just --skill flag(s) -- e.g. "--skill=my-custom-skill add OAuth login with Google", not "--skill=my-custom-skill" alone.'
+  );
+}
+// Object-form args may also carry a structured list directly, for a future
+// caller that never goes through the string-flag convention at all.
+const skillsFromArgs = Array.isArray(args?.mandatorySkills) ? args.mandatorySkills : [];
+const mandatorySkillNames = [...new Set([...skillsFromFlags, ...skillsFromArgs])];
+
+// Validate before anything else runs -- same "never silently fall back or
+// guess" posture as the registry load above. This script has no filesystem
+// access of its own (comment block item #1), so validation is itself an
+// agent() call, not a local fs check.
+if (mandatorySkillNames.length > 0) {
+  const skillCheckResult = await agent(
+    `Check whether each of these skill names resolves to an installed skill with a real SKILL.md: ${JSON.stringify(mandatorySkillNames)}. ` +
+      'The installer syncs the same skill set to every harness it detects, so check all of these global locations, not just the first: ' +
+      '~/.claude/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md, ~/.codex/skills/<name>/SKILL.md, ' +
+      '~/.cursor/skills/<name>/SKILL.md, ~/.roo/skills/<name>/SKILL.md. A skill present in any one of them counts as installed — ' +
+      'this workflow may be driven from a harness whose directory is not ~/.claude. ' +
+      'If this project has its own skills/ directory, also accept skills/<name>/SKILL.md or skills/<container>/<name>/SKILL.md. ' +
+      'This is a read-only lookup, not a reasoning task -- do not invent a path that does not exist, and never report a close match as `found`.\n\n' +
+      'For any name that does NOT resolve, list up to five installed skills whose directory names are plausible near-misses ' +
+      '(substring, obvious typo, or the same words in another order) in `suggestions`. Read the real directory listing to do this -- ' +
+      'suggest only names that actually exist on disk. `--skill=` requires an exact directory name, and a user who mistyped one ' +
+      'has no way to discover the right spelling from an error that only says "not found".\n\n' +
+      'Return only: { "found": string[], "missing": string[], "suggestions": string[] }.',
+    {
+      label: 'validate-mandatory-skills',
+      model: 'haiku',
+      schema: {
+        type: 'object',
+        required: ['found', 'missing'],
+        properties: {
+          found: { type: 'array', items: { type: 'string' } },
+          missing: { type: 'array', items: { type: 'string' } },
+          suggestions: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    }
+  );
+  const missing = skillCheckResult?.missing ?? [];
+  if (missing.length > 0) {
+    const near = skillCheckResult?.suggestions ?? [];
+    return await escalate(
+      `--skill named skill(s) that could not be found on this machine: ${missing.join(', ')}. ` +
+        (near.length
+          ? `Did you mean: ${near.join(', ')}? `
+          : 'No installed skill has a similar name. ') +
+        '--skill= takes the exact skill directory name; run /ask-tim to find the one you want. ' +
+        'Refusing to silently proceed without a mandated skill.'
+    );
+  }
+  mandatorySkills = skillCheckResult?.found ?? mandatorySkillNames;
+}
+
 // ---------------------------------------------------------------------
 // Architect <-> TechLead: plan, then capability-map approval. Sequential --
 // not part of the CHANGE 1 race, writes state.json directly as before.
@@ -323,7 +444,7 @@ while (!approved) {
         : '') +
       `Turn this goal into a system plan with an explicit capability map (module boundaries, ` +
       `dependency direction, build order). Write it to production_artifacts/00_execution_plan.md. ` +
-      `Set state.goal, state.phase = "plan", state.artifacts.plan to that path. ` +
+      `Set state.goal, state.phase = "plan", state.artifacts.plan to that path, and state.mandatory_skills to ${JSON.stringify(mandatorySkills)}. ` +
       `Decide whether the goal needs the Media_EventTech build node (TouchDesigner/show-control/3D/media work) -- most goals don't.\n\n` +
       `Return only: { "planPath": string, "needsMedia": boolean }.`,
     {
@@ -349,6 +470,11 @@ while (!approved) {
     `You are acting as the ${techleadNode.label} agent (${techleadNode.personaFile}). ${dispatchNote(techleadNode)}${skillsNote(techleadNode)}\n\n` +
       `Read the plan at ${planPath}. Approve it only if it has an explicit capability map: ` +
       `module boundaries, dependency direction, and build order are all stated, not implicit. ` +
+      (mandatorySkills.length > 0
+        ? `The user also required this run to use the following skill(s) via /startcycle-graph's --skill flag: ${mandatorySkills.join(', ')}. ` +
+          `Reject the plan if it does not actually account for them — catching that here costs one planning round, ` +
+          `whereas letting it through wastes a full build cycle before Reviewer flags it.\n`
+        : '') +
       `Record your decision in state.json (plan approval, state.phase = "build" if approved).\n\n` +
       `Return only: { "approved": boolean, "reason": string }.`,
     {
@@ -459,6 +585,11 @@ while (!reviewedClean) {
       }, and the actual code). ` +
       `Do an adversarial review against the contract: find what is wrong, do not validate, do not summarize. ` +
       `Do not assume the implementation is correct just because it exists. ` +
+      (mandatorySkills.length > 0
+        ? `The user explicitly required these skill(s) to be used this run, via /startcycle-graph's --skill flag: ${mandatorySkills.join(', ')}. ` +
+          `If an artifact shows no sign of applying a mandated skill's guidance, that is a contract misread finding (blocking), owned by whichever build node should have applied it. ` +
+          `A mandated skill being merely available is not enough -- check for it actually being used.\n`
+        : '') +
       `Classify every finding by precedence: contract misread > valid & actionable (blocking) > valid trade-off (advisory) > noise (discard). ` +
       `Each finding must name which node owns fixing it: ${NODE_NAMES} -- no other value is valid. ` +
       `If you are re-reviewing after a repair round and an issue you flagged before is still present and still unfixed, ` +

package/.claude/workflows/teamwork-dispatch.mjs

@@ -0,0 +1,287 @@
+// Dispatcher for /teamwork-preview. Turns the 9-step prompt-crafting protocol
+// from skills/basic/teamwork-preview/SKILL.md into an actual runnable sequence.
+//
+// Why a script and not prose: this repo has already paid for the alternative
+// once, recorded verbatim in skills/basic/startcycle-graph/SKILL.md --
+//
+//   "an earlier version of this file embedded the full pipeline description in
+//    prose, and the model followed it 'in spirit' inline instead of invoking the
+//    script -- silently skipping the whole graph, with no state.json, no
+//    subagents, no Reviewer, and no quality gate ever running."
+//
+// A 9-step protocol with acceptance criteria and integrity modes is exactly the
+// kind of thing that gets followed approximately. A script either runs or it
+// does not.
+//
+// Runtime constraints inherited from startcycle-dispatch.mjs, all four of which
+// this script obeys:
+//   1. No filesystem access from the script itself. Every read and write happens
+//      inside an agent() call; the script branches on schema-validated returns.
+//   2. No module loading. `agent`, `args` are ambient globals injected by the
+//      runtime, not imports.
+//   3. Concurrent agents writing one file race. This script is deliberately
+//      sequential -- each step's answers reshape the next question, so there is
+//      nothing to parallelise and no fragment/merge dance is needed.
+//   4. Prompts are the interface. An agent that returns prose instead of the
+//      declared schema breaks the branch, so every step declares one.
+//
+// This is NOT Antigravity's /teamwork-preview. That command is compiled into the
+// agy binary (its own conductor/orchestrator/auditor agent types, maintained by
+// Google). This is an independent implementation of the same idea, on a
+// different runtime, and it will behave differently.
+
+export const meta = {
+  name: 'teamwork-dispatch',
+  description:
+    'Interactive 9-step prompt crafting for multi-agent delegation: elicit, disambiguate, set integrity mode, draft requirements, design verification, set acceptance criteria, then assemble and validate a spec. Produces prompt_draft.md; does not build anything.',
+};
+
+// The user's answers accumulate here. Each step gets the answers so far, so a
+// later question can be shaped by an earlier one -- which is the whole point of
+// an interview and the reason these run sequentially rather than in parallel.
+const spec = {
+  idea: null,
+  scale: null,
+  integrityMode: null,
+  requirements: [],
+  verification: null,
+  acceptanceCriteria: [],
+  infrastructure: null,
+  workingDirectory: null,
+};
+
+// One shared preamble. Every step is an interview turn, not a build turn: the
+// agent asks, the human answers, nothing gets implemented. Stated once here
+// rather than restated nine times, where the ninth copy would drift.
+const INTERVIEW_RULE =
+  'You are conducting one step of an interactive interview. Ask the user, wait for their answer, and record it. ' +
+  'Do NOT implement anything, do NOT write project code, and do NOT proceed past your own step. ' +
+  'Finding facts is your job, not the user\'s: if a question can be answered by reading the filesystem or running a command, ' +
+  'do that yourself instead of asking. The decisions are the user\'s: put each to them and wait. ' +
+  'If the user has already answered something in an earlier step, do not ask it again -- the answers so far are given below.';
+
+function answersSoFar() {
+  const known = Object.entries(spec).filter(([, v]) =>
+    Array.isArray(v) ? v.length > 0 : v !== null
+  );
+  if (known.length === 0) return 'Nothing settled yet -- this is the first step.';
+  return `Answers settled so far:\n${JSON.stringify(Object.fromEntries(known), null, 2)}`;
+}
+
+async function step(n, title, instruction, schema, label) {
+  return await agent(
+    `${INTERVIEW_RULE}\n\n` +
+      `## Step ${n} of 9: ${title}\n\n${instruction}\n\n` +
+      `${answersSoFar()}\n\n` +
+      'Return only the declared JSON.',
+    { label: label || `step-${n}`, schema }
+  );
+}
+
+const goal = typeof args === 'string' ? args : args?.goal;
+
+// ---------------------------------------------------------------------
+// Steps 1-3: what is this, how big, and what is it allowed to use
+// ---------------------------------------------------------------------
+
+const s1 = await step(
+  1,
+  'Elicit the idea',
+  'Ask what the user wants to build, what its purpose is (production, demo, eval, or prototype), and who the audience is. ' +
+    'Condense their answer into a description of one or two sentences -- not a paragraph, and not a restatement of the question.' +
+    (goal ? `\n\nThe user already said: ${JSON.stringify(goal)}. Start from that; ask only what it leaves open.` : ''),
+  {
+    type: 'object',
+    required: ['description', 'purpose'],
+    properties: {
+      description: { type: 'string' },
+      purpose: { type: 'string', enum: ['production', 'demo', 'eval', 'prototype'] },
+      audience: { type: 'string' },
+    },
+  }
+);
+spec.idea = s1;
+
+const s2 = await step(
+  2,
+  'Identify ambiguity and scale',
+  'Probe every point that has more than one reasonable interpretation -- data sources, third-party services, where the scope stops. ' +
+    'Then establish the shape of the effort:\n' +
+    '- a single self-contained fix or feature (one implementer plus repeated adversarial review)\n' +
+    '- math, formal proofs, or a massive search space (may warrant a large agent team)\n' +
+    '- a standard multi-agent build\n\n' +
+    'Ambiguity you leave unresolved here becomes a wrong assumption baked into the spec, so be thorough now rather than agreeable.',
+  {
+    type: 'object',
+    required: ['scale'],
+    properties: {
+      scale: { type: 'string', enum: ['single-focused', 'large-scale', 'standard'] },
+      ambiguitiesResolved: { type: 'array', items: { type: 'string' } },
+    },
+  }
+);
+spec.scale = s2;
+
+const s3 = await step(
+  3,
+  'Determine integrity mode',
+  'Clarify the operational boundaries: may code be copied from existing open-source projects? Are pre-built libraries allowed for the core logic ' +
+    '(as opposed to the scaffolding)? May the implementer inspect the tests before writing the code?\n\n' +
+    'Map the answers: unrestricted → `development`; some shortcuts acceptable because it is a showcase → `demo`; ' +
+    'strict isolation, zero external leakage → `benchmark`.\n\n' +
+    'The last question matters more than it looks: an implementer who can read the tests first can satisfy them without solving the problem.',
+  {
+    type: 'object',
+    required: ['integrityMode'],
+    properties: {
+      integrityMode: { type: 'string', enum: ['development', 'demo', 'benchmark'] },
+      rationale: { type: 'string' },
+    },
+  }
+);
+spec.integrityMode = s3.integrityMode;
+
+// ---------------------------------------------------------------------
+// Steps 4-6: what must be true, and how anyone would know
+// ---------------------------------------------------------------------
+
+const s4 = await step(
+  4,
+  'Draft requirements',
+  'Write two to five requirement blocks (R1, R2, ...). Each states **what** is required, never **how** to implement it.\n\n' +
+    'Apply the litmus test to every one: would a senior engineer feel over-constrained by this? If yes, prune it. ' +
+    'A requirement that dictates implementation removes the judgement you are hiring the implementer for.',
+  {
+    type: 'object',
+    required: ['requirements'],
+    properties: {
+      requirements: {
+        type: 'array',
+        minItems: 2,
+        maxItems: 5,
+        items: {
+          type: 'object',
+          required: ['id', 'text'],
+          properties: { id: { type: 'string' }, text: { type: 'string' } },
+        },
+      },
+    },
+  }
+);
+spec.requirements = s4.requirements;
+
+const s5 = await step(
+  5,
+  'Design the verification mechanism',
+  'This is the forcing function, and it is the step that decides whether the whole exercise works.\n\n' +
+    'Its job is to create an objective target that forces a real build → test → debug loop and makes premature self-certification impossible. ' +
+    'An agent that can declare its own work done, will.\n\n' +
+    'Prefer something programmatic: a unit test suite, a test runner invocation, a CLI script that asserts. ' +
+    'Only if that is genuinely infeasible, draft an explicit agent-as-judge rubric -- and say why programmatic was not possible. ' +
+    'Ask whether the user has existing test suites, schemas, or a reference implementation to hand the implementer.',
+  {
+    type: 'object',
+    required: ['mechanism', 'isProgrammatic'],
+    properties: {
+      mechanism: { type: 'string' },
+      isProgrammatic: { type: 'boolean' },
+      resources: { type: 'array', items: { type: 'string' } },
+    },
+  }
+);
+spec.verification = s5;
+
+const s6 = await step(
+  6,
+  'Set acceptance criteria',
+  'Convert the verification mechanism into checkable criteria -- each one a thing that is either true or false, never a judgement call.\n\n' +
+    `Calibrate to the stated purpose (${spec.idea.purpose}): a demo must be achievable in a rapid time budget; ` +
+    'production needs real coverage, error handling and readiness; an eval needs reproducible metrics far more than polish.\n\n' +
+    'A criterion nobody can mechanically check is a wish, not a criterion.',
+  {
+    type: 'object',
+    required: ['criteria'],
+    properties: { criteria: { type: 'array', minItems: 1, items: { type: 'string' } } },
+  }
+);
+spec.acceptanceCriteria = s6.criteria;
+
+// ---------------------------------------------------------------------
+// Steps 7-8: where it runs
+// ---------------------------------------------------------------------
+
+const s7 = await step(
+  7,
+  'Infrastructure constraints',
+  'Only if the work reaches outside the local workspace: define the sandboxing or controlled APIs for remote file operations, ' +
+    'job launching, and outbound network calls.\n\n' +
+    'If the project stays entirely within local workspace files, say so and skip -- do not invent constraints to fill this step.',
+  {
+    type: 'object',
+    required: ['applicable'],
+    properties: { applicable: { type: 'boolean' }, constraints: { type: 'string' } },
+  }
+);
+spec.infrastructure = s7.applicable ? s7.constraints : null;
+
+const s8 = await step(
+  8,
+  'Choose the working directory',
+  'Confirm where this runs. Default to a path inside the current repository if the work belongs to it, ' +
+    `otherwise \`~/teamwork_projects/<project_name>\`. Check that the path exists or can be created, and say which.`,
+  {
+    type: 'object',
+    required: ['workingDirectory'],
+    properties: { workingDirectory: { type: 'string' }, exists: { type: 'boolean' } },
+  }
+);
+spec.workingDirectory = s8.workingDirectory;
+
+// ---------------------------------------------------------------------
+// Step 9: assemble, validate, and stop for approval
+// ---------------------------------------------------------------------
+
+const s9 = await agent(
+  'You are assembling the final specification from a completed 9-step interview. Do NOT implement any of it.\n\n' +
+    `Write \`prompt_draft.md\` into ${JSON.stringify(spec.workingDirectory)} with this structure:\n\n` +
+    '- the one-to-two sentence project description\n' +
+    '- `Working directory: <path>`\n' +
+    '- `Integrity mode: <mode>`\n' +
+    '- a team-scaling directive, if the scale calls for one\n' +
+    '- `## Requirements` — the R1..Rn blocks\n' +
+    '- `## Verification` — the mechanism, and the resources it may use\n' +
+    '- `## Acceptance Criteria` — as markdown checkboxes (`- [ ]`)\n' +
+    (spec.infrastructure ? '- `## Infrastructure Constraints`\n' : '') +
+    '\nThen validate it against three checks and report each honestly:\n' +
+    '1. Does every acceptance criterion trace back to a stated requirement? An orphan criterion means the interview missed a requirement.\n' +
+    '2. Is every criterion mechanically checkable — true or false, no judgement call?\n' +
+    '3. Does any requirement dictate *how* rather than *what*?\n\n' +
+    'Report failures rather than quietly fixing them: a validation step that edits its own input proves nothing.\n\n' +
+    `The interview produced:\n${JSON.stringify(spec, null, 2)}`,
+  {
+    label: 'step-9-assemble',
+    schema: {
+      type: 'object',
+      required: ['draftPath', 'validationsPassed'],
+      properties: {
+        draftPath: { type: 'string' },
+        validationsPassed: { type: 'boolean' },
+        issues: { type: 'array', items: { type: 'string' } },
+      },
+    },
+  }
+);
+
+// Deliberately stops here. Delegation is a separate, human-approved act: the
+// spec is the deliverable of this workflow, not a launch command. Handing an
+// unapproved spec straight to a swarm is precisely the premature
+// self-certification step 5 exists to prevent.
+return {
+  phase: s9.validationsPassed ? 'ready_for_approval' : 'validation_failed',
+  draftPath: s9.draftPath,
+  issues: s9.issues ?? [],
+  integrityMode: spec.integrityMode,
+  reason: s9.validationsPassed
+    ? `Spec assembled at ${s9.draftPath}. Review it, then delegate to the execution harness of your choice — this workflow deliberately does not launch anything.`
+    : `Spec assembled at ${s9.draftPath} but validation found issues; resolve them before delegating.`,
+};