refactor(lock): Consolidate utilities and fix circular dependencies

Co-authored-by: PR0M3TH3AN <[email protected]>
2026-11-06 04:42:24 +00:00 · 2026-02-25 17:09:10 +00:00
1 parent 244dbe1511
commit e7b858d84a
@@ -28,3 +28,30 @@
 - Treat these as environment-sensitive test failures until assertions are aligned with Codex platform semantics and child-process output behavior.
 - If updating tests, follow spec-correction protocol and preserve strict behavioral intent.
 - Keep `KNOWN_ISSUES.md` dates/status current after remediation.
+
+## Update 2026-02-21
+
+### Context
+- Agent: `test-audit-agent`
+- Scope: scenario-first audit run using `scripts/test-audit/run-flaky-check.mjs` and targeted scheduler e2e verification.
+
+### Observation
+- The scheduler platform mismatch is still reproducible:
+  - Expected in test assertion: `platform: unknown` (derived from test-side `detectPlatform() || 'unknown'`)
+  - Actual log frontmatter: `platform: codex`
+- Reproduced with:
+  - `node test/scheduler-preflight-lock.e2e.test.mjs`
+  - `node --test test/scheduler-preflight-lock.e2e.test.mjs`
+
+### Action taken
+- Reclassified the issue in `KNOWN_ISSUES.md` from Resolved back to Active (`KNOWN-ISSUE-scheduler-preflight-platform`) with updated workaround and verification date.
+- Did not weaken/modify scenario expectations in the e2e test without explicit spec correction.
+
+### Validation performed
+- `node test/scheduler-preflight-lock.e2e.test.mjs` (fails with platform mismatch)
+- `node --test test/scheduler-preflight-lock.e2e.test.mjs` (fails)
+
+### Recommendation for next agents
+- Resolve via spec correction only:
+  1. Decide canonical platform source for scheduler logs in fixtures (`AGENT_PLATFORM` fallback vs runtime detector).
+  2. Update assertion to match documented scheduler behavior, not incidental environment state.
@@ -0,0 +1,58 @@
+# Ops Module Overview (`src/ops.mjs`)
+
+## What this module does
+This module implements the core CLI operations for the Torch agent system: `init` and `update`. It handles the scaffolding of the agent environment, including directory structure creation, asset copying, configuration generation, and upgrades.
+
+## Initialization Flow (`cmdInit`)
+1.  **Resolve Configuration**:
+    - Queries user for install directory, namespace, hashtag, and relays.
+    - Validates inputs (prevents path injection).
+2.  **Ensure Directories**:
+    - Creates `torch/prompts/`, `src/proposals/`, `.torch/prompt-history/`.
+3.  **Install Assets**:
+    - Copies app directories (`src`, `bin`, `dashboard`, etc.).
+    - Copies static files (`META_PROMPTS.md`, scheduler docs).
+    - Copies prompts (`daily/`, `weekly/`).
+4.  **Configure**:
+    - Generates `torch-config.json`.
+    - Updates `.gitignore` to exclude `node_modules`.
+    - Generates `TORCH_DASHBOARD.md`.
+5.  **Inject Scripts**:
+    - Adds `torch:*` scripts to the host `package.json` if installed in a subdirectory.
+
+## Update Flow (`cmdUpdate`)
+1.  **Detect Installation**:
+    - Finds the existing `torch` directory.
+2.  **Backup**:
+    - Creates a timestamped backup in `torch/_backups/`.
+3.  **Update App**:
+    - Overwrites application code (`src`, `bin`, etc.).
+    - Overwrites static files.
+4.  **Update Prompts**:
+    - Adds new prompts from the package.
+    - Preserves existing prompts (unless `--force` is used).
+5.  **Preserve Roster**:
+    - `roster.json` is preserved to avoid resetting rotation (unless `--force` is used).
+
+## Public API
+
+### `cmdInit(force, cwd, mockAnswers)`
+Initializes a new Torch environment.
+- `force`: Boolean, overwrite existing directory if not empty.
+- `cwd`: Current working directory.
+- `mockAnswers`: Optional object for testing (bypasses interactive prompts).
+
+### `cmdUpdate(force, cwd)`
+Updates an existing Torch environment.
+- `force`: Boolean, overwrite modified prompts/roster.
+- `cwd`: Current working directory.
+
+## Key Invariants
+- **Safe Installation**: `validateInstallDir` ensures the target directory name is safe (alphanumeric + safe chars).
+- **Non-Destructive Defaults**: `init` fails if directory is not empty (unless forced). `update` preserves user data (prompts, roster, config) by default.
+- **Backup First**: `update` always creates a full backup before modifying files.
+
+## When to change
+- When adding new CLI commands or workflows.
+- When changing the directory structure or asset layout.
+- When updating the default configuration logic or `torch-config.json` schema.
@@ -0,0 +1,542 @@
+# Proposal: Plan Agent Architecture — Closing the Idea-to-Implementation Gap
+
+## Problem Statement
+
+TORCH has **44 agents** generating proposals, audits, and feature ideas — but **zero agents** that evaluate those proposals, plan implementation strategies, or build approved features. The result is a growing pile of dead ends:
+
+### Diagnosed Dead Ends (Current State)
+
+| Dead End | Type | Why It's Stuck |
+|----------|------|----------------|
+| Node-based prompt editor | Proposal | 306-line design doc, zero implementation, no champion |
+| Prompt packages system | Proposal | Concept doc only, never prioritized into work |
+| Hybrid distribution (binary + dashboard) | Proposal | Architecture written, zero progress |
+| `event-schema-agent` | Broken agent | References `src/lib/eventSchemas.js` which doesn't exist — failed 2x, never fixed |
+| `content-audit-agent` | Scope mismatch | Audits upload/contribution features that don't exist in TORCH |
+| `style-agent` | Missing tooling | Blocked on missing `npm run format` script — never added |
+| 7 proposed agents in `AGENT_COVERAGE_GAPS.md` | Coverage gaps | Documented but no agent builds new agents |
+| 77 scattered TODO files | Organizational debt | Created daily, never consolidated or triaged |
+| 130+ dead artifacts | Audit fatigue | Reports generated continuously, never acted upon |
+
+### Root Cause: Missing Pipeline Stages
+
+The current pipeline has a structural gap. Ideas flow in but never flow through to completion:
+
+```
+CURRENT PIPELINE (broken feedback loop)
+
+  feature-proposer-agent ──→ creates single file in features/
+  prompt-gap-analysis-agent ──→ identifies gaps, writes report
+  weekly-synthesis-agent ──→ summarizes activity
+  governance-agent ──→ applies/rejects prompt changes
+
+  ┌─────────────────────────────────────────────────┐
+  │  MISSING: Who evaluates proposals?              │
+  │  MISSING: Who plans implementation strategy?    │
+  │  MISSING: Who builds multi-file features?       │
+  │  MISSING: Who retires dead-end work?            │
+  │  MISSING: Who closes the loop on artifacts?     │
+  └─────────────────────────────────────────────────┘
+```
+
+The `feature-proposer-agent` creates single-file features in `features/`. It explicitly cannot modify existing files or execute multi-step implementations. The `governance-agent` handles prompt changes but not feature development. Nobody triages the 3 stalled proposals, 7 unimplemented agent gaps, or 15 failed task logs.
+
+---
+
+## Proposed Solution: Three New Pipeline Agents
+
+Add three new weekly agents that close the gap between "idea" and "implementation":
+
+```
+PROPOSED PIPELINE (closed loop)
+
+  IDEAS IN                          BUILT OUT
+  ─────────                         ─────────
+  feature-proposer-agent ─┐
+  prompt-gap-analysis-agent ─┤
+  docs/proposals/*.md ──────┤
+  AGENT_COVERAGE_GAPS.md ───┤
+  KNOWN_ISSUES.md ──────────┤
+  artifacts/ reports ───────┘
+                            │
+                    ┌───────▼────────┐
+                    │  proposal-     │  TRIAGE: Evaluates all pending
+                    │  triage-agent  │  proposals, dead ends, and gaps.
+                    │                │  Produces prioritized backlog.
+                    └───────┬────────┘
+                            │
+                    ┌───────▼────────┐
+                    │  plan-agent    │  PLAN: Takes top-priority item
+                    │                │  from backlog. Produces step-by-step
+                    │                │  implementation plan with file list,
+                    │                │  test strategy, and acceptance criteria.
+                    └───────┬────────┘
+                            │
+                    ┌───────▼────────┐
+                    │  builder-agent │  BUILD: Executes approved plan.
+                    │                │  Creates/modifies files, writes tests,
+                    │                │  validates against acceptance criteria.
+                    └────────────────┘
+```
+
+### Why Three Agents, Not One?
+
+A single "do everything" agent would violate TORCH's core design principles:
+
+1. **Single responsibility** — Each agent has one job, one prompt, one failure mode
+2. **Round-robin fairness** — Three separate agents get three separate time slots; a monolithic agent would monopolize an entire weekly slot
+3. **Incremental progress** — Triage can run without planning; planning can run without building; each produces value independently
+4. **Auditable handoffs** — Each stage produces artifacts that the next stage consumes, creating a reviewable paper trail
+5. **Failure isolation** — If the builder fails, the plan still exists for the next cycle; if triage fails, existing plans aren't affected
+
+---
+
+## Agent 1: `proposal-triage-agent` (Weekly)
+
+### Identity
+
+> You are: **proposal-triage-agent**, a weekly agent that evaluates pending proposals, identifies dead ends, and produces a prioritized implementation backlog.
+
+### Mission
+
+Synthesize all pending work items (proposals, coverage gaps, dead-end agents, stale artifacts) into a single prioritized backlog file that downstream agents can consume.
+
+### Inputs (Read)
+
+| Source | What to Extract |
+|--------|----------------|
+| `docs/proposals/*.md` | Active proposals and their implementation status |
+| `docs/AGENT_COVERAGE_GAPS.md` | Proposed but unimplemented agents |
+| `KNOWN_ISSUES.md` | Blocking issues that need tooling fixes |
+| `task-logs/daily/` + `task-logs/weekly/` | Failed agent runs (pattern detection) |
+| `artifacts/` | Reports that haven't driven action |
+| `src/todo/` | Scattered TODO files needing consolidation |
+| `features/` | Single-file features from `feature-proposer-agent` |
+| `docs/agent-handoffs/incidents/` | Unresolved incidents |
+| Previous backlog (`src/backlog/BACKLOG.md`) | Carry forward items not yet addressed |
+
+### Output (Write)
+
+**Primary artifact:** `src/backlog/BACKLOG.md`
+
+```markdown
+# Implementation Backlog — <YYYY-MM-DD>
+
+## Triage Summary
+- Items evaluated: <N>
+- New items added: <N>
+- Items retired (dead end): <N>
+- Items promoted to ready: <N>
+
+## Priority 1: Ready to Plan
+<!-- Items with clear scope, no blockers, high value -->
+
+### BACKLOG-001: Add `npm run format` script to package.json
+- **Source:** KNOWN_ISSUES.md, style-agent failures
+- **Impact:** Unblocks style-agent (daily cadence)
+- **Scope:** Single line in package.json
+- **Status:** ready-to-plan
+- **Acceptance:** `npm run format` exits 0; style-agent completes successfully
+
+### BACKLOG-002: Create `src/lib/eventSchemas.js`
+- **Source:** event-schema-agent failures (2x)
+- **Impact:** Unblocks event-schema-agent (weekly cadence)
+- **Scope:** Extract event builders from `src/nostr-lock.mjs` into shared module
+- **Status:** ready-to-plan
+- **Acceptance:** event-schema-agent completes; `src/nostr-lock.mjs` imports from new module
+
+## Priority 2: Needs Scoping
+<!-- Items with clear value but unclear implementation -->
+
+### BACKLOG-003: Implement Phase 0 of prompt graph extraction
+- **Source:** docs/proposals/node-based-prompt-editor.md
+- **Impact:** Machine-readable agent metadata for all 44 prompts
+- **Scope:** 4 new scripts in `scripts/prompt-graph/`
+- **Status:** needs-scoping
+- **Blockers:** None
+- **Open Questions:** Regex patterns may not cover all prompt variations
+
+## Priority 3: Deferred
+<!-- Items with value but dependencies or low urgency -->
+
+## Retired (Dead Ends)
+<!-- Items explicitly marked as not worth pursuing, with rationale -->
+
+### RETIRED: content-audit-agent upload/contribution scope
+- **Rationale:** TORCH has no upload UI, API, or storage. Agent audits features
+  that don't exist. Recommend revising agent scope instead of building features.
+```
+
+### Triage Criteria
+
+Items are scored on four dimensions:
+
+| Dimension | Weight | Scoring |
+|-----------|--------|---------|
+| **Unblock** | 3x | Does this unblock a currently-broken agent or workflow? |
+| **Value** | 2x | Does this deliver user-visible value or reduce failure rate? |
+| **Scope** | 1x | Is the implementation scope clear and bounded? |
+| **Risk** | -1x | Does this require architectural changes or new dependencies? |
+
+### Retirement Rules
+
+An item should be retired (not deferred) when:
+- The feature it depends on doesn't exist and isn't planned (e.g., content-audit-agent auditing upload features)
+- The proposal has been superseded by a different approach
+- The cost clearly exceeds the benefit with no path to improvement
+- The item has been deferred for 4+ consecutive triage cycles with no progress
+
+### Weekly Workflow
+
+1. Read all inputs listed above
+2. Read previous `src/backlog/BACKLOG.md` if it exists
+3. Evaluate each pending item against triage criteria
+4. Score and rank items
+5. Write updated `src/backlog/BACKLOG.md`
+6. Write triage summary to `src/decisions/DECISIONS_<timestamp>.md`
+
+---
+
+## Agent 2: `plan-agent` (Weekly)
+
+### Identity
+
+> You are: **plan-agent**, a weekly agent that creates detailed implementation plans for the highest-priority backlog item.
+
+### Mission
+
+Take the top `ready-to-plan` item from the backlog and produce a concrete, step-by-step implementation plan that a builder agent can execute without ambiguity.
+
+### Inputs (Read)
+
+| Source | What to Extract |
+|--------|----------------|
+| `src/backlog/BACKLOG.md` | Top `ready-to-plan` item |
+| Original proposal/source doc | Full context for the item |
+| Relevant codebase files | Current implementation to understand integration points |
+| `KNOWN_ISSUES.md` | Active blockers that might affect the plan |
+| `docs/agent-handoffs/learnings/` | Past learnings relevant to this work |
+| Previous plans (`src/plans/`) | Avoid re-planning already-planned items |
+
+### Output (Write)
+
+**Primary artifact:** `src/plans/PLAN-<backlog-id>.md`
+
+```markdown
+# Implementation Plan: BACKLOG-001 — Add `npm run format` script
+
+## Backlog Reference
+- **ID:** BACKLOG-001
+- **Source:** KNOWN_ISSUES.md, style-agent failures
+- **Priority:** P1 (unblocks daily agent)
+
+## Objective
+Add a working `npm run format` script to `package.json` that the
+`style-agent` can invoke to auto-format code.
+
+## Analysis
+- `style-agent` prompt references `npm run format` at line 12
+- `package.json` has `prettier` in devDependencies (v3.2.x)
+- `.prettierrc` exists with project configuration
+- No existing format script; only `lint` exists
+
+## Implementation Steps
+
+### Step 1: Add format script to package.json
+- **File:** `package.json`
+- **Change:** Add `"format": "prettier --write ."` to `scripts` object
+- **Test:** `npm run format` exits 0 without errors
+
+### Step 2: Add format check script (CI-friendly)
+- **File:** `package.json`
+- **Change:** Add `"format:check": "prettier --check ."` to `scripts` object
+- **Test:** `npm run format:check` exits 0 after formatting
+
+### Step 3: Validate style-agent can complete
+- **Action:** Verify `style-agent` prompt references match available scripts
+- **Test:** Dry-run style-agent workflow mentally against available npm scripts
+
+## Files Modified
+- `package.json` (2 lines added to `scripts`)
+
+## Files Created
+- None
+
+## Acceptance Criteria
+1. `npm run format` exits 0 and formats `.js` / `.mjs` files per `.prettierrc`
+2. `npm run format:check` exits 0 after running `npm run format`
+3. `style-agent` prompt commands all resolve to valid npm scripts
+4. No existing tests break
+
+## Test Strategy
+- Run `npm run format` and verify exit code
+- Run `npm run format:check` and verify exit code
+- Run `npm test` to verify no regressions
+- Run `npm run lint` to verify compatibility
+
+## Risk Assessment
+- **Low risk:** Adding scripts to package.json is additive
+- **No architectural changes required**
+- **Rollback:** Remove the two script lines
+
+## Dependencies
+- None — self-contained change
+
+## Estimated Complexity
+- **Simple** (< 5 file changes, no new modules)
+```
+
+### Planning Rules
+
+1. **One plan per cycle** — Don't try to plan everything. Pick the single highest-priority `ready-to-plan` item
+2. **Concrete file paths** — Every step must name the exact file(s) to create or modify
+3. **Testable acceptance** — Every acceptance criterion must be verifiable by running a command
+4. **No ambiguity** — A builder agent reading only this plan should be able to implement it without guessing
+5. **Scope guard** — If the item is too large for a single builder cycle, break it into sub-plans and update the backlog
+
+### Status Updates
+
+After planning, update the backlog item's status:
+
+```
+- **Status:** ready-to-plan  →  planned (see src/plans/PLAN-BACKLOG-001.md)
+```
+
+### Weekly Workflow
+
+1. Read `src/backlog/BACKLOG.md`
+2. Select top `ready-to-plan` item
+3. If no items are `ready-to-plan`, check for `needs-scoping` items and attempt to scope them (update status to `ready-to-plan` if successful)
+4. Read all referenced source documents and relevant codebase files
+5. Write implementation plan to `src/plans/PLAN-<backlog-id>.md`
+6. Update backlog item status to `planned`
+7. Write planning rationale to `src/decisions/DECISIONS_<timestamp>.md`
+
+---
+
+## Agent 3: `builder-agent` (Weekly)
+
+### Identity
+
+> You are: **builder-agent**, a weekly agent that implements the oldest approved plan from the plans directory.
+
+### Mission
+
+Execute an implementation plan by making the code changes described in it, running the specified tests, and verifying all acceptance criteria are met.
+
+### Inputs (Read)
+
+| Source | What to Extract |
+|--------|----------------|
+| `src/plans/PLAN-*.md` | Oldest plan with status `planned` (not `completed` or `in-progress`) |
+| All files referenced in the plan | Current state of code to be modified |
+| `KNOWN_ISSUES.md` | Active blockers that might affect implementation |
+| `src/backlog/BACKLOG.md` | Context for the work item |
+
+### Implementation Protocol
+
+1. **Claim the plan** — Add frontmatter `status: in-progress` and `started: <timestamp>` to the plan file
+2. **Execute steps sequentially** — Follow the plan's implementation steps in order
+3. **Validate after each step** — Run the step's test command if specified
+4. **Run acceptance criteria** — Execute every acceptance criterion command
+5. **Update plan status** — Set `status: completed` with `completed: <timestamp>` if all criteria pass
+6. **Update backlog** — Set backlog item status to `completed`
+7. **Handle failures** — If any acceptance criterion fails:
+   - Set plan status to `blocked` with `blocked_reason`
+   - Do NOT mark backlog item as completed
+   - Document the failure in `KNOWN_ISSUES.md` if it's a new issue
+   - Write incident note to `docs/agent-handoffs/incidents/`
+
+### Output (Write)
+
+- Modified/created files per the plan
+- Updated plan file (status, timestamps)
+- Updated backlog (item status)
+- Test log in `src/test_logs/TEST_LOG_<timestamp>.md`
+
+### Builder Rules
+
+1. **Follow the plan exactly** — Don't improvise. If the plan says "add line X to file Y", do that
+2. **Don't expand scope** — Only make changes listed in the plan. No bonus refactors, no "while I'm here" improvements
+3. **Fail loudly** — If a step can't be completed, stop and document why. Don't skip steps
+4. **Test everything** — Run every test command in the plan. Run `npm test` and `npm run lint` as final validation
+5. **One plan per cycle** — Complete one plan fully before starting another
+
+### Conflict with `feature-proposer-agent`
+
+The existing `feature-proposer-agent` creates single-file features in `features/`. The `builder-agent` executes multi-step plans that may modify existing files. These agents have different scopes:
+
+| Aspect | feature-proposer-agent | builder-agent |
+|--------|----------------------|---------------|
+| Scope | Single new file in `features/` | Any files specified in plan |
+| Input | Own analysis of codebase | Explicit plan from `plan-agent` |
+| Modifications | New files only | New + existing files |
+| Validation | Self-verified | Acceptance criteria from plan |
+| Autonomy | High (chooses what to build) | Low (follows plan exactly) |
+
+Both agents should continue to exist. The `feature-proposer-agent` handles quick, self-contained additions. The `builder-agent` handles planned, multi-step implementations.
+
+---
+
+## Integration with Existing Pipeline
+
+### Roster Changes
+
+Add to `src/prompts/roster.json` under `weekly`:
+
+```json
+{
+  "weekly": [
+    "bug-reproducer-agent",
+    "builder-agent",
+    "changelog-agent",
+    "dead-code-agent",
+    "feature-proposer-agent",
+    "frontend-console-debug-agent",
+    "fuzz-agent",
+    "perf-deepdive-agent",
+    "perf-optimization-agent",
+    "plan-agent",
+    "pr-review-agent",
+    "prompt-fixer-agent",
+    "prompt-gap-analysis-agent",
+    "prompt-maintenance-agent",
+    "prompt-safety-agent",
+    "proposal-triage-agent",
+    "race-condition-agent",
+    "refactor-agent",
+    "repo-fit-agent",
+    "smoke-agent",
+    "telemetry-agent",
+    "test-coverage-agent",
+    "ui-ux-agent",
+    "weekly-synthesis-agent"
+  ]
+}
+```
+
+### New Directories
+
+```
+src/backlog/          # Prioritized implementation backlog (from proposal-triage-agent)
+src/plans/            # Implementation plans (from plan-agent)
+```
+
+### New Prompt Files
+
+```
+src/prompts/weekly/proposal-triage-agent.md
+src/prompts/weekly/plan-agent.md
+src/prompts/weekly/builder-agent.md
+```
+
+### Execution Order Consideration
+
+In the current round-robin, these agents run in alphabetical order within the weekly cadence. The ideal execution order is:
+
+1. `proposal-triage-agent` (produces backlog)
+2. `plan-agent` (consumes backlog, produces plan)
+3. `builder-agent` (consumes plan, produces implementation)
+
+Since round-robin is alphabetical (`builder-agent` < `plan-agent` < `proposal-triage-agent`), the builder would run *before* the planner in any given week. This is acceptable because:
+
+- Plans persist across weeks — a plan written in week N is built in week N+1
+- The pipeline is designed for multi-week cadence, not single-week completion
+- Each agent checks for existing artifacts from previous cycles
+
+If same-week execution is desired in the future, the Phase 3+ custom flow configurations from the prompt editor proposal would enable DAG-based ordering.
+
+### Interaction with Existing Agents
+
+| Existing Agent | Interaction |
+|---------------|-------------|
+| `feature-proposer-agent` | Features it creates may be evaluated by `proposal-triage-agent` |
+| `prompt-gap-analysis-agent` | Gap reports feed into `proposal-triage-agent` inputs |
+| `weekly-synthesis-agent` | Summarizes triage/plan/build activity in weekly report |
+| `governance-agent` | Prompt changes from builder go through normal governance |
+| `prompt-maintenance-agent` | Validates new agent prompts follow contract |
+| `dead-code-agent` | May identify retired items for triage to confirm |
+
+---
+
+## Addressing the Identified Dead Ends
+
+Here's how the new pipeline would handle each current dead end:
+
+| Dead End | Agent | Action |
+|----------|-------|--------|
+| Missing `npm run format` | triage → plan → builder | P1: triage identifies, plan writes 2-line change, builder implements |
+| Missing `eventSchemas.js` | triage → plan → builder | P1: triage identifies, plan designs extraction, builder creates module |
+| content-audit-agent scope | triage | Retired: agent audits nonexistent features |
+| Prompt editor Phase 0 | triage → plan | Scoped: triage breaks into sub-tasks, plan designs Phase 0 extraction |
+| Prompt packages | triage → plan | Deferred or scoped depending on priority vs. other items |
+| Distribution binary | triage | Deferred: requires external tooling, low relative priority |
+| 7 coverage gap agents | triage → plan → builder | Each gap becomes a backlog item; plan designs prompt, builder creates it |
+| 77 scattered TODOs | triage | Consolidated into backlog; triage replaces scattered TODO creation |
+| 130+ dead artifacts | triage | Evaluated for actionability; non-actionable artifacts flagged for GC |
+
+---
+
+## Success Metrics
+
+| Metric | Current | Target (4 weeks) | Target (8 weeks) |
+|--------|---------|-------------------|-------------------|
+| Stalled proposals | 3 | 2 (1 retired, 1 planned) | 0 (all planned or retired) |
+| Broken agents | 3 (event-schema, style, content-audit) | 1 (content-audit retired) | 0 |
+| Unimplemented coverage gaps | 7 | 5 (2 planned) | 3 (2 built, 2 planned) |
+| Backlog items with clear status | 0 | 10+ | 15+ |
+| Plans executed per month | 0 | 2 | 4 |
+
+---
+
+## Implementation Plan for This Proposal
+
+This proposal itself should go through the pipeline it describes. Bootstrap order:
+
+### Step 1: Create directories
+```bash
+mkdir -p src/backlog src/plans
+```
+
+### Step 2: Create `proposal-triage-agent.md`
+- Write prompt following shared agent run contract
+- Add to `roster.json` weekly array
+
+### Step 3: Create `plan-agent.md`
+- Write prompt following shared agent run contract
+- Add to `roster.json` weekly array
+
+### Step 4: Create `builder-agent.md`
+- Write prompt following shared agent run contract
+- Add to `roster.json` weekly array
+
+### Step 5: Seed initial backlog
+- Create `src/backlog/BACKLOG.md` with known dead ends pre-triaged
+- This gives the plan-agent something to work with on its first run
+
+### Step 6: Validate
+- Run `node scripts/validate-prompt-contract.mjs`
+- Run `node scripts/validate-scheduler-roster.mjs`
+- Run `npm run lint`
+- Run `npm test`
+
+---
+
+## Risks
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| Builder agent makes incorrect changes | High | Plan must have testable acceptance criteria; builder runs all tests |
+| Triage agent deprioritizes important work | Medium | Triage criteria are explicit and weighted; human can override backlog |
+| Plan scope creep | Medium | Planning rules enforce one plan per cycle, concrete file paths |
+| Agents produce circular work (triage creates items that triage later retires) | Low | Retirement rules require 4+ deferred cycles before retirement |
+| Builder conflicts with other agents modifying same files | Medium | Lock system prevents concurrent modification; plan specifies exact files |
+
+---
+
+## Relationship to Other Proposals
+
+- **Prompt Editor (Phase 0):** The triage agent would evaluate this proposal and potentially break Phase 0 into backlog items. The plan agent would design the extraction scripts. The builder agent would create them.
+- **Prompt Packages:** Same pipeline — triage evaluates, plan designs, builder implements.
+- **Distribution Plan:** Triage would likely defer this (requires external tooling) but keep it visible in the backlog.
+- **Agent Coverage Gaps:** Each gap becomes a backlog item. The builder agent is literally designed to create new agent prompts from plans.
@@ -0,0 +1,95 @@
+# TORCH Style Guide
+
+This document outlines the design system, color palette, and typography used in the TORCH project (`dashboard/` and `landing/`).
+
+## Color Palette
+
+The project uses a dark theme with high-contrast text and vibrant accents.
+
+### Core Colors
+
+| Name           | CSS Variable       | Hex       | Usage                                      |
+|:---------------|:-------------------|:----------|:-------------------------------------------|
+| **Surface**    | `--surface`        | `#0b1020` | Main background color.                     |
+| **Surface Alt**| `--surface-alt`    | `#151b2f` | Card backgrounds, headers, secondary areas.|
+| **Text**       | `--text`           | `#dbe4ff` | Primary body text (slightly blue-tinted).  |
+| **Text Strong**| `--text-strong`    | `#ffffff` | Headings, emphasized text.                 |
+| **Muted**      | `--muted`          | `#9aa6c6` | Secondary text, metadata, descriptions.    |
+| **Border**     | `--border`         | `#2a3456` | Borders for cards, inputs, dividers.       |
+
+### Brand & Functional Colors
+
+| Name           | CSS Variable       | Hex       | Usage                                      |
+|:---------------|:-------------------|:----------|:-------------------------------------------|
+| **Accent**     | `--accent`         | `#4f8cff` | Primary buttons, active states, links.     |
+| **Accent Strong**| `--accent-strong`| `#2f6be5` | Hover states for accent elements.          |
+| **Info**       | `--info`           | `#46b7ff` | Informational messages, icons.             |
+| **Info Strong**| `--info-strong`    | `#8ad4ff` | Stronger info emphasis.                    |
+| **Success**    | `--success`        | `#35c47c` | Success messages, "Active" statuses.       |
+| **Warning**    | `--warning`        | `#f5b84b` | Warning alerts.                            |
+| **Danger**     | `--danger`         | `#ff6b6b` | Error messages, destructive actions.       |
+
+### Auxiliary Colors
+
+| Name           | CSS Variable       | Hex       |
+|:---------------|:-------------------|:----------|
+| **Purple**     | `--purple`         | `#a855f7` |
+| **Pink**       | `--pink`           | `#ec4899` |
+| **Teal**       | `--teal`           | `#2dd4bf` |
+
+## Typography
+
+### Font Families
+
+*   **Primary**: `Inter`, `system-ui`, `-apple-system`, `Segoe UI`, `Roboto`, `sans-serif`
+*   **Monospace**: `ui-monospace`, `SFMono-Regular`, `Menlo`, `Monaco`, `Consolas`, `monospace`
+
+### Hierarchy
+
+*   **Headings**: Bold (`700`), `Text Strong`.
+*   **Body**: Regular (`400`), `Text`.
+*   **Small/Meta**: Small size, `Muted`.
+
+## Components
+
+### Buttons
+
+*   **Primary CTA**:
+    *   Background: `var(--accent)`
+    *   Text: `white`
+    *   Border Radius: `9999px` (Pill shape)
+    *   Hover: `var(--accent-strong)`, slight transform up.
+*   **Secondary CTA**:
+    *   Background: Transparent or low opacity white.
+    *   Border: `var(--border)`
+    *   Text: `var(--text)`
+    *   Hover: Lighter background, `Text Strong`.
+
+### Cards
+
+*   Background: `var(--surface-alt)`
+*   Border: `1px solid var(--border)`
+*   Radius: `12px` or `1rem`
+*   Hover: Border color changes to `var(--accent)`, slight lift (`transform: translateY(-5px)`).
+
+### Status Badges
+
+*   Small, pill-shaped (`border-radius: 99px`).
+*   Uppercase, bold, small font size.
+*   Active: Background `var(--accent)`, Text `var(--surface)`.
+*   Disabled/Inactive: Background `rgba(255,255,255,0.1)`, Text `var(--muted)`.
+
+## Layout
+
+*   **Container**: Max-width `1200px` centered.
+*   **Grid**: Responsive grids using `grid-template-columns: repeat(auto-fit, minmax(..., 1fr))`.
+*   **Spacing**: Uses `rem` units (e.g., `1rem`, `2rem`, `4rem`).
+
+## Accessibility Guidelines
+
+*   **Contrast**: Ensure text passes WCAG AA standards against the dark background.
+*   **Interactive Elements**:
+    *   Must have `role="button"` or be `<button>`/`<a>`.
+    *   Must be keyboard accessible (`tabindex="0"`).
+    *   Must have visible focus states (`focus:ring`).
+*   **Images**: All images must have `alt` text. Decorative images should use `aria-hidden="true"`.