@rryando/arcs 3.3.2 → 3.4.1

package/scripts/deploy-claudecode-bundle.mjs

@@ -31,8 +31,11 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { wireCodegraphMcp, wireRtk } from "./lib/bundle-helpers.mjs";
 
-const repoRoot = resolve(import.meta.dirname, "..");
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
 const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
 const defaultConfigRoot = resolve(homedir(), ".claude");
 const defaultProjectRoot = repoRoot;
@@ -85,71 +88,84 @@ const agentTierMap = {
   "arcs-docs": "heavy",
   "oncall-ops": "heavy",
   "system-architect": "heavy",
-  general: "heavy",
   "arcs-orchestrate": "standard",
   "arcs-orchestrate-caveman": "standard",
   "devil-advocate": "standard",
+  "graph-explorer": "light",
   "code-reviewer": "light",
   "tech-architect": "light",
   "qa-analyst": "light",
 };
 
+// Agent descriptions mirror opencode/arcs/manifest.json (canonical) — keep in sync.
 const agentMetadata = {
   "software-engineer": {
     name: "Software Engineer",
-    description: "Implementation specialist. Writes code, runs tests, and ships features.",
+    description:
+      "Implementation specialist. Writes code, runs tests, ships features. Loads quick-dev, code-agent, test-driven-development, and executing-plans skills as needed.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
   "devil-advocate": {
     name: "Devil's Advocate",
-    description: "Adversarial phase-gate agent. Checks work using KISS/YAGNI/DRY principles.",
+    description:
+      "Adversarial phase-gate agent. Checks work at phase boundaries using KISS/YAGNI/DRY principles. Runs tests, reads diffs, delivers pass/block verdicts. Cannot edit code.",
+    tools: "Read, Glob, Grep, Bash",
+    model: "inherit",
+  },
+  "graph-explorer": {
+    name: "Graph Explorer",
+    description:
+      "DAG-first codebase and knowledge exploration specialist. Queries arcs search, related, and context first, then codegraph MCP code-intelligence tools, before falling back to raw file-system tools. Replaces vanilla explore for ARCS projects.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "tech-architect": {
     name: "Technical Architect",
     description:
-      "Architecture and analysis specialist. Deep structural reasoning and trade-off evaluation.",
+      "Architecture and analysis specialist. Deep structural reasoning, refactor guidance, trade-off evaluation, and root cause analysis without making hasty edits.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "code-reviewer": {
     name: "Code Reviewer",
-    description: "Reviews code changes for correctness, maintainability, and testing issues.",
+    description:
+      "Reviews code changes for production readiness and catches correctness, maintainability, and testing issues.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "qa-analyst": {
     name: "QA Analyst",
-    description: "Quality enforcement specialist. Proactive code audits and convention compliance.",
+    description:
+      "Quality enforcement specialist. Proactive code audits, review dispatch, convention compliance.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "system-architect": {
     name: "System Architect",
     description:
-      "Architecture and design specialist. Module boundaries, dependency graphs, and design decisions.",
+      "Architecture and design specialist. Module boundaries, dependency graphs, migration strategies, and cross-project design decisions.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "arcs-docs": {
     name: "ARCS Docs Specialist",
     description:
-      "Documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health.",
+      "ARCS documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health. Knows ARCS structure intimately.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
   "docs-researcher": {
     name: "Docs Researcher",
-    description: "Handles documentation writing, research synthesis, and document-heavy analysis.",
+    description:
+      "Handles documentation writing, research synthesis, OCR-adjacent extraction, and document-heavy analysis tasks.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
   "oncall-ops": {
     name: "On-Call Ops",
     description:
-      "Debugging and diagnosis specialist. Finds root causes through systematic investigation.",
+      "Debugging and diagnosis specialist. Finds root causes through systematic investigation, log triage, bisect, and performance profiling.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
@@ -422,6 +438,14 @@ function main() {
     }
   }
 
+  // Best-effort: wire the codegraph MCP server. Skipped on dry-run; never fatal.
+  const codegraphWired = dryRun ? false : wireCodegraphMcp("claude");
+
+  // Best-effort: wire RTK instructions + hook. `rtk init -g` only writes the
+  // user-global config, so project-scoped deploys skip it. Skipped on dry-run;
+  // never fatal.
+  const rtkWired = dryRun || scope === "project" ? false : wireRtk("claude");
+
   const result = {
     dryRun,
     source: bundleRoot,
@@ -431,6 +455,8 @@ function main() {
     filesChanged,
     filesRemoved,
     filesUnchanged,
+    codegraphWired,
+    rtkWired,
   };
 
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/deploy-opencode-bundle.mjs

@@ -23,8 +23,11 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { wireCodegraphMcp, wireRtk } from "./lib/bundle-helpers.mjs";
 
-const repoRoot = resolve(import.meta.dirname, "..");
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
 const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
 const defaultConfigRoot = resolve(homedir(), ".config/opencode");
 
@@ -176,6 +179,12 @@ async function main() {
     }
   }
 
+  // Best-effort: wire the codegraph MCP server. Skipped on dry-run; never fatal.
+  const codegraphWired = dryRun ? false : wireCodegraphMcp("opencode");
+
+  // Best-effort: wire RTK instructions + hook. Skipped on dry-run; never fatal.
+  const rtkWired = dryRun ? false : wireRtk("opencode");
+
   const result = {
     dryRun,
     source: bundleRoot,
@@ -186,6 +195,8 @@ async function main() {
     filesUnchanged,
     restartRequired,
     cliRegistered: !dryRun,
+    codegraphWired,
+    rtkWired,
     ...(restartRequired && {
       restartGuidance: "Plugin file changed. Restart opencode for changes to take effect.",
     }),

package/scripts/lib/bundle-helpers.mjs

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { isAbsolute, relative, resolve } from "node:path";
 
 export function normalizeRelativePath(filePath) {
@@ -170,3 +171,45 @@ export function validateDeclaredPath(relativePath, outputRoot, validationRoot) {
 
   return normalizedPath;
 }
+
+export function wireCodegraphMcp(target) {
+  // Best-effort: wire the codegraph MCP server for this host. Non-fatal.
+  // Skipped silently if the codegraph binary is absent, or when
+  // ARCS_SKIP_CODEGRAPH=1 (set by the test suite so deploy-script runs never
+  // mutate the developer's real host config).
+  if (process.env.ARCS_SKIP_CODEGRAPH === "1") return false;
+  try {
+    const r = spawnSync("codegraph", ["install", `--target=${target}`, "--yes"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 120_000,
+    });
+    if (r.error || r.status !== 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function wireRtk(target) {
+  // Best-effort: wire RTK (token-optimized command proxy) for this host.
+  // `rtk init -g` always covers Claude Code; `--opencode` additionally
+  // installs the OpenCode plugin. Non-fatal. Skipped silently if the rtk
+  // binary is absent, or when ARCS_SKIP_RTK=1 (set by the test suite so
+  // deploy-script runs never mutate the developer's real host config).
+  if (process.env.ARCS_SKIP_RTK === "1") return false;
+  try {
+    const args = ["init", "-g"];
+    if (target === "opencode") args.push("--opencode");
+    args.push("--auto-patch");
+    const r = spawnSync("rtk", args, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 120_000,
+    });
+    if (r.error || r.status !== 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/lint-bundle.mjs

@@ -9,9 +9,12 @@
 // Exit code: 0 if no errors, 1 if errors found.
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const repoRoot = resolve(import.meta.dirname, "..");
+// import.meta.dirname is Node >=20.11; derive it for Node 18 compatibility.
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
 const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
 
 const bundleRoot = process.env.BUNDLE_LINT_BUNDLE_ROOT
@@ -25,7 +28,6 @@ const preservedFiles = new Set([
   ".opencode/plugins/arcs.js",
   "skills/loop/SKILL.md",
   "skills/caveman-commit/SKILL.md",
-  "skills/caveman-review/SKILL.md",
   "skills/init-project/SKILL.md",
   // Sub-agent prompt files (repo-authored, referenced from manifest.json
   // requiredMerges, not from bundle-runtime.json's `agents` array).

package/skills/init-project.md

@@ -19,11 +19,11 @@ flowchart TD
     B --> C[Present summary to user]
     C -->|confirmed| D[arcs project init]
     D --> E[arcs project update-doc × 4]
-    E --> F{graphify on PATH?}
-    F -->|yes| G[graphify update --force --no-cluster]
+    E --> F{codegraph on PATH?}
+    F -->|yes| G[codegraph index --force --quiet]
     F -->|no| H[Skip graph step, log gap]
     G --> G2[ingestGraph → ≤20 proposals]
-    G2 --> G3[graphify query / explain for enrichment]:::sub
+    G2 --> G3[codegraph MCP explore / impact for enrichment]:::sub
     H & G3 --> I[Fan out: system-architect + docs-researcher + tech-architect]:::sub
     I --> J[Collect proposals → dedup → arcs knowledge create × N]
     J --> K[Done]
@@ -43,31 +43,31 @@ Discovery: `arcs --commands --json`
 - Init creates empty plans/ and knowledge/ indexes
 - Repo analysis is **fan-out across typed agents**, not a generic "analysis sub-agent" (see Agent Dispatch table below)
 
-## Graphify Sub-Flow (DEFAULT: ON when binary present)
+## Codegraph Sub-Flow (DEFAULT: ON when binary present)
 
-The orchestrator runs graphify directly during INIT to seed knowledge entries with structural evidence before any sub-agent reads code.
+The orchestrator runs codegraph directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals land on the proposal-store ledger (`pending_enrichment: true`); agents enrich them into knowledge entries via the `enriching-codegraph-proposals` skill.
 
-1. **Detect:** `detectGraphify()` from `src/utils/graphify.ts`. If unavailable, skip cleanly — never block INIT on graphify.
-2. **Trust the gitignore guarantee:** `runExtraction()` already auto-appends `graphify-out/` to `.gitignore` (`ensureGitignoreEntry`). Don't redundantly check or modify `.gitignore` from agents — running extraction is sufficient.
-3. **Extract (AST-only, no LLM key required):**
+1. **Detect:** `detectCodegraph()` from `src/utils/codegraph.ts`. If unavailable, skip cleanly — never block INIT on codegraph.
+2. **Trust the gitignore guarantee:** `runIndex()` already auto-appends `.codegraph/` to `.gitignore` (`ensureGitignoreEntry`). Don't redundantly check or modify `.gitignore` from agents — running the index is sufficient.
+3. **Index (AST-based; CLI drives the bundled runtime, no LLM key required):**
    ```bash
-   graphify update <workspacePath> --force --no-cluster
+   codegraph index <workspacePath> --force --quiet
    ```
-   Produces `graphify-out/graph.json`.
-4. **Ingest:** call internal `ingestGraph(graphJsonPath, slug)` → up to 20 `KnowledgeProposal` records:
-   - 8 god nodes (`kind=module`, top 5% degree, test files filtered)
-   - 8 architecture clusters (`kind=architecture`, by community or directory grouping)
+   Builds a per-project SQLite index under `<workspacePath>/.codegraph/`. There is no `graph.json` artifact.
+4. **Ingest:** `arcs project init` internally calls `ingestGraph(workspacePath, slug)` → up to 20 `KnowledgeProposal` records written to `proposals/graphify.json` (filename retained for compatibility; rename pending; test files filtered):
+   - 8 god nodes (`kind=module`, ranked by callers+callees / impact)
+   - 8 architecture clusters (`kind=architecture`, synthesized pseudo-communities by directory prefix)
    - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs)
-5. **Enrich** with read-only graph queries (sub-agents may run these):
-   - `graphify query "entry points and main commands" --graph graphify-out/graph.json --budget 2000` → seeds for "key files" reference entries
-   - `graphify query "core data flow" --graph graphify-out/graph.json --budget 2000` → seeds for "core modules" entries
-   - `graphify explain "<godNodeLabel>" --graph graphify-out/graph.json` → plain-language summary for module entry bodies
-   - `graphify affected "<critical-symbol>" --graph graphify-out/graph.json --depth 2` → reverse-impact map for high-risk modules
-   - `graphify path "<A>" "<B>" --graph graphify-out/graph.json` → shortest dependency path for architecture entries
+5. **Enrich** with the `enriching-codegraph-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), persist via `arcs proposal promote` and `arcs proposal drop`. Sub-agents may run read-only codegraph MCP queries for evidence (the MCP server auto-syncs via its own file watcher):
+   - `codegraph_search "entry points and main commands"` → seeds for "key files" reference entries
+   - `codegraph_explore` on core modules → seeds for "core modules" entries
+   - `codegraph_node "<godNodeLabel>"` → structural summary for module entry bodies
+   - `codegraph_impact "<critical-symbol>"` → reverse-impact map for high-risk modules
+   - `codegraph_callers` / `codegraph_callees "<symbol>"` → dependency paths for architecture entries
 6. **Hand to typed agents:** the proposals + query results go to the sub-agents listed in **Agent Dispatch** below; they merge graph evidence with code reading and return finalized knowledge entries.
 7. **Write** the entries directly via `arcs batch --file=ops.json` (one batch invocation for all knowledge entries) or `arcs knowledge create` per entry.
 
-If graphify is missing, log "graphify not on PATH; proceeding without graph signal" and skip steps 3–5. Sub-agents still run; they just lack the graph priors.
+If codegraph is missing, log "codegraph not on PATH; proceeding without graph signal" and skip steps 3–5. Sub-agents still run; they just lack the graph priors.
 
 ## Content Guidelines
 
@@ -87,19 +87,19 @@ If graphify is missing, log "graphify not on PATH; proceeding without graph sign
 | `tech-architect` | Cross-module couplings, structural gotchas, lessons | `gotcha`, `lesson` |
 | `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
 
-Dispatch in parallel (load `dispatching-parallel-agents`). Each agent receives the relevant `KnowledgeProposal` records from `ingestGraph` plus targeted graphify queries for evidence. Each agent returns finalized proposals (title, kind, summary, keywords, sourceFiles, body) for the orchestrator to write directly via `arcs knowledge create` (or `arcs batch`).
+Dispatch in parallel. Each agent receives the relevant `KnowledgeProposal` records from `ingestGraph` plus targeted codegraph MCP queries for evidence. Each agent returns finalized proposals (title, kind, summary, keywords, sourceFiles, body) for the orchestrator to write directly via `arcs knowledge create` (or `arcs batch`).
 
 ## Knowledge Categories for Analysis Sub-Agents
 
 | Category | Kind | What to discover | Primary agent |
 |----------|------|------------------|---------------|
 | tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
-| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (graphify query "entry points") |
+| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (codegraph_search "entry points") |
 | code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `qa-analyst` or `system-architect` |
 | coding style | `pattern` | Formatting, linting, import ordering, file organization | `qa-analyst` |
-| core modules | `module` | Core modules/shared functions — what, where, interconnections | `system-architect` (god nodes from graphify) |
+| core modules | `module` | Core modules/shared functions — what, where, interconnections | `system-architect` (god nodes from codegraph) |
 | external services | `module` | APIs, databases, message queues the project interacts with | `docs-researcher` |
 | third-party libraries | `reference` | Key dependencies and why they are used | `docs-researcher` |
 | features | `feature` | Major user-facing or system-facing features | `docs-researcher` |
-| cross-module couplings | `gotcha` | Hot edges between modules surfaced by graphify | `tech-architect` (auto from `ingestGraph`) |
-| architecture clusters | `architecture` | Community/directory groupings from graphify | `system-architect` (auto from `ingestGraph`) |
+| cross-module couplings | `gotcha` | Hot edges between modules surfaced by codegraph | `tech-architect` (auto from `ingestGraph`) |
+| architecture clusters | `architecture` | Pseudo-community/directory groupings from codegraph | `system-architect` (auto from `ingestGraph`) |

package/skills/orchestrate.md

@@ -86,9 +86,16 @@ Discovery: `arcs --commands --json`
 
 Pair with `loop` skill for iteration discipline.
 
+## Verification Contract
+
+- Sub-agents run ONLY the scoped VERIFY command from their dispatch (tests/lint on files they touched) — never the full suite.
+- The orchestrator never verifies: no tests, lint, builds, or `tsc`.
+- `devil-advocate` PHASE: completion is the session's single full-project pass (full suite + `tsc --noEmit`); on BLOCK, re-dispatch scoped fixes from its FAILURES attribution and re-gate. Two consecutive BLOCKs → stop, report.
+
 ## Completion
 
 Every session ends with:
-1. What was done
-2. Current project state
-3. Suggested next steps
+1. Gate — if any agent reported FILES_TOUCHED ≠ none, dispatch `devil-advocate` PHASE: completion (the only full-project verification); BLOCK → fix loop; never claim done before PASS. Zero-file-change sessions skip the gate.
+2. What was done
+3. Current project state
+4. Suggested next steps