@rryando/arcs 3.1.2 → 3.2.1

package/opencode/arcs/manifest.json

@@ -44,11 +44,19 @@
           }
         }
       },
+      {
+        "path": [
+          "lsp"
+        ],
+        "value": true,
+        "mode": "if-absent"
+      },
       {
         "path": [
           "model"
         ],
-        "value": "github-copilot/claude-sonnet-4.6"
+        "value": "github-copilot/claude-sonnet-4.6",
+        "mode": "if-absent"
       },
       {
         "path": [
@@ -56,7 +64,8 @@
           "build",
           "model"
         ],
-        "value": "github-copilot/claude-sonnet-4.6"
+        "value": "github-copilot/claude-sonnet-4.6",
+        "mode": "if-absent"
       },
       {
         "path": [
@@ -64,7 +73,8 @@
           "plan",
           "model"
         ],
-        "value": "github-copilot/claude-opus-4.6"
+        "value": "github-copilot/claude-opus-4.6",
+        "mode": "if-absent"
       },
       {
         "path": [
@@ -72,7 +82,8 @@
           "general",
           "model"
         ],
-        "value": "github-copilot/claude-opus-4.6"
+        "value": "github-copilot/claude-opus-4.6",
+        "mode": "if-absent"
       },
       {
         "path": [
@@ -80,7 +91,8 @@
           "explore",
           "model"
         ],
-        "value": "github-copilot/claude-haiku-4.5"
+        "value": "github-copilot/claude-haiku-4.5",
+        "mode": "if-absent"
       },
       {
         "path": [
@@ -93,9 +105,11 @@
           "model": "github-copilot/claude-haiku-4.5",
           "prompt": "{file:./prompts/code-reviewer.txt}",
           "permission": {
-            "edit": "deny",
+            "edit": "allow",
             "bash": "allow",
-            "webfetch": "deny"
+            "webfetch": "allow",
+            "mcp": "allow",
+            "external_directory": { "*": "allow" }
           }
         }
       },
@@ -109,15 +123,11 @@
           "mode": "subagent",
           "model": "github-copilot/claude-opus-4.6",
           "permission": {
-            "edit": "ask",
-            "bash": "ask",
+            "edit": "allow",
+            "bash": "allow",
             "webfetch": "allow",
-            "external_directory": {
-              "/tmp": "allow",
-              "/tmp/**": "allow",
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow"
-            }
+            "mcp": "allow",
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/docs-researcher.txt}"
         }
@@ -132,13 +142,11 @@
           "mode": "subagent",
           "model": "github-copilot/claude-haiku-4.5",
           "permission": {
-            "edit": "ask",
-            "bash": "ask",
-            "webfetch": "deny",
-            "external_directory": {
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow"
-            }
+            "edit": "allow",
+            "bash": "allow",
+            "webfetch": "allow",
+            "mcp": "allow",
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/tech-architect.txt}"
         }
@@ -155,14 +163,9 @@
           "permission": {
             "edit": "allow",
             "bash": "allow",
-            "webfetch": "deny",
+            "webfetch": "allow",
             "mcp": "allow",
-            "external_directory": {
-              "/tmp": "allow",
-              "/tmp/**": "allow",
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow"
-            }
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/software-engineer.txt}"
         }
@@ -179,16 +182,9 @@
           "permission": {
             "edit": "allow",
             "bash": "allow",
-            "webfetch": "deny",
+            "webfetch": "allow",
             "mcp": "allow",
-            "external_directory": {
-              "/tmp": "allow",
-              "/tmp/**": "allow",
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow",
-              "~/.config/opencode": "allow",
-              "~/.config/opencode/**": "allow"
-            }
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/arcs-docs.txt}"
         }
@@ -203,14 +199,11 @@
           "mode": "subagent",
           "model": "github-copilot/claude-haiku-4.5",
           "permission": {
-            "edit": "deny",
+            "edit": "allow",
             "bash": "allow",
-            "webfetch": "deny",
+            "webfetch": "allow",
             "mcp": "allow",
-            "external_directory": {
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow"
-            }
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/qa-analyst.txt}"
         }
@@ -225,16 +218,11 @@
           "mode": "subagent",
           "model": "github-copilot/claude-sonnet-4.6",
           "permission": {
-            "edit": "deny",
+            "edit": "allow",
             "bash": "allow",
-            "webfetch": "deny",
+            "webfetch": "allow",
             "mcp": "allow",
-            "external_directory": {
-              "/tmp": "allow",
-              "/tmp/**": "allow",
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow"
-            }
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/devil-advocate.txt}"
         }
@@ -249,16 +237,11 @@
           "mode": "subagent",
           "model": "github-copilot/claude-opus-4.6",
           "permission": {
-            "edit": "ask",
+            "edit": "allow",
             "bash": "allow",
-            "webfetch": "deny",
+            "webfetch": "allow",
             "mcp": "allow",
-            "external_directory": {
-              "/tmp": "allow",
-              "/tmp/**": "allow",
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow"
-            }
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/oncall-ops.txt}"
         }
@@ -273,14 +256,11 @@
           "mode": "subagent",
           "model": "github-copilot/claude-opus-4.6",
           "permission": {
-            "edit": "deny",
+            "edit": "allow",
             "bash": "allow",
             "webfetch": "allow",
             "mcp": "allow",
-            "external_directory": {
-              "~/.arcs": "allow",
-              "~/.arcs/**": "allow"
-            }
+            "external_directory": { "*": "allow" }
           },
           "prompt": "{file:./prompts/system-architect.txt}"
         }
@@ -289,7 +269,8 @@
         "path": [
           "small_model"
         ],
-        "value": "github-copilot/claude-haiku-4.5"
+        "value": "github-copilot/claude-haiku-4.5",
+        "mode": "if-absent"
       }
     ]
   }

package/opencode/arcs/prompts/arcs-orchestrate-caveman.txt

@@ -134,7 +134,7 @@ Discovery: `arcs --commands --json` (cache once per session). Batch op names are
 | List tasks | `arcs task list <slug> --json` |
 | List plans | `arcs plan list <slug> --json` |
 | Search | `arcs search <slug> "<query>" --json` |
-| Diagram ready | `arcs diagram ready <slug> <planId> --json` |
+| Diagram ready | `arcs diagram ready <slug> <planId> --json` — returns `{ready, blocked, inProgress, done}` arrays |
 | Validate | `arcs validate <slug> --json` |
 | Task transition | `arcs task transition <slug> <taskId> <status> --planId=<id> --diagramNodeId=<node> --json` |
 | Batch writes | `arcs batch --file=ops.json --json` |
@@ -292,6 +292,7 @@ Use `recommendedSurface` to pick the routing branch: `QUEUE` → EXECUTE, `PLAN`
 | External research / docs | `docs-researcher` | |
 | 2+ independent problems | parallel fan-out across typed agents | Load `dispatching-parallel-agents` |
 | Multi-step plan with independent leaves | `software-engineer` × N coordinated by orchestrator | Load `subagent-driven-development` |
+| Pending graphify enrichment after init/sync | calling agent (or sub-agent) loads `enriching-graphify-proposals` | When envelope has `pending_enrichment: true` — drives `arcs proposal list/promote/drop` |
 
 **Anti-pattern:** dispatching `software-engineer` for analysis, audit, review, debugging, or research.
 
@@ -310,7 +311,7 @@ flowchart TD
     A -->|executing pre-written plan| EP[executing-plans]
 ```
 
-### Skill Catalogue (14 surviving skills)
+### Skill Catalogue (15 surviving skills)
 
 | Skill | Load when |
 |-------|----------|
@@ -327,6 +328,7 @@ flowchart TD
 | `deep-pr-review` | GitHub PR link with "deep review" trigger |
 | `requesting-code-review` | Self-review gate at phase/feature completion |
 | `caveman-commit` | Writing git commit messages |
+| `enriching-graphify-proposals` | `arcs project init` or `arcs graphify-sync` returned `pending_enrichment: true` |
 
 > **Note:** `confidence-gate` and `verification-before-completion` have been replaced by the `devil-advocate` subagent dispatched at phase checkpoints.
 
@@ -398,11 +400,12 @@ CLI:
 3. Present summary → user confirms → `arcs project init`
 4. `arcs project update-doc × 4`
 5. Fan out (if needed): `system-architect` (architecture entries) + `docs-researcher` (tech-stack, features) + `tech-architect` (couplings, gotchas) → collect proposals → dedup → `arcs knowledge create × N`
+6. **Proposal-gate enrichment:** if `arcs project init`'s envelope returned `data.graphify.pending_enrichment === true`, load the `enriching-graphify-proposals` skill on the calling agent (or dispatch a sub-agent with that skill). The skill reads `arcs proposal list <slug> --json`, decides per-proposal verdicts (keep / merge / drop), and persists results via `arcs proposal promote` and `arcs proposal drop`. Graphify never writes directly to the knowledge surface — promotion is the only path from proposal to knowledge entry.
 
 **Constraints:**
 - Do NOT read repo to infer name/description — gather from user or T0
 - See the `init-project` skill for full category table and worked example
-- Graphify (if on PATH): `arcs project init` auto-runs extraction + seeding. Load `graphify-aware` skill on sub-agents when `graphify-out/graph.json` exists.
+- Graphify (if on PATH): `arcs project init` auto-runs extraction and writes structural proposals to `proposals/graphify.json`. When the envelope returns `pending_enrichment: true`, load `enriching-graphify-proposals` and consume via `arcs proposal list/promote/drop`. The previous direct-write knowledge ingestion has been replaced — graphify never writes directly to the knowledge surface anymore.
 
 ### BRAINSTORM Workflow
 
@@ -435,7 +438,7 @@ CLI:
 - `arcs next` is dependency-aware (topological sort) — it returns the first task whose `dependsOn` are all done. Use it as the primary task selection mechanism.
 - `arcs task transition` atomically updates task status + diagram node. MUST pass both `--planId` and `--diagramNodeId` (both required for diagram patch)
 - Sub-agents NEVER edit `.mmd` files — agents must NOT manually patch `.mmd` for status transitions. Scope changes reported back, orchestrator regenerates via `arcs diagram sort-metadata <slug> <planId> --json`
-- `arcs diagram ready` after each transition to discover newly-unblocked nodes
+- `arcs diagram ready` after each transition to discover newly-unblocked nodes — read `data.ready` (and `data.blocked` to surface what's still gated)
 - If blocked → note blocker, advance to next unblocked task
 
 **Auto-sync triggers** (any one sufficient): 3+ transitions, `lastSyncedAt` > 7 days, plan reached `done`.
@@ -447,6 +450,7 @@ CLI:
 3. Delegate to arcs-docs sub-agent with T0 context + validate output + staleness info
 4. Sub-agent: audit + repair + write checkpoints (`lastSyncedAt`, `lastSyncGitCommit`, `lastSyncStats`) via ARCS CLI
 5. Receive sync report → present to user
+6. **Proposal-gate enrichment:** if SYNC includes `arcs graphify-sync` and that command returned `data.graphify.pending_enrichment === true`, dispatch the `enriching-graphify-proposals` skill (same protocol as INIT step 6) before declaring SYNC complete. New proposals from the latest extraction must be triaged in the same session that surfaced them.
 
 **arcs-docs sub-agent covers:**
 overview.md, tasks.md, dependencies.md, knowledge.md, plans/ status, knowledge/ accuracy, .diagram.mmd diagram drift (classDef mismatch, phantom nodes), AGENTS.md staleness, sourceFiles existence. Graph recalculation includes `task_blocks_task` edges derived from `dependsOn` fields.

package/opencode/arcs/prompts/arcs-orchestrate.txt

@@ -42,7 +42,7 @@ Discovery: `arcs --commands --json` (cache once per session). Batch op names are
 | List tasks | `arcs task list <slug> --json` |
 | List plans | `arcs plan list <slug> --json` |
 | Search | `arcs search <slug> "<query>" --json` |
-| Diagram ready | `arcs diagram ready <slug> <planId> --json` |
+| Diagram ready | `arcs diagram ready <slug> <planId> --json` — returns `{ready, blocked, inProgress, done}` arrays |
 | Validate | `arcs validate <slug> --json` |
 | Task transition | `arcs task transition <slug> <taskId> <status> --planId=<id> --diagramNodeId=<node> --json` |
 | Batch writes | `arcs batch --file=ops.json --json` |
@@ -200,6 +200,7 @@ Use `recommendedSurface` to pick the routing branch: `QUEUE` → EXECUTE, `PLAN`
 | External research / docs | `docs-researcher` | |
 | 2+ independent problems | parallel fan-out across typed agents | Load `dispatching-parallel-agents` |
 | Multi-step plan with independent leaves | `software-engineer` × N coordinated by orchestrator | Load `subagent-driven-development` |
+| Pending graphify enrichment after init/sync | calling agent (or sub-agent) loads `enriching-graphify-proposals` | When envelope has `pending_enrichment: true` — drives `arcs proposal list/promote/drop` |
 
 **Anti-pattern:** dispatching `software-engineer` for analysis, audit, review, debugging, or research.
 
@@ -218,7 +219,7 @@ flowchart TD
     A -->|executing pre-written plan| EP[executing-plans]
 ```
 
-### Skill Catalogue (14 surviving skills)
+### Skill Catalogue (15 surviving skills)
 
 | Skill | Load when |
 |-------|----------|
@@ -235,6 +236,7 @@ flowchart TD
 | `deep-pr-review` | GitHub PR link with "deep review" trigger |
 | `requesting-code-review` | Self-review gate at phase/feature completion |
 | `caveman-commit` | Writing git commit messages |
+| `enriching-graphify-proposals` | `arcs project init` or `arcs graphify-sync` returned `pending_enrichment: true` |
 
 > **Note:** `confidence-gate` and `verification-before-completion` have been replaced by the `devil-advocate` subagent dispatched at phase checkpoints.
 
@@ -306,11 +308,12 @@ CLI:
 3. Present summary → user confirms → `arcs project init`
 4. `arcs project update-doc × 4`
 5. Fan out (if needed): `system-architect` (architecture entries) + `docs-researcher` (tech-stack, features) + `tech-architect` (couplings, gotchas) → collect proposals → dedup → `arcs knowledge create × N`
+6. **Proposal-gate enrichment:** if `arcs project init`'s envelope returned `data.graphify.pending_enrichment === true`, load the `enriching-graphify-proposals` skill on the calling agent (or dispatch a sub-agent with that skill). The skill reads `arcs proposal list <slug> --json`, decides per-proposal verdicts (keep / merge / drop), and persists results via `arcs proposal promote` and `arcs proposal drop`. Graphify never writes directly to the knowledge surface — promotion is the only path from proposal to knowledge entry.
 
 **Constraints:**
 - Do NOT read repo to infer name/description — gather from user or T0
 - See the `init-project` skill for full category table and worked example
-- Graphify (if on PATH): `arcs project init` auto-runs extraction + seeding. Load `graphify-aware` skill on sub-agents when `graphify-out/graph.json` exists.
+- Graphify (if on PATH): `arcs project init` auto-runs extraction and writes structural proposals to `proposals/graphify.json`. When the envelope returns `pending_enrichment: true`, load `enriching-graphify-proposals` and consume via `arcs proposal list/promote/drop`. The previous direct-write knowledge ingestion has been replaced — graphify never writes directly to the knowledge surface anymore.
 
 ### BRAINSTORM Workflow
 
@@ -343,7 +346,7 @@ CLI:
 - `arcs next` is dependency-aware (topological sort) — it returns the first task whose `dependsOn` are all done. Use it as the primary task selection mechanism.
 - `arcs task transition` atomically updates task status + diagram node. MUST pass both `--planId` and `--diagramNodeId` (both required for diagram patch)
 - Sub-agents NEVER edit `.mmd` files — agents must NOT manually patch `.mmd` for status transitions. Scope changes reported back, orchestrator regenerates via `arcs diagram sort-metadata <slug> <planId> --json`
-- `arcs diagram ready` after each transition to discover newly-unblocked nodes
+- `arcs diagram ready` after each transition to discover newly-unblocked nodes — read `data.ready` (and `data.blocked` to surface what's still gated)
 - If blocked → note blocker, advance to next unblocked task
 
 **Auto-sync triggers** (any one sufficient): 3+ transitions, `lastSyncedAt` > 7 days, plan reached `done`.
@@ -355,6 +358,7 @@ CLI:
 3. Delegate to arcs-docs sub-agent with T0 context + validate output + staleness info
 4. Sub-agent: audit + repair + write checkpoints (`lastSyncedAt`, `lastSyncGitCommit`, `lastSyncStats`) via ARCS CLI
 5. Receive sync report → present to user
+6. **Proposal-gate enrichment:** if SYNC includes `arcs graphify-sync` and that command returned `data.graphify.pending_enrichment === true`, dispatch the `enriching-graphify-proposals` skill (same protocol as INIT step 6) before declaring SYNC complete. New proposals from the latest extraction must be triaged in the same session that surfaced them.
 
 **arcs-docs sub-agent covers:**
 overview.md, tasks.md, dependencies.md, knowledge.md, plans/ status, knowledge/ accuracy, .diagram.mmd diagram drift (classDef mismatch, phantom nodes), AGENTS.md staleness, sourceFiles existence. Graph recalculation includes `task_blocks_task` edges derived from `dependsOn` fields.

package/opencode/arcs/skills/enriching-graphify-proposals/SKILL.md

@@ -0,0 +1,170 @@
+---
+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.
+---
+
+# Skill: enriching-graphify-proposals
+
+## When
+
+The CLI surfaced raw graphify 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.
+
+> **Read-write skill.** This skill mutates the DAG via `arcs proposal promote/drop`. Self-score ≥80% via `confidence-gate` before each promote.
+
+## Flow
+
+```mermaid
+flowchart TD
+    classDef decision fill:#f59e0b,color:#fff
+    classDef terminal fill:#22c55e,color:#fff
+
+    A[arcs proposal list slug --json] --> B{Proposals empty?}
+    B -->|Yes| Done[Done — surface summary]:::terminal
+    B -->|No| C[Pick highest-degree proposal]
+    C --> D[Read structuralFacts + suggestedDedupCandidates]
+    D --> E{Verdict}:::decision
+    E -->|drop| F[arcs proposal drop slug id --reason='...']
+    E -->|keep| G[Author title + summary + body]
+    E -->|merge| H[Identify dedup target id]
+    H --> I[Author append-style body]
+    I --> J[arcs proposal promote slug id --merge-with=target ...]
+    G --> K[arcs proposal promote slug id ...]
+    F --> L{Budget left?}
+    J --> L
+    K --> L
+    L -->|Yes & proposals remain| C
+    L -->|No or empty| Done
+
+    class E decision
+```
+
+## Decision Heuristics
+
+This is the meat of the skill. Apply per proposal — never skip.
+
+### Keep
+
+Promote as a fresh knowledge entry when ALL of:
+
+- The cluster / module covers a real architectural boundary AND existing knowledge does not already cover it (verify via `suggestedDedupCandidates` length 0 or low overlap).
+- `structuralFacts.fileCount >= 3` and `fileTypeBreakdown` is code-dominant (`.ts`, `.tsx`, `.js`, `.py`, etc. — not 100% docs/templates/skills).
+- `topHubs` includes named exports / functions / classes, not just file basenames.
+- The boundary is distinct enough that a future agent editing inside it would benefit from a one-paragraph map.
+
+### Drop
+
+Reject the proposal (use `arcs proposal drop`) when ANY of:
+
+- `structuralFacts.fileTypeBreakdown` has zero code (all `.md`, `.mdx`, `.txt`, `.html` templates, skill files). T007 should already filter these — drop is defense-in-depth.
+- Cluster covers test directories only (`test/`, `__tests__/`, `*.test.ts`, `*.spec.ts`, `tests/`).
+- Cluster size `<= 2` distinct files — too small to be architecturally meaningful.
+- All `topHubs` resolve to deprecated, dead, or vendored code (`vendor/`, `legacy/`, `_archive/`).
+- `suggestedDedupCandidates` shows perfect overlap with an existing knowledge entry AND the proposal contributes no new structural insight (no new degree numbers, no new hubs, no new edges).
+- Proposal is a near-duplicate of one already promoted in this session.
+
+Always pass a `--reason` string. The reason is durable on the proposal-store ledger and helps future SYNC rounds skip the same noise.
+
+### Merge
+
+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.
+
+## Enrichment Output Contract
+
+For every "keep" or "merge" verdict, the agent produces three fields. None may be the templated default from `ingestGraph`.
+
+### `--title` (6–12 words)
+
+Tell a human what this code surface DOES, not just where it lives. Verb- or role-led, specific.
+
+| Bad (templated)             | Good (agent-authored)                                      |
+|-----------------------------|------------------------------------------------------------|
+| "Cluster of 7 entities"     | "Storage hub re-exporting helpers to all persistent stores" |
+| "Module storage-utils"      | "Task / plan / knowledge front-matter parser & guards"     |
+| "Architecture: src/cli"     | "CLI router and command-registry dispatch surface"         |
+
+### `--summary` (1–2 sentences, action-oriented)
+
+State what the boundary is and what ripples when it changes. Prefer concrete consequences over abstract description.
+
+> Example: "Storage hub re-exporting `nowISO` and `sanitizeFileRefs` to all three persistent stores; editing here ripples through every persistent surface and the file-lock contract."
+
+### `--body` (3–5 paragraphs)
+
+Suggested structure — adapt as needed but cover all five beats:
+
+1. **What it is** — one sentence definition of the architectural boundary.
+2. **Top hubs and what they do** — brief expansion of `structuralFacts.topHubs`. Name each hub, name its responsibility in one clause.
+3. **Cross-cutting implications** — what depends on this surface; what this surface depends on. Pull from `structuralFacts.crossModuleEdges` if present.
+4. **When to read this entry** — concrete agent-facing trigger. ("Before editing `storage-utils.ts`. Before adding a new field to any task / plan / knowledge front-matter. Before changing the file-lock policy.")
+5. **Cross-references** — link to related knowledge entries by id (use `suggestedDedupCandidates` and `arcs related` output).
+
+Always pass `--source-files` listing the files in `structuralFacts.fileList` (or the top-N if list is huge — cap at 12 paths). Graph-retrieval `shares_source_file` edges weight 0.9; without `--source-files` the entry is invisible to the graph.
+
+## Cost Discipline
+
+- **Cap at 12 enrichments per session.** If proposals list exceeds 12, drop low-signal entries en masse before enriching the keep set.
+- **Process highest-degree clusters first.** Sort proposals by `structuralFacts.degree` descending; the top 3–5 carry most of the value.
+- **Bulk drop early.** A single triage pass over all proposals — calling `arcs proposal drop` on obvious noise — is cheaper than enriching one and discovering the next is also noise.
+- **Stop early on budget.** If the agent has spent ~12 enrichments, drop the remainder with reason `"session budget exhausted; reconsider next sync"` rather than producing rushed entries.
+
+## Failure Modes
+
+| Symptom                                                   | Recovery                                                                                       |
+|-----------------------------------------------------------|------------------------------------------------------------------------------------------------|
+| `promote --merge-with=<id>` fails: target doesn't exist   | Drop the merge plan; re-run as a fresh `promote` (no `--merge-with`).                          |
+| Body too long for shell argv (errno E2BIG / argv overflow)| Switch to `--body-file=path/to/body.md` or pipe via `--body-stdin`.                            |
+| `proposal_not_found` on promote/drop                      | Another agent already handled it. Skip and continue — proposal-store lock is first-come-first-serve. |
+| Promote succeeds but knowledge graph misses the edge      | Verify `--source-files` was passed and points at real paths under the project root.            |
+| `structuralFacts` field absent                            | Treat as drop candidate — proposal has no evidence to enrich from.                             |
+| Verdict drift: same proposal triaged twice in one session | Re-list with `arcs proposal list --json` — the store is the single source of truth.            |
+
+## Constraints
+
+- **Do not invent structural facts** not present in `structuralFacts`. If real-code grounding is needed, defer to `arcs context <slug> --audience=<role>` or `arcs related <slug> <id>` and read source. Hallucinated graph facts poison every downstream retrieval.
+- **Always specify `--source-files`** on promote — graph-retrieval depends on it (per AGENTS.md "Knowledge gravity"). An entry without source files is a leaf with no inbound edges.
+- **Never edit `.mmd` files** directly — diagram ownership rules in AGENTS.md still apply during enrichment.
+- **No batch promote.** Each promote is one decision, one `arcs proposal promote` call. Bulk-promoting via `arcs batch` bypasses dedup checks and per-proposal review.
+- **Preserve proposal IDs in commit messages / summaries** when reporting back so the human can audit the verdict ledger.
+
+## Worked Example
+
+```bash
+# 1. List pending proposals (highest-degree first by default)
+arcs proposal list arcs --json
+
+# 2. Drop obvious noise in bulk
+arcs proposal drop arcs prop_test_dirs_only \
+  --reason="cluster covers test/ only — defense in depth past T007 filter" --json
+
+# 3. Promote a keep verdict with full enrichment
+arcs proposal promote arcs prop_storage_hub \
+  --title="Storage hub re-exporting helpers to all persistent stores" \
+  --summary="Central re-export point for nowISO and sanitizeFileRefs used by task/plan/knowledge stores; edits ripple through every persistent surface." \
+  --body-file=/tmp/storage-hub.body.md \
+  --kind=architecture \
+  --source-files=src/utils/storage-utils.ts,src/utils/task-store.ts,src/utils/plan-store.ts,src/utils/knowledge-store.ts \
+  --json
+
+# 4. Merge into an existing entry
+arcs proposal promote arcs prop_cli_registry \
+  --merge-with=cli-registry-pattern-handlers-typed-via-parsedparams \
+  --body-file=/tmp/cli-registry-graph-evidence.md \
+  --source-files=src/cli/command-registry.ts,src/cli/index.ts \
+  --json
+
+# 5. Confirm queue drained
+arcs proposal list arcs --json   # expect data.proposals == []
+```
+
+## Exit
+
+When `arcs proposal list <slug> --json` returns an empty `proposals` array, the enrichment pass is done. Surface a one-line summary to the orchestrator: kept N, merged M, dropped K, deferred D.

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

@@ -48,27 +48,29 @@ Discovery: `arcs --commands --json`. Mutating commands run directly — no token
 
 ## Graphify 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. This is the default path when `graphify` is on PATH; skip cleanly otherwise.
+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.
 
-1. **Detect:** call `detectGraphify()` from `src/utils/graphify.ts`. If unavailable, log "graphify not on PATH; proceeding without graph signal" and skip steps 3–5.
+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):
    ```bash
    graphify update <workspacePath> --force --no-cluster
    ```
    Produces `<workspacePath>/graphify-out/graph.json`.
-4. **Ingest:** call internal `ingestGraph(graphJsonPath, slug)` → up to 20 `KnowledgeProposal` records (test files filtered):
+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)
-5. **Enrich** with read-only graph queries (sub-agents may run these):
+
+   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
-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: `arcs batch --file=ops.json` for one batched invocation, or repeated `arcs knowledge create` per entry.
+7. **Hand to typed agents** (in parallel) for code-grounded follow-up entries that go beyond what graphify proposals cover — see **Agent Dispatch** below.
 
 ## Content Guidelines
 
@@ -125,16 +127,21 @@ 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)
+# 4. Graphify (if available) — runs inside `arcs project init`
 graphify update . --force --no-cluster
-# ingestGraph produces proposals; enrich with graphify query/explain
-
-# 5. Fan out typed agents (parallel)
+# ingestGraph writes proposals to proposals/graphify.json
+# init envelope: data.graphify.pending_enrichment === true → load
+# `enriching-graphify-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
+
+# 5. Fan out typed agents (parallel) for entries beyond proposal scope
 #    system-architect → architecture/module entries
 #    docs-researcher  → reference/feature entries
 #    tech-architect   → gotcha/lesson entries
 
-# 6. Write knowledge entries directly
+# 6. Write any non-proposal-derived knowledge entries directly
 arcs knowledge create foo "Tech stack: TypeScript + Node 20" --kind=architecture --summary="..." --body="..." --json
 # ... repeat per entry, or use arcs batch
 ```

package/opencode/arcs/skills/to-diagram/SKILL.md

@@ -163,7 +163,7 @@ Between plan-level header and `flowchart TD` declaration:
 | `sort-metadata <file>` | Order metadata blocks by node ID |
 | `regenerate <file> --metadata f.json` | Full regeneration from canonical data |
 
-Preferred: `arcs diagram ready <slug> <planId>` for ready detection. Script is fallback for file-level ops.
+Preferred: `arcs diagram ready <slug> <planId>` for ready detection. The CLI returns `{ok, data: {ready, blocked, inProgress, done}}` — four disjoint arrays of node IDs that together cover every node in the diagram. The bundled `manage-diagram.mjs ready` script remains the file-level fallback (emits a bare list of ready IDs only).
 
 ## File Convention
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rryando/arcs",
-  "version": "3.1.2",
+  "version": "3.2.1",
   "description": "ARCS — DAG-based task orchestration for AI agents. Persistent workflow continuity via graph-structured context.",
   "type": "module",
   "main": "dist/index.js",