@rryando/arcs 4.0.0 → 4.2.0

package/opencode/arcs/skills/test-driven-development/testing-anti-patterns.md

@@ -1,299 +1,12 @@
 # Testing Anti-Patterns
 
-**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
+Avoid:
 
-## Overview
+- tests that assert private call order instead of behavior;
+- mocks that reproduce the implementation;
+- broad snapshots with no meaningful contract;
+- sleeps instead of observable conditions;
+- one test covering several unrelated behaviors;
+- adding tests solely to increase line coverage.
 
-Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
-
-**Core principle:** Test what the code does, not what the mocks do.
-
-**Following strict TDD prevents these anti-patterns.**
-
-## The Iron Laws
-
-```
-1. NEVER test mock behavior
-2. NEVER add test-only methods to production classes
-3. NEVER mock without understanding dependencies
-```
-
-## Anti-Pattern 1: Testing Mock Behavior
-
-**The violation:**
-```typescript
-// ❌ BAD: Testing that the mock exists
-test('renders sidebar', () => {
-  render(<Page />);
-  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
-});
-```
-
-**Why this is wrong:**
-- You're verifying the mock works, not that the component works
-- Test passes when mock is present, fails when it's not
-- Tells you nothing about real behavior
-
-**your human partner's correction:** "Are we testing the behavior of a mock?"
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test real component or don't mock it
-test('renders sidebar', () => {
-  render(<Page />);  // Don't mock sidebar
-  expect(screen.getByRole('navigation')).toBeInTheDocument();
-});
-
-// OR if sidebar must be mocked for isolation:
-// Don't assert on the mock - test Page's behavior with sidebar present
-```
-
-### Gate Function
-
-```
-BEFORE asserting on any mock element:
-  Ask: "Am I testing real component behavior or just mock existence?"
-
-  IF testing mock existence:
-    STOP - Delete the assertion or unmock the component
-
-  Test real behavior instead
-```
-
-## Anti-Pattern 2: Test-Only Methods in Production
-
-**The violation:**
-```typescript
-// ❌ BAD: destroy() only used in tests
-class Session {
-  async destroy() {  // Looks like production API!
-    await this._workspaceManager?.destroyWorkspace(this.id);
-    // ... cleanup
-  }
-}
-
-// In tests
-afterEach(() => session.destroy());
-```
-
-**Why this is wrong:**
-- Production class polluted with test-only code
-- Dangerous if accidentally called in production
-- Violates YAGNI and separation of concerns
-- Confuses object lifecycle with entity lifecycle
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test utilities handle test cleanup
-// Session has no destroy() - it's stateless in production
-
-// In test-utils/
-export async function cleanupSession(session: Session) {
-  const workspace = session.getWorkspaceInfo();
-  if (workspace) {
-    await workspaceManager.destroyWorkspace(workspace.id);
-  }
-}
-
-// In tests
-afterEach(() => cleanupSession(session));
-```
-
-### Gate Function
-
-```
-BEFORE adding any method to production class:
-  Ask: "Is this only used by tests?"
-
-  IF yes:
-    STOP - Don't add it
-    Put it in test utilities instead
-
-  Ask: "Does this class own this resource's lifecycle?"
-
-  IF no:
-    STOP - Wrong class for this method
-```
-
-## Anti-Pattern 3: Mocking Without Understanding
-
-**The violation:**
-```typescript
-// ❌ BAD: Mock breaks test logic
-test('detects duplicate server', () => {
-  // Mock prevents config write that test depends on!
-  vi.mock('ToolCatalog', () => ({
-    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
-  }));
-
-  await addServer(config);
-  await addServer(config);  // Should throw - but won't!
-});
-```
-
-**Why this is wrong:**
-- Mocked method had side effect test depended on (writing config)
-- Over-mocking to "be safe" breaks actual behavior
-- Test passes for wrong reason or fails mysteriously
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mock at correct level
-test('detects duplicate server', () => {
-  // Mock the slow part, preserve behavior test needs
-  vi.mock('MCPServerManager'); // Just mock slow server startup
-
-  await addServer(config);  // Config written
-  await addServer(config);  // Duplicate detected ✓
-});
-```
-
-### Gate Function
-
-```
-BEFORE mocking any method:
-  STOP - Don't mock yet
-
-  1. Ask: "What side effects does the real method have?"
-  2. Ask: "Does this test depend on any of those side effects?"
-  3. Ask: "Do I fully understand what this test needs?"
-
-  IF depends on side effects:
-    Mock at lower level (the actual slow/external operation)
-    OR use test doubles that preserve necessary behavior
-    NOT the high-level method the test depends on
-
-  IF unsure what test depends on:
-    Run test with real implementation FIRST
-    Observe what actually needs to happen
-    THEN add minimal mocking at the right level
-
-  Red flags:
-    - "I'll mock this to be safe"
-    - "This might be slow, better mock it"
-    - Mocking without understanding the dependency chain
-```
-
-## Anti-Pattern 4: Incomplete Mocks
-
-**The violation:**
-```typescript
-// ❌ BAD: Partial mock - only fields you think you need
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' }
-  // Missing: metadata that downstream code uses
-};
-
-// Later: breaks when code accesses response.metadata.requestId
-```
-
-**Why this is wrong:**
-- **Partial mocks hide structural assumptions** - You only mocked fields you know about
-- **Downstream code may depend on fields you didn't include** - Silent failures
-- **Tests pass but integration fails** - Mock incomplete, real API complete
-- **False confidence** - Test proves nothing about real behavior
-
-**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mirror real API completeness
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' },
-  metadata: { requestId: 'req-789', timestamp: 1234567890 }
-  // All fields real API returns
-};
-```
-
-### Gate Function
-
-```
-BEFORE creating mock responses:
-  Check: "What fields does the real API response contain?"
-
-  Actions:
-    1. Examine actual API response from docs/examples
-    2. Include ALL fields system might consume downstream
-    3. Verify mock matches real response schema completely
-
-  Critical:
-    If you're creating a mock, you must understand the ENTIRE structure
-    Partial mocks fail silently when code depends on omitted fields
-
-  If uncertain: Include all documented fields
-```
-
-## Anti-Pattern 5: Integration Tests as Afterthought
-
-**The violation:**
-```
-✅ Implementation complete
-❌ No tests written
-"Ready for testing"
-```
-
-**Why this is wrong:**
-- Testing is part of implementation, not optional follow-up
-- TDD would have caught this
-- Can't claim complete without tests
-
-**The fix:**
-```
-TDD cycle:
-1. Write failing test
-2. Implement to pass
-3. Refactor
-4. THEN claim complete
-```
-
-## When Mocks Become Too Complex
-
-**Warning signs:**
-- Mock setup longer than test logic
-- Mocking everything to make test pass
-- Mocks missing methods real components have
-- Test breaks when mock changes
-
-**your human partner's question:** "Do we need to be using a mock here?"
-
-**Consider:** Integration tests with real components often simpler than complex mocks
-
-## TDD Prevents These Anti-Patterns
-
-**Why TDD helps:**
-1. **Write test first** → Forces you to think about what you're actually testing
-2. **Watch it fail** → Confirms test tests real behavior, not mocks
-3. **Minimal implementation** → No test-only methods creep in
-4. **Real dependencies** → You see what the test actually needs before mocking
-
-**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
-
-## Quick Reference
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Assert on mock elements | Test real component or unmock it |
-| Test-only methods in production | Move to test utilities |
-| Mock without understanding | Understand dependencies first, mock minimally |
-| Incomplete mocks | Mirror real API completely |
-| Tests as afterthought | TDD - tests first |
-| Over-complex mocks | Consider integration tests |
-
-## Red Flags
-
-- Assertion checks for `*-mock` test IDs
-- Methods only called in test files
-- Mock setup is >50% of test
-- Test fails when you remove mock
-- Can't explain why mock is needed
-- Mocking "just to be safe"
-
-## The Bottom Line
-
-**Mocks are tools to isolate, not things to test.**
-
-If TDD reveals you're testing mock behavior, you've gone wrong.
-
-Fix: Test real behavior or question why you're mocking at all.
+Prefer stable public boundaries, realistic inputs, clear failure messages, and the smallest check that proves the requirement.

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

@@ -1,220 +1,32 @@
 ---
 name: to-diagram
-description: Use when creating or updating a Mermaid diagram for a ARCS plan — selecting dialect, encoding task status via classDef, managing the standalone .mmd file, and detecting or resolving diagram/metadata drift.
+description: Create or update a helper-managed Mermaid execution diagram
 ---
 
-# Skill: to-diagram
+# Plan Diagrams
 
-## When
+## Contract
 
-Creating, updating, or auditing a Mermaid `.mmd` diagram for a ARCS plan.
+Task metadata is the source of truth. The `.diagram.mmd` file is derived data for execution order and status.
 
-> Follows ARCS CLI Primer: `arcs --commands --json` for discovery, `--json --lean` on all calls.
+Use `manage-diagram.mjs` with the supported `flowchart TD` format. Prefer ARCS CLI wrappers:
 
-## Flow
+- `arcs diagram init <slug> <planId>`
+- `arcs diagram inspect <slug> <planId>`
+- `arcs diagram ready <slug> <planId>`
+- `arcs diagram status <slug> <planId> <node> <status>`
+- `arcs diagram validate <slug> <planId>`
 
-```mermaid
-flowchart TD
-    classDef decision fill:#f59e0b,color:#fff
+## Metadata
 
-    Start[Plan needs diagram] --> HasDiagram{.mmd exists?}
-    HasDiagram -->|No| Create[Create from canonical metadata]
-    HasDiagram -->|Yes| Detect[Compare diagram vs metadata]
-    Detect --> DriftType{Drift type?}
-    DriftType -->|None| Done[No action]
-    DriftType -->|Status only| StatusUpdate[Surgical status update]
-    DriftType -->|Scope change| Regen[Full regeneration]
-    DriftType -->|Mixed| Regen
-    Create --> Validate[Validate .mmd syntax]
-    StatusUpdate --> Validate
-    Regen --> Validate
-    Validate --> Write[Write .mmd]
-    Write --> Done
+Each node uses stable `T001`-style IDs and records title, status, skill, work mode, scope, acceptance, verify command, and dependencies. Implementation tasks use `skill: implementation` with `work-mode: bounded|inspect`.
 
-    class HasDiagram,DriftType decision
-```
+Dependencies come from task `dependsOn`; do not hand-maintain conflicting arrows. New plans begin in backlog. Use the standard `done`, `inProgress`, `blocked`, and `backlog` classes.
 
-## Supported Dialect
+## Update
 
-ARCS helper-managed execution diagrams use `flowchart TD` with `classDef` status styling. `manage-diagram.mjs` is the executable authority for this format; other Mermaid dialects are unmanaged and must not be passed to the helper.
+- Status-only change: use `arcs diagram status`.
+- Scope, task, or dependency change: update task metadata, then regenerate.
+- Always validate after every write.
 
-## Status-Only Update
-
-```mermaid
-flowchart TD
-    Read[Read .mmd] --> Verify{Node/edge count matches metadata?}
-    Verify -->|No| Escalate[Escalate to regeneration]
-    Verify -->|Yes| UpdateClass[Replace :::oldClass with :::newClass]
-    UpdateClass --> UpdateHeader[Recalc plan-level %% comments]
-    UpdateHeader --> UpdateMeta[Update per-node %% status lines]
-    UpdateMeta --> VerifyByte{Node/edge sets byte-identical?}
-    VerifyByte -->|Yes| Write[Write .mmd]
-    VerifyByte -->|No| Escalate
-```
-
-## Scope-Change Regeneration
-
-```mermaid
-flowchart TD
-    ReadMeta[Read canonical metadata] --> MapIDs[Map existing task→node IDs]
-    MapIDs --> AssignNew[Assign T### for new tasks]
-    AssignNew --> Retire[Retire removed IDs, never reuse]
-    Retire --> BuildGraph[Build flowchart TD from deps]
-    BuildGraph --> GenNodeMeta[Generate per-node %% blocks]
-    GenNodeMeta --> GenHeader[Generate plan-level %% comments]
-    GenHeader --> Preview[Preview diff summary]
-    Preview --> Write[Write .mmd]
-```
-
-## Canonical Source of Truth (Priority Order)
-
-1. **Structured task metadata** (ARCS tasks) — always wins
-2. **Plan body checkboxes** (`- [ ]`/`- [x]`) — fallback if no structured tasks
-3. **`%%` comments in .mmd** — cache only, never authoritative
-
-Metadata always wins. Diagram is regenerated from metadata on drift, never the reverse.
-
-**Diagrams are derived data.** `-->` arrows and `%% blocked-by:` lines are auto-generated by `generateDiagramFromTasks` from each task's `dependsOn` field. Manual arrow edits are allowed but will be overwritten on the next regeneration — treat them as cosmetic only. The `dependsOn` field on the task record is the authoritative source for topology.
-
-## Drift Types
-
-| # | Type | Symptom |
-|---|------|---------|
-| 1 | classDef mismatch | Node has wrong :::class vs metadata status |
-| 2 | Phantom node | Diagram node has no corresponding task |
-| 3 | Missing node | Task exists but no diagram node |
-| 4 | Topology mismatch | Edges don't match dependency metadata |
-| 5 | Stale plan-level comments | %% status/ready/blocked inconsistent |
-| 6 | Incomplete node metadata | Missing %% block or stale fields |
-
-**Resolution for all 6:** Regenerate from metadata. Never patch metadata to match diagram.
-
-## classDef Conventions
-
-Always declare at top of every `flowchart TD`:
-
-```
-classDef done fill:#22c55e,color:#fff
-classDef inProgress fill:#f59e0b,color:#fff
-classDef blocked fill:#ef4444,color:#fff
-classDef backlog fill:#94a3b8,color:#fff
-```
-
-Assign via `:::className` suffix. At plan creation, all nodes start `:::backlog`.
-
-## Node ID Rules
-
-- Format: `T001`, `T002`, ... (zero-padded 3+ digits)
-- If ARCS structured tasks exist, use their canonical IDs
-- IDs are stable — never change on rename/reorder
-- Removed IDs are retired, never reused
-- New tasks get next unused sequential ID
-
-## Per-Node Metadata Format
-
-Between plan-level header and `flowchart TD` declaration:
-
-```
-%% node: T003
-%% title: Build order management UI
-%% status: backlog
-%% skill: implementation
-%% work-mode: inspect
-%% scope: src/components/orders/, src/pages/orders/
-%% files: src/components/orders/OrderList.tsx (optional)
-%% acceptance: Order list renders with pagination
-%% verify: npm test -- --testPathPattern=orders
-%% blocked-by: T002 (optional)
-%% delegate: yes (optional)
-```
-
-**Required:** node, title, status, skill, work-mode, scope, acceptance. **Optional:** files, verify, blocked-by, delegate.
-
-Implementation nodes use `%% skill: implementation` plus `%% work-mode: bounded|inspect`. Structured task metadata supplies this canonical pair directly.
-
-`verify` must name a command scoped to the node's files (e.g. `npm test -- --testPathPattern=orders`, `vitest run test/orders.test.ts`) — never the bare full suite (`npm test`, `vitest run`). The devil-advocate completion gate owns the single full-project pass.
-
-## Plan-Level Header Comments
-
-```
-%% plan: <plan-id>
-%% status: T001=done, T002=inProgress, T003=backlog
-%% ready: T003 (all deps done)
-%% blocked: T005 (waiting on T003)
-%% next-action: Start T003
-```
-
-## manage-diagram.mjs Commands
-
-| Command | Purpose |
-|---------|---------|
-| `inspect <file>` | Structured JSON of nodes/edges/metadata |
-| `ready <file>` | Compute executable nodes from topology |
-| `validate <file> [--metadata f.json]` | Check integrity (+ drift detection) |
-| `status <file> <nodeId> <status>` | Update single node status atomically |
-| `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. 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
-
-- Path: `plans/<plan-id>.diagram.mmd`
-- Pure Mermaid syntax (no markdown fences)
-- First line: `%% plan: <plan-id>`
-- One diagram per plan
-- Plan body references: `> Diagram: plans/<plan-id>.diagram.mmd`
-
-## Scalability
-
-Plans with 15+ nodes: cluster into `subgraph` blocks by phase. If unreadable, split into sub-plans.
-
-## Constraints
-
-- **Ownership:** Only orchestrator/coordinator writes .mmd files. Sub-agents read only and report status back
-- **Presentation:** Internal skill — never narrate conventions to user. Show rendered diagram or URL only
-- **Determinism:** Same metadata must produce byte-identical .mmd output (nodes ordered by ID, edges by source→target, fields in fixed order)
-- **Confidence gate:** Self-score ≥80% before writing .mmd files
-- **Validation before write:** unique IDs, valid edges, all 4 classDef present, valid :::class suffixes
-- **Backward compat:** Plans without .mmd remain valid; diagrams without rich metadata upgraded during SYNC
-
-## Reference Example
-
-```
-%% plan: order-system
-%% status: T001=done, T002=inProgress, T003=backlog, T004=backlog, T005=blocked
-%% ready: T003 (T001 done)
-%% blocked: T005 (waiting on T003 and T004)
-%% next-action: Start T003
-
-%% node: T001
-%% title: Design database schema for orders
-%% status: done
-%% skill: implementation
-%% work-mode: bounded
-%% scope: db/migrations/
-%% acceptance: Migration runs; orders table has all required columns
-%% verify: npm run db:migrate
-
-%% node: T002
-%% title: Build REST API endpoints
-%% status: inProgress
-%% skill: test-driven-development
-%% work-mode: bounded
-%% scope: src/api/orders/
-%% acceptance: CRUD endpoints return correct status codes
-%% verify: npm test -- --testPathPattern=api/orders
-%% blocked-by: T001
-
-flowchart TD
-    classDef done fill:#22c55e,color:#fff
-    classDef inProgress fill:#f59e0b,color:#fff
-    classDef blocked fill:#ef4444,color:#fff
-    classDef backlog fill:#94a3b8,color:#fff
-
-    T001[Design database schema]:::done --> T002[Build REST API]:::inProgress
-    T001 --> T003[Write integration tests]:::backlog
-    T002 --> T004[Build order UI]:::backlog
-    T003 --> T005[Deploy to staging]:::blocked
-    T004 --> T005
-```
+Never make the diagram authoritative over task records. Ask only when a proposed topology change materially changes the approved goal or scope.

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

@@ -1,75 +1,23 @@
 ---
 name: writing-knowledge
-description: Use when capturing a knowledge entry, before writing its body — to author a substantive per-kind body, not a summary-only stub
+description: Capture durable, actionable project knowledge without summary-only stubs
 ---
 
-# Skill: writing-knowledge
+# Writing Knowledge
 
 ## When
 
-You are about to author a durable insight proposal for the DAG and need the entry to be *actionable*, not a stub.
+Capture a non-obvious fact that will save future work. Skip mechanical or instantly re-derived information.
 
-> CLI Primer: `arcs --commands --json` for discovery. This skill authors proposal text; it does not execute `arcs knowledge upsert`.
+## Method
 
-## The Floor: Every Entry Needs a Body
+1. Choose the right kind: gotcha, lesson, pattern, architecture, decision, module, feature, or reference.
+2. Run `arcs knowledge template --kind=<kind>` when the kind's structure is useful.
+3. Write a specific title, useful summary, substantive body, keywords, and source files.
+4. Search for an existing entry when duplication is plausible; prefer idempotent `upsert`.
 
-A knowledge entry is two things: a `--summary` (the headline) and a `--body` (the substance). The single most common KB failure is the **summary-only stub** — an entry whose summary just restates its title and whose body is empty. It is structurally "healthy" and worthless to the next dispatch.
+Summary is the headline; body is the reasoning and operational detail; source files anchor the entry to current code. A file-specific entry should include all three.
 
-EVERY non-mechanical entry MUST carry a real `--body` (`--body="…"` inline, or `--body-file=<path>` once it's long enough to fight shell-escaping). The value lives in the body, written to the **anatomy of its kind**.
+When the user requested the knowledge write, execute it directly with `arcs knowledge upsert` and report the resulting ID. Otherwise return the proposed entry for confirmation only when the write would be surprising.
 
-## Scaffold, Don't Freehand
-
-Before writing, scaffold the section skeleton from the command:
-
-```bash
-arcs knowledge template --kind=<kind> --json   # structured sections
-arcs knowledge template --kind=<kind>          # plain markdown skeleton
-```
-
-This emits one `## <heading>` per section with a deletable hint comment. **Fill EVERY section** — a half-filled skeleton is still a stub.
-
-> **DRY / authoritative source:** `arcs knowledge template` is the AUTHORITATIVE skeleton. The anatomy below only *illustrates* the shape. If the table here ever diverges from the command output, **the command wins** — scaffold from it, not from this file.
-
-## The 8 Kinds at a Glance
-
-| Kind | Section anatomy |
-| --- | --- |
-| **gotcha** | Symptom · Root cause · Fix or workaround · Trigger |
-| **lesson** | Expectation · What happened · Why · Next time |
-| **pattern** | When to use · Shape · Example · When not to use |
-| **architecture** | Structure · Invariant or constraint · Failure mode |
-| **decision** | Decision · Rationale and forces · Alternatives rejected · Consequences |
-| **module** | Purpose · Key files and entry points · Responsibilities · Dependencies |
-| **feature** | What it does · How it works · Entry points · Edge cases |
-| **reference** | Summary · Canonical location · Usage notes |
-
-Pick the kind by what the insight *is*: a bug you hit → `gotcha`; a wrong belief corrected → `lesson`; a reusable shape → `pattern`; a structural why → `architecture`; a single settled call → `decision`; an area of the codebase → `module`/`feature`; a pointer to a canonical source → `reference`.
-
-## Author the Proposal
-
-```bash
-arcs knowledge upsert <slug> "<title>" \
-  --kind=<kind> \
-  --summary="<one-line headline>" \
-  --body="<every section of the kind, filled>" \
-  --keywords="<k1,k2>" \
-  --source-files="<path[:anchor],…>" \
-  --json
-```
-
-Return the command without executing it. The orchestrator applies approved proposals at fan-in. `upsert` is idempotent by title — create-or-update, no dedup search dance. `--summary` AND `--body` AND `--source-files` together are the floor for a file-specific entry.
-
-## Self-Check Before You Return the Proposal
-
-> **"Could someone act on this in six months without re-deriving it?"**
-
-If the insight cost you reasoning, a debug session, or a dead end, capture *that* — not just its one-line conclusion. Inverse (per implementation minimalism): if anyone could re-derive it in ten seconds, don't write it at all.
-
-## Constraints
-
-- Scaffold from `arcs knowledge template` — never freehand the section headings.
-- Fill every section; a half-filled skeleton is a stub.
-- `--summary` is the headline, `--body` is the value — never ship summary-only.
-- Match kind to the nature of the insight; don't force everything into `gotcha`.
-- Skip capture entirely for purely mechanical work (renames, config nudges, diagram regens).
-- Proposal-only: do not execute `arcs knowledge upsert` or any other DAG mutation from this skill.
+Validate that a future agent could act on the entry without re-deriving it.