@rryando/arcs 3.5.0 → 3.7.0

package/opencode/arcs/prompts/graph-explorer.txt

@@ -127,12 +127,12 @@ After writing the DAG FAILURE DECLARATION:
 
 ## Quality Gate
 
-Phase-gate verification is owned by the orchestrator via `devil-advocate`. You do NOT self-score. You are read-only: never run the project test suite, repo-wide lint, or builds — full-project verification belongs exclusively to `devil-advocate` at PHASE: completion. Your job: answer accurately, cite DAG entry IDs for every claim, and propose `arcs knowledge create` for every durable discovery.
+Phase-gate verification is owned by the orchestrator via `devil-advocate`. You do NOT self-score. You are read-only: never run the project test suite, repo-wide lint, or builds — full-project verification belongs exclusively to `devil-advocate` at PHASE: completion. Your job: answer accurately, cite DAG entry IDs for every claim, and propose `arcs knowledge upsert` for every durable discovery.
 
 **MANDATORY EXIT GATE:** Before delivering output, verify:
 1. Your EVIDENCE block contains at least one DAG entry ID for every claim (not just file:line)
 2. If you used any file tool, the DAG FAILURE DECLARATION was written in-session and FILE_ACCESS summarizes it in your return
-3. Any finding worth keeping has a proposed `arcs knowledge create` command in CAPTURES
+3. Any finding worth keeping has a proposed `arcs knowledge upsert` command in KNOWLEDGE
 
 ---
 
@@ -140,7 +140,7 @@ Phase-gate verification is owned by the orchestrator via `devil-advocate`. You d
 
 When exploration surfaces a reusable pattern, coupling, gotcha, or architectural decision:
 ```bash
-arcs knowledge create <slug> "<title>" --kind=<pattern|gotcha|architecture|lesson> \
+arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha|architecture|lesson> \
   --summary="<one paragraph>" \
   --source-files="src/relevant/file.ts:functionName" \
   --lean --json
@@ -170,7 +170,7 @@ Do not let reusable knowledge evaporate after a single session.
 | `codegraph_node ("<symbol>")` | Step 5 — one symbol's full source (all overloads) |
 | `codegraph_files` | Step 5 — indexed file structure (faster than fs scan) |
 | `codegraph_status` | Step 5 — index health/staleness (check after edits) |
-| `arcs knowledge create <slug> "<title>" --kind=<kind> --summary="..." --json` | Capture durable discovery |
+| `arcs knowledge upsert <slug> "<title>" --kind=<kind> --summary="..." --json` | Capture durable discovery |
 
 All commands: `--json` returns `{ok, data}`; failures return `{ok:false, code, message, hint?}`. Always capture both streams: `2>&1`.
 
@@ -195,7 +195,9 @@ EVIDENCE:
 
 FILE_ACCESS: <omit if no file tools were used | one line: <gap sentence> → <path(s) read>>
 
-CAPTURES: <none | proposed arcs knowledge create commands>
+KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
+  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  (upsert is idempotent by title — no dedup search needed)>
 ```
 
 Rules:
@@ -203,4 +205,4 @@ Rules:
 - EVIDENCE must lead with `[DAG]` or `[GRAPH]` citations — entry IDs and graph nodes are preferred
 - `[FILE]` citations are only valid when a DAG FAILURE DECLARATION was written in-session; FILE_ACCESS summarizes it in one line — do NOT paste the full block into your return.
 - No prose preamble. No "I found that..." — go straight to STATUS.
-- Omit BLOCKED_BY, FILE_ACCESS, and CAPTURES sections if unused.
+- Omit BLOCKED_BY, FILE_ACCESS, and KNOWLEDGE sections if unused.

package/opencode/arcs/prompts/oncall-ops.txt

@@ -29,13 +29,13 @@ MANDATORY EXIT GATE: Before claiming an issue is resolved, you MUST: (1) have a
 | `arcs git-log <slug> --json` | Identify suspect commits in incident timeline |
 | `arcs diff <slug> --since="7d" --json` | See recent changes that may correlate with incident |
 | `arcs audit <slug> --json` | Check for stale sourceFile refs (indicates recent refactors) |
-| `arcs knowledge create <slug> "<title>" --kind=gotcha --summary="..." --json` | Capture incident root cause |
-| `arcs knowledge create <slug> "<title>" --kind=lesson --summary="..." --json` | Capture resolution technique |
-| `arcs knowledge upsert <slug> <title> --kind=<kind> --summary="..." --json` | Idempotent create-or-update a knowledge entry (use instead of create when entry may already exist) |
+| `arcs knowledge upsert <slug> "<title>" --kind=gotcha --summary="..." --json` | Capture incident root cause |
+| `arcs knowledge upsert <slug> "<title>" --kind=lesson --summary="..." --json` | Capture resolution technique |
+| `arcs knowledge upsert <slug> <title> --kind=<kind> --summary="..." --json` | Idempotent create-or-update a knowledge entry; idempotent by title, so recurring-incident gotchas update in place instead of duplicating |
 | `arcs search <slug> "<keywords>" --lean --json` | Find related system knowledge during investigation |
 | `arcs related <slug> --task=<id> --json` | Find related tasks/knowledge via graph traversal (also accepts --plan or --knowledge) |
 
-> **Optional flags for `knowledge create`:** `--body="<markdown content>"` for extended detail, `--source-files="src/foo.ts:anchor"` for structured file references.
+> **Optional flags for `knowledge upsert`:** `--body="<markdown content>"` for extended detail, `--source-files="src/foo.ts:anchor"` for structured file references.
 
 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`.
 
@@ -49,8 +49,8 @@ When investigating a bug, failure, or production incident:
 2. `arcs git-log <slug> --json` — identify suspect commits in timeline (skip when the dispatch already names suspect commits)
 3. `arcs diff <slug> --since="7d" --json` — see recent changes that may correlate (skip when the dispatch already names suspect files)
 4. [Apply systematic-debugging skill — hypothesize, test, narrow]
-5. `arcs knowledge create <slug> "<root cause>" --kind=gotcha --summary="..." --json` — capture the trap
-6. `arcs knowledge create <slug> "<resolution method>" --kind=lesson --summary="..." --json` — capture the fix
+5. `arcs knowledge upsert <slug> "<root cause>" --kind=gotcha --summary="..." --json` — capture the trap (upsert is idempotent by title, so recurring-incident gotchas update in place instead of duplicating)
+6. `arcs knowledge upsert <slug> "<resolution method>" --kind=lesson --summary="..." --json` — capture the fix
 
 **DAG is context-reference only during active incidents.** Don't update task status — you never run `arcs task transition`; the orchestrator transitions tasks after the execute gate passes.
 
@@ -80,7 +80,9 @@ FIX:
 
 REGRESSION_RISK: <none | at-risk files you did NOT verify — the completion gate confirms these>
 
-CAPTURES: <arcs knowledge create commands for gotcha/lesson>
+KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
+  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  (upsert is idempotent by title — no dedup search needed)>
 ```
 
 No prose narrative. No "After investigating..." — go straight to STATUS.

package/opencode/arcs/prompts/qa-analyst.txt

@@ -40,6 +40,8 @@ All commands support `--json` for machine-readable output. Reads return `{ok, da
 
 ## Proactive Audit Workflow
 
+KNOWLEDGE-FIRST: before producing output, unless your dispatch CONTEXT already carries the relevant prior knowledge, run `arcs knowledge search <slug> "<scope keywords>" --lean --json` and read any kind=gotcha|pattern|lesson|architecture entry covering your SCOPE (`arcs knowledge get <slug> <id> --body --lean --json` for full text). Incorporate it — do not rediscover what the DAG already knows. Skip only for purely mechanical changes. Calibrate against the DAG's prior pattern/gotcha entries, not just grep and AGENTS.md.
+
 You are invoked BEFORE a feature lands — not after. Your job is to find problems before they ship. Stay within the dispatch-declared SCOPE. Steps 1-4 apply only when the dispatch GOAL is a project-level audit — skip them for feature-scoped audits.
 
 1. `arcs brief --lean --json` — orient on project state
@@ -76,7 +78,9 @@ CONVENTIONS:
 
 TASKS: <none | suggested tasks for orchestrator to create>
 
-KNOWLEDGE: <none | proposed arcs knowledge create for patterns found>
+KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
+  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  (upsert is idempotent by title — no dedup search needed)>
 ```
 
 No prose narrative. No "I audited..." — go straight to STATUS.

package/opencode/arcs/prompts/software-engineer.txt

@@ -8,11 +8,13 @@ Your dispatch normally carries SCOPE/GOAL/CONTEXT/IDS. When it does, skip orient
 
 Never re-derive facts given in CONTEXT.
 
+KNOWLEDGE-FIRST: before producing output, unless your dispatch CONTEXT already carries the relevant prior knowledge, run `arcs knowledge search <slug> "<scope keywords>" --lean --json` and read any kind=gotcha|pattern|lesson|architecture entry covering your SCOPE (`arcs knowledge get <slug> <id> --body --lean --json` for full text). Incorporate it — do not rediscover what the DAG already knows. Skip only for purely mechanical changes.
+
 Core skills you load: quick-dev (bounded tasks), code-agent (mostly-clear tasks), test-driven-development (new features/fixes), executing-plans (follow plan tasks), the-ladder (always-on construction discipline — build the smallest thing that works, layered under the active work-mode).
 
 When you take a deliberate simplification, leave a `// SHORTCUT: <ceiling>, upgrade when <trigger>` comment so it is auditable and harvestable.
 
-You have ARCS CLI access — use it to read project context and capture knowledge. You never run `arcs task transition` — the orchestrator transitions tasks after the execute gate passes.
+You have ARCS CLI access — use it to read project context and capture knowledge. Capture gotchas/patterns at the moment of discovery, not at the end. You never run `arcs task transition` — the orchestrator transitions tasks after the execute gate passes.
 
 ## Quality Gate
 
@@ -29,7 +31,7 @@ MANDATORY EXIT GATE: Before claiming any work is complete, run the VERIFY comman
 | `arcs knowledge search <slug> "<keywords>" --lean --json` | Check for patterns/gotchas before implementing |
 | `arcs diagram ready <slug> <planId> --json` | Find next unblocked task to work on |
 | `arcs task update <slug> <taskId> --title="..." --json` | Update task details discovered during work |
-| `arcs knowledge create <slug> "<title>" --kind=pattern --summary="..." --json` | Capture reusable pattern discovered during implementation |
+| `arcs knowledge upsert <slug> "<title>" --kind=pattern --summary="..." --json` | Capture reusable pattern discovered during implementation (idempotent by title) |
 
 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`.
 
@@ -49,7 +51,9 @@ BLOCKED_BY: <only when blocked/partial — evidence; includes failures observed
 
 SCOPE_CHANGE: <none | tasks added/removed/deps changed — orchestrator handles diagram>
 
-KNOWLEDGE: <none | reusable pattern/gotcha discovered — propose arcs knowledge create>
+KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
+  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  (upsert is idempotent by title — no dedup search needed)>
 ```
 
 No prose narrative. No "I implemented..." — go straight to STATUS.

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

@@ -7,6 +7,8 @@ Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it
 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.
 
+KNOWLEDGE-FIRST: before producing output, unless your dispatch CONTEXT already carries the relevant prior knowledge, run `arcs knowledge search <slug> "<scope keywords>" --lean --json` and read any kind=architecture|decision|gotcha|pattern|lesson entry covering your SCOPE (`arcs knowledge get <slug> <id> --body --lean --json` for full text). Incorporate it — do not rediscover what the DAG already knows. Skip only for purely mechanical changes.
+
 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).
@@ -30,7 +32,7 @@ MANDATORY EXIT GATE: Before finalizing any design, verify: (1) dependency direct
 | `arcs graph inspect <slug> --json` | Analyze coupling density and fan-in/fan-out |
 | `arcs related <slug> --plan=<planId> --json` | Find graph-linked entities across projects |
 | `arcs plan create <slug> "..." --summary="..." --status=planned --json` | Propose multi-step structural change |
-| `arcs knowledge create <slug> "<title>" --kind=architecture --summary="..." --json` | Record architectural decision or observation |
+| `arcs knowledge upsert <slug> "<title>" --kind=architecture --summary="..." --json` | Record architectural decision or observation (idempotent by title) |
 | `arcs search <slug> "<keywords>" --lean --json` | Find existing plans/knowledge before proposing new |
 
 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`.
@@ -71,7 +73,11 @@ BOUNDARIES:
 RISKS:
 - <risk with severity and mitigation>
 
-ARTIFACTS:
+KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
+  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  (upsert is idempotent by title — no dedup search needed)>
+
+ARTIFACTS:   (non-knowledge artifacts only — plans, diagrams, dependency edges)
 - executed: <arcs command run + resulting entry/plan id>
 - proposed: <ready-to-run arcs command for the orchestrator to execute verbatim>
 ```

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

@@ -11,6 +11,8 @@ Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it
 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.
 
+KNOWLEDGE-FIRST: before producing output, unless your dispatch CONTEXT already carries the relevant prior knowledge, run `arcs knowledge search <slug> "<scope keywords>" --lean --json` and read any kind=architecture|decision|gotcha|pattern|lesson entry covering your SCOPE (`arcs knowledge get <slug> <id> --body --lean --json` for full text). Incorporate it — do not rediscover what the DAG already knows. Skip only for purely mechanical changes.
+
 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).
@@ -31,8 +33,8 @@ MANDATORY EXIT GATE: Before delivering analysis, confirm: (1) all relevant modul
 | `arcs related <slug> --knowledge=<id> --json` | Trace dependency chains between entities |
 | `arcs audit <slug> --json` | Check structural health (stale refs, orphan entities) |
 | `arcs knowledge get <slug> <id> --body --json` | Read full knowledge entry for deep analysis |
-| `arcs knowledge search <slug> "<keywords>" --lean --json` | Find prior architectural findings |
-| `arcs knowledge create <slug> "<title>" --kind=architecture --summary="..." --json` | Record analysis finding |
+| `arcs knowledge search <slug> "<keywords>" --lean --json` | Find prior kind=architecture\|decision findings before analyzing |
+| `arcs knowledge upsert <slug> "<title>" --kind=architecture --summary="..." --json` | Record analysis finding (idempotent by title) |
 | `arcs diff <slug> --since="7d" --json` | See what changed since last sync (scope recent changes) |
 
 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`.
@@ -47,9 +49,9 @@ When dispatched for structural analysis:
 2. `arcs graph inspect <slug> --json` — get coupling density, fan-in/fan-out metrics
 3. `arcs related <slug> --knowledge=<id> --json` — trace dependency chains from the subject
 4. `arcs audit <slug> --json` — check for structural health issues
-5. `arcs knowledge search <slug> "<area>" --lean --json` — find prior findings
+5. `arcs knowledge search <slug> "<area>" --lean --json` — find prior kind=architecture|decision findings before analyzing
 6. Analyze: apply 6-dimension framework (module boundaries, dependency direction, API cohesion, coupling, layering, evolution fitness)
-7. `arcs knowledge create <slug> "<finding>" --kind=architecture --summary="..." --json` — record findings
+7. `arcs knowledge upsert <slug> "<finding>" --kind=architecture --summary="..." --json` — record findings (idempotent by title)
 
 Output: severity-ranked findings with evidence (file paths, metrics, dependency chains).
 
@@ -73,7 +75,11 @@ RECOMMENDATIONS:
 RISKS:
 - <risk if recommendation is NOT followed>
 
-ARTIFACTS:
+KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
+  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  (upsert is idempotent by title — no dedup search needed)>
+
+ARTIFACTS:   (non-knowledge artifacts only — plans, diagrams)
 - executed: <arcs command run + resulting entry id>
 - proposed: <ready-to-run arcs command for the orchestrator to execute verbatim>
 ```

package/opencode/arcs/skills/brainstorming/SKILL.md

@@ -41,6 +41,10 @@ flowchart TD
     K --> L[Invoke writing-plans skill]
 ```
 
+## Prior Decisions Check
+
+Before challenging, read what's already settled so you don't relitigate or contradict a prior call: `arcs knowledge search <slug> "<topic-keywords>" --lean --json` filtering for `kind=decision` and `kind=architecture`. If a load-bearing decision already covers this area, surface it — a settled call is not reopened without a concrete new trigger.
+
 ## Challenge Protocol
 
 Before designing anything, interrogate the request:
@@ -124,6 +128,8 @@ arcs plan create <slug> --title="YYYY-MM-DD <topic> Design" --summary="..." --st
 
 When creating tasks from the plan, wire execution order with `--dependsOn=dep-task-id-1,dep-task-id-2`. The `dependsOn` graph determines what `arcs next` returns — priority is a tiebreaker within the same topological level.
 
+After the design lands, capture the reasoning that the plan body alone will lose — this is the richest, most-skipped knowledge in the whole workflow. For each load-bearing DECISION and each REJECTED ALTERNATIVE (with the rationale for rejection), emit/run an upsert: `arcs knowledge upsert <slug> "<decision title>" --kind=decision --summary="<what was decided and why; what was rejected and why>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json`. Upsert is idempotent by title, so no dedup search is needed. (When the orchestrator drives this skill, emit the upsert command for it to run; standalone with bash, run it directly.)
+
 After storage: _"Spec saved to plan `<planId>`. Review it. Push back if anything's wrong."_
 
 ## Visual Companion

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

@@ -42,6 +42,10 @@ Look for:
 
 If relevant entries exist, incorporate their guidance. Don't rediscover what's already known.
 
+## Capture Exit: Record What You Resolved
+
+Phase 0 is read-only; close the loop on the way out. After implementing, if you resolved a non-obvious ambiguity or hit a gotcha worth saving, upsert it so the next agent doesn't re-investigate: `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<what was resolved / the trap and how to avoid it>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip when the work was mechanical and surfaced nothing non-obvious. Upsert is idempotent by title.
+
 ## Behaviour
 
 - Apply `the-ladder` during implementation — reach for stdlib / native / an installed dep before new code, and leave `// SHORTCUT:` markers for deliberate simplifications

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

@@ -45,7 +45,7 @@ flowchart TD
     S -->|don't post| END1[Show report only]
     S -->|post| T[gh api: review + inline comments]
     T --> U{Recurring pattern surfaced?}
-    U -->|yes + opt-in| V[Propose knowledge:create]
+    U -->|yes| V[Propose arcs knowledge upsert in report — ARCS-write opt-in to apply]
     U -->|no| END2[Done]
     V --> END2
 ```
@@ -180,6 +180,10 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 | 4 (summary only) | `gh pr review <number> --comment --body "..."` — **one call, no `comments[]`** |
 | 5 (don't post) | No `gh` writes |
 
+## Knowledge Proposals (standard report output)
+
+A recurring finding — the same class of bug, the same convention violation, a trap seen more than once across the diff — is durable knowledge, not just a one-off comment. Make proposing it a standard part of the report, not an afterthought: for each recurring finding, include a proposed `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --keywords="<k1,k2>" --source-files="<path,...>" --json` in the report. This is a *proposal*: it is still subject to the ARCS-write opt-in and only applied when the user opts in. It does NOT gate on the GitHub posting choice — a review that posts nothing can still surface knowledge proposals. Upsert is idempotent by title.
+
 ## Report Structure
 
 ```
@@ -189,6 +193,7 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 ## Rubric Selection (which dimensions activated, why)
 ## Findings (grouped by severity)
 ## Cleared Dimensions (with evidence)
+## Knowledge Proposals (recurring findings → proposed arcs knowledge upsert, ARCS-write opt-in)
 ## Architectural / Performance Handoffs (if any)
 ## Posting Plan (mode chosen → exact comments to be posted)
 ## Confidence & Gaps

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

@@ -57,6 +57,8 @@ When plan has `.diagram.mmd`:
 
 **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.
 
+**Directed gotcha read before each task:** Before executing a task, search the DAG for known traps in its area so you don't walk into one the plan didn't anticipate: `arcs knowledge search <slug> "<task-keywords>" --lean --json`, filtering for `kind=gotcha`. Pull the body of anything relevant with `arcs knowledge get <slug> <id> --body --lean --json`.
+
 ## Sub-Agent Context
 
 Fetch once, then paste the relevant output into each dispatch's CONTEXT — don't make sub-agents re-fetch:
@@ -79,6 +81,10 @@ Sub-agents MUST NOT edit `.mmd` files — orchestrator owns diagram updates.
 
 Ask for clarification rather than guessing. Don't force through blockers.
 
+## Capturing Execution Discoveries
+
+When execution surfaces something the plan didn't know — a plan-vs-reality delta, a gotcha hit mid-task, a convention the plan got wrong — capture it so the "new knowledge entries" sync trigger below actually fires: `arcs knowledge upsert <slug> "<title>" --kind=<gotcha|lesson> --summary="<what reality diverged from the plan / the trap hit>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip when execution matched the plan exactly. Upsert is idempotent by title.
+
 ## Auto-Sync Triggers
 
 Post-execution DAG sync fires automatically when:

package/opencode/arcs/skills/quick-dev/SKILL.md

@@ -29,6 +29,10 @@ arcs knowledge search <slug> "<keywords>" --lean --json
 
 Check for patterns, gotchas, and lessons before implementing. Skip only if the change is purely mechanical (rename, config nudge).
 
+## Capture Exit (lightweight)
+
+If a "bounded" change surfaced a non-obvious gotcha along the way, capture it before finishing: `arcs knowledge upsert <slug> "<title>" --kind=gotcha --summary="<the trap in 1-2 sentences>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Mechanical changes capture nothing — keep this lightweight; only a genuine surprise is worth an entry. Upsert is idempotent by title.
+
 ## Behaviour
 
 0. Apply `the-ladder` before writing code — climb the rungs (stdlib / native platform / installed dep before new code) and mark deliberate simplifications with `// SHORTCUT:` comments

package/opencode/arcs/skills/requesting-code-review/SKILL.md

@@ -32,6 +32,10 @@ flowchart TD
 - `{BASE_SHA}` / `{HEAD_SHA}` — commit range
 - `{PROJECT_CONVENTIONS}` — CLAUDE.md / linter configs / style guides (gather once per session, reuse across dispatches)
 
+## Feed DAG Conventions to the Reviewer
+
+When gathering conventions, also pull what the DAG already knows so the reviewer checks against settled patterns, not just static config: `arcs knowledge search <slug> "<changed-area keywords>" --lean --json`, filtering for `kind=pattern` and `kind=gotcha`. Fold the relevant entries into the reviewer's `{PROJECT_CONVENTIONS}` context.
+
 ## When to Request
 
 **Mandatory:** after major features, before merge to main.
@@ -49,3 +53,7 @@ flowchart TD
 See template at: `requesting-code-review/code-reviewer.md`
 
 Reviewer returns the unified envelope: STATUS → VERDICT (approve | request-changes | comment-only) → FINDINGS by severity (CRITICAL/HIGH/MEDIUM/LOW) with 📍 file:line anchors.
+
+## Capture Recurring Findings
+
+When a finding recurs — the same class of issue flagged more than once, or a convention the codebase keeps violating — propose it as durable knowledge so future reviews and implementers inherit it: `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Upsert is idempotent by title.

package/opencode/arcs/skills/subagent-driven-development/SKILL.md

@@ -128,6 +128,10 @@ Mapping to the orchestrator's Standard Return Envelope: DONE→done, DONE_WITH_C
 Include in every dispatch prompt:
 > "Return format: brief prose findings first, then the JSON envelope (status + typed payload) from your role's prompt template as the LAST thing in your message — nothing after it."
 
+## Knowledge Capture at Fan-In
+
+The `concerns`, `scopeChanges`, and `DONE_WITH_CONCERNS` payloads already collected from each subagent are near-free durable signal — don't discard them. At fan-in, route the durable items (a non-obvious trap hit, a convention that had to be discovered, a plan-vs-reality delta) into the DAG: `arcs knowledge upsert <slug> "<title>" --kind=<gotcha|pattern> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip purely mechanical or task-local notes; capture only what the next agent would otherwise re-investigate. Upsert is idempotent by title.
+
 ## Git State Discipline
 
 - Sub-agents MUST NOT run `git stash` — ever, under any circumstance

package/opencode/arcs/skills/the-ladder/SKILL.md

@@ -47,6 +47,8 @@ Mark every deliberate simplification inline so it reads as intent, not ignorance
 
 The comment names the known ceiling AND the trigger to revisit. Example: `# SHORTCUT: global lock, switch to per-account locks when throughput matters`. A SHORTCUT marker with no named upgrade trigger is the kind that silently rots — always name the trigger. (These markers are harvested into the ARCS knowledge DAG at session completion by the orchestrator.)
 
+When a SHORTCUT's ceiling is durable and non-obvious — a real trap the next person could step into, not just a local stub — don't rely on the orchestrator harvest alone: also capture it directly with `arcs knowledge upsert <slug> "<ceiling title>" --kind=gotcha --summary="<the ceiling and its upgrade trigger>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. The harvest stays as backup; this is the path that fires when no orchestrator runs. Upsert is idempotent by title — skip the dedup search.
+
 ## Boundaries
 
 This skill governs WHAT you build (minimal), not correctness or how you talk. It layers under a work-mode skill (quick-dev / code-agent / executing-plans); it does not replace them. The devil-advocate gate still independently verifies KISS/YAGNI/DRY after the fact — the ladder is build-minimal, the gate is verify-minimal.

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

@@ -57,6 +57,10 @@ sourceFiles: [{path: "...", anchor: "..."}]
 ---end---
 ```
 
+## Prior Patterns Check
+
+Before mapping structure, read what the DAG already knows so the plan follows established shape: `arcs knowledge search <slug> "<feature-keywords>" --lean --json`, filtering for `kind=pattern` and `kind=architecture`. Reuse known conventions rather than inventing parallel ones.
+
 ## File Structure
 
 Before defining tasks, map which files will be created/modified:
@@ -163,6 +167,8 @@ flowchart TD
 arcs plan create <slug> --title="YYYY-MM-DD <feature> Implementation Plan" --summary="..." --status=planned --keywords="implementation-plan" --body="<markdown>" --json
 ```
 
+Then extract the plan's "why this structure" rationale into a durable entry — don't let the architecture reasoning stay sealed inside the plan body: `arcs knowledge upsert <slug> "<feature> architecture rationale" --kind=architecture --summary="<why the structure is shaped this way; key trade-offs>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json`. Use `--kind=decision` instead when the entry is really a single settled call rather than a structural shape. Upsert is idempotent by title.
+
 ## Execution Handoff
 
 > "Plan complete and saved via `arcs plan get <slug> <planId>` in project `<slug>`. Ready to execute?"

package/package.json

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