@hybridlabor-api/aos 4.10.0 → 4.11.0

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)`,

package/installer.js

@@ -3674,6 +3674,106 @@ function injectHarnessRules() {
     }
 }
 
+// Copy the OpenCode plugin + command payload and register both in
+// opencode.jsonc. This is the single copy site: the Quick Update path
+// (injectHarnessRules -> installGlobalHooks) and the fresh-install path
+// (universalHarnessSync -> syncOpencodeConfig) both reach it, so a version that
+// adds or changes the plugin can no longer ship to one path and miss the other.
+//
+// `data` is mutated in place when the caller owns the config write (Universal
+// Sync merges MCP servers in the same pass and writes once). When `data` is
+// omitted the function loads and saves the config itself, which is what lets the
+// Quick Update path register the plugin as well as copy it.
+function installOpencodePlugin({ targetHome = homeDir, configPath = null, data = null } = {}) {
+    const opencodeDir = configPath
+        ? path.dirname(configPath)
+        : (process.platform === 'win32'
+            ? path.join(process.env.APPDATA || targetHome, 'opencode')
+            : path.join(targetHome, '.config', 'opencode'));
+
+    const pluginSrc = path.join(srcDir, '.opencode', 'plugins', 'bdb-aos.js');
+    let pluginInstalled = false;
+    if (fs.existsSync(pluginSrc)) {
+        const pluginDest = path.join(opencodeDir, 'plugins', 'bdb-aos.js');
+        try {
+            fs.mkdirSync(path.dirname(pluginDest), { recursive: true });
+            fs.copyFileSync(pluginSrc, pluginDest);
+            try { fs.chmodSync(pluginDest, 0o644); } catch (e) { logDebug(e, 'chmod opencode plugin'); }
+            pluginInstalled = true;
+            log.step(`Installed OpenCode plugin to ${pluginDest}`);
+        } catch (e) {
+            log.warn(`Could not install OpenCode plugin: ${e.message}`);
+        }
+    }
+
+    // Slash-command payloads. Without these the /startcycle-graph command has no
+    // native resolution and only survives as a raw-text match in the plugin.
+    const commandsSrc = path.join(srcDir, '.opencode', 'commands');
+    if (fs.existsSync(commandsSrc)) {
+        try {
+            copyDirRecursiveSync(commandsSrc, path.join(opencodeDir, 'commands'));
+            log.step(`Installed OpenCode commands to ${path.join(opencodeDir, 'commands')}`);
+        } catch (e) {
+            log.warn(`Could not install OpenCode commands: ${e.message}`);
+        }
+    }
+
+    if (!pluginInstalled) return data;
+
+    const ownsWrite = data === null;
+    let beforeSerialized = null;
+    if (ownsWrite) {
+        if (!configPath) return data;
+        const existing = readJsoncFile(configPath) || {};
+        // Snapshot before mutating: `data` becomes the same object, so
+        // comparing afterwards would always report "unchanged".
+        beforeSerialized = JSON.stringify(existing, null, 2);
+        data = existing;
+    }
+
+    // Register the plugin.
+    if (!Array.isArray(data.plugin)) data.plugin = [];
+    const pluginPathNormalized = path.join(opencodeDir, 'plugins', 'bdb-aos.js').replace(/\\/g, '/');
+    const alreadyRegistered = data.plugin.some(p => {
+        const str = typeof p === 'string' ? p : (Array.isArray(p) ? p[0] : '');
+        return str.includes('bdb-aos');
+    });
+    if (!alreadyRegistered) data.plugin.push(pluginPathNormalized);
+
+    // Skill paths. `.agents/skills` stays project-relative on purpose: it is the
+    // per-project contract, and OpenCode resolves it against each project, so it
+    // is meaningful in a bootstrapped project and inert elsewhere. The absolute
+    // ~/.agents/skills is added only when it is really there -- registering a
+    // path that does not exist is the defect this replaces.
+    const homeAgentsSkills = path.join(targetHome, '.agents', 'skills').replace(/\\/g, '/');
+    const desired = ['.agents/skills'];
+    if (fs.existsSync(homeAgentsSkills)) desired.unshift(homeAgentsSkills);
+    if (!data.skills || typeof data.skills !== 'object' || !Array.isArray(data.skills.paths)) {
+        data.skills = { paths: desired.slice() };
+    } else {
+        for (const p of desired) {
+            if (!data.skills.paths.includes(p)) data.skills.paths.push(p);
+        }
+    }
+
+    if (ownsWrite) {
+        // Write only on a real change. readJsoncFile strips comments, so
+        // serialising an unchanged config would silently eat a user's comments
+        // for no benefit. When a write is genuinely needed the comments in the
+        // file are lost -- acceptable, and worth saying out loud in the PR.
+        const serialized = JSON.stringify(data, null, 2);
+        if (beforeSerialized === serialized) return data;
+        try {
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, serialized, { mode: 0o600 });
+            try { fs.chmodSync(configPath, 0o600); } catch (e) { logDebug(e, 'chmod opencode config'); }
+        } catch (e) {
+            log.warn(`Could not write ${configPath}: ${e.message}`);
+        }
+    }
+    return data;
+}
+
 // Deliver the hook scripts to ~/.claude/hooks/ and wire them in settings.json.
 // Both the full install and Quick Update funnel through here. Quick Update used
 // to do neither: it refreshes skills and submodules, but hooks are harness
@@ -3733,22 +3833,15 @@ function installGlobalHooks({ targetHome = homeDir, targetGemini = geminiDir } =
     mergeCodexTomlHooks(path.join(targetHome, '.codex', 'config.toml'));
 
     // 4. OpenCode CLI
-    const opencodeDir = process.platform === 'win32'
-        ? path.join(process.env.APPDATA || targetHome, 'opencode')
-        : path.join(targetHome, '.config', 'opencode');
-    const opencodePluginSrc = path.join(srcDir, '.opencode', 'plugins', 'bdb-aos.js');
-    if (fs.existsSync(opencodePluginSrc)) {
-        const opencodePluginsDir = path.join(opencodeDir, 'plugins');
-        const opencodePluginDest = path.join(opencodePluginsDir, 'bdb-aos.js');
-        try {
-            fs.mkdirSync(opencodePluginsDir, { recursive: true });
-            fs.copyFileSync(opencodePluginSrc, opencodePluginDest);
-            try { fs.chmodSync(opencodePluginDest, 0o644); } catch (e) { logDebug(e, 'chmod opencode plugin'); }
-            log.step(`Installed OpenCode plugin to ${opencodePluginDest}`);
-        } catch (e) {
-            log.warn(`Could not install OpenCode plugin: ${e.message}`);
-        }
-    }
+    installOpencodePlugin({
+        targetHome,
+        configPath: path.join(
+            process.platform === 'win32'
+                ? path.join(process.env.APPDATA || targetHome, 'opencode')
+                : path.join(targetHome, '.config', 'opencode'),
+            'opencode.jsonc'
+        ),
+    });
 
     // 5. Global CLI launcher binaries (aos-config, aos-dashboard, aos-uninstall)
     installGlobalBinaries();
@@ -4778,47 +4871,10 @@ async function universalHarnessSync(primaryMcpConfigPath, installedModules = [])
                 }
             }
 
-            // Wire BDB AOS Plugin for OpenCode
-            const opencodeDir = path.dirname(targetPath);
-            const pluginsDir = path.join(opencodeDir, 'plugins');
-            const pluginFile = path.join(pluginsDir, 'bdb-aos.js');
-            const pluginSrc = path.join(srcDir, '.opencode', 'plugins', 'bdb-aos.js');
-
-            try {
-                if (fs.existsSync(pluginSrc)) {
-                    fs.mkdirSync(pluginsDir, { recursive: true });
-                    fs.copyFileSync(pluginSrc, pluginFile);
-                    try { fs.chmodSync(pluginFile, 0o644); } catch (e) { logDebug(e, 'chmod pluginFile'); }
-                }
-            } catch (pluginErr) {
-                log.warn(`Could not install OpenCode plugin: ${pluginErr.message}`);
-            }
-
-            // Register plugin in opencode.jsonc if plugin file exists
-            if (fs.existsSync(pluginFile)) {
-                if (!Array.isArray(data.plugin)) {
-                    data.plugin = [];
-                }
-                const pluginPathNormalized = pluginFile.replace(/\\/g, '/');
-                const alreadyRegistered = data.plugin.some(p => {
-                    const str = typeof p === 'string' ? p : (Array.isArray(p) ? p[0] : '');
-                    return str.includes('bdb-aos');
-                });
-                if (!alreadyRegistered) {
-                    data.plugin.push(pluginPathNormalized);
-                }
-            }
-
-            // Register skills paths for OpenCode
-            if (!data.skills || typeof data.skills !== 'object') {
-                data.skills = { paths: [".agents/skills"] };
-            } else if (Array.isArray(data.skills.paths)) {
-                if (!data.skills.paths.includes(".agents/skills")) {
-                    data.skills.paths.push(".agents/skills");
-                }
-            } else {
-                data.skills.paths = [".agents/skills"];
-            }
+            // Wire BDB AOS Plugin for OpenCode. `data` is handed in because this
+            // function owns the write -- it merges MCP servers in the same pass.
+            // homeDir matches how the opencode harness entry builds its path.
+            installOpencodePlugin({ targetHome: homeDir, configPath: targetPath, data });
 
             fs.mkdirSync(path.dirname(targetPath), { recursive: true });
             fs.writeFileSync(targetPath, JSON.stringify(data, null, 2), { mode: 0o600 });
@@ -5497,6 +5553,7 @@ module.exports = {
     mergeCodexHooks: mergeCodexTomlHooks,
     mergeCodexTomlMcpServers,
     installGlobalHooks,
+    installOpencodePlugin,
     installProjectHarness,
     promptMcpSelection,
     mirrorMcpServersTo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.10.0",
+  "version": "4.11.0",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "engines": {
@@ -27,7 +27,7 @@
     "plugin:build": "node scripts/build-plugin-manifest.mjs",
     "plugin:check": "node scripts/build-plugin-manifest.mjs --check",
     "doctor": "node bin/aos-doctor.mjs",
-    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node tests/aos-store.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs"
+    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node --test tests/opencode-graph-gate.test.js && node --test tests/cross-harness-hooks.test.js && node tests/aos-store.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs"
   },
   "publishConfig": {
     "access": "public"