@rryando/arcs 3.2.0 → 3.2.1

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.2.0",
+  "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",