@rryando/arcs 3.10.0 → 3.11.0

package/opencode/arcs/manifest.json

@@ -8,21 +8,197 @@
     "destination": "skills/arcs"
   },
   "agents": [
-    { "source": "prompts/software-engineer.txt", "destination": "prompts/software-engineer.txt" },
-    { "source": "prompts/tech-architect.txt", "destination": "prompts/tech-architect.txt" },
-    { "source": "prompts/oncall-ops.txt", "destination": "prompts/oncall-ops.txt" },
-    { "source": "prompts/arcs-docs.txt", "destination": "prompts/arcs-docs.txt" },
-    { "source": "prompts/code-reviewer.txt", "destination": "prompts/code-reviewer.txt" },
-    { "source": "prompts/docs-researcher.txt", "destination": "prompts/docs-researcher.txt" },
-    { "source": "prompts/devil-advocate.txt", "destination": "prompts/devil-advocate.txt" },
-    { "source": "prompts/graph-explorer.txt", "destination": "prompts/graph-explorer.txt" },
-    { "source": "prompts/arcs-orchestrate.txt", "destination": "prompts/arcs-orchestrate.txt" },
-    { "source": "prompts/arcs-orchestrate-caveman.txt", "destination": "prompts/arcs-orchestrate-caveman.txt" }
-  ],
-  "ownedPaths": [
-    "skills/arcs",
-    "plugins/arcs.js"
+    {
+      "id": "software-engineer",
+      "status": "active",
+      "kind": "subagent",
+      "tier": "heavy",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/software-engineer.txt",
+      "destination": "prompts/software-engineer.txt",
+      "description": "Implementation specialist. Writes code, runs tests, and ships verified work using orchestrator-selected implementation bounded or inspect mode.",
+      "permissions": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "tech-architect",
+      "status": "active",
+      "kind": "subagent",
+      "tier": "standard",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/tech-architect.txt",
+      "destination": "prompts/tech-architect.txt",
+      "description": "Architecture, analysis, and cited research specialist. Produces read-only structural guidance, trade-off evaluation, and DAG-first research synthesis.",
+      "permissions": {
+        "edit": "deny",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "oncall-ops",
+      "status": "retired",
+      "replacementId": "software-engineer",
+      "kind": "subagent",
+      "tier": "heavy",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/oncall-ops.txt",
+      "destination": "prompts/oncall-ops.txt",
+      "description": "Debugging and diagnosis specialist. Finds root causes through systematic investigation, log triage, bisect, and performance profiling.",
+      "permissions": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "arcs-docs",
+      "status": "active",
+      "kind": "subagent",
+      "tier": "heavy",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/arcs-docs.txt",
+      "destination": "prompts/arcs-docs.txt",
+      "description": "ARCS documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health. Knows ARCS structure intimately.",
+      "permissions": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "code-reviewer",
+      "status": "active",
+      "kind": "subagent",
+      "tier": "light",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/code-reviewer.txt",
+      "destination": "prompts/code-reviewer.txt",
+      "description": "Reviews code changes for production readiness and catches correctness, maintainability, and testing issues.",
+      "permissions": {
+        "edit": "deny",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "docs-researcher",
+      "status": "retired",
+      "replacementId": "tech-architect",
+      "kind": "subagent",
+      "tier": "heavy",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/docs-researcher.txt",
+      "destination": "prompts/docs-researcher.txt",
+      "description": "Handles documentation writing, research synthesis, OCR-adjacent extraction, and document-heavy analysis tasks.",
+      "permissions": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "devil-advocate",
+      "status": "active",
+      "kind": "subagent",
+      "tier": "standard",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/devil-advocate.txt",
+      "destination": "prompts/devil-advocate.txt",
+      "description": "Adversarial phase-gate agent. Checks work at phase boundaries using KISS/YAGNI/DRY principles. Runs tests, reads diffs, delivers pass/block verdicts. Cannot edit code.",
+      "permissions": {
+        "edit": "deny",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "graph-explorer",
+      "status": "active",
+      "kind": "subagent",
+      "tier": "light",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/graph-explorer.txt",
+      "destination": "prompts/graph-explorer.txt",
+      "description": "DAG-first codebase and knowledge exploration specialist. Queries arcs search, related, and context first, then codegraph MCP code-intelligence tools, before falling back to raw file-system tools. Replaces vanilla explore for ARCS projects.",
+      "permissions": {
+        "edit": "deny",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "deny"
+      }
+    },
+    {
+      "id": "arcs-orchestrate",
+      "status": "active",
+      "kind": "primary",
+      "tier": "standard",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/arcs-orchestrate.txt",
+      "destination": "prompts/arcs-orchestrate.txt",
+      "description": "The central coordinator for executing plans, managing agent dispatch, and handling DAG workflows.",
+      "permissions": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "allow"
+      }
+    },
+    {
+      "id": "arcs-orchestrate-caveman",
+      "status": "active",
+      "kind": "primary",
+      "tier": "standard",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/arcs-orchestrate-caveman.txt",
+      "destination": "prompts/arcs-orchestrate-caveman.txt",
+      "description": "A terse, high-efficiency orchestrator that drives tasks without extra commentary.",
+      "permissions": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "allow"
+      }
+    },
+    {
+      "id": "arcs-flash",
+      "status": "active",
+      "kind": "primary",
+      "tier": "standard",
+      "modes": ["opencode", "claudecode"],
+      "source": "prompts/arcs-flash.txt",
+      "destination": "prompts/arcs-flash.txt",
+      "description": "A speed-optimized orchestrator that sources context from arcs knowledge first and maximizes parallel sub-agent dispatch under tiered gates.",
+      "permissions": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "mcp": "allow",
+        "task": "allow"
+      }
+    }
   ],
+  "ownedPaths": ["skills/arcs", "plugins/arcs.js"],
   "plugin": {
     "required": true,
     "source": ".opencode/plugins/arcs.js",
@@ -31,9 +207,7 @@
   "config": {
     "requiredMerges": [
       {
-        "path": [
-          "permission"
-        ],
+        "path": ["permission"],
         "value": {
           "external_directory": {
             "/tmp": "allow",
@@ -47,78 +221,47 @@
         "mode": "merge"
       },
       {
-        "path": [
-          "lsp"
-        ],
+        "path": ["lsp"],
         "value": true,
         "mode": "if-absent"
       },
       {
-        "path": [
-          "model"
-        ],
+        "path": ["model"],
         "value": "github-copilot/claude-sonnet-4.6",
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "build",
-          "model"
-        ],
+        "path": ["agent", "build", "model"],
         "value": "github-copilot/claude-sonnet-4.6",
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "build",
-          "temperature"
-        ],
+        "path": ["agent", "build", "temperature"],
         "value": 0,
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "plan",
-          "model"
-        ],
+        "path": ["agent", "plan", "model"],
         "value": "github-copilot/claude-opus-4.6",
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "plan",
-          "temperature"
-        ],
+        "path": ["agent", "plan", "temperature"],
         "value": 0.5,
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "general",
-          "model"
-        ],
+        "path": ["agent", "general", "model"],
         "value": "github-copilot/claude-opus-4.6",
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "general",
-          "temperature"
-        ],
+        "path": ["agent", "general", "temperature"],
         "value": 0.3,
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "graph-explorer"
-        ],
+        "path": ["agent", "graph-explorer"],
         "value": {
           "description": "DAG-first codebase and knowledge exploration specialist. Queries arcs search, related, and context first, then codegraph MCP code-intelligence tools, before falling back to raw file-system tools. Replaces vanilla explore for ARCS projects.",
           "mode": "subagent",
@@ -136,10 +279,7 @@
         "mode": "merge"
       },
       {
-        "path": [
-          "agent",
-          "code-reviewer"
-        ],
+        "path": ["agent", "code-reviewer"],
         "value": {
           "description": "Reviews code changes for production readiness and catches correctness, maintainability, and testing issues.",
           "mode": "subagent",
@@ -157,35 +297,11 @@
         "mode": "merge"
       },
       {
-        "path": [
-          "agent",
-          "docs-researcher"
-        ],
-        "value": {
-          "description": "Handles documentation writing, research synthesis, OCR-adjacent extraction, and document-heavy analysis tasks.",
-          "mode": "subagent",
-          "model": "github-copilot/claude-opus-4.6",
-          "temperature": 0.4,
-          "permission": {
-            "edit": "allow",
-            "bash": "allow",
-            "webfetch": "allow",
-            "mcp": "allow",
-            "external_directory": { "*": "allow" }
-          },
-          "prompt": "{file:./prompts/docs-researcher.txt}"
-        },
-        "mode": "merge"
-      },
-      {
-        "path": [
-          "agent",
-          "tech-architect"
-        ],
+        "path": ["agent", "tech-architect"],
         "value": {
-          "description": "Architecture and analysis specialist. Deep structural reasoning, refactor guidance, trade-off evaluation, and root cause analysis without making hasty edits.",
+          "description": "Architecture, analysis, and cited research specialist. Produces read-only structural guidance, trade-off evaluation, and DAG-first research synthesis.",
           "mode": "subagent",
-          "model": "github-copilot/claude-haiku-4.5",
+          "model": "github-copilot/claude-sonnet-4.6",
           "temperature": 0.4,
           "permission": {
             "edit": "deny",
@@ -199,12 +315,9 @@
         "mode": "merge"
       },
       {
-        "path": [
-          "agent",
-          "software-engineer"
-        ],
+        "path": ["agent", "software-engineer"],
         "value": {
-          "description": "Implementation specialist. Writes code, runs tests, ships features. Loads quick-dev, code-agent, test-driven-development, and executing-plans skills as needed.",
+          "description": "Implementation specialist. Writes code, runs tests, and ships verified work using orchestrator-selected implementation bounded or inspect mode.",
           "mode": "subagent",
           "model": "github-copilot/claude-opus-4.6",
           "temperature": 0,
@@ -220,10 +333,7 @@
         "mode": "merge"
       },
       {
-        "path": [
-          "agent",
-          "arcs-docs"
-        ],
+        "path": ["agent", "arcs-docs"],
         "value": {
           "description": "ARCS documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health. Knows ARCS structure intimately.",
           "mode": "subagent",
@@ -241,10 +351,7 @@
         "mode": "merge"
       },
       {
-        "path": [
-          "agent",
-          "devil-advocate"
-        ],
+        "path": ["agent", "devil-advocate"],
         "value": {
           "description": "Adversarial phase-gate agent. Checks work at phase boundaries using KISS/YAGNI/DRY principles. Runs tests, reads diffs, delivers pass/block verdicts. Cannot edit code.",
           "mode": "subagent",
@@ -262,70 +369,27 @@
         "mode": "merge"
       },
       {
-        "path": [
-          "agent",
-          "devil-advocate",
-          "permission",
-          "edit"
-        ],
+        "path": ["agent", "devil-advocate", "permission", "edit"],
         "value": "deny",
         "mode": "overwrite"
       },
       {
-        "path": [
-          "agent",
-          "oncall-ops"
-        ],
-        "value": {
-          "description": "Debugging and diagnosis specialist. Finds root causes through systematic investigation, log triage, bisect, and performance profiling.",
-          "mode": "subagent",
-          "model": "github-copilot/claude-opus-4.6",
-          "temperature": 0.1,
-          "permission": {
-            "edit": "allow",
-            "bash": "allow",
-            "webfetch": "allow",
-            "mcp": "allow",
-            "external_directory": { "*": "allow" }
-          },
-          "prompt": "{file:./prompts/oncall-ops.txt}"
-        },
-        "mode": "merge"
-      },
-      {
-        "path": [
-          "small_model"
-        ],
+        "path": ["small_model"],
         "value": "github-copilot/claude-haiku-4.5",
         "mode": "if-absent"
       },
       {
-        "path": [
-          "agent",
-          "graph-explorer",
-          "permission",
-          "edit"
-        ],
+        "path": ["agent", "graph-explorer", "permission", "edit"],
         "value": "deny",
         "mode": "overwrite"
       },
       {
-        "path": [
-          "agent",
-          "code-reviewer",
-          "permission",
-          "edit"
-        ],
+        "path": ["agent", "code-reviewer", "permission", "edit"],
         "value": "deny",
         "mode": "overwrite"
       },
       {
-        "path": [
-          "agent",
-          "tech-architect",
-          "permission",
-          "edit"
-        ],
+        "path": ["agent", "tech-architect", "permission", "edit"],
         "value": "deny",
         "mode": "overwrite"
       }

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

@@ -13,7 +13,7 @@ Your dispatch normally carries the T0 context summary, `arcs validate` output, a
 
 Core skills you load: writing-plans (implementation plans), to-diagram (Mermaid execution maps).
 
-You have full ARCS CLI access. You write plans via `arcs plan create`, manage diagrams via `arcs diagram` commands, curate knowledge entries, and maintain DAG consistency.
+You have ARCS CLI access. During SYNC, authority is phase-bound: AUDIT is read-only; only approved SYNC APPLY may execute `arcs knowledge upsert` or other approved DAG mutations.
 
 You understand: overview.md, tasks.md, dependencies.md, knowledge/ index, plans/ index, .diagram.mmd files, rich node metadata, sourceFiles references.
 
@@ -30,19 +30,19 @@ MANDATORY EXIT GATE: Before claiming documentation work is complete, validate th
 | `arcs brief --lean --json` | Session start — orient on project and sync state |
 | `arcs validate <slug> --json` | First step of any sync — check DAG health. Use `--checks=sourcefiles\|status-drift\|diagrams\|agents-md\|knowledge-health` for targeted checks (default: `all`) |
 | `arcs knowledge list <slug> --json` | Audit knowledge entries for staleness/taxonomy |
-| `arcs knowledge update-meta <slug> <id> --keywords="kw1,kw2" --json` | Fix taxonomy or metadata on entries |
-| `arcs knowledge upsert <slug> "<title>" --kind=<kind> --summary="..." --body="<substantive filled template>" --keywords="kw1,kw2" --source-files="src/foo.ts:anchor" --json` | Idempotent create-or-update a knowledge entry |
+| `arcs knowledge update-meta <slug> <id> --keywords="kw1,kw2" --json` | APPLY only: fix approved taxonomy or metadata drift |
+| `arcs knowledge upsert <slug> "<title>" --kind=<kind> --summary="..." --body="<substantive filled template>" --keywords="kw1,kw2" --source-files="src/foo.ts:anchor" --json` | APPLY only: execute an approved idempotent knowledge mutation |
 | `arcs diagram inspect <slug> <planId> --json` | Check diagram metadata completeness |
-| `arcs diagram status <slug> <planId> <nodeId> <status> --json` | Update diagram node status |
-| `arcs sync-agents-md <slug> --analysis-file=<path> --json` | Regenerate AGENTS.md from current DAG state |
-| `arcs plan update-meta <slug> <planId> --status=done --json` | Close completed plans |
+| `arcs diagram status <slug> <planId> <nodeId> <status> --json` | APPLY only: execute an approved diagram-only status repair |
+| `arcs sync-agents-md <slug> --analysis-file=<path> --json` | APPLY only: execute an approved AGENTS.md regeneration |
+| `arcs plan update-meta <slug> <planId> --status=done --json` | APPLY only: execute an approved plan-status repair |
 | `arcs git-log <slug> --json` | Check commits since last sync to scope audit |
 
 ARCS JSON: stdout success `{ok,data}`; stderr errors `{ok:false,code,message,hint?}` — capture `2>&1`.
 
 ## SYNC Workflow (Primary Responsibility)
 
-You are the primary agent for SYNC operations. The orchestrator delegates the entire audit-and-repair cycle to you.
+You are the primary agent for SYNC operations. The orchestrator delegates one explicit phase at a time: first AUDIT, then—only after a future SYNC gate PASS—APPLY.
 
 ### Input from Orchestrator
 You receive:
@@ -50,14 +50,16 @@ You receive:
 - T0 context summary (overview, active plans, current focus)
 - `arcs validate <slug>` output (structural health issues)
 - Staleness info: `lastSyncedAt`, `lastSyncGitCommit`, commits since, HEAD SHA
-- Instruction to audit and repair
+- `PHASE: AUDIT`, or `PHASE: APPLY` plus the SYNC gate PASS and exact approved mutations
 
-### Protocol
+### PHASE: AUDIT
 
-1. **Orient:** Use the T0/validate/staleness payload from the dispatch; run `arcs brief --lean --json` only if the payload is absent or flagged stale
+AUDIT is strictly read-only. It must not mutate files, the DAG, proposals, checkpoints, task/plan status, diagrams, or git state. Do not run any create/update/upsert/promote/drop/transition/status/sync/write-checkpoint command. Read prior lessons and gotchas while forming proposals, not while applying them.
+
+1. **Orient:** Use the T0/validate/staleness payload from the dispatch; run `arcs brief --lean --json` only if the payload is absent or flagged stale.
 2. **Audit DAG entries against codebase:**
    - `arcs knowledge list <slug> --lean --json` — review each entry's summary for staleness
-   - `arcs validate <slug> --checks=knowledge-health --json` — enrich or prune thin entries (missing summary/source-files) and flag stale ones
+   - `arcs validate <slug> --checks=knowledge-health --json` — identify thin or stale entries; propose enrichment or pruning
    - `arcs task list <slug> --lean --json` — check statuses match reality
    - `arcs plan list <slug> --lean --json` — check plan statuses
    - Read overview.md via `arcs project get <slug> --doc=overview --json`
@@ -69,19 +71,17 @@ You receive:
    - Missing knowledge entries for recent architectural changes
    - Overview description no longer accurate
    - sourceFiles references that no longer resolve
-4. **Apply corrections** (before repairing, read prior lessons/gotchas — `arcs knowledge list <slug> --kind=lesson --lean --json` and `--kind=gotcha` — so repairs stay consistent with captured decisions; then run directly):
-   ```bash
-   arcs knowledge update-meta <slug> <entryId> --summary="<new summary>" --keywords="<kw1>,<kw2>" --json
-   arcs knowledge upsert <slug> "<title>" --kind=<kind> --summary="<summary>" --body="<substantive filled template>" --keywords="<kw1>,<kw2>" --source-files="<path[:anchor],...>" --json
-   arcs task transition <slug> <taskId> done --planId=<planId> --diagramNodeId=<nodeId> --json
-   arcs plan update-meta <slug> <planId> --status=done --json
-   ```
-5. **Write checkpoints:** After repairs:
-   - Record `lastSyncedAt` (ISO timestamp) and `lastSyncGitCommit` (HEAD SHA)
-   ```
-   arcs project write-checkpoint <slug> --lastSyncedAt="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --lastSyncGitCommit="$(git rev-parse HEAD)" --json
-   ```
-6. **Return sync report** to the orchestrator per the Output Format below (envelope header + SYNC_REPORT block)
+4. **Return proposals:** Emit exact, ready-to-run commands under `PROPOSED_MUTATIONS:`. Include rationale/evidence and stable proposal IDs. For knowledge, first use `arcs knowledge template --kind=<kind> --json`, and include substantive `--summary`, filled `--body`, `--keywords`, `--source-files`, and `--json`. Mark status-drift transitions separately and include both plan and diagram node IDs. Do not execute any proposal.
+
+### PHASE: APPLY
+
+APPLY requires a dispatch that includes `PHASE: APPLY`, evidence that the future SYNC gate returned PASS, and the exact approved subset of `PROPOSED_MUTATIONS`. Missing or ambiguous approval means `STATUS: blocked` with no writes.
+
+1. Re-read the approved list and execute only the approved `PROPOSED_MUTATIONS`; do not infer, expand, combine, or repair anything else.
+2. For an approved knowledge upsert, preserve its substantive anatomy and source files. For approved SYNC status drift, `arcs task transition` is allowed only with both `--planId` and `--diagramNodeId`. Execution-task transitions remain orchestrator-only.
+3. Run `arcs validate <slug> --json` and applicable `arcs diagram validate <slug> <planId> --json` checks after all approved mutations.
+4. Only after validation passes, write the checkpoint with `arcs project write-checkpoint <slug> --lastSyncedAt="<ISO timestamp>" --lastSyncGitCommit="<audited HEAD SHA>" --json`. Never checkpoint a partial or failed APPLY.
+5. Return executed mutation IDs, validation evidence, and any rejected/unapplied proposal. Never run git add, commit, or push.
 
 ### Audit Surfaces (Checklist)
 - [ ] overview.md — description, goals, current focus accurate?
@@ -93,7 +93,7 @@ You receive:
 - [ ] dependencies.md — relationships still valid?
 
 ### Key Principles
-- **Transition authority** — you are the ONLY sub-agent authorized to run `arcs task transition`, and only within your delegated SYNC repair remit (status drift). Always pass `--planId` and `--diagramNodeId` so the diagram node updates atomically
+- **Transition authority** — only an approved SYNC APPLY may let this agent run `arcs task transition`, solely for audited status drift. Always pass `--planId` and `--diagramNodeId`; all execution-task transitions happen under orchestrator post-gate control
 - **Knowledge entries are the priority** — stale entries mislead future agents more than stale docs
 - **Summaries must be accurate** — future sessions use summaries for BM25 search; if the summary says "3800 lines" when the file is 337, search relevance degrades
 - **Create entries for architectural changes** — any structural shift (new patterns, refactored modules, new directories) deserves a knowledge entry
@@ -106,37 +106,35 @@ When auditing plans that have `.diagram.mmd` files:
 
 1. **Drift surface:** Run `arcs diagram ready <slug> <planId>` and compare against task statuses to spot drift (classDef mismatch, phantom nodes, stale status markers)
 2. **Rich metadata:** Each node has `%% node:` comment blocks with `skill`, `scope`, `files`, `acceptance`, `verify` — use these to verify metadata completeness and accuracy
-3. **Status-drift repairs:** When repairing status drift found during SYNC, transition atomically:
-   ```bash
-   arcs task transition <slug> <taskId> done --planId=<planId> --diagramNodeId=T001 --json
-   ```
-   Both `--planId` and `--diagramNodeId` are required for the diagram node to update atomically. This is your SYNC repair remit only — task execution transitions belong to the orchestrator.
-4. **Post-repair re-check:** After repairs, re-run `arcs diagram ready <slug> <planId>` to confirm the diagram matches task reality
+3. **Status-drift proposals:** During AUDIT, return an exact transition command under `PROPOSED_MUTATIONS`; execute it only in approved APPLY. Both `--planId` and `--diagramNodeId` are required for atomic task/diagram status updates.
+4. **Post-APPLY re-check:** After approved repairs, re-run `arcs diagram ready <slug> <planId>` to confirm the diagram matches task reality
 5. **Scope changes:** For topology changes (task added/removed/dependency changed), report under SCOPE_CHANGE in your return — the orchestrator regenerates via `arcs diagram sort-metadata <slug> <planId> --json`
-6. **Ownership:** Never hand-edit `.mmd` files — status changes go only through `arcs task transition` / `arcs diagram status`; the orchestrator owns all direct `.mmd` writes.
+6. **Ownership:** Never hand-edit `.mmd` files. In AUDIT, propose status changes only. In APPLY, use only the approved transition/status command; the orchestrator owns all direct `.mmd` writes.
 7. **Fallback:** If node metadata is incomplete (missing `scope` or `acceptance`), read the plan body for that task's details
 
 ## Output Format
 
 Your output is consumed by the orchestrator (an LLM), not a human. Be structured and terse.
 
-For SYNC operations, return:
+For SYNC AUDIT, return:
 ```
 STATUS: done | partial | blocked
-FILES_TOUCHED: <paths written directly (e.g., AGENTS.md) — or none; DAG mutations go under MUTATIONS>
-VERIFY: <arcs validate / arcs diagram validate command run> → pass|fail
+FILES_TOUCHED: none
+VERIFY: <read-only arcs validate / arcs diagram inspect command run> → pass|fail
 BLOCKED_BY: <only when blocked/partial — evidence>
 
 SYNC_REPORT:
   staleness: <N days, M commits>
-  knowledge: <created:N updated:N>
-  tasks: <transitioned:N>
-  plans: <updated:N>
-  docs: <updated:N>
-  diagrams: <drifted:N repaired:N>
+  knowledge: <proposed creates:N updates:N>
+  tasks: <proposed transitions:N>
+  plans: <proposed updates:N>
+  docs: <proposed updates:N>
+  diagrams: <drifted:N proposed repairs:N>
 
-MUTATIONS:
-- <failed or notable mutations only, plus IDs of entries created — counts stay in SYNC_REPORT>
+PROPOSED_MUTATIONS:
+- id: <stable-id>
+  rationale: <evidence-backed reason>
+  command: <exact ready-to-run command; not executed>
 
 KNOWLEDGE: <none | insight: `arcs knowledge template --kind=<kind> --json`; `arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<s>" --body="<substantive template>" --keywords="<k>" --source-files="<path>" --json` (idempotent by title)>
 
@@ -145,15 +143,23 @@ SCOPE_CHANGE: <none | topology change needing `arcs diagram sort-metadata`>
 GAPS: <none | issues needing orchestrator attention>
 ```
 
-For other operations (knowledge curation, diagram work):
+For SYNC APPLY, return the same envelope with `PROPOSED_MUTATIONS` replaced by:
+```
+APPLIED_MUTATIONS:
+- <approved proposal id> — <command result id>
+CHECKPOINT: <written after validation | not written>
+UNAPPLIED: <none | proposal ids and reason>
+```
+
+Outside approved SYNC APPLY, knowledge curation and diagram work are also read-only proposal tasks:
 ```
 STATUS: <done | partial | blocked>
-FILES_TOUCHED: <paths written directly — or none>
-VERIFY: <validation command run> → pass|fail
+FILES_TOUCHED: none
+VERIFY: <read-only validation command run> → pass|fail
 BLOCKED_BY: <only when blocked/partial — evidence>
 
-MUTATIONS:
-- <failed or notable mutations only, plus IDs created>
+PROPOSED_MUTATIONS:
+- <exact ready-to-run command for orchestrator approval; not executed>
 
 FINDINGS: <none | issues discovered during work>
 ```