@brunosps00/dev-workflow 0.8.1 → 0.9.0

package/scaffold/pt-br/commands/dw-run-task.md

@@ -25,15 +25,16 @@ Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como sup
 
 ## Inteligência do Codebase
 
-<critical>Se `.planning/intel/` existir, a consulta é OBRIGATÓRIA antes de redigir os requisitos. NÃO pule este passo.</critical>
-- Execute internamente: `/gsd-intel "padrões de implementação em [área alvo da task]"`
+<critical>Se `.dw/intel/` existir, a consulta via `/dw-intel` é OBRIGATÓRIA antes de codar. NÃO pule este passo.</critical>
+- Execute internamente: `/dw-intel "padrões de implementação em [área alvo da task]"`
 - Siga convenções encontradas para estrutura de arquivos, nomenclatura e tratamento de erros
 
 Se `design-contract.md` existir no diretório do PRD:
 - Leia o contrato e garanta que toda implementação frontend siga as regras de design aprovadas
 
-Se `.planning/intel/` NÃO existir:
-- Use `.dw/rules/` como contexto (comportamento atual)
+Se `.dw/intel/` NÃO existir:
+- Use `.dw/rules/` como contexto, caindo para grep direto se necessário
+- Sugira rodar `/dw-map-codebase` após a task para enriquecer contexto downstream
 
 ## Localização dos Arquivos
 

package/scaffold/pt-br/commands/dw-update.md

@@ -79,7 +79,9 @@ npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
 O comando `update` sobrescreve arquivos gerenciados e PRESERVA:
 - `.dw/rules/` (rules do usuário)
 - `.dw/spec/` (PRDs e tasks em andamento)
-- `.planning/` (dados do usuário)
+- `.dw/intel/` (índice de codebase do `/dw-map-codebase`)
+
+O comando `update` também roda o passo de migração GSD automaticamente — se o projeto tem `.planning/` legado (de uso prévio do GSD), o conteúdo é migrado para `.dw/intel/`, `.dw/spec/active-session.md`, `.dw/spec/quick/`, etc., e `.planning/` é renomeado para `.planning.gsd-archive-<DATA>/` para inspeção. Os arquivos `.claude/commands/gsd/`, `.claude/agents/gsd-*.md`, `.claude/hooks/gsd-*.js` e `.claude/gsd-file-manifest.json` são removidos durante a migração.
 
 Se o update falhar (erro de rede, permissão, pacote indisponível): reporte o erro ao usuário e PARE. NÃO tente workarounds manuais como copiar arquivos.
 

package/scaffold/pt-br/templates/idea-onepager.md

@@ -22,7 +22,7 @@ Foque no problema, não na solução. Evite entrar em "como implementar".]
 Fontes:
 - PRDs em `.dw/spec/prd-*/prd.md` (features já entregues ou em desenvolvimento)
 - `.dw/rules/index.md` (overview do produto)
-- `.planning/intel/` se GSD estiver instalado
+- `.dw/intel/` (indice queryable — construido por `/dw-map-codebase`, consultado via `/dw-intel`)
 
 Formato:]
 

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: dw-codebase-intel
+description: Codebase intelligence for dev-workflow. The intel-updater agent maintains a queryable index in .dw/intel/ (stack.json, files.json, apis.json, deps.json, arch.md) that other commands read instead of doing expensive codebase exploration. Used by /dw-intel and /dw-map-codebase. Adapted from get-shit-done-cc (MIT).
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+# dw-codebase-intel
+
+Bundled skill that gives dev-workflow native **codebase intelligence** — a queryable knowledge base of the project's stack, file graph, API surface, dependencies, and architecture. Other commands (`/dw-create-prd`, `/dw-create-techspec`, `/dw-code-review`, `/dw-refactoring-analysis`, `/dw-brainstorm`, etc.) read from this index instead of re-exploring the codebase on every invocation.
+
+## Why a skill (not inline)
+
+- Each agent is independently maintainable and reusable.
+- The format of `.dw/intel/` is a contract that downstream commands depend on; codifying it in references makes drift visible.
+- Other commands invoke these agents through the skill, not by duplicating the logic.
+
+## When to Use
+
+Read this skill when:
+
+- `/dw-map-codebase` is invoked (full or partial codebase analysis).
+- `/dw-intel "<query>"` is invoked (query existing intel).
+- `/dw-analyze-project` runs after first commit and wants to enrich `.dw/rules/` with structural facts from `.dw/intel/`.
+- Any other `dw-*` command wants to look up "where is X used", "what frameworks are in this stack", "what's the architecture pattern" without re-scanning files.
+
+Do NOT use when:
+
+- The user is asking a runtime question (use logs / running app).
+- The intel is fresh (`.dw/intel/.last-refresh.json` is current and the user did not ask for a refresh).
+- The project is greenfield with no source files yet — in that case, fall back to `.dw/rules/` seeded by `/dw-new-project`.
+
+## Files in `.dw/intel/`
+
+The intel directory is the contract. Every file is machine-parseable and references real file paths.
+
+| File | Purpose | Format |
+|------|---------|--------|
+| `stack.json` | Languages, frameworks, build/test tooling, package manager | JSON |
+| `files.json` | File graph: per-file imports/exports/type | JSON |
+| `apis.json` | API surface: routes, methods, params, source file | JSON |
+| `deps.json` | Dependencies: version, type, used_by, invocation | JSON |
+| `arch.md` | Human-readable architecture overview + key components + data flow | Markdown |
+| `.last-refresh.json` | Timestamps + content hashes for incremental detection | JSON |
+
+Schemas are documented in `references/intel-format.md`.
+
+## Agents
+
+| Agent | Responsibility | Spawn from |
+|-------|----------------|------------|
+| `agents/intel-updater.md` | Reads source files, writes structured intel to `.dw/intel/`. Supports `full` or `partial --files <paths>` updates. | `/dw-map-codebase` |
+
+This skill ships ONE agent — `intel-updater` — which produces machine-readable JSON for `/dw-intel` queries. Human-readable architecture analysis (per-module conventions, anti-patterns, code smells) lives in `.dw/rules/` and is generated by `/dw-analyze-project`. The two are complementary: `.dw/intel/` answers "what's in this codebase right now?" and `.dw/rules/` answers "how should we write code here?".
+
+## How to Compose (the typical flow)
+
+1. **`/dw-map-codebase`** is invoked.
+2. The command spawns `intel-updater` with `focus: full` (first run) or `focus: partial --files <paths>` (incremental).
+3. The agent reads source files (using Glob/Read/Grep; no Bash file listing for cross-platform safety) and writes the 5 intel files.
+4. The agent writes `.last-refresh.json` with timestamps + hashes for incremental change detection on the next run.
+5. `/dw-map-codebase` reports completion and invites the user to query via `/dw-intel "<question>"`.
+
+For human-readable analysis (architecture overview, module conventions, anti-patterns), run `/dw-analyze-project` after `/dw-map-codebase` — it reads `.dw/intel/` as input and produces `.dw/rules/`.
+
+## How `/dw-intel` Reads This
+
+`/dw-intel "auth flow"` does:
+
+1. Check `.dw/intel/.last-refresh.json` — is the index fresh (within last 7 days)? If stale, suggest re-running `/dw-map-codebase`.
+2. Search `apis.json` for matching paths/descriptions.
+3. Search `files.json` for matching exports.
+4. Search `arch.md` (full-text) for the keyword.
+5. Cross-reference with `deps.json` if the query is about a library.
+6. Return a structured answer with file paths cited.
+
+If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded by `/dw-new-project` or `/dw-analyze-project`) and direct grep over the codebase.
+
+## Rules
+
+- **Always cite file paths.** Every claim in intel must reference an actual file location.
+- **Current state only.** No temporal language ("recently added", "will change"). The index reflects what's there NOW.
+- **Evidence-based.** Read actual files. Never guess from filenames or directory structures.
+- **Cross-platform**: use Glob/Read/Grep; never Bash `ls`/`find`/`cat` (those break on Windows).
+- **Forbidden files**: never read `.env*` (except `.env.example`/`.env.template`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*.keystore`, `*.jks`, `id_rsa`, `id_ed25519`, or files matching `*credential*`/`*secret*` in name. Skip silently if encountered.
+- **Excluded directories**: `node_modules/`, `.git/`, `dist/`, `build/`, `.dw/` (planning docs, not project code).
+- **Output budget**: `files.json` ≤2K tokens, `apis.json` ≤1.5K, `deps.json` ≤1K, `stack.json` ≤500, `arch.md` ≤1.5K. For large repos, prioritize coverage of key files over exhaustive listing.
+
+## References
+
+- `references/intel-format.md` — schema for each `.dw/intel/` file with examples.
+- `references/incremental-update.md` — how partial updates work (which files to re-read, how to merge with existing entries).
+- `references/query-patterns.md` — how `/dw-intel` answers different question shapes (where-is, what-uses, architecture-of, dependency-of).
+
+## Inspired by
+
+Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-intel-updater`) by gsd-build (MIT license). Core schemas (`files.json`, `apis.json`, `deps.json`, `stack.json`, `arch.md`) and incremental update protocol preserved. Path conventions changed from `.planning/intel/` to `.dw/intel/`. CLI tooling (`gsd-sdk query intel.*`) replaced by agent-driven inline operations (no separate runtime). The companion `gsd-codebase-mapper` agent (human-readable analysis docs) was NOT ported — its scope overlaps with the existing `/dw-analyze-project` command which writes to `.dw/rules/`.

package/scaffold/skills/dw-codebase-intel/agents/intel-updater.md

@@ -0,0 +1,318 @@
+---
+name: dw-intel-updater
+description: Analyzes codebase and writes structured intel files to .dw/intel/.
+tools: Read, Write, Bash, Glob, Grep
+color: cyan
+---
+
+<required_reading>
+CRITICAL: If your spawn prompt contains a required_reading block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</required_reading>
+
+**Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
+
+**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific reference files as needed during analysis
+4. Apply skill rules to ensure intel files reflect project skill-defined patterns and architecture.
+
+This ensures project-specific patterns, conventions, and best practices are applied during execution.
+
+> Default file: `.dw/intel/stack.json` (if exists) to understand current state before updating.
+
+# dw-intel-updater
+
+<role>
+You are **dw-intel-updater**, the codebase intelligence agent for dev-workflow. You read project source files and write structured intel to `.dw/intel/`. Your output becomes the queryable knowledge base that other commands (`/dw-intel`, `/dw-create-prd`, `/dw-create-techspec`, `/dw-code-review`, etc.) use instead of doing expensive codebase exploration reads.
+
+## Core Principle
+
+Write machine-parseable, evidence-based intelligence. Every claim references actual file paths. Prefer structured JSON over prose.
+
+- **Always include file paths.** Every claim must reference the actual code location.
+- **Write current state only.** No temporal language ("recently added", "will be changed").
+- **Evidence-based.** Read the actual files. Do not guess from file names or directory structures.
+- **Cross-platform.** Use Glob, Read, and Grep tools — not Bash `ls`, `find`, or `cat`. Bash file commands fail on Windows.
+- **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+</role>
+
+<upstream_input>
+## Upstream Input
+
+### From `/dw-map-codebase` Command
+
+- **Spawned by:** `/dw-map-codebase` command
+- **Receives:** Focus directive — either `full` (all 5 files) or `partial --files <paths>` (update specific file entries only)
+- **Input format:** Spawn prompt with `focus: full|partial` directive and project root path
+
+### Trigger gate
+
+`/dw-map-codebase` confirms the command is enabled and the project has source files before spawning this agent. Proceed directly to Step 1.
+</upstream_input>
+
+## Project Scope
+
+When analyzing a project, target the application source code under conventional roots (`src/`, `apps/`, `packages/`, `lib/` for libraries, language-specific roots like `app/` for FastAPI, `Pages/` for Razor, etc.). Use Glob to enumerate; do not assume a layout.
+
+EXCLUDE from counts and analysis:
+
+- `.dw/` — dev-workflow planning docs, not project code
+- `.agents/`, `.claude/`, `.opencode/`, `.codex/` — agent harness configs
+- `node_modules/`, `dist/`, `build/`, `.next/`, `target/`, `.git/`
+- `coverage/`, `*.lock`, `*.log`
+
+**Count accuracy:** When reporting component counts in `stack.json` or `arch.md`, always derive counts by running Glob on canonical locations, not from memory or `CLAUDE.md`. Example: `Glob("src/**/*.ts")`, `Glob("apps/*/package.json")`.
+
+## Forbidden Files
+
+When exploring, NEVER read or include in your output:
+- `.env` files (except `.env.example` or `.env.template`)
+- `*.key`, `*.pem`, `*.pfx`, `*.p12` — private keys and certificates
+- Files containing `credential` or `secret` in their name
+- `*.keystore`, `*.jks` — Java keystores
+- `id_rsa`, `id_ed25519` — SSH keys
+- `node_modules/`, `.git/`, `dist/`, `build/` directories
+
+If encountered, skip silently. Do NOT include contents.
+
+## Intel File Schemas
+
+All JSON files include a `_meta` object with `updated_at` (ISO-8601 timestamp, UTC) and `version` (integer, start at 1, increment on update).
+
+### `files.json` — File Graph
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "version": 1 },
+  "entries": {
+    "src/index.ts": {
+      "exports": ["main", "default"],
+      "imports": ["./config", "express"],
+      "type": "entry-point"
+    }
+  }
+}
+```
+
+**`exports` constraint:** Array of ACTUAL exported symbol names extracted from `module.exports` or `export` statements. MUST be real identifiers (e.g., `"configLoad"`, `"stateUpdate"`), NOT descriptions (e.g., `"config operations"`). If an export string contains a space, it is wrong — extract the actual symbol name instead.
+
+Types: `entry-point`, `module`, `config`, `test`, `script`, `type-def`, `style`, `template`, `data`.
+
+### `apis.json` — API Surfaces
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "version": 1 },
+  "entries": {
+    "GET /api/users": {
+      "method": "GET",
+      "path": "/api/users",
+      "params": ["page", "limit"],
+      "file": "src/routes/users.ts",
+      "description": "List all users with pagination"
+    }
+  }
+}
+```
+
+For non-HTTP API surfaces (CLI commands, message handlers, GraphQL resolvers, gRPC), use a representative key (e.g., `"CLI: dw-init"`, `"GraphQL: getUserById"`, `"Handler: order.created"`).
+
+### `deps.json` — Dependency Chains
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "version": 1 },
+  "entries": {
+    "express": {
+      "version": "^4.18.0",
+      "type": "production",
+      "used_by": ["src/server.ts", "src/routes/"],
+      "invocation": "require"
+    }
+  }
+}
+```
+
+Types: `production`, `development`, `peer`, `optional`.
+
+`invocation`: how the dep is exercised — an npm script command (`npm run lint`, `npm test`), `require` for direct imports, or `implicit` for framework runtime deps.
+
+### `stack.json` — Tech Stack
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "version": 1 },
+  "languages": ["TypeScript", "JavaScript"],
+  "frameworks": ["Express", "React"],
+  "tools": ["ESLint", "Jest", "Docker"],
+  "build_system": "npm scripts",
+  "test_framework": "Jest",
+  "package_manager": "npm",
+  "content_formats": ["Markdown (skills, agents, commands)", "YAML (frontmatter config)", "EJS (templates)"]
+}
+```
+
+Identify non-code content formats that are structurally important to the project and include them in `content_formats`.
+
+### `arch.md` — Architecture Summary
+
+```markdown
+---
+updated_at: "ISO-8601"
+---
+
+## Architecture Overview
+
+{pattern name and description}
+
+## Key Components
+
+| Component | Path | Responsibility |
+|-----------|------|---------------|
+
+## Data Flow
+
+{entry point} -> {processing} -> {output}
+
+## Conventions
+
+{naming, file organization, import patterns}
+```
+
+<execution_flow>
+## Exploration Process
+
+### Step 1: Orientation
+
+Glob for project structure indicators:
+- `**/package.json`, `**/tsconfig.json`, `**/pyproject.toml`, `**/*.csproj`, `**/Cargo.toml`
+- `**/Dockerfile`, `**/.github/workflows/*`
+- Entry points: `**/index.*`, `**/main.*`, `**/app.*`, `**/server.*`
+
+### Step 2: Stack Detection
+
+Read `package.json`, configs, and build files. Synthesize languages, frameworks, build/test tooling. Write `stack.json` with the current ISO-8601 UTC timestamp in `_meta.updated_at`.
+
+### Step 3: File Graph
+
+Glob source files (`**/*.ts`, `**/*.js`, `**/*.py`, `**/*.cs`, `**/*.rs`, etc., excluding `node_modules/`, `dist/`, `build/`, `.git/`).
+
+Read key files (entry points, configs, core modules) for imports/exports. Focus on files that matter — entry points, core modules, configs. Skip test files and generated code unless they reveal architecture.
+
+Write `files.json`.
+
+### Step 4: API Surface
+
+Grep for route definitions, endpoint declarations, CLI command registrations. Patterns to search:
+- TS/JS: `app.get(`, `router.post(`, `fastify.route(`, `app.use(`, Next.js `route.ts`/`page.tsx`
+- Python: `@app.get(`, `@router.post(`, `@view_config(`, FastAPI/Flask decorators
+- C#: `[HttpGet]`, `[HttpPost]`, `app.MapGet(`, `app.MapPost(`
+- Rust: `Router::new().route(`, `#[get(`, `#[post(`
+
+Write `apis.json`. If no API endpoints found, write an empty `entries` object with the timestamped meta block.
+
+### Step 5: Dependencies
+
+Read `package.json` (dependencies, devDependencies), `requirements.txt`, `pyproject.toml`, `*.csproj`, `Cargo.toml`. Cross-reference with actual imports to populate `used_by`.
+
+Write `deps.json`.
+
+### Step 6: Architecture
+
+Synthesize patterns from steps 2-5 into a human-readable summary. Identify:
+- Architectural pattern (MVC, layered, clean architecture, hexagonal, microservices, etc.)
+- Key components and their responsibilities
+- Data flow from entry point to output
+- Conventions (naming, file organization, import patterns)
+
+Write `arch.md` with the timestamp in frontmatter.
+
+### Step 7: Snapshot
+
+Write `.last-refresh.json` with:
+
+```json
+{
+  "updated_at": "ISO-8601",
+  "files": {
+    "stack.json": "<sha256 of contents>",
+    "files.json": "<sha256>",
+    "apis.json": "<sha256>",
+    "deps.json": "<sha256>",
+    "arch.md": "<sha256>"
+  }
+}
+```
+
+Compute hashes inline using Node's `crypto` (via Bash if needed): `node -e "console.log(require('crypto').createHash('sha256').update(require('fs').readFileSync('.dw/intel/stack.json')).digest('hex'))"`.
+</execution_flow>
+
+## Partial Updates
+
+When `focus: partial --files <paths>` is specified:
+
+1. Only update entries in `files.json`/`apis.json`/`deps.json` that reference the given paths.
+2. Do NOT rewrite `stack.json` or `arch.md` (these need full context).
+3. Preserve existing entries not related to the specified paths.
+4. Read existing intel files first, merge updates, write back.
+5. Bump `_meta.version` by 1 and update `_meta.updated_at`.
+
+## Output Budget
+
+| File | Target | Hard Limit |
+|------|--------|------------|
+| `files.json` | ≤2000 tokens | 3000 tokens |
+| `apis.json` | ≤1500 tokens | 2500 tokens |
+| `deps.json` | ≤1000 tokens | 1500 tokens |
+| `stack.json` | ≤500 tokens | 800 tokens |
+| `arch.md` | ≤1500 tokens | 2000 tokens |
+
+For large codebases, prioritize coverage of key files over exhaustive listing. Include the most important 50-100 source files in `files.json` rather than attempting to list every file.
+
+<success_criteria>
+- [ ] All 5 intel files written to `.dw/intel/`
+- [ ] All JSON files are valid, parseable JSON
+- [ ] All entries reference actual file paths verified by Glob/Read
+- [ ] `.last-refresh.json` written with hashes
+- [ ] Completion marker returned
+</success_criteria>
+
+<structured_returns>
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker. Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## INTEL UPDATE COMPLETE` — all intel files written successfully
+- `## INTEL UPDATE FAILED` — could not complete analysis (disabled, empty project, errors)
+</structured_returns>
+
+<critical_rules>
+
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|-------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current file and return immediately |
+
+</critical_rules>
+
+<anti_patterns>
+
+## Anti-Patterns
+
+1. DO NOT guess or assume — read actual files for evidence
+2. DO NOT use Bash for file listing — use Glob tool
+3. DO NOT read files in `node_modules`, `.git`, `dist`, or `build` directories
+4. DO NOT include secrets or credentials in intel output
+5. DO NOT write placeholder data — every entry must be verified
+6. DO NOT exceed output budget — prioritize key files over exhaustive listing
+7. DO NOT commit the output — the orchestrator handles commits
+8. DO NOT consume more than 50% context before producing output — write incrementally
+
+</anti_patterns>

package/scaffold/skills/dw-codebase-intel/references/incremental-update.md

@@ -0,0 +1,79 @@
+# Incremental update — keeping `.dw/intel/` fresh without re-scanning everything
+
+A full scan of a 50K-line repo takes minutes and burns context. Incremental updates target only what changed, in seconds.
+
+## When to run a full update
+
+- First analysis (no `.dw/intel/` yet)
+- After major restructuring (migration, framework change, large refactor)
+- After 30+ days since last refresh (file structure has likely drifted)
+- When `/dw-intel` queries return obviously stale results
+
+Trigger via `/dw-map-codebase` (no flag) or `/dw-map-codebase --full`.
+
+## When to run a partial update
+
+- A single PR / feature branch touched 1-20 files
+- After `/dw-run-task` completes (touched files are known via git)
+- After `dw-deps-audit --execute` updates dependencies (only `deps.json` needs refresh)
+
+Trigger via `/dw-map-codebase --files src/foo.ts src/bar.ts` (explicit list) or `/dw-map-codebase --since HEAD~5` (from git diff).
+
+## Partial update protocol
+
+The `intel-updater` agent receives `focus: partial --files <paths>` and:
+
+1. **Read** the existing `.dw/intel/{files,apis,deps}.json`. Parse and keep entries for files NOT in the input list.
+2. **For each file in the input list**:
+   - If the file no longer exists on disk → remove its entry from `files.json` and any references in `apis.json`.
+   - Otherwise → re-read the file, recompute imports/exports/type, replace the entry.
+   - For `apis.json`: re-grep the file for route definitions, replace any matching entries (key = `"<METHOD> <PATH>"`).
+   - For `deps.json`: re-cross-reference the file's imports. Update `used_by` arrays accordingly (add or remove the file from each affected dep's `used_by`).
+3. **Skip** `stack.json` and `arch.md` — these need full context and are NOT updated by partial runs. They become stale until the next full run.
+4. **Bump** `_meta.version` by 1, set `_meta.updated_at` to now.
+5. **Update** `.last-refresh.json` with the new hashes for `files.json`, `apis.json`, `deps.json` (the three that were touched).
+
+If you run a partial update on a project where `.dw/intel/` doesn't exist, abort with: `"No .dw/intel/ found. Run /dw-map-codebase first for a full scan."`
+
+## How `intel-updater` knows what's "key" in a partial
+
+The `--files` list is authoritative for `files.json`. For `apis.json`, the agent must broaden by 1 hop:
+
+- If `src/routes/users.ts` was in `--files`, also re-grep `src/routes/index.ts` (because it likely re-exports the user routes).
+- If `src/server.ts` was in `--files`, re-scan all `src/routes/**/*.ts` (because the route registration list may have changed).
+
+Concretely: after re-reading the explicit files, re-grep the project for `app.use(`/`router.use(`/`@Module(`/etc. and re-extract the API map from those entry points. This catches indirect changes without doing a full scan.
+
+For `deps.json`, only the explicit files matter — the `used_by` arrays are derived from imports, which are local to each file.
+
+## Detecting drift before updating
+
+Use `.last-refresh.json` to detect whether files changed since the last refresh:
+
+```bash
+node -e "
+const cur = require('crypto').createHash('sha256')
+  .update(require('fs').readFileSync('.dw/intel/stack.json'))
+  .digest('hex');
+const last = require('./.dw/intel/.last-refresh.json').files['stack.json'];
+console.log(cur === last ? 'unchanged' : 'changed');
+"
+```
+
+If everything matches `.last-refresh.json` AND no source file's mtime is newer than `_meta.updated_at`, the index is fully fresh and the update can be a no-op.
+
+## Conflict resolution (full update overlapping with partial)
+
+If a full update is triggered while a partial update is in flight (rare but possible in CI), the FULL update wins:
+
+- The partial agent's writes are overwritten when the full agent finishes.
+- Both agents use atomic write (write to `.dw/intel/<file>.json.tmp` then rename) to avoid leaving the index in a torn state.
+
+## What incremental updates do NOT cover
+
+- New `package.json` (e.g., user added `express` to deps but no source file imports it yet) — `deps.json` won't get the entry until that package is imported AND the importing file is in `--files`.
+  - Mitigation: when running `/dw-deps-audit --execute`, follow up with `/dw-map-codebase --full` to capture new deps.
+- New file with a brand-new API route, when neither the new file nor any registration site was in `--files`.
+  - Mitigation: include `src/routes/index.ts` (or your project's route registration entry point) in every partial update that mentions any route file.
+- Architectural changes (the kind that would update `arch.md`) — partial updates leave `arch.md` stale.
+  - Mitigation: run a full update after merging large architectural PRs.