@hybridlabor-api/aos 4.7.0 → 4.7.1

package/docs/PLAN_AOS_STORE_PHASE1.md

@@ -0,0 +1,190 @@
+# Execution Plan: AOS Skill, Subagent & Extras Store (Phase 1)
+
+**Target Repository:** `/Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills`  
+**Target Worktree:** `/Users/timrennings/dev/bdb-dev/aos-wt-store`  
+**Branch:** `feat/aos-store` (branched from `main`)  
+**Scope:** Phase 1 — Core Store Infrastructure, Offline Index, CLI, and Dispatcher Fallback  
+**Audience:** Autonomous Implementation Agent  
+**Upstream Source:** `https://github.com/affaan-m/ECC` (Pinned Commit, MIT License)
+
+---
+
+## 🎯 1. Mission & Architectural Invariants
+
+You are implementing Phase 1 of the **AOS Store** (`@hybridlabor-api/aos`). This provides an on-demand fallback layer for skills and subagents sourced from `affaan-m/ECC` whenever a requested capability is not in AOS's 185-skill core.
+
+### ⚠️ Non-Negotiable Invariants (Audit-Mandated)
+1. **No Forks:** Do NOT fork ECC to GitHub. Pin `affaan-m/ECC` directly via Git SHA in `vendor-manifest.json` (identical to `anti-slop` and `skylos`).
+2. **No Mid-Run Downloads:** Never download or prompt to download during a `/startcycle-graph` run (violates the GO-Gate and headless guarantees). If `--skill=<name>` is missing, the dispatcher must escalate with a clear manual install instruction:
+   ```text
+   "<name> is not installed. Found in the ECC store.
+   Run: aos store install <name>
+   Then re-run your startcycle command."
+   ```
+3. **No File System in Dispatcher:** `.claude/workflows/startcycle-dispatch.mjs` has no direct `fs` access. The mandatory skill check is an `agent()` call (Haiku); you must extend its JSON schema with `store_matches: string[]` instead of adding `fs` calls.
+4. **Trust Anchor is AOS Package:** `lib/ecc-store-index.json` ships inside the `@hybridlabor-api/aos` npm package. Downloads from GitHub must match the SHA-256 hash in this index. Hash mismatch = hard failure.
+5. **Phase-1 Scope: Markdown Only:**
+   - Only import `skills/` and `agents/` (Subagents).
+   - **Strictly exclude** `scripts/`, `hooks/`, and `rules/` (prevents RCE and config pollution).
+6. **Collision Invariant:** AOS core skills ALWAYS take precedence. If an ECC skill shares a name with an existing AOS skill, it is skipped and logged.
+7. **Future-Proofing for Fucksaas & AO:** Every store item must contain schema fields for `tier: "free"`, `requires_auth: false`, and `origin: "ecc"` so Fucksaas PRO pay-gates and AO marketplace UI can be layered on in Phase 2 without changing the schema.
+
+---
+
+## 🛠️ 2. Worktree Initialization
+
+Execute the following commands to create and enter the isolated worktree:
+
+```bash
+cd /Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills
+git fetch origin main
+git worktree add -b feat/aos-store /Users/timrennings/dev/bdb-dev/aos-wt-store main
+cd /Users/timrennings/dev/bdb-dev/aos-wt-store
+```
+
+All modifications below MUST take place inside `/Users/timrennings/dev/bdb-dev/aos-wt-store/`.
+
+---
+
+## 📋 3. Step-by-Step Implementation Checklist
+
+### Step 1: Upstream Pinning & Provenance
+- [ ] Inspect the latest stable commit SHA of `affaan-m/ECC`:
+  ```bash
+  gh api repos/affaan-m/ECC/commits/main --jq '.sha'
+  ```
+- [ ] Add `ecc-store` entry to `vendor-manifest.json`:
+  ```json
+  "ecc-store": {
+    "upstream": "https://github.com/affaan-m/ECC",
+    "pinned_commit": "<FULL_SHA>",
+    "purpose": "On-demand fallback store for skills and auxiliary subagents",
+    "target": "lib/ecc-store-index.json"
+  }
+  ```
+- [ ] Update `THIRD_PARTY_NOTICES.md` to document the full scope of ECC components and MIT license terms.
+
+### Step 2: Store Index Generator (`scripts/build-ecc-store-index.mjs`)
+- [ ] Create `scripts/build-ecc-store-index.mjs`. The script must:
+  1. Fetch the tree from GitHub API for the pinned commit (`repos/affaan-m/ECC/git/trees/<sha>?recursive=1`) or clone to a temporary cache.
+  2. Filter strictly for Markdown:
+     - `skills/**/SKILL.md` or `skills/**/*.md`
+     - `agents/*.md`
+  3. Validate & sanitize frontmatter:
+     - Must conform to AOS standards (runnable through `scripts/validate-skills.mjs` rules).
+     - Compute SHA-256 for each raw file.
+     - Scan for forbidden tokens (hardcoded Claude-only tools like `Bash`, `View`; replace or flag compatibility).
+  4. Build schema:
+     ```typescript
+     interface StoreIndex {
+       version: "1.0.0";
+       generated_at: string;
+       pinned_commit: string;
+       skills: Record<string, {
+         name: string;
+         description: string;
+         category: string;
+         tier: "free";
+         origin: "ecc";
+         requires_auth: false;
+         sha256: string;
+         upstream_path: string;
+         harness_support: ("claude" | "antigravity" | "codex" | "cursor" | "roo")[];
+       }>;
+       subagents: Record<string, {
+         name: string;
+         description: string;
+         role: string;
+         tier: "free";
+         origin: "ecc";
+         sha256: string;
+         upstream_path: string;
+       }>;
+     }
+     ```
+  5. Check collisions against local `skills/` in AOS. Any collision is skipped.
+  6. Output the compiled index to `lib/ecc-store-index.json` (keep size under 100 KB).
+- [ ] Run `node scripts/build-ecc-store-index.mjs` and verify `lib/ecc-store-index.json`.
+
+### Step 3: CLI Implementation (`bin/aos-store.mjs` & `installer.js`)
+- [ ] Create `bin/aos-store.mjs`:
+  - `aos store list [--type=skills|agents]` -> Formatted table of available items.
+  - `aos store search <query>` -> Search by name, tags, description in `lib/ecc-store-index.json`.
+  - `aos store install <name> [--project]` ->
+    1. Look up `<name>` in `lib/ecc-store-index.json`.
+    2. Check if already installed locally; collision guard against AOS core.
+    3. Download raw content from `https://raw.githubusercontent.com/affaan-m/ECC/<pinned_sha>/<upstream_path>`.
+    4. Compute SHA-256 and assert match with index (halt on mismatch).
+    5. Write file:
+       - If `--project`: write to `./skills/<name>/SKILL.md`.
+       - If global: fan-out to all active harnesses (`~/.agents/skills/<name>/SKILL.md`, `~/.claude/skills/<name>/SKILL.md`, etc., reusing logic from `installer.js`).
+    6. Log success with green checkmark.
+- [ ] Make `bin/aos-store.mjs` executable (`chmod +x bin/aos-store.mjs`).
+- [ ] Register in `package.json`:
+  ```json
+  "bin": {
+    ...
+    "aos-store": "bin/aos-store.mjs"
+  }
+  ```
+- [ ] Wire up `aos store <args>` in `installer.js` so running `aos store search` forwards directly to `bin/aos-store.mjs`.
+
+### Step 4: Dispatcher Hook (`.claude/workflows/startcycle-dispatch.mjs`)
+- [ ] Locate the `validate-mandatory-skills` agent call around lines 701–741.
+- [ ] Update the prompt and JSON schema:
+  - Add `store_matches: { type: 'array', items: { type: 'string' } }` to the output schema.
+  - Instruct the agent to check `lib/ecc-store-index.json` for any skill not found locally on disk.
+- [ ] Update escalation handling (lines 728–739):
+  ```javascript
+  const missing = skillCheckResult?.missing ?? [];
+  if (missing.length > 0) {
+    const storeMatches = skillCheckResult?.store_matches ?? [];
+    const suggestions = skillCheckResult?.suggestions ?? [];
+    
+    let msg = `--skill named skill(s) that are not currently installed: ${missing.join(', ')}.\n`;
+    if (storeMatches.length > 0) {
+      msg += `Found in the AOS / ECC Store: ${storeMatches.join(', ')}.\n` +
+             `Run: aos store install ${storeMatches.join(' ')}\n` +
+             `Then re-run your startcycle command.\n`;
+    } else if (suggestions.length > 0) {
+      msg += `Did you mean: ${suggestions.join(', ')}?\n`;
+    }
+    return await escalate(msg);
+  }
+  ```
+
+### Step 5: Router Update (`skills/global_config/ask-tim/SKILL.md`)
+- [ ] Add a new section in `ask-tim/SKILL.md` titled `## Outside the core: the ECC store`:
+  - Explain that when no native AOS skill fits (e.g. Django, Spring, Godot), the user can query the store via `aos store search <query>`.
+  - Document `aos store install <name>` for on-demand activation.
+  - Reiterate that the core remains 185 high-trust skills.
+
+### Step 6: Verification & Quality Gate
+- [ ] Run skill validator:
+  ```bash
+  npm run test
+  npm run validate:strict
+  ```
+- [ ] Test the CLI commands:
+  ```bash
+  node bin/aos-store.mjs list | head -n 20
+  node bin/aos-store.mjs search django
+  node bin/aos-store.mjs search spring
+  ```
+- [ ] Test mock installation:
+  ```bash
+  node bin/aos-store.mjs install <test-skill> --dry-run
+  ```
+- [ ] Ensure Git working tree is clean and commits follow Conventional Commits:
+  - `feat(store): add build-ecc-store-index generator and store-index.json`
+  - `feat(store): implement aos-store CLI and installer integration`
+  - `feat(dispatcher): suggest aos store install on missing mandatory skills`
+  - `docs(ask-tim): add ECC store fallback section`
+
+---
+
+## 🚀 4. Definition of Done
+1. `npm test` and `npm run validate` pass with zero errors.
+2. `lib/ecc-store-index.json` is generated, valid JSON, under 100 KB.
+3. `bin/aos-store.mjs` executes cleanly without unhandled rejections.
+4. Worktree is ready for review and merge into `main`.

package/installer.js

@@ -3608,7 +3608,7 @@ function installGlobalBinaries() {
     }
 
     const isWin = process.platform === 'win32';
-    const cliBins = ['aos-config', 'aos-dashboard', 'aos-uninstall'];
+    const cliBins = ['aos-config', 'aos-dashboard', 'aos-uninstall', 'aos-store', 'aos-doctor'];
 
     for (const name of cliBins) {
         const targetMjs = path.join(globalAgentsBin, `${name}.mjs`);
@@ -4809,7 +4809,38 @@ async function runQuickUpdate(installState) {
 }
 
 
+function buildAoAnnouncementBanner() {
+    return [
+        '\x1b[36m╭──────────────────────────────────────────────────────────────────────────────╮\x1b[0m',
+        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m   \x1b[1m\x1b[35m🚀 BDB AGENT ORCHESTRATOR APP — FINALE BETA JETZT VERFÜGBAR!\x1b[0m              \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m   Die nächste Generation der Cross-Harness Multi-Agenten-Orchestrierung      \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m   ist jetzt als finale Beta für alle User freigeschaltet.                    \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m   • \x1b[1mDashboard & WebUI:\x1b[0m  http://localhost:3101                                \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m   • \x1b[1mService-Befehl:\x1b[0m     ao service install  (Hintergrunddienst aktivieren)   \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m   • \x1b[1mQuick Launch:\x1b[0m       ao open  oder  ao service status                     \x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m   • \x1b[1mFeatures:\x1b[0m           Session-Telemetrie, Live-AgentTrail & Multi-Workspaces\x1b[36m│\x1b[0m',
+        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
+        '\x1b[36m╰──────────────────────────────────────────────────────────────────────────────╯\x1b[0m\n'
+    ].join('\n');
+}
+
 async function main() {
+    if (process.argv[2] === 'store') {
+        const storeScript = path.join(srcDir, 'bin', 'aos-store.mjs');
+        const result = spawnSync(process.execPath, [storeScript, ...process.argv.slice(3)], { stdio: 'inherit' });
+        process.exitCode = result.status == null ? 1 : result.status;
+        return;
+    }
+    if (process.argv[2] === 'doctor' || process.argv[2] === 'checkup' || process.argv.includes('--doctor')) {
+        const doctorScript = path.join(srcDir, 'bin', 'aos-doctor.mjs');
+        const doctorArgs = process.argv.slice(process.argv[2] === 'doctor' || process.argv[2] === 'checkup' ? 3 : 2).filter(a => a !== '--doctor');
+        const result = spawnSync(process.execPath, [doctorScript, ...doctorArgs], { stdio: 'inherit' });
+        process.exitCode = result.status == null ? 1 : result.status;
+        return;
+    }
     const skipIntro = isAutoYes || process.argv.includes('--no-intro') || process.argv.includes('--no-animation');
     await renderKineticIntro({ rotations: 1, fps: 12.5, skip: skipIntro, pkgVersion: pkg.version });
     console.log(buildWordmarkBanner());
@@ -4827,6 +4858,7 @@ async function main() {
 
     intro(buildHeroHeader(pkg.version));
     console.log(buildTelemetryCard({ installState, detections, daemonStatus }));
+    console.log(buildAoAnnouncementBanner());
 
     if (DRY_RUN) {
         // Precise on purpose: version comparison still queries the registry, and
@@ -4869,12 +4901,14 @@ async function main() {
         const options = installState.updateAvailable
             ? [
                 { value: 'quick', label: `⚡ Quick Update (v${installState.localVersion} ➔ v${installState.currentVersion})`, hint: 'refresh skills, templates & daemons' },
+                { value: 'doctor', label: '🩺 Run System Checkup / Doctor', hint: 'verify environment, placement, daemons & AO' },
                 { value: 'project', label: '📁 Drop Local Project Harness', hint: 'copy dispatcher contract to cwd' },
                 { value: 'reconfigure', label: '🛠️ Reconfigure System', hint: 'change targets, tier or options' },
                 { value: 'uninstall', label: '🗑️ Uninstall AOS', hint: 'remove what this installer placed; your data stays' },
                 { value: 'cancel', label: '❌ Exit' }
               ]
             : [
+                { value: 'doctor', label: '🩺 Run System Checkup / Doctor', hint: 'verify environment, placement, daemons & AO' },
                 { value: 'project', label: '📁 Drop Local Project Harness', hint: 'copy dispatcher contract to cwd' },
                 { value: 'quick', label: '🔄 Verify & Refresh All Skills', hint: 're-sync and health check' },
                 { value: 'reconfigure', label: '🛠️ Reconfigure System', hint: 'switch tier or targets' },
@@ -4892,6 +4926,12 @@ async function main() {
             outro('Cancelled.');
             return;
         }
+        if (action === 'doctor') {
+            const doctorScript = path.join(srcDir, 'bin', 'aos-doctor.mjs');
+            spawnSync(process.execPath, [doctorScript], { stdio: 'inherit' });
+            outro('System Checkup complete.');
+            return;
+        }
         if (action === 'project') {
             installProjectHarness();
             outro('Project harness installation complete.');

package/lib/aos-archify-contract.mjs

@@ -0,0 +1,277 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ARCHITECTURE_SPEC_PATH = 'production_artifacts/00_architecture.json';
+export const ARCHITECTURE_HTML_PATH = 'production_artifacts/00_architecture.html';
+export const ARCHITECTURE_STATE_KEY = 'architecture';
+export const ARCHITECTURE_CHECK_COUNT = 9;
+export const RECEIPT_MAX_BYTES = 65536;
+export const LOG_MAX_CHARS = 400;
+export const ARCHIFY_REL_BIN = 'skills/global_config/archify/bin/archify.mjs';
+export const ARCHIFY_TIMEOUT_MS = 120000;
+export const ARCHIFY_MAX_BYTES = 65536;
+export const PLAN_CANVAS_BIN = 'aos-plan-canvas';
+export const PLAN_CANVAS_TIMEOUT_MS = 15000;
+export const PLAN_CANVAS_MAX_BYTES = 16384;
+export const AGENT_TRAIL_BIN = 'aos-trail';
+export const EXECUTION_PLAN_PATH = 'production_artifacts/00_execution_plan.md';
+
+const ALLOWED_PATHS = new Set([ARCHITECTURE_SPEC_PATH, ARCHITECTURE_HTML_PATH]);
+const SHA256_RE = /^[a-fA-F0-9]{64}$/;
+const LONG_HEX_RE = /[a-fA-F0-9]{64}/g;
+const HOME_RE = /\/(Users|home)\/[^\s/]+/g;
+
+export function isAllowedArchitecturePath(value) {
+  if (typeof value !== 'string') return false;
+  return ALLOWED_PATHS.has(value);
+}
+
+function boundedString(raw, maxBytes) {
+  if (typeof raw !== 'string') return { ok: false, value: '' };
+  if (Buffer.byteLength(raw, 'utf8') > maxBytes) return { ok: false, value: '' };
+  return { ok: true, value: raw };
+}
+
+function firstDiagnosticMessage(diagnostics) {
+  if (!Array.isArray(diagnostics)) return '';
+  for (const entry of diagnostics) {
+    if (entry && typeof entry.message === 'string' && entry.message) return entry.message;
+    if (entry && typeof entry.code === 'string' && entry.code) return entry.code;
+  }
+  return '';
+}
+
+export function parseDeliverReceipt(raw, options = {}) {
+  const maxBytes = Number.isInteger(options.maxBytes) ? options.maxBytes : RECEIPT_MAX_BYTES;
+  const bounded = boundedString(raw, maxBytes);
+  if (!bounded.ok) {
+    return { ok: false, error: 'receipt exceeds bounded size, refusing to parse' };
+  }
+  let obj = null;
+  try {
+    obj = JSON.parse(bounded.value);
+  } catch {
+    return { ok: false, error: 'receipt is not valid JSON' };
+  }
+  if (!obj || typeof obj !== 'object') {
+    return { ok: false, error: 'receipt is not a JSON object' };
+  }
+  if (obj.ok !== true) {
+    const detail = (typeof obj.error === 'string' && obj.error) || firstDiagnosticMessage(obj.diagnostics) || 'archify deliver failed';
+    return { ok: false, error: String(detail).slice(0, 300), stage: typeof obj.stage === 'string' ? obj.stage : 'unknown' };
+  }
+  const validation = obj.validation && typeof obj.validation === 'object' ? obj.validation : null;
+  const checksPassed = validation ? validation.checksPassed : undefined;
+  const checkCount = validation ? validation.checkCount : undefined;
+  const errors = validation ? validation.errors : undefined;
+  const artifactSha = obj.artifact && typeof obj.artifact.sha256 === 'string' ? obj.artifact.sha256 : '';
+  const specSha = obj.specification && typeof obj.specification.sha256 === 'string' ? obj.specification.sha256 : '';
+  if (checksPassed !== checkCount || checkCount !== ARCHITECTURE_CHECK_COUNT || errors !== 0) {
+    return { ok: false, error: `deliver receipt incomplete: ${checksPassed}/${checkCount} checks, errors ${errors}` };
+  }
+  if (!SHA256_RE.test(artifactSha) || !SHA256_RE.test(specSha)) {
+    return { ok: false, error: 'deliver receipt missing sha256 evidence' };
+  }
+  return {
+    ok: true,
+    checksPassed,
+    checkCount,
+    errors: 0,
+    warnings: typeof validation.warnings === 'number' ? validation.warnings : 0,
+    artifactSha256: artifactSha,
+    specificationSha256: specSha,
+  };
+}
+
+export function mergeArchitectureState(state, receipt) {
+  const base = state && typeof state === 'object' ? state : {};
+  const artifacts = base.artifacts && typeof base.artifacts === 'object' ? { ...base.artifacts } : {};
+  if (receipt && receipt.ok === true) {
+    artifacts[ARCHITECTURE_STATE_KEY] = ARCHITECTURE_HTML_PATH;
+    return { state: { ...base, artifacts }, escalate: null };
+  }
+  const detail = receipt && typeof receipt.error === 'string' && receipt.error ? receipt.error : 'archify deliver/validate failed';
+  return {
+    state: { ...base, artifacts },
+    escalate: `archify deliver/validate failed: ${String(detail).slice(0, 200)}, previous artifact preserved`,
+  };
+}
+
+export function buildUrlLine() {
+  return `url: ${ARCHITECTURE_HTML_PATH}`;
+}
+
+export function planCanvasCommands() {
+  return {
+    open: `aos-plan-canvas open ${ARCHITECTURE_HTML_PATH}`,
+    awaitCmd: `aos-plan-canvas await ${ARCHITECTURE_HTML_PATH}`,
+  };
+}
+
+export function agentTrailCommand() {
+  return 'aos-trail . --plan production_artifacts/00_execution_plan.md --no-open';
+}
+
+export function buildPlanCanvasOpenArgs(htmlPath) {
+  if (!isAllowedArchitecturePath(htmlPath)) return null;
+  if (htmlPath !== ARCHITECTURE_HTML_PATH) return null;
+  return ['open', ARCHITECTURE_HTML_PATH, '--no-open'];
+}
+
+export function buildAgentTrailArgs() {
+  return ['.', '--plan', EXECUTION_PLAN_PATH, '--no-open'];
+}
+
+export async function runArchitectureCanvas(options = {}) {
+  const cwd = options.cwd;
+  const htmlPath = options.htmlPath;
+  const exists = options.exists;
+  const run = options.run;
+  const maxBytes = Number.isInteger(options.maxBytes) ? options.maxBytes : PLAN_CANVAS_MAX_BYTES;
+  const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : PLAN_CANVAS_TIMEOUT_MS;
+  const args = buildPlanCanvasOpenArgs(htmlPath);
+  if (!args || typeof cwd !== 'string' || cwd.length === 0) {
+    return { displayed: false, reason: 'plan-canvas rejected untrusted arguments, architecture preserved', architecturePreserved: true };
+  }
+  if (typeof exists === 'function') {
+    let present = false;
+    try {
+      present = exists(htmlPath);
+    } catch {
+      present = false;
+    }
+    if (!present) {
+      return { displayed: false, reason: 'architecture artifact missing, canvas skipped', architecturePreserved: true };
+    }
+  }
+  if (typeof run !== 'function') {
+    return { displayed: false, reason: 'plan-canvas unavailable, architecture preserved', architecturePreserved: true };
+  }
+  let res = null;
+  try {
+    res = await run(args, { cwd, timeoutMs, shell: false });
+  } catch (error) {
+    return { displayed: false, error: redactForLog(error && error.message ? error.message : 'plan-canvas open failed'), architecturePreserved: true };
+  }
+  const out = boundedOutputText(res ? res.stdout : '', maxBytes);
+  if (!out.ok) {
+    return { displayed: false, error: 'plan-canvas output exceeds bounded size', architecturePreserved: true };
+  }
+  if (!res || res.status !== 0) {
+    return { displayed: false, error: redactForLog((res && res.stderr) || 'plan-canvas open failed'), architecturePreserved: true };
+  }
+  return { displayed: true, architecturePreserved: true };
+}
+
+export function redactForLog(value) {
+  const text = String(value ?? '');
+  const homes = text.replace(HOME_RE, '~');
+  const shas = homes.replace(LONG_HEX_RE, (m) => `${m.slice(0, 12)}..`);
+  return shas.slice(0, LOG_MAX_CHARS);
+}
+
+function isWithin(root, candidate) {
+  const relativePath = path.relative(root, candidate);
+  return relativePath === '' || (relativePath !== '..' && !relativePath.startsWith(`..${path.sep}`) && !path.isAbsolute(relativePath));
+}
+
+export function resolveArchifyBin(cwd) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return null;
+  try {
+    const root = fs.realpathSync(path.resolve(cwd));
+    if (!fs.statSync(root).isDirectory()) return null;
+    const binaryPath = fs.realpathSync(path.resolve(root, ARCHIFY_REL_BIN));
+    if (!isWithin(root, binaryPath) || !fs.statSync(binaryPath).isFile()) return null;
+    return binaryPath;
+  } catch {
+    return null;
+  }
+}
+
+export function buildValidateArgs(specPath) {
+  if (!isAllowedArchitecturePath(specPath)) return null;
+  if (specPath !== ARCHITECTURE_SPEC_PATH) return null;
+  return ['validate', 'architecture', specPath, '--quality', 'showcase', '--json'];
+}
+
+export function buildDeliverArgs(specPath, htmlPath) {
+  if (!isAllowedArchitecturePath(specPath) || !isAllowedArchitecturePath(htmlPath)) return null;
+  if (specPath !== ARCHITECTURE_SPEC_PATH || htmlPath !== ARCHITECTURE_HTML_PATH) return null;
+  return ['deliver', 'architecture', specPath, htmlPath, '--quality', 'showcase', '--json'];
+}
+
+function boundedOutputText(value, maxBytes) {
+  if (typeof value !== 'string') return { ok: false, text: '' };
+  let size = 0;
+  try {
+    size = Buffer.byteLength(value, 'utf8');
+  } catch {
+    size = value.length;
+  }
+  if (size > maxBytes) return { ok: false, text: '' };
+  return { ok: true, text: value };
+}
+
+function boundaryFailure(stage, detail) {
+  return {
+    ok: false,
+    stage,
+    error: redactForLog(String(detail || 'archify boundary step failed')).slice(0, LOG_MAX_CHARS),
+    preservePrevious: true,
+  };
+}
+
+export async function runArchifyBoundary(options = {}) {
+  const cwd = options.cwd;
+  const specPath = options.specPath;
+  const htmlPath = options.htmlPath;
+  const run = options.run;
+  const maxBytes = Number.isInteger(options.maxBytes) ? options.maxBytes : ARCHIFY_MAX_BYTES;
+  const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : ARCHIFY_TIMEOUT_MS;
+  const validateArgs = buildValidateArgs(specPath);
+  const deliverArgs = buildDeliverArgs(specPath, htmlPath);
+  if (!validateArgs || !deliverArgs || typeof cwd !== 'string' || cwd.length === 0) {
+    return boundaryFailure('arguments', 'archify boundary rejected untrusted arguments');
+  }
+  if (typeof run !== 'function') {
+    return boundaryFailure('executor', 'archify boundary has no executor in this runtime');
+  }
+  let validateRes = null;
+  try {
+    validateRes = await run(validateArgs, { cwd, timeoutMs, shell: false, maxBuffer: maxBytes });
+  } catch (error) {
+    return boundaryFailure('validate', error && error.message ? error.message : 'archify validate executor failed');
+  }
+  const validateOut = boundedOutputText(validateRes ? validateRes.stdout : '', maxBytes);
+  if (!validateRes || validateRes.status !== 0 || !validateOut.ok) {
+    const detail = !validateOut.ok
+      ? 'archify validate output exceeds bounded size'
+      : (validateRes && validateRes.stderr) || 'archify validate failed';
+    return boundaryFailure('validate', detail);
+  }
+  let deliverRes = null;
+  try {
+    deliverRes = await run(deliverArgs, { cwd, timeoutMs, shell: false, maxBuffer: maxBytes });
+  } catch (error) {
+    return boundaryFailure('deliver', error && error.message ? error.message : 'archify deliver executor failed');
+  }
+  const deliverOut = boundedOutputText(deliverRes ? deliverRes.stdout : '', maxBytes);
+  if (!deliverRes || deliverRes.status !== 0 || !deliverOut.ok) {
+    const detail = !deliverOut.ok
+      ? 'archify deliver output exceeds bounded size'
+      : (deliverRes && deliverRes.stderr) || 'archify deliver failed';
+    return boundaryFailure('deliver', detail);
+  }
+  const receipt = parseDeliverReceipt(deliverOut.text, { maxBytes });
+  if (!receipt || receipt.ok !== true) {
+    return boundaryFailure('deliver', (receipt && receipt.error) || 'archify deliver receipt invalid');
+  }
+  return {
+    ok: true,
+    stage: 'deliver',
+    validate: { status: 0 },
+    deliver: { status: 0 },
+    receipt,
+    preservePrevious: false,
+  };
+}