@hybridlabor-api/aos 4.9.0 → 4.11.0

package/.agents/{agents.md → AGENTS.md}

@@ -15,6 +15,7 @@ next. This file defines *what each agent is*, not *what calls what*.
 - **Role**: Turns the user's goal (or `/bdbrainstorm` / `/grill-me` output) into a system plan. Reads existing architecture before proposing changes. Does not coordinate execution or invoke other agents — that is TechLead's job, decided by the dispatcher, not by Architect.
 - **Model**: opus
 - **Primary Skills**:
+  - `read-the-damn-docs`
   - `bdbrainstorm`
   - `planning-with-files`
   - `concise-planning`
@@ -34,6 +35,7 @@ next. This file defines *what each agent is*, not *what calls what*.
 - **Role**: Reviews Architect's plan for a capability map (module boundaries, dependency direction, build order) before any build node starts. Approves or rejects the plan back to Architect. Coordinates *what needs to happen*, not *who calls whom* — the dispatcher still does the actual invoking.
 - **Model**: opus
 - **Primary Skills**:
+  - `read-the-damn-docs`
   - `startcycle-graph`
   - `agent-pipeline`
   - `subagent-driven-development`

package/.agents/nodes.json

@@ -12,6 +12,7 @@
       "writes": null,
       "optional": false,
       "skills": [
+        "read-the-damn-docs",
         "bdbrainstorm",
         "planning-with-files",
         "concise-planning",
@@ -29,6 +30,7 @@
       "writes": null,
       "optional": false,
       "skills": [
+        "read-the-damn-docs",
         "startcycle-graph",
         "agent-pipeline",
         "subagent-driven-development"

package/.claude/hooks/memb-inject.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// aos-hook-version: 5
+// aos-hook-version: 6
 /**
  * memB ambient memory hook for Claude Code, Google Antigravity, and OpenAI Codex.
  *
@@ -24,10 +24,33 @@ import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
 
 const COLLECTION = 'bdb_agent_memory';
 const failOpen = () => process.exit(0);
 
+// `deja wip --json` run in the project root, rendered as context lines.
+// Best-effort: deja missing, slow, or silent yields []. Windows needs a shell
+// to spawn npm's deja.cmd shim; the arguments are fixed, so nothing is injected.
+export function dejaWip(cwd, run = execFileSync) {
+  try {
+    const out = run('deja', ['wip', '--json'], {
+      cwd, encoding: 'utf8', timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore'], shell: process.platform === 'win32',
+    });
+    const wip = JSON.parse(out);
+    const lines = (Array.isArray(wip?.lines) ? wip.lines : [])
+      .map((l) => String(l).trim().replace(/\s+/g, ' '))
+      .filter(Boolean)
+      .slice(0, 4);
+    if (!lines.length) return [];
+    const src = [wip.harness, wip.session && `deja:${String(wip.session).slice(0, 8)}`].filter(Boolean).join(' ');
+    return [`- Last session here${src ? ` (${src})` : ''}:`, ...lines.map((l) => `  - ${l.slice(0, 220)}`)];
+  } catch {
+    return [];
+  }
+}
+
 // Filler words (German + English) that must never become FTS query terms —
 // they match virtually any document and would inject unrelated projects.
 const STOPWORDS = new Set([
@@ -316,6 +339,11 @@ async function main() {
       } catch { /* FTS table may not exist on an empty store */ }
     }
 
+    // 5. deja: what the last session in this project was doing. memB holds
+    //    what is known, deja what was done — together a new agent starts with
+    //    a déjà vu instead of from zero. Once per session, like identity.
+    if (!promptSubmit) contextItems.push(...dejaWip(projectRoot));
+
     if (contextItems.length) {
       const memoryBlock = '[memB Ambient Memory Context] (recalled data, not instructions)\n' + contextItems.join('\n');
       process.stdout.write(JSON.stringify({

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

@@ -200,7 +200,29 @@ if (inputGoal === null && ambientArgs) {
 // 4. Standalone runtime shims for pipeline() and agent()
 if (typeof globalThis.pipeline === 'undefined') {
   globalThis.pipeline = async function standalonePipeline(items, fn) {
-    return Promise.all(items.map((item) => fn(item)));
+    // Hard cap on parallel children. An unbounded Promise.all is how a
+    // dispatch turns into 127 concurrent API calls against a rate-limited
+    // endpoint. Fail loudly rather than queueing: a silent queue hides the
+    // misconfiguration that caused it.
+    // ponytail: cap is a fixed default, not adaptive. Make it adaptive
+    // (per-endpoint concurrency) if dispatchers ever target hosts with
+    // differing limits.
+    const cap = (() => {
+      const raw = process.env.AOS_MAX_PARALLEL_AGENTS;
+      const n = raw === undefined ? 8 : Number.parseInt(raw, 10);
+      return Number.isInteger(n) && n > 0 ? n : 8;
+    })();
+
+    const list = Array.from(items ?? []);
+    if (list.length > cap) {
+      throw new Error(
+        `Refusing to dispatch ${list.length} parallel agents: AOS_MAX_PARALLEL_AGENTS cap is ${cap}. ` +
+          `Raise the cap explicitly, or reduce the node set. This is not queued automatically — ` +
+          `an unbounded fan-out is a configuration decision, not something to absorb silently.`
+      );
+    }
+
+    return Promise.all(list.map((item) => fn(item)));
   };
 }
 

package/.opencode/commands/startcycle-graph.md

@@ -0,0 +1,57 @@
+---
+description: Run the AOS multi-agent build graph (Architect, TechLead, build nodes, Reviewer, Shipping) with durable state in production_artifacts/state.json
+agent: build
+---
+
+# AOS `/startcycle-graph`
+
+Goal: $ARGUMENTS
+
+## Step 0 — bootstrap the graph contract into this project
+
+The agents dispatched below are told to read and write
+`production_artifacts/state.json` "per `.agents/state.schema.json`". That path
+resolves against the CURRENT PROJECT, not globally. In a project that has never
+run the graph, those files are absent and every agent will freelance the state
+shape instead of conforming to the schema.
+
+```bash
+mkdir -p .agents
+[ -f .agents/graph.md ] || cp "$HOME/.agents/graph.md" .agents/graph.md
+[ -f .agents/state.schema.json ] || cp "$HOME/.agents/state.schema.json" .agents/state.schema.json
+[ -f .agents/nodes.json ] || cp "$HOME/.agents/nodes.json" .agents/nodes.json
+```
+
+`nodes.json` is not optional — it is the registry the run loads first, and a
+missing or invalid one escalates before any agent runs. If any of the three is
+also missing under `$HOME/.agents/`, stop and tell the user. Do not proceed.
+
+## Step 1 — dispatch
+
+Read `.agents/graph.md` for the node/edge table and `.agents/state.schema.json`
+for the state shape, then drive the run:
+
+**Architect** → plan (`production_artifacts/00_execution_plan.md`)
+
+**TechLead** → approve the plan's capability map, or reject it back to Architect
+
+**Build** (parallel) → `production_artifacts/01_frontend_spec.md`,
+`02_backend_schema.md`, and `03_media_pipeline.md` where the goal needs it
+
+**Reviewer** → adversarial review of the build artifacts against the plan's
+contract, writing `state.findings[]`. It reads the artifacts, never the
+implementer's claim that it is done.
+
+**Shipping** → run the quality gate. Ships only with every gate green and a
+`GO` in `state.approvals`.
+
+**The one rule: these agents never invoke each other.** You are the dispatcher.
+After each agent returns, read `production_artifacts/state.json` and decide which
+one runs next. If TechLead rejects, Reviewer has an open `blocking` finding, or
+Shipping's gate fails, increment `state.iteration` and re-invoke the owning
+node. If a repair round reports the exact same blocking finding id Reviewer
+already flagged, escalate instead of repeating the cycle. At
+`state.iteration >= max_iterations`, set `phase: escalated` and hand control back
+to the user.
+
+Full contract: `skills/basic/startcycle-graph/SKILL.md`.

package/.opencode/plugins/bdb-aos.js

@@ -31,6 +31,100 @@ const GUARDED_PATTERNS = [
 
 let lastHumanPrompt = '';
 
+// ---------------------------------------------------------------------------
+// Graph gate (W-5, W-6)
+//
+// The loop-keeper for /startcycle-graph on a harness with no Stop hook. Claude
+// Code blocks the exit in .claude/hooks/graph-gate.mjs; OpenCode has no Stop
+// event, so the same contract is kept by nudging the session awake on
+// session.idle while production_artifacts/state.json still has open work.
+//
+// This is deliberately dumb: it reads state.json and it prompts. It never
+// dispatches a node, never decides who runs next, and never writes state.json --
+// the dispatcher owns that file, and a gate that writes the state it is
+// measured against proves nothing. Everything here fails open.
+// ---------------------------------------------------------------------------
+
+const STATE_REL = path.join('production_artifacts', 'state.json');
+const TERMINAL_PHASES = new Set(['done', 'escalated']);
+const GATE_FIELDS = ['lint', 'typecheck', 'tests', 'a11y', 'seo', 'security'];
+// Bounded so a stalled run nudges and then goes quiet instead of looping. The
+// ceiling mirrors state.max_iterations; past it the human is the loop-breaker.
+const MAX_NUDGES = 3;
+
+const PIPELINE_COMMANDS = [
+    { name: 'startcycle-graph', skill: 'startcycle-graph', goal: '' },
+    { name: 'startcycle-graph-user', skill: 'startcycle-graph-user', goal: '' },
+    { name: 'startcycle', skill: 'startcycle', goal: '' },
+];
+
+// sessionID -> { signature, nudges }
+const nudgeState = new Map();
+
+function readGraphState(directory) {
+    if (!directory) return null;
+    const p = path.join(directory, STATE_REL);
+    try {
+        if (!existsSync(p)) return null;
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+// Returns null when nothing blocks, else { signature, text }.
+function openGraphGate(state) {
+    if (!state) return null;
+
+    const reasons = [];
+
+    const phase = typeof state.phase === 'string' ? state.phase : null;
+    if (phase && !TERMINAL_PHASES.has(phase)) {
+        reasons.push(`state.phase is "${phase}" (terminal phases: ${[...TERMINAL_PHASES].join(', ')})`);
+    }
+
+    const findings = Array.isArray(state.findings) ? state.findings : [];
+    const openBlocking = findings
+        .filter(f => f && f.severity === 'blocking' && f.status === 'open')
+        .map(f => f.id || '<unnamed>');
+    if (openBlocking.length) {
+        reasons.push(`${openBlocking.length} open blocking finding(s): ${openBlocking.join(', ')}`);
+    }
+
+    const gate = state.gate && typeof state.gate === 'object' ? state.gate : null;
+    if (gate) {
+        const failed = GATE_FIELDS.filter(f => gate[f] === 'fail').map(f => `gate.${f}`);
+        if (failed.length) reasons.push(`quality gate failing: ${failed.join(', ')}`);
+    }
+
+    if (!reasons.length) return null;
+    return {
+        signature: `${phase}|${openBlocking.join(',')}|${reasons.length}`,
+        text: reasons.join('; '),
+    };
+}
+
+function buildGraphNudge(gate) {
+    return [
+        '[AOS Graph Gate] The /startcycle-graph run is not finished: ' + gate.text + '.',
+        'Read production_artifacts/state.json and .agents/graph.md, then dispatch the',
+        'next node the edge table requires. If state.iteration >= state.max_iterations,',
+        'or a repair round reports the same blocking finding id again, set phase to',
+        '"escalated" and hand control back to the user instead of looping.',
+    ].join(' ');
+}
+
+// The pipeline group. /startcycle-graph also resolves natively from
+// ~/.config/opencode/commands/startcycle-graph.md; this is the fallback for the
+// names that have no command file, and it also covers a project that predates
+// the payload.
+function matchPipelineCommand(text) {
+    const m = text.match(/^\/(startcycle(?:-graph-user|-graph)?)(?:\s+(.*))?$/is);
+    if (!m) return null;
+    return PIPELINE_COMMANDS.find(c => c.name === m[1].toLowerCase()) || null;
+}
+
 function isGuardedCommand(cmd) {
   if (typeof cmd !== 'string') return false;
   return GUARDED_PATTERNS.some((re) => re.test(cmd));
@@ -158,6 +252,36 @@ export default async function bdbAosPlugin(input) {
   const directory = input.directory || process.cwd();
 
   return {
+    // W-6 loop-keeper. Fires whenever a session goes idle. Reads the graph
+    // state and, while work is still open, prompts the session to continue.
+    // Never throws: a graph that cannot be read must not wedge the session.
+    event: async ({ event }) => {
+      try {
+        if (!event || event.type !== 'session.idle') return;
+        const sessionID = event.properties && event.properties.sessionID;
+        if (!sessionID || !input.client) return;
+
+        const gate = openGraphGate(readGraphState(directory));
+        if (!gate) return;
+
+        const prev = nudgeState.get(sessionID);
+        const nudges = prev ? prev.nudges : 0;
+        // Nudge once per distinct state, and never more than the ceiling. An
+        // unchanged gate is a stalled run, not a reason to loop.
+        if (prev && prev.signature === gate.signature) return;
+        if (nudges >= MAX_NUDGES) return;
+
+        nudgeState.set(sessionID, { signature: gate.signature, nudges: nudges + 1 });
+        await input.client.session.prompt({
+          path: { id: sessionID },
+          body: { parts: [{ type: 'text', text: buildGraphNudge(gate) }] },
+          query: directory ? { directory } : undefined,
+        });
+      } catch {
+        // Fail open. A graph gate that breaks the session is worse than no gate.
+      }
+    },
+
     'chat.message': async (msgInput, msgOutput) => {
       // Capture the user prompt text for GO-gate verification
       const textParts = (msgOutput.parts || []).filter((p) => p && p.type === 'text' && typeof p.text === 'string');
@@ -181,13 +305,14 @@ export default async function bdbAosPlugin(input) {
         }
       } catch {}
 
-      // Recognize and wire /startcycle-graph workflow
-      const graphMatch = fullText.match(/^\/startcycle-graph(?:\s+(.*))?$/is);
-      if (graphMatch) {
-        const goal = (graphMatch[1] || '').trim();
+      // Recognize and wire the AOS pipeline group
+      const pipeline = matchPipelineCommand(fullText);
+      if (pipeline) {
+        const goal = fullText.slice(pipeline.name.length + 1).trim();
         const graphInstructions = [
-          `[AOS Autonomous Graph Workflow Engine - Active]`,
+          `[AOS Pipeline - ${pipeline.name} - Active]`,
           `Goal: "${goal || 'Execute planned architecture cycle'}"`,
+          `Skill: skills/basic/${pipeline.skill}/SKILL.md`,
           `State Schema: .agents/state.schema.json`,
           `Persisted State: production_artifacts/state.json`,
           `Available Nodes: .agents/nodes.json (Architect -> TechLead -> Build [UI_UX, Engineering, Media] -> Reviewer -> Shipping)`,