@rryando/arcs 3.3.2 → 3.4.1

package/opencode/arcs/prompts/system-architect.txt

@@ -1,15 +1,13 @@
 You are a system architect — multi-project structural design, topology decisions, migration planning, cross-project boundary enforcement.
 
-## Session Start — T0 Orientation (MANDATORY)
+## Session Start — T0 Orientation (Conditional)
 
-Before any task work:
-1. Read `AGENTS.md` at the workspace root — it contains team conventions (tech stack, file naming, code patterns, testing patterns) plus live project context (overview, active plans, current focus). Use `cat AGENTS.md` or the Read tool.
-2. Run `arcs brief --lean --json` to get live DAG state (tasks, plans, knowledge).
-3. Search for relevant context: `arcs search <slug> "<keywords>" --json`
+Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it does, skip orientation and start — never re-derive facts given in CONTEXT. Run these ONLY to fill gaps the dispatch left open:
+1. Read `AGENTS.md` at the workspace root for team conventions (tech stack, file naming, code patterns, testing patterns) — ONLY when CONTEXT doesn't already state them.
+2. Run `arcs brief --lean --json` for live DAG state — ONLY when the dispatch carries no T0 excerpt.
+3. Run `arcs search <slug> "<keywords>" --json` — ONLY for context the dispatch left open.
 
-Only proceed after all three steps complete.
-
-Core skills you load: brainstorming (design exploration with dual-mode ARCS integration), writing-plans (implementation plans), to-diagram (visual execution maps), architecture-review (6-dimension structural audit), dispatching-parallel-agents (swarm coordination).
+Core skills you load: brainstorming (design exploration with dual-mode ARCS integration), writing-plans (implementation plans), to-diagram (visual execution maps).
 
 You have ARCS CLI access — use it to read project context across multiple projects, check dependency graphs, create plans, and capture architectural decisions as knowledge entries (kind: architecture).
 
@@ -17,7 +15,7 @@ You DO NOT write implementation code. You produce: design docs, plans, diagrams,
 
 ## Quality Gate
 
-Phase-gate verification is owned by the orchestrator (via `devil-advocate` subagent at checkpoints). You do NOT self-score. Your job: produce designs with clear rationale, flag risks, confirm testability at boundaries.
+Phase-gate verification is owned by the orchestrator (via `devil-advocate` subagent at checkpoints). You do NOT self-score. Never run the project test suite, repo-wide lint, or builds — full-project verification belongs exclusively to `devil-advocate` at PHASE: completion. Your job: produce designs with clear rationale, flag risks, confirm testability at boundaries.
 
 MANDATORY EXIT GATE: Before finalizing any design, verify: (1) dependency direction is correct (abstractions don't depend on concretions), (2) no circular dependencies introduced, (3) design is testable at each boundary, (4) migration path exists from current state.
 
@@ -37,6 +35,8 @@ MANDATORY EXIT GATE: Before finalizing any design, verify: (1) dependency direct
 
 All commands support `--json` for machine-readable output. Reads return `{ok, data}`; failures return `{ok:false, code, message, hint?}`. **Routing:** success → stdout, errors → stderr — always capture both with `2>&1`.
 
+**codegraph (when indexed):** For verifying real code-level coupling behind a proposed boundary or migration — actual call/import edges and change blast radius — prefer the `codegraph_*` MCP tools (`codegraph_impact`, `codegraph_explore`, `codegraph_callers`) over assuming structure from names. Skip if no `.codegraph/` index exists.
+
 ## Cross-Project Workflow
 
 When dispatched for structural design or migration planning:
@@ -55,7 +55,11 @@ Your scope is project TOPOLOGY — how projects relate, where boundaries should
 
 Your output is consumed by the orchestrator (an LLM), not a human. Be structured and terse.
 
-\`\`\`
+```
+STATUS: done | partial | blocked
+FILES_TOUCHED: none
+BLOCKED_BY: <only when blocked/partial — evidence>
+
 DELIVERABLE: <plan | design | knowledge entry | migration sequence>
 
 DECISIONS:
@@ -67,10 +71,13 @@ BOUNDARIES:
 RISKS:
 - <risk with severity and mitigation>
 
-ARTIFACTS: <arcs commands executed or proposed>
-\`\`\`
+ARTIFACTS:
+- executed: <arcs command run + resulting entry/plan id>
+- proposed: <ready-to-run arcs command for the orchestrator to execute verbatim>
+```
 
-No prose narrative. No "After analyzing..." — go straight to DELIVERABLE.
+STATUS is the first line — the orchestrator's join key. You write no code: FILES_TOUCHED is always `none`; omit VERIFY entirely. Omit BLOCKED_BY unless blocked/partial.
+No prose narrative. No "After analyzing..." — go straight to STATUS.
 
 ## Diagrams as Execution Maps
 

package/opencode/arcs/prompts/tech-architect.txt

@@ -4,22 +4,20 @@ You are a tech architect — a single-project deep structural analysis specialis
 
 ANALYSIS BEFORE RECOMMENDATIONS. You produce analysis artifacts — never topology decisions, never implementation code, never multi-project dependency mutations. Your scope is ONE project at a time, deep.
 
-## Session Start — T0 Orientation (MANDATORY)
+## Session Start — T0 Orientation (Conditional)
 
-Before any task work:
-1. Read `AGENTS.md` at the workspace root — it contains team conventions (tech stack, file naming, code patterns, testing patterns) plus live project context (overview, active plans, current focus). Use `cat AGENTS.md` or the Read tool.
-2. Run `arcs brief --lean --json` to get live DAG state (tasks, plans, knowledge).
-3. Search for relevant context: `arcs search <slug> "<keywords>" --json`
+Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it does, skip orientation and start — never re-derive facts given in CONTEXT. Run these ONLY to fill gaps the dispatch left open:
+1. Read `AGENTS.md` at the workspace root for team conventions (tech stack, file naming, code patterns, testing patterns) — ONLY when CONTEXT doesn't already state them.
+2. Run `arcs brief --lean --json` for live DAG state — ONLY when the dispatch carries no T0 excerpt.
+3. Run `arcs search <slug> "<keywords>" --json` — ONLY for context the dispatch left open.
 
-Only proceed after all three steps complete.
-
-Core skills you load: architecture-review (module boundaries, coupling, dependency direction, API surface cohesion), brainstorming (design exploration), writing-plans (structured plans from analysis findings), dispatching-parallel-agents (parallel module analysis).
+Core skills you load: brainstorming (design exploration), writing-plans (structured plans from analysis findings).
 
 You have ARCS CLI access — use it to read project context, check existing architectural knowledge entries, and capture findings as durable knowledge entries (kind: architecture or lesson).
 
 ## Quality Gate
 
-Phase-gate verification is owned by the orchestrator (via `devil-advocate` subagent at checkpoints). You do NOT self-score. Your job: analyze deeply, cite evidence for every finding, flag risks explicitly.
+Phase-gate verification is owned by the orchestrator (via `devil-advocate` subagent at checkpoints). You do NOT self-score. Never run the project test suite, repo-wide lint, or builds — full-project verification belongs exclusively to `devil-advocate` at PHASE: completion. Your job: analyze deeply, cite evidence for every finding, flag risks explicitly.
 
 MANDATORY EXIT GATE: Before delivering analysis, confirm: (1) all relevant modules examined, not just the symptom site, (2) every recommendation includes a concrete rationale, (3) risks and alternatives are called out, (4) changes that could affect other modules are flagged.
 
@@ -39,6 +37,8 @@ MANDATORY EXIT GATE: Before delivering analysis, confirm: (1) all relevant modul
 
 All commands support `--json` for machine-readable output. Reads return `{ok, data}`; failures return `{ok:false, code, message, hint?}`. **Routing:** success → stdout, errors → stderr — always capture both with `2>&1`.
 
+**codegraph (when indexed):** For fine-grained structural analysis — call chains, refactor blast radius, and verbatim symbol source — prefer the `codegraph_*` MCP tools (`codegraph_explore`, `codegraph_impact`, `codegraph_callers`, `codegraph_callees`) over raw file scanning; they surface dynamic-dispatch hops grep misses. Skip if no `.codegraph/` index exists.
+
 ## Analysis Workflow
 
 When dispatched for structural analysis:
@@ -57,7 +57,11 @@ Output: severity-ranked findings with evidence (file paths, metrics, dependency
 
 Your output is consumed by the orchestrator (an LLM), not a human. Be structured and terse.
 
-\`\`\`
+```
+STATUS: done | partial | blocked
+FILES_TOUCHED: none
+BLOCKED_BY: <only when blocked/partial — evidence>
+
 ANALYSIS: <one-line summary of what was analyzed>
 
 FINDINGS:
@@ -69,7 +73,10 @@ RECOMMENDATIONS:
 RISKS:
 - <risk if recommendation is NOT followed>
 
-ARTIFACTS: <arcs commands executed or proposed>
-\`\`\`
+ARTIFACTS:
+- executed: <arcs command run + resulting entry id>
+- proposed: <ready-to-run arcs command for the orchestrator to execute verbatim>
+```
 
-No prose narrative. No "I examined..." — go straight to ANALYSIS.
+STATUS is the first line — the orchestrator's join key. You write no code: FILES_TOUCHED is always `none`; omit VERIFY entirely. Omit BLOCKED_BY unless blocked/partial.
+No prose narrative. No "I examined..." — go straight to STATUS.

package/opencode/arcs/skills/code-agent/SKILL.md

@@ -45,12 +45,12 @@ If relevant entries exist, incorporate their guidance. Don't rediscover what's a
 ## Behaviour
 
 - Inspect repo before asking anything
-- Score self-confidence per `confidence-gate` before any code edit; <80% triggers explore/web recovery, not improvisation
+- Score self-confidence before any code edit; <80% triggers explore/web recovery, not improvisation
 - Proceed on inferred defaults when repo makes it clear
 - Ask at most one targeted question (product direction, naming, breaking trade-off)
 - TDD for new non-trivial behavior; skip for structural changes covered by existing tests
 - Lightweight bullet plan only when 3+ files and sequencing matters
-- Verify scoped: lint + test only files you touched (full suite only if change is pervasive — shared types, config, build)
+- Verify scoped: lint + test only files you touched — NEVER the full suite. Pervasive change (shared types, config, build) or failures in out-of-scope files → report under BLOCKED_BY, never fix; full-project verification belongs to the devil-advocate completion gate
 
 ## NOT for
 

package/opencode/arcs/skills/deep-pr-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deep-pr-review
-description: Use when the user provides a GitHub PR link with a "deep review" trigger inside a locally cloned repo, to perform a thorough multi-dimensional code review grounded in ARCS DAG context, AGENTS.md conventions, and optional graphify coupling analysis, then post findings as inline GitHub review comments under explicit user gate
+description: Use when the user provides a GitHub PR link with a "deep review" trigger inside a locally cloned repo, to perform a thorough multi-dimensional code review grounded in ARCS DAG context, AGENTS.md conventions, and optional codegraph coupling analysis, then post findings as inline GitHub review comments under explicit user gate
 ---
 
 # Skill: deep-pr-review
@@ -34,8 +34,8 @@ flowchart TD
     J --> K
     K --> L{Diff size?}
     L -->|huge >40 files OR >2000 lines| M[Force summary mode]
-    L -->|normal| N{graphify available?}
-    N -->|yes| O[Run affected/query on changed symbols]
+    L -->|normal| N{codegraph available?}
+    N -->|yes| O[Run impact/query on changed symbols]
     N -->|no| P[Skip coupling check — note in report]
     M --> Q[Aggregate findings + cite each]
     O --> Q
@@ -81,14 +81,14 @@ Agent picks dimensions from diff context. **Correctness is always evaluated.** O
 | **YAGNI** | Code written "for later" with no current caller; abstractions with one concrete use; configurable hooks with one known value; generic machinery built for hypothetical consumers |
 | **SOLID** | Module gains responsibilities, dependency direction shifts, large classes touched |
 | **Convention fit** | AGENTS.md or DAG `pattern`/`architecture` knowledge applies to changed files |
-| **Architectural risk** → handoff `architecture-review` | Diff crosses module boundaries, touches god nodes, changes public API |
-| **Performance risk** → handoff `performance-diagnosis` | Hot paths, loops over external IO, new queries, allocations in render |
+| **Architectural risk** → handoff to the system-architect agent (structural audit) | Diff crosses module boundaries, touches god nodes, changes public API |
+| **Performance risk** → handoff to the oncall-ops agent (performance investigation) | Hot paths, loops over external IO, new queries, allocations in render |
 
 Skipped dimensions are reported as `cleared (not applicable: <reason>)`. Never silently dropped.
 
 ## Severity Prefixes
 
-Reuses `caveman-review` format for inline output:
+Inline findings are one line — `<file>:L<line>: problem. fix.` — prefixed by severity:
 
 | Prefix | Meaning | Posting default |
 |--------|---------|-----------------|
@@ -120,7 +120,7 @@ Every finding cites a source. No uncited findings:
 
 - `see knowledge/<id>: <title>` — ARCS knowledge entry
 - `AGENTS.md §<section>` — project convention
-- `graphify: <observation>` — coupling/affected result
+- `codegraph: <observation>` — coupling/impact result
 - `principle: <KISS|DRY|YAGNI|SOLID|correctness>` — first-principles label
 
 If only first-principles applies, that is sufficient — but it must be stated.
@@ -131,7 +131,7 @@ GitHub `​```suggestion` blocks render an "Apply suggestion" button. Use **only
 
 - Multi-line code restructure → inline review comment with a fenced code block (no `suggestion` tag)
 - Missing block / new file content → top-level review body bullet
-- Cross-file refactor → handoff finding with `architecture-review` recommendation
+- Cross-file refactor → handoff finding recommending the system-architect agent (structural audit)
 
 ## Posting Protocol (ONE `gh api` call — never per-finding)
 
@@ -182,10 +182,10 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 - Never post to GitHub before user picks a posting mode
 - Cite every finding — no uncited claims
 - ` ```suggestion ` blocks only for small line-replacement fixes
-- Defer to `architecture-review` for full structural drift; surface as handoff flag, do not run inline
-- Defer to `performance-diagnosis` for perf investigation; surface as risk flag
-- Compose with `auditing-a-feature` rubric and `caveman-review` inline format — do not duplicate
+- Defer to the system-architect agent (structural audit) for full structural drift; surface as handoff flag, do not run inline
+- Defer to the oncall-ops agent (performance investigation) for perf work; surface as risk flag
+- Review dimensions are defined in this skill (Adaptive Rubric); inline findings use the one-line format `<file>:L<line>: problem. fix.` — do not duplicate
 - Re-review detection: if AI has reviewed before, scope to diff since last review's commit_id
 - Tag each posted suggestion with `<!-- arcs:deep-review:<finding-id> -->` for re-review tracking
 - See `review-template.md` for GitHub review body template
-- See `graphify-diff.md` for the changed-symbols-to-affected algorithm
+- See `codegraph-diff.md` for the changed-symbols-to-impact algorithm

package/opencode/arcs/skills/deep-pr-review/{graphify-diff.md → codegraph-diff.md}

@@ -1,19 +1,21 @@
-# Graphify Diff Algorithm
+# Codegraph Diff Algorithm
 
-`graphify` has no native "diff against PR" command. This file defines how `deep-pr-review` builds coupling/duplication checks on top of the existing `affected`, `query`, and `diagnose multigraph` primitives.
+`codegraph` has no native "diff against PR" command. This file defines how `deep-pr-review` builds coupling/duplication checks on top of the existing `impact`, `callers`/`callees`, and `query` primitives.
 
 ## Prerequisites
 
 ```bash
-which graphify || echo "skip"            # graceful absence
-ls graphify-out/graph.json 2>/dev/null   # graph must exist
+which codegraph || echo "skip"           # graceful absence
+codegraph status --json 2>/dev/null      # index must exist + be initialized
 ```
 
-If graphify is missing or `graph.json` is older than the PR's base commit, refresh:
+If codegraph is missing or the index is stale relative to the PR's base commit, refresh:
 ```bash
-graphify update .
+codegraph sync .        # incremental; or `codegraph index . --force` for a full rebuild
 ```
 
+The index lives in `.codegraph/` (SQLite, gitignored) — there is no `graph.json` file.
+
 ## Step 1: Extract changed symbols from the diff
 
 ```bash
@@ -22,7 +24,7 @@ gh pr diff <num> --patch > /tmp/pr.diff
 
 Parse `/tmp/pr.diff` to extract changed symbols:
 - For each `+++ b/<file>` hunk, capture the file path
-- For each added / modified function or exported identifier, capture `<file>::<symbol>`
+- For each added / modified function or exported identifier, capture `<symbol>` (codegraph addresses symbols by name, not `<file>::<symbol>`)
 - Skip pure deletions (handled separately under "removed coupling" check)
 
 Heuristic for symbol extraction (language-aware):
@@ -32,16 +34,19 @@ Heuristic for symbol extraction (language-aware):
 - Rust: `fn X`, `struct X`, `impl X`
 - Other: fall back to file-level granularity
 
-## Step 2: Run `affected` per changed symbol
+## Step 2: Run `impact` per changed symbol
 
 ```bash
-graphify affected "<file>::<symbol>" --depth 2 --json
+codegraph impact "<symbol>" --json      # what code is affected by changing this symbol
+codegraph callers "<symbol>" --json     # direct callers (one hop)
 ```
 
+`codegraph impact` is the closest equivalent to the old `affected --depth N`: it walks the reverse-dependency closure for a symbol. Use `callers` for a precise one-hop view when `impact` is too broad.
+
 Collect for each symbol:
-- **Fan-out callers** — who depends on this symbol (changes ripple here)
-- **Fan-out depth** — how many hops to leaves
-- **Cross-module edges** — callers in different top-level dirs
+- **Fan-out callers** — who depends on this symbol (changes ripple here), from `callers` / `impact`
+- **Fan-out reach** — size of the impact set (proxy for blast radius)
+- **Cross-module edges** — callers in different top-level dirs (derive from each caller's `file_path`)
 
 ## Step 3: Detect surprising fan-out
 
@@ -57,23 +62,15 @@ Flag as 🟠 **risk** in the report when:
 
 For each new function added in the diff, run:
 ```bash
-graphify query "functions similar to <new-symbol-signature>" --budget 8 --json
-```
-
-If results include symbols with similar signatures (≥70% name overlap or matching parameter shape), flag as 🟡 **suggestion** with citation `graphify: similar to <existing-symbol>` and propose extraction or reuse.
-
-## Step 5: Diagnose multigraph (architectural drift)
-
-```bash
-graphify diagnose multigraph --json
+codegraph query "<new-symbol-name or signature keywords>" --json
 ```
 
-If the PR introduces edges that contribute to a multigraph collapse (multiple edges between the same node pair), flag as 🟠 **risk** with handoff to `architecture-review`. Same-endpoint multi-edges are a structural duplication signal worth surfacing but not worth diagnosing inline.
+`codegraph query` is a symbol search over the index. If results include symbols with similar names/signatures (≥70% name overlap or matching parameter shape), flag as 🟡 **suggestion** with citation `codegraph: similar to <existing-symbol>` and propose extraction or reuse.
 
-## Step 6: Aggregate findings
+## Step 5: Aggregate findings
 
-Each graphify-derived finding must include:
-- The `graphify` command that produced it (for reproducibility)
+Each codegraph-derived finding must include:
+- The `codegraph` command that produced it (for reproducibility)
 - The cited symbol(s) — use backticks
 - The cited module path(s)
 - A finding ID for re-review tracking: `<file>:<line>:<dimension>:<short-hash>`
@@ -84,19 +81,18 @@ Each graphify-derived finding must include:
   - All exported / public symbols first (always)
   - Then internal symbols by descending hunk size
 - Skip step 4 (duplication) entirely if diff size exceeds 1500 LOC — too noisy
-- Skip step 5 (multigraph) if `graphify diagnose multigraph` runtime exceeds 10s — log and continue without
 
 ## Graceful degradation
 
-If any graphify call fails or returns empty:
-- Note in report: `Graphify step <N> unavailable: <reason>` under "Cleared Dimensions"
+If any codegraph call fails or returns empty:
+- Note in report: `Codegraph step <N> unavailable: <reason>` under "Cleared Dimensions"
 - Continue with the remaining dimensions
-- Never let a graphify failure abort the review
+- Never let a codegraph failure abort the review
 
 ## Output integration
 
-Graphify findings flow back into the standard finding pipeline. Each one is:
-- Cited as `graphify: <one-line observation>`
+Codegraph findings flow back into the standard finding pipeline. Each one is:
+- Cited as `codegraph: <one-line observation>`
 - Severity-classified (most are 🟡 suggestion or 🟠 risk; rarely 🔴)
 - Attached to a specific file+line if possible; otherwise lives in the top-level review body
 - Tagged for re-review with `<!-- arcs:deep-review:<finding-id> -->`

package/opencode/arcs/skills/deep-pr-review/review-template.md

@@ -25,13 +25,13 @@ Used as the `body` field of `gh api repos/{owner}/{repo}/pulls/{pull_number}/rev
 
 ### Architectural / Performance Handoffs
 <only if any; otherwise omit section>
-- [architecture-review] <reason — e.g. crosses 3 modules, touches god node X>
-- [performance-diagnosis] <reason — e.g. new query in render path>
+- [system-architect] <reason — e.g. crosses 3 modules, touches god node X>
+- [oncall-ops] <reason — e.g. new query in render path>
 
 ### Citations Used
 - AGENTS.md §<section> — <what was checked>
 - knowledge/<id> — <what was checked>
-- graphify — <observations, if run>
+- codegraph — <observations, if run>
 
 ---
 <!-- arcs:deep-review:meta version=1 commit=<HEAD_SHA> rubric=<activated> mode=<posting-mode> -->
@@ -51,7 +51,7 @@ Used as the `body` field of `gh api repos/{owner}/{repo}/pulls/{pull_number}/rev
 
 <optional 1-2 sentences of why, only if not obvious from problem>
 
-Citation: <AGENTS.md §x | knowledge/<id> | graphify | principle: <name>>
+Citation: <AGENTS.md §x | knowledge/<id> | codegraph | principle: <name>>
 
 ​```suggestion
 <replacement code — only for small line replacements>

package/opencode/arcs/skills/{enriching-graphify-proposals → enriching-codegraph-proposals}/SKILL.md

@@ -1,17 +1,17 @@
 ---
-name: enriching-graphify-proposals
-description: Use when `arcs project init` or `arcs graphify-sync` returns `pending_enrichment: true` — drives the per-proposal verdict loop (keep/drop/merge) and produces agent-authored knowledge entries from raw graphify proposals.
+name: enriching-codegraph-proposals
+description: Use when `arcs project init` or `arcs codegraph-sync` returns `pending_enrichment: true` — drives the per-proposal verdict loop (keep/drop/merge) and produces agent-authored knowledge entries from raw codegraph proposals.
 ---
 
-# Skill: enriching-graphify-proposals
+# Skill: enriching-codegraph-proposals
 
 ## When
 
-The CLI surfaced raw graphify proposals and is waiting for an agent to turn them into real knowledge entries. Mandatory triggers:
+The CLI surfaced raw codegraph proposals and is waiting for an agent to turn them into real knowledge entries. Mandatory triggers:
 
-- `arcs project init` returned `graphify.pending_enrichment: true` in its JSON envelope.
-- `arcs graphify-sync` returned `pending_enrichment: true`.
-- User said "enrich the proposals", "process the graphify queue", "promote the pending proposals", or similar.
+- `arcs project init` returned `codegraph.pending_enrichment: true` in its JSON envelope.
+- `arcs codegraph-sync` returned `pending_enrichment: true`.
+- User said "enrich the proposals", "process the codegraph queue", "promote the pending proposals", or similar.
 
 > **Read-write skill.** This skill mutates the DAG via `arcs proposal promote/drop`. Self-score ≥80% via `confidence-gate` before each promote.
 
@@ -75,7 +75,7 @@ Use `arcs proposal promote --merge-with=<existing-id>` when:
 - `suggestedDedupCandidates` lists an existing knowledge entry whose `kind` matches the proposal's natural kind, AND
 - The proposal adds genuinely new structural facts the existing entry does not already document (e.g. precise degree numbers, additional top hubs, cross-module edges, fileCount).
 
-The agent appends a `## From graphify analysis` section to the existing entry — it does NOT replace prior body content. Treat the existing entry as the spine; the merge adds a graph-evidence rib.
+The agent appends a `## From codegraph analysis` section to the existing entry — it does NOT replace prior body content. Treat the existing entry as the spine; the merge adds a graph-evidence rib.
 
 ## Enrichment Output Contract
 

package/opencode/arcs/skills/executing-plans/SKILL.md

@@ -27,20 +27,20 @@ flowchart TD
     E --> F{Concerns about plan?}
     F -->|Yes| G[Raise with human — STOP]
     F -->|No| H[Select next ready task]
-    H --> I[Transition task → in_progress]
+    H --> I[Mark task started — see Transition ownership]
     I --> J[Execute steps exactly]
-    J --> K[Run verification command]
+    J --> K[Run task's scoped verify command]
     K --> L{Passes?}
     L -->|No| M{Repeated failure?}
     M -->|Yes| N[STOP — ask for help]
     M -->|No| J
-    L -->|Yes| O[Transition task → done]
+    L -->|Yes| O[Report task done — see Transition ownership]
     O --> P{More ready tasks?}
     P -->|Yes| H
     P -->|No| Q{All tasks done?}
     Q -->|No| R[Re-scan: arcs diagram ready]
     R --> P
-    Q -->|Yes| S[Use finishing-a-development-branch skill]
+    Q -->|Yes| S[Report completion — devil-advocate gate owns the full-project pass]
 ```
 
 ## Diagram-First Task Selection
@@ -53,16 +53,20 @@ When plan has `.diagram.mmd`:
 
 **Dependency-aware ordering:** `arcs next` respects `dependsOn` — it only surfaces tasks whose dependencies are all `done`. Use `arcs next` as the authoritative source for what's executable; you don't need to manually parse `.mmd` for ordering. `arcs diagram ready` remains useful for per-plan metadata inspection.
 
-**Transition requires both flags:** `arcs task transition <slug> <taskId> done --diagramNodeId=T001 --planId=<planId>`
+**Transition ownership:** When dispatched by the ARCS orchestrator, you never run `arcs task transition` — report each task done in your return envelope (STATUS/FILES_TOUCHED/VERIFY) and the orchestrator transitions after the execute gate passes. Only when running standalone (no orchestrator session) transition yourself, with both flags: `arcs task transition <slug> <taskId> done --diagramNodeId=T001 --planId=<planId>`
+
+**Verify scope rule:** Run ONLY the current task's `verify` command, scoped to that task's `files`. If the authored command is broader than the task's scope (bare `npm test`, `vitest run`, `biome check .`), narrow it to the touched files first (e.g. `npm test -- test/orders.test.ts`). Failures in files outside the task's scope are report-only — list them under BLOCKED_BY, never fix them. Full-project verification happens once, at the devil-advocate completion gate.
 
 ## Sub-Agent Context
 
-Include in sub-agent prompts:
+Fetch once, then paste the relevant output into each dispatch's CONTEXT — don't make sub-agents re-fetch:
 ```bash
 arcs context <slug> --audience=implementer --lean --json
 arcs search <slug> "<task-keywords>" --lean --json
 ```
 
+Sub-agents run `arcs` lookups only to fill gaps the dispatch left open — never to re-derive what CONTEXT already states.
+
 Sub-agents MUST NOT edit `.mmd` files — orchestrator owns diagram updates.
 
 ## Review Checkpoint Criteria
@@ -87,7 +91,7 @@ Post-execution DAG sync fires automatically when:
 
 - Review plan critically before starting — raise concerns first
 - Follow plan steps exactly — don't improvise
-- Never skip verifications
+- Never skip verifications — and never widen them beyond the task's scope
 - Never start on main/master without explicit consent
 - Reference sub-skills when plan specifies them
-- Use `finishing-a-development-branch` after all tasks complete
+- After all tasks complete: report completion — the devil-advocate completion gate runs the single full-project verification

package/opencode/arcs/skills/init-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: init-project
-description: Use when initializing a new ARCS project — bootstrapping a repo into the DAG with metadata, docs, and structural knowledge entries. Covers gather → present summary → init → graphify ingestion → fan-out analysis across typed sub-agents.
+description: Use when initializing a new ARCS project — bootstrapping a repo into the DAG with metadata, docs, and structural knowledge entries. Covers gather → present summary → init → codegraph ingestion → fan-out analysis across typed sub-agents.
 ---
 
 # Skill: init-project
@@ -21,11 +21,11 @@ flowchart TD
     B --> C[Present summary to user]
     C -->|user confirms| 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]
@@ -44,33 +44,33 @@ Discovery: `arcs --commands --json`. Mutating commands run directly — no token
 - Verify `dependsOn` targets exist via `arcs project list --json`
 - `arcs project init` creates empty `plans/`, `knowledge/`, `tasks/` indexes — don't pre-populate
 - Repo analysis is **fan-out across typed agents**, never a generic "analysis sub-agent" (see Agent Dispatch below)
-- Never block INIT on graphify — it's optional. Skip cleanly if missing.
+- Never block INIT on codegraph — it's optional. Skip cleanly if missing.
 
-## Graphify Sub-Flow (DEFAULT: ON when binary present)
+## Codegraph Sub-Flow (DEFAULT: ON when binary present)
 
-The orchestrator runs graphify directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals are durable on the proposal-store ledger; agents enrich them into knowledge entries via the `enriching-graphify-proposals` skill. This is the default path when `graphify` is on PATH; skip cleanly otherwise.
+The orchestrator runs codegraph directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals are durable on the proposal-store ledger; agents enrich them into knowledge entries via the `enriching-codegraph-proposals` skill. This is the default path when `codegraph` is on PATH; skip cleanly otherwise.
 
-1. **Detect:** call `detectGraphify()` from `src/utils/graphify.ts`. If unavailable, log "graphify not on PATH; proceeding without graph signal" and skip steps 3–6.
-2. **Trust the gitignore guarantee:** `runExtraction()` already auto-appends `graphify-out/` to `.gitignore` via `ensureGitignoreEntry`. Do NOT redundantly check or modify `.gitignore` from agents — running extraction is sufficient.
-3. **Extract** (AST-only, no LLM API key required):
+1. **Detect:** call `detectCodegraph()` from `src/utils/codegraph.ts`. If unavailable, log "codegraph not on PATH; proceeding without graph signal" and skip steps 3–6.
+2. **Trust the gitignore guarantee:** `runIndex()` already auto-appends `.codegraph/` to `.gitignore` via `ensureGitignoreEntry`. Do NOT redundantly check or modify `.gitignore` from agents — running the index is sufficient.
+3. **Index** (project-based; CLI drives the bundled runtime — no LLM API key required):
    ```bash
-   graphify update <workspacePath> --force --no-cluster
+   codegraph index <workspacePath> --force --quiet
    ```
-   Produces `<workspacePath>/graphify-out/graph.json`.
-4. **Ingest as proposals:** `arcs project init` internally calls `ingestGraph(graphJsonPath, slug)`, which writes up to 20 structural proposals to `proposals/graphify.json` (test files filtered):
-   - 8 god nodes (`kind=module`, top 5% degree)
-   - 8 architecture clusters (`kind=architecture`, by community or directory grouping)
-   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs)
-
-   Graphify never writes directly to the knowledge surface. The init envelope returns `data.graphify.pending_enrichment: true` to signal that proposals are waiting.
-5. **Enrich** with the `enriching-graphify-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), persist via `arcs proposal promote` and `arcs proposal drop`. The skill encodes the decision heuristics, output contract, and cost discipline; do not paraphrase.
-6. **Optional graph queries** for evidence during enrichment (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
-7. **Hand to typed agents** (in parallel) for code-grounded follow-up entries that go beyond what graphify proposals cover — see **Agent Dispatch** below.
+   Builds a per-project codegraph index under `<workspacePath>/.codegraph/`.
+4. **Ingest as proposals:** `arcs project init` internally calls `ingestGraph(slug)`, which parses codegraph CLI `--json` output and writes up to 20 structural proposals to `proposals/graphify.json` (filename retained for compatibility; rename pending; test files filtered):
+   - 8 god nodes (`kind=module`, ranked by callers+callees / impact as a proxy for degree)
+   - 8 architecture clusters (`kind=architecture`, synthesized pseudo-communities by directory prefix — codegraph has no community/cluster export)
+   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs; relations hard-coded as `["calls"]`)
+
+   Codegraph never writes directly to the knowledge surface. The init envelope returns `data.codegraph.pending_enrichment: true` to signal that proposals are waiting.
+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`. The skill encodes the decision heuristics, output contract, and cost discipline; do not paraphrase.
+6. **Optional graph queries** for evidence during enrichment (sub-agents may run these via the codegraph MCP server, which auto-syncs through 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
+7. **Hand to typed agents** (in parallel) for code-grounded follow-up entries that go beyond what codegraph proposals cover — see **Agent Dispatch** below.
 
 ## Content Guidelines
 
@@ -92,9 +92,9 @@ Update via `arcs project update-doc <slug> <doc> --content="..."`.
 | `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` (so they don't rediscover what graphify already found)
-- Targeted graphify queries for evidence (e.g., `graphify explain` output for the modules they own)
+Dispatch in parallel — all agents in one message, per the orchestrator's Parallelism rules. Each agent receives:
+- The relevant `KnowledgeProposal` records from `ingestGraph` (so they don't rediscover what codegraph already found)
+- Targeted codegraph queries for evidence (e.g., `codegraph_node` / `codegraph_impact` output for the modules they own)
 - Explicit scope (which files / which kinds to produce)
 
 Each agent returns finalized proposals: `{title, kind, summary, keywords, sourceFiles, body}`. The orchestrator dedups, then writes the entries directly via `arcs knowledge create` (or `arcs batch`).
@@ -104,15 +104,15 @@ Each agent returns finalized proposals: `{title, kind, summary, keywords, source
 | 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` (use `graphify query "entry points"`) |
+| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (use `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`) |
 
 ## Worked Example
 
@@ -127,11 +127,11 @@ arcs project init "Foo" --description="Foo CLI tool" --path="$(pwd)" --json
 arcs project update-doc foo overview --content="..." --json
 # ... repeat for tasks, dependencies, knowledge
 
-# 4. Graphify (if available) — runs inside `arcs project init`
-graphify update . --force --no-cluster
-# ingestGraph writes proposals to proposals/graphify.json
-# init envelope: data.graphify.pending_enrichment === true → load
-# `enriching-graphify-proposals` and run the verdict loop:
+# 4. Codegraph (if available) — runs inside `arcs project init`
+codegraph index . --force --quiet
+# ingestGraph parses codegraph CLI --json → proposals/graphify.json (filename retained; rename pending)
+# init envelope: data.codegraph.pending_enrichment === true → load
+# `enriching-codegraph-proposals` and run the verdict loop:
 arcs proposal list foo --json
 arcs proposal promote foo <id> --title="..." --summary="..." --body-file=... --kind=module --source-files=... --json
 arcs proposal drop foo <id> --reason="..." --json
@@ -152,6 +152,6 @@ arcs knowledge create foo "Tech stack: TypeScript + Node 20" --kind=architecture
 |-----------|--------|
 | Project already in DAG (slug collision) | Stop. Surface conflict; ask user to rename or use existing |
 | User declines summary | Stop. No mutations performed |
-| `graphify` missing | Continue without graph signal; sub-agents run with code reading only |
+| `codegraph` missing | Continue without graph signal; sub-agents run with code reading only |
 | `dependsOn` target missing | Stop. Ask user to init dependencies first or remove the link |
 | Init succeeds but knowledge fan-out fails | Project exists in DAG; rerun knowledge phase later via SYNC |