devloom 1.0.0 → 1.2.0

package/protocol/model-routing.md

@@ -0,0 +1,194 @@
+# DevLoom Model Routing Profiles
+
+## Overview
+
+Model routing assigns a specific language model to each agent role. Different models offer different trade-offs between reasoning quality, context, cost, and speed. Profiles let users pick the right balance without changing agent logic.
+
+Each of the 10 DevLoom agents (orchestrator, planner, developer, qa, verifier, security, documenter, vision, visual-director, visual-critic) receives a model from the active profile. The orchestrator applies these when dispatching tasks. In every profile the `visual-director` and `visual-critic` roles resolve through the same model as `vision`.
+
+## How Profile Selection Works
+
+1. Profile is read from `.opencode/devloom/project/config.json` under `modelRouting`.
+2. Default: `go-flash` (deepseek-v4-flash for every role except vision).
+3. Override per task via `--model` flag or `OPENCODE_MODEL_OVERRIDE` env var.
+
+```json
+{ "modelRouting": "go" }
+```
+
+## Profiles
+### go (max quality)
+The highest quality profile for production work. Orchestrator uses DeepSeek V4 Flash (cheapest — runs every turn; vision delegated to `devloom-vision`). Qwen 3.7 Max to planner (strong reasoning), Kimi K2.7 Code to implementation, GLM 5.2 to security (forensic depth), DeepSeek V4 Pro to QA/verifier, Qwen 3.7 Plus to documentation, Qwen 3.6 Plus to vision (low-cost multimodal).
+
+| Role | Model |
+|---|---|
+| orchestrator | opencode-go/deepseek-v4-flash |
+| planner | opencode-go/qwen3.7-max |
+| developer | opencode-go/kimi-k2.7-code |
+| qa | opencode-go/deepseek-v4-pro |
+| verifier | opencode-go/deepseek-v4-pro |
+| security | opencode-go/glm-5.2 |
+| documenter | opencode-go/qwen3.7-plus |
+| vision | opencode-go/qwen3.6-plus |
+
+### go-economy
+A lower cost profile that retains Kimi K2.7 Code for the developer role and uses DeepSeek V4 Pro for orchestrator, qa, verifier, and security roles. Qwen 3.6 Plus handles documentation at reduced cost. Suitable for routine development work where premium reasoning is not essential.
+
+| Role | Model |
+|---|---|
+| orchestrator | opencode-go/deepseek-v4-pro |
+| planner | opencode-go/kimi-k2.7-code |
+| developer | opencode-go/kimi-k2.7-code |
+| qa | opencode-go/deepseek-v4-pro |
+| verifier | opencode-go/deepseek-v4-pro |
+| security | opencode-go/deepseek-v4-pro |
+| documenter | opencode-go/qwen3.6-plus |
+| vision | opencode-go/qwen3.6-plus |
+
+### go-flash
+All agents on DeepSeek V4 Flash for maximum throughput at minimum cost. Vision uses Qwen 3.6 Plus (multimodal).
+
+| Role | Model |
+|---|---|
+| orchestrator | opencode-go/deepseek-v4-flash |
+| planner | opencode-go/deepseek-v4-flash |
+| developer | opencode-go/deepseek-v4-flash |
+| qa | opencode-go/deepseek-v4-flash |
+| verifier | opencode-go/deepseek-v4-flash |
+| security | opencode-go/deepseek-v4-flash |
+| documenter | opencode-go/deepseek-v4-flash |
+| vision | opencode-go/qwen3.6-plus |
+
+### deepseek
+All DeepSeek V4 Pro agents (consistent provider affinity). Vision uses DeepSeek V4 Flash Vision Exp (cheapest vision-capable DeepSeek model: 0.22 input / 0.66 output vs Qwen 3.6 Plus 0.5/3).
+
+| Role | Model |
+|---|---|
+| orchestrator | opencode-go/deepseek-v4-pro |
+| planner | opencode-go/deepseek-v4-pro |
+| developer | opencode-go/deepseek-v4-pro |
+| qa | opencode-go/deepseek-v4-pro |
+| verifier | opencode-go/deepseek-v4-pro |
+| security | opencode-go/deepseek-v4-pro |
+| documenter | opencode-go/deepseek-v4-pro |
+| vision | opencode-go/deepseek-v4-flash-vision-exp |
+
+### free
+A zero-cost profile using only freely available models. Intended for experimentation, open-source projects, learning, and low-stakes development where cost must be zero. All agents use the best available free-tier model. If a specific free model is unavailable, the fallback chains are: orchestration: opencode/big-pickle -> opencode/muse-spark-1.3-contributor-free -> opencode/mimo-v2.5-free -> opencode/muse-spark-1.2-contributor-free -> opencode/nemotron-3.5-lightning-free -> opencode/nemotron-3-ultra-free -> opencode/ling-3.0-flash-fin-free; implementation/verification: opencode/big-pickle -> opencode/muse-spark-1.3-contributor-free -> opencode/nemotron-3.5-lightning-free -> opencode/mimo-v2.5-free -> opencode/nemotron-3-ultra-free -> opencode/ling-3.0-flash-fin-free; planning: opencode/nemotron-3-ultra-free -> opencode/muse-spark-1.3-contributor-free -> opencode/muse-spark-1.2-contributor-free -> opencode/big-pickle -> opencode/nemotron-3.5-lightning-free -> opencode/ling-3.0-flash-fin-free; documentation: opencode/muse-spark-1.3-contributor-free -> opencode/muse-spark-1.2-contributor-free -> opencode/nemotron-3-ultra-free -> opencode/mimo-v2.5-free -> opencode/ling-3.0-flash-fin-free; vision: opencode/mimo-v2.5-free -> opencode-go/deepseek-v4-flash-vision-exp -> opencode-go/minimax-m3 -> opencode-go/mimo-v2.5-pro (paid fallbacks ordered by cost, cheapest first: deepseek 0.22/0.66 < minimax 0.3/1.2 < mimo-pro 0.435/0.87).
+
+| Role | Model |
+|---|---|
+| orchestrator | opencode/big-pickle |
+| planner | opencode/nemotron-3-ultra-free |
+| developer | opencode/big-pickle |
+| qa | opencode/big-pickle |
+| verifier | opencode/big-pickle |
+| security | opencode/big-pickle |
+| documenter | opencode/muse-spark-1.2-contributor-free |
+| vision | opencode/mimo-v2.5-free |
+
+### mimo (locked tier)
+
+A single multimodal stack: every role — including vision, visual-director, and visual-critic — resolves to the first available MiMo V2.6 Flash candidate from the chain `mimo/mimo-v2.6-flash` -> `xiaomi/mimo-v2.6-flash` -> `opencode-go/mimo-v2.6-flash`, checked against `opencode models`. `opencode/mimo-v2.6-flash-free` is deliberately excluded from free chains. If no candidate is available the profile is NOT activated: `profile.mjs` exits with code 1 and prints the attempted candidates — never an unrelated substitution. Tier overrides are locked for this profile. Activate with `/devloom-mimo`.
+
+| Role | Model |
+|---|---|
+| all 10 roles | resolved MiMo V2.6 Flash candidate |
+
+### deepseek-mimo (hybrid, tier unlocked)
+
+Fast everyday work on DeepSeek V4.1 Flash; graphical/complex work on MiMo V2.6 Flash. The 7 general roles (orchestrator, planner, developer, qa, verifier, security, documenter) resolve to `opencode-go/deepseek-v4.1-flash`; vision, visual-director, and visual-critic resolve through the `MIMO_V26_FLASH_CANDIDATES` chain. Both chains resolve strictly against `opencode models` — if either finds nothing the profile exits code 1 with the attempted candidates, never an unrelated substitution. Activate with `/devloom-deepseek-mimo`.
+
+| Role | Model |
+|---|---|
+| 7 general roles | opencode-go/deepseek-v4.1-flash |
+| vision, visual-director, visual-critic | resolved MiMo V2.6 Flash candidate |
+
+## Model Guidance
+
+### When to Use GLM 5.2
+
+GLM 5.2 (opencode-go/glm-5.2) provides the strongest reasoning and planning capabilities among available models. It is the best choice when a task requires:
+
+- Architectural design and system decomposition
+- Requirements analysis and specification writing
+- UX-aware decisions that balance user experience with technical constraints
+- Multi-step planning with dependency management
+- High-stakes decisions where incorrect reasoning would be costly
+
+In practice, GLM 5.2 should be assigned to the orchestrator, planner, and any agent that makes strategic decisions. For UI/UX-heavy Angular or React SaaS frontend work, GLM 5.2 delivers superior reasoning around component hierarchies, state management patterns, accessibility, and user flow design.
+
+### When to Use Kimi K2.7 Code
+
+Kimi K2.7 Code (opencode-go/kimi-k2.7-code) offers strong code generation quality with a large context window. Successor to K2.6 with fewer hallucinations and better long-context adherence. Ideal for multi-file changes, refactors, code exploration, deep bug fixes, and backend work that needs to hold many services/schemas in context simultaneously. Primary workhorse for the developer role in the go and go-economy profiles.
+
+### When to Use Kimi K3 (Senior Developer)
+
+Kimi K3 (opencode-go/kimi-k3) is the newest Kimi generation. It is the model assigned to the `senior` tier for the developer role when the orchestrator classifies the prompt as complex (architecture change, large refactor, deep debugging, security-sensitive implementation). It offers stronger code reasoning and longer context than K2.7 Code.
+
+### When to Use MiniMax M3 (Multimodal)
+
+MiniMax M3 (opencode-go/minimax-m3) is multimodal but is not the default in any current profile. The `devloom-vision` agent uses Qwen 3.6 Plus (multimodal, lower cost). MiniMax M3 may still be used as a vision fallback if Qwen 3.6 Plus is unavailable. Use it directly only when you need a multimodal model with no vision delegation overhead.
+
+### When to Use DeepSeek V4 Pro
+
+DeepSeek V4 Pro (opencode-go/deepseek-v4-pro) excels at structured, analytical tasks. It is the default qa and verifier in the go profile, and the default for most roles in `deepseek` and `go-economy`, because these roles benefit from precision over open-ended reasoning.
+
+Best uses: planning, verification, writing/running tests, debugging, root-cause analysis, regression reviews.
+
+### When to Use DeepSeek V4 Flash
+
+DeepSeek V4 Flash (opencode-go/deepseek-v4-flash) is the cheapest Go model. It is the default orchestrator in the go and go-economy profiles because the orchestrator runs every turn and accumulates the highest token volume. Vision is delegated to `devloom-vision` (Qwen 3.6 Plus), so the orchestrator does not need multimodal capability. It is also the default for every role in the `go-flash` profile.
+
+### When to Use Qwen Models
+
+Qwen 3.7 Plus (opencode-go/qwen3.7-plus) is the latest Qwen model — documentation, analysis, code summarization. Qwen 3.7 Max (opencode-go/qwen3.7-max) is the planner in the `go` profile for strong reasoning. Qwen 3.6 Plus (opencode-go/qwen3.6-plus) is the default multimodal model for the `devloom-vision` agent — lowest-cost multimodal option on the OpenCode Go plan.
+
+### When to Use Free Tier Models
+
+Free models (opencode/big-pickle, opencode/nemotron-3-ultra-free, opencode/nemotron-3.5-lightning-free, opencode/mimo-v2.5-free, opencode/muse-spark-1.3-contributor-free, opencode/muse-spark-1.2-contributor-free, opencode/ling-3.0-flash-fin-free) are suitable only when cost must be zero — experimentation, learning, or evaluation. They have lower reasoning capability than paid Go models in some roles, not recommended for production work. The `vision` role always resolves to a vision-capable model (mimo-v2.5-free on the free tier, with DeepSeek V4 Flash Vision Exp as cheapest paid fallback).
+
+## Frontend vs Backend Guidance
+
+**UI/UX-heavy frontend (Angular, React, SaaS):** component decomposition, state management, accessibility, responsive layout, and user-flow decisions benefit from strong reasoning rather than large context. Use DeepSeek V4 Pro (planner) for planning, architecture, and review; Kimi K2.7 Code for implementation when the task spans many files.
+
+**Backend and data-intensive work:** context size matters more than peak reasoning. Use Kimi K2.7 Code for backend implementation roles — its large context window holds services, database schemas, API contracts, and data pipelines without truncation.
+
+## Configuration and Overrides
+
+### Setting the Profile
+
+In `.opencode/devloom/project/config.json`:
+
+```json
+{
+  "modelRouting": "go"
+}
+```
+
+Valid values: `"go"`, `"go-economy"`, `"deepseek"`, `"go-flash"`, `"free"`, `"mimo"`, `"deepseek-mimo"`.
+
+### Overrides
+
+Per-task: `opencode task --model opencode-go/glm-5.2 "implement feature"`. Environment: set `OPENCODE_MODEL_OVERRIDE=<model-id>` to force every agent onto one model — it takes precedence over both the profile and the `--model` flag.
+
+### Per-Role Override in Config
+
+Individual role assignments can be overridden by adding a `modelRoutingOverrides` object in config.json:
+
+```json
+{
+  "modelRouting": "go-economy",
+  "modelRoutingOverrides": {
+    "developer": "opencode-go/glm-5.2",
+    "qa": "opencode-go/kimi-k2.7-code"
+  }
+}
+```
+
+Overrides merge on top of the selected profile and take precedence for the specified roles.
+
+### Sidebar visibility and plugin cache
+
+The sidebar reflects the active profile via the plugin `config` hook, which injects all 17 agents, renders a `DevLoom - {profile}` header, and shows the resolved model next to every agent row. The orchestrator agent description carries the profile label — e.g. `DevLoom Orchestrator: autonomous multi-agent delivery (profile: go-flash)`, extended to `(profile: go, tier: senior)` when the senior tier is active. The sidebar lists only the 10 base agents: all `-flash` and `-senior` variants are hidden for every profile, yet all 17 stay registered so `task()` routing is unaffected.
+OpenCode installs npm plugins into `~/.cache/opencode/packages/` with `ignoreScripts`, so the cached copy can go stale and the hook never runs. Run `/devloom-refresh` after installing/updating DevLoom or switching profiles — it rebuilds `dist/` from source before refreshing the cache — then restart opencode (or `opencode --continue`) to see the updated profile and agents in the sidebar.

package/protocol/orchestrator-core.md

@@ -0,0 +1,43 @@
+# Orchestrator Core
+
+LOAD: ~/.config/opencode/devloom-ai/core.dsl|~/.config/opencode/devloom-ai/workflow.dsl
+
+SM:
+`IDLE>TRIAGE>CHAIN[step1..stepN]>GATE>DONE`
+
+TRIAGE:
+- classify prompt intent, select minimal chain from workflow.dsl CHAINS
+- append COND_ADDONS only when their condition holds
+- full pipeline only when intent=feature with UI+API+flows touched
+- orchestrator routes+persists only; chain steps run in subagents
+
+STATE:
+- LEGACY=.opencode/devloom/state.json
+- BOARD=.opencode/devloom/project/board.json
+- PSTATE=.opencode/devloom/project/state.json
+
+RULES:
+- COMPLIANCE: you MUST follow every rule in this file and every LOADed file. No rule may be skipped or abbreviated.
+- COMPLIANCE: you MUST verify every sub-agent output against the protocol gates defined in this file. Reject non-compliant results and re-delegate.
+- load BOARD+PSTATE every prompt
+- load memory context and relevant skills every prompt before planning
+- if board.cols.doing is non-empty: queue the new prompt (append to backlog + TODO.md), set phase=queued, do NOT triage or execute
+- append the current prompt as the last task/todo before execution (only when doing is empty)
+- continue pending work first
+- single active ticket — new prompts queue behind current work unless explicitly overridden
+- orchestrator may invoke any DevLoom subagent automatically when the phase requires it
+- orchestrator must delegate specialist phase work to the matching DevLoom subagent when one exists
+- orchestrator must invoke devloom-security for CRUD endpoint work and for any change that exposes internal component/module input or output
+- orchestrator keeps routing and state ownership; subagents do the phase-specific execution
+- orchestrator updates tickets, todos, and plan artifacts on each state transition
+- orchestrator saves state before reprioritization, pause, and completion
+- all artifacts EN
+- official docs + latest stable check before stack-specific plan/code
+- defect => developer(rootCauseFix)>qa(regr)
+- max3 fix cycles per defect, then mark blocked + BLOCKED report
+- max100 steps
+- clear context every 5 completed tasks if needed
+- FILES: never use /tmp, /var/tmp, or system temp — use .opencode/devloom/.tmp/ for temp files and test artifacts
+
+EXIT:
+- only DEVLOOM_DONE when all gates pass and no open high/critical defect

package/protocol/project-system.md

@@ -0,0 +1,45 @@
+# Project System
+
+LOAD: ~/.config/opencode/devloom-ai/core.dsl|~/.config/opencode/devloom-ai/workflow.dsl
+
+ROOT: `.opencode/devloom/project/`
+
+TREE:
+- README.md
+- config.json
+- board.json
+- state.json
+- stories/
+- tasks/
+- bugs/
+- decisions/
+- reports/
+
+CFG_JSONM:
+```json
+{"v":1,"lang":"en","tracker":"local","gh":{"enabled":false,"owner":"","repo":"","project":""},"rules":{"flow":["analysis","documentation","implementation","verification","regression","done"],"tests":"required","regression":"required","queue":"single","docs":"official","delegation":"required","skills":"required","memory":"load","save":"always","promptTask":"append-last"}}
+```
+
+BOARD_JSONM:
+```json
+{"v":1,"tracker":"local","active":"","cols":{"backlog":[],"ready":[],"doing":[],"review":[],"blocked":[],"done":[]},"updatedAt":""}
+```
+
+STATE_JSONM:
+```json
+{"v":1,"phase":"idle","prompt":"","ticket":"","next":"analysis","updatedAt":"","notes":[]}
+```
+
+RULES:
+- EN
+- JSONM for AI-only state
+- doing<=1 unless explicit user override
+- when doing is occupied, new prompts queue to backlog — never preempt active work
+- never drop pending work
+- tests+regr required for code change
+- load memory and relevant skills every prompt
+- append each new prompt as the last task/todo entry before execution continues (only when doing is empty)
+- keep tickets, todos, and plan synchronized automatically
+- tracker=github only with explicit user authorization
+- local files remain fallback source of truth even in github mode
+- phase=queued means prompts are waiting in backlog behind active work — resume dequeues the next item

package/protocol/rules.md

@@ -0,0 +1,18 @@
+# DevLoom Protocol Rules
+
+CORE: EN only | SOLID+TDD+CleanArch | SingleActive | AppendPromptTask | OfficialDocsFirst | tests+regr required | delegation required | save every phase | load memory+skills every prompt
+
+QUEUE: doing<=1 | new prompt while doing non-empty → append to backlog, set phase=queued, do NOT triage or execute | /devloom-resume dequeues next backlog item
+
+CHAIN: feature=planner>dev>qa>doc | bug=dev(rca)>qa(regr) | refactor=planner>dev>qa | small=dev>qa | docs=planner>doc | task=dev | explore=verifier
+
+ADDONS: image→vision FIRST | UI→visual-director(DESIGN_FILE, persist .opencode/devloom/context/design.md) then verifier(route,form,a11y,visual,responsive,motion) + visual-critic(≤3 cycles, verdict passed to verifier; backend-only never routes visual agents) | API→verifier(api,contract) | CRUD/endpoint→security | defect→dev(rca)>qa(regr) max3 cycles | high-risk→peer-review (verifier with multi-model consensus)
+
+GATES: build(lint+tests) | qa(test+review+regr) | verifier(all requested scopes) | visual(design.md exists + critic verdict or VISUAL_CRITIQUE_LIMITED, VISUAL_REQUIRED only for UI work) | security(all checks) | peer-review(≥2 models agree) | doc(done+verified only)
+
+ANTI-LOOP: max3 retries per defect | max100 steps | BLOCKED+reason after 2 failed retries | never self-delegate | never loop same agent
+
+OUTPUT: DEVLOOM_DONE only when chain gates pass | sub-agents emit their OUT signal | final response ≤40 lines, full detail in artifacts | sub-agent never calls orchestrator back
+FILES: never use /tmp, /var/tmp, or any system temp dirs — use .opencode/devloom/.tmp/ in the project workspace for all temporary files, test artifacts, and scratch work
+SESSIONS: orchestrator tracks sub-agent task IDs in state.sessions. Reuse task_id when re-delegating to the same agent type mid-pipeline — prevents context loss across turns.
+DEGRADE: if a sub-agent fails twice (timeout, rate-limit, empty response), fall back one tier: senior→mid, mid→junior, junior→skip. Set state.degraded=true and log the fallback.

package/protocol/verification-policy.md

@@ -0,0 +1,48 @@
+# Verification Policy
+
+LOAD: ~/.config/opencode/devloom-ai/verify.dsl
+
+RULES:
+- ROUTE-001=render|noBlank|noCrash|noConsoleErr|noNavFail|noHydrationErr
+- ROUTE-002=domVisible|size>0|notHidden|notBlocked|inViewport
+- ROUTE-003=screenshot/vision when available
+- FORM-001=valid|invalid|required|boundary|successMsg|errorMsg|loading
+- FORM-002=input|select|checkbox|radio|textarea|submit|reset
+- A11Y-001=role|label|expanded|selected|current
+- A11Y-002=tabReachable|focusVisible|orderOk|noTrap|enterSpace|escClose|arrowKeys
+- A11Y-003=contrastText|contrastFocus|noColorOnly
+- A11Y-004=nav|main|headingOrder|buttonVsLink|labelAssoc
+- API-001=auth|authz|inputVal|outputSchema|statusCodes|errorShape|paging/filter/sort if app
+- API-002=openapi if missing|runtime vs contract
+- E2E-001=targeted impacted suite during iteration
+- E2E-002=full suite before acceptance
+- JOURNEY-001=generate from REQ+routes+ui
+- JOURNEY-002=test valid state transitions
+- PERF-001=loadTime|noLeak|noExcessRender|bundleOk
+- VISUAL-001=screenshots or CRITIC_VERDICT required|else VISUAL_CRITIQUE_LIMITED (never fake VISUAL_PASS)
+- VISUAL-002=10-dim score vs design.md contract|hierarchy|spacing|typography|color|alignment|consistency|affordance|density|polish|fidelity
+- VISUAL-003=no overflow|no clipped text|no overlap|component states match tokens
+- RESP-001=viewports 360|768|1280|no horizontal scroll|no overlap|touch targets >=44px|images scale
+- MOTION-001=prefers-reduced-motion|duration <=300ms standard <=500ms complex|no layout shift|states complete|easing matches design.md
+- SEC-001=depAudit|noSecrets|cors|sanitize|auth|authz|leastPrivilege
+- SEC-002=inputVal|outputSchema|errorShape|massAssignment|overposting
+- SEC-003=noInternalFieldLeak|noDebugLeak|idor|xss|csrf|ssrf if applicable
+- SEC-004=mandatory for CRUD endpoints and any internal component/module exposure via input/output
+
+MAP:
+- RouteVerifier=ROUTE-001|002|003
+- FormVerifier=FORM-001|002
+- A11yVerifier=A11Y-001|002|003|004
+- ApiVerifier=API-001|002
+- VisualVerifier=VISUAL-001|002|003
+- ResponsiveVerifier=RESP-001
+- MotionVerifier=MOTION-001
+- SecurityVerifier=SEC-001|002|003|004
+- JourneyAgent=JOURNEY-001|002
+- QA=run applicable rules
+- Regression=E2E-001 during work; E2E-002 before done
+
+ENFORCE:
+- each violation => defect
+- critical/high defect blocks gate
+- skip is invalid; only escalate after 3 failed repair cycles

package/scripts/briefing.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// Incremental briefing tracker: answers "what changed since the briefing was
+// written?" so orchestrator/sub-agents re-read ONLY modified files.
+//
+// Signal: sha256 content fingerprints recorded at init/touch — the same
+// content-addressed idea as git, but immune to commit/uncommitted state (a
+// file already re-read after `touch` never reappears until it truly changes).
+// The git baseCommit is kept for provenance/status only.
+//
+// Commands:
+//   briefing.mjs init <ticket>  create briefing.md stub + record fingerprints
+//   briefing.mjs changed        print changed paths (one per line), exit 0
+//   briefing.mjs touch          re-anchor after the briefing was patched
+//   briefing.mjs status         show ticket/base/counters
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs"
+import { execSync } from "child_process"
+import { resolve, dirname, join, relative, sep } from "path"
+import { fileURLToPath } from "url"
+import { createHash } from "crypto"
+
+const DIR = ".opencode/devloom/context"
+export const BRIEFING_MD = `${DIR}/briefing.md`
+export const BRIEFING_JSON = `${DIR}/briefing.json`
+
+const EXCLUDE_DIRS = new Set([
+  "node_modules", ".git", "dist", ".angular", ".next", "build", "coverage",
+  "logs", ".tmp", "tmp", ".opencode", ".idea", ".vscode",
+])
+const EXCLUDE_FILES = /^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|\.DS_Store|.*\.log)$/
+
+export function walkFiles(root = process.cwd()) {
+  const out = []
+  const stack = [root]
+  while (stack.length > 0) {
+    const dir = stack.pop()
+    let entries = []
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") && entry.isDirectory() && entry.name !== ".ai") continue
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (!EXCLUDE_DIRS.has(entry.name)) stack.push(full)
+        continue
+      }
+      if (!entry.isFile() || EXCLUDE_FILES.test(entry.name)) continue
+      const rel = relative(root, full).split(sep).join("/")
+      out.push(rel)
+    }
+  }
+  return out.sort()
+}
+
+export function hashFile(rel, root = process.cwd()) {
+  try {
+    const data = readFileSync(join(root, rel))
+    return createHash("sha256").update(data).digest("hex").slice(0, 12)
+  } catch {
+    return null
+  }
+}
+
+export function computeHashes(paths, root = process.cwd()) {
+  const files = {}
+  for (const p of paths) files[p] = hashFile(p, root)
+  return files
+}
+
+export function diffHashes(previous, paths, root = process.cwd()) {
+  const changed = []
+  const prev = previous || {}
+  for (const p of paths) {
+    if (prev[p] !== hashFile(p, root)) changed.push(p)
+  }
+  for (const p of Object.keys(prev)) {
+    if (!paths.includes(p) && prev[p] !== null) changed.push(p)
+  }
+  return [...new Set(changed)].sort()
+}
+
+function run(cmd, cwd = process.cwd()) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", timeout: 15000 }).trim()
+  } catch {
+    return null
+  }
+}
+
+export function gitAvailable(cwd = process.cwd()) {
+  return run("git rev-parse --is-inside-work-tree", cwd) === "true"
+}
+
+export function gitHead(cwd = process.cwd()) {
+  const out = run("git rev-parse HEAD", cwd)
+  return out && !out.includes("fatal") ? out : null
+}
+
+function readJson() {
+  try {
+    return JSON.parse(readFileSync(BRIEFING_JSON, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+function writeJson(data) {
+  mkdirSync(DIR, { recursive: true })
+  writeFileSync(BRIEFING_JSON, JSON.stringify(data, null, 2) + "\n")
+}
+
+export function init(ticket = "ticket") {
+  mkdirSync(DIR, { recursive: true })
+  const paths = walkFiles()
+  const useGit = gitAvailable()
+  const data = {
+    ticket,
+    baseCommit: useGit ? gitHead() : null,
+    files: computeHashes(paths),
+    updatedAt: new Date().toISOString(),
+  }
+  writeJson(data)
+  if (!existsSync(BRIEFING_MD)) {
+    writeFileSync(
+      BRIEFING_MD,
+      `# Briefing — ${ticket}\n` +
+        `> Created: ${data.updatedAt}\n` +
+        `> Refresh rule: run \`briefing.mjs changed\`, re-read ONLY those paths, patch this file, then \`briefing.mjs touch\`.\n` +
+        `> Every task() prompt starts with: "Read .opencode/devloom/context/briefing.md first — do not re-discover."\n\n` +
+        `## Goal\n\n## Constraints\n\n## File map\n\n## Decisions\n`
+    )
+  }
+  return data
+}
+
+export function changed() {
+  const data = readJson()
+  if (!data) return []
+  return diffHashes(data.files, walkFiles())
+}
+
+export function touch() {
+  const data = readJson() || init("ticket")
+  const paths = walkFiles()
+  data.baseCommit = gitAvailable() ? gitHead() : null
+  data.files = computeHashes(paths)
+  data.updatedAt = new Date().toISOString()
+  writeJson(data)
+  return data
+}
+
+export function status() {
+  const data = readJson()
+  if (!data) {
+    console.log("No briefing recorded. Run: briefing.mjs init <ticket>")
+    return
+  }
+  console.log(`Ticket: ${data.ticket}`)
+  console.log(`Base commit: ${data.baseCommit || "(no git)"}`)
+  console.log(`Tracked files: ${Object.keys(data.files).length}`)
+  console.log(`Updated: ${data.updatedAt}`)
+}
+
+function main() {
+  const args = process.argv.slice(2)
+  const command = args[0] || ""
+  switch (command) {
+    case "init":
+      init(args[1] || "ticket")
+      console.log(`Briefing initialized${args[1] ? ` for ${args[1]}` : ""}: ${BRIEFING_MD}`)
+      break
+    case "changed": {
+      const paths = changed()
+      for (const p of paths) console.log(p)
+      break
+    }
+    case "touch":
+      touch()
+      console.log("Briefing anchors refreshed.")
+      break
+    case "status":
+      status()
+      break
+    default:
+      console.log("Usage: briefing.mjs <init <ticket>|changed|touch|status>")
+  }
+}
+
+const isMain = process.argv[1] ? fileURLToPath(import.meta.url) === resolve(process.argv[1]) : false
+if (isMain) main()