devlyn-cli 1.7.3 → 1.8.1

package/CLAUDE.md

@@ -68,6 +68,26 @@ Optional flags:
 - `--skip-docs` — skip update-docs phase
 - `--with-codex [evaluate|review|both]` — use OpenAI Codex as cross-model evaluator/reviewer (requires codex-mcp-server)
 
+## Preflight Check (Post-Roadmap Verification)
+
+After completing a roadmap (or a phase), verify that everything was actually implemented correctly:
+
+```
+/devlyn:preflight
+```
+
+This reads every commitment from VISION.md, ROADMAP.md, and item specs, then audits the codebase evidence-based. Finds: missing features, incomplete implementations, spec divergence, bugs, stale documentation. Also checks in the browser for web projects.
+
+Output: `.devlyn/PREFLIGHT-REPORT.md` with categorized findings (MISSING, INCOMPLETE, DIVERGENT, BROKEN, STALE_DOC). Confirmed gaps can be promoted to new roadmap items for auto-resolve.
+
+Optional flags:
+- `--phase N` — audit only phase N items
+- `--autofix` — auto-promote CRITICAL/HIGH findings and run auto-resolve
+- `--skip-browser` — skip browser validation
+- `--skip-docs` — skip documentation audit
+
+**Recommended workflow**: `/devlyn:ideate` → `/devlyn:auto-resolve` (repeat) → `/devlyn:preflight` → fix gaps → `/devlyn:preflight` (verify)
+
 ## Manual Pipeline (Step-by-Step Control)
 
 When you want to run each step yourself with review between phases:

package/README.md

@@ -31,12 +31,12 @@ That's it. The interactive installer handles everything. Run it again anytime to
 
 ---
 
-## How It Works — Two Commands, Full Cycle
+## How It Works — Three Steps, Full Cycle
 
 devlyn-cli turns Claude Code into an autonomous development pipeline. The core loop is simple:
 
 ```
-ideate  →  auto-resolve  →  ship  →  repeat
+ideate  →  auto-resolve  →  preflight  →  fix gaps  →  ship
 ```
 
 ### Step 1 — Plan with `/devlyn:ideate`
@@ -78,6 +78,26 @@ Build → Browser Test → Evaluate → Fix Loop → Simplify → Review → Sec
 
 Skip phases you don't need: `--skip-browser`, `--skip-review`, `--skip-clean`, `--skip-docs`, `--max-rounds 6`
 
+### Step 3 — Verify with `/devlyn:preflight`
+
+After implementing all roadmap items, run a final alignment check:
+
+```
+/devlyn:preflight
+```
+
+Reads every commitment from your vision, roadmap, and item specs, then audits the codebase evidence-based. Catches what you missed:
+
+| Category | What It Finds |
+|---|---|
+| `MISSING` | In roadmap but not implemented |
+| `INCOMPLETE` | Started but unfinished |
+| `DIVERGENT` | Implemented differently than spec |
+| `BROKEN` | Has a bug preventing it from working |
+| `STALE_DOC` | Docs don't match current code |
+
+Confirmed gaps become new roadmap items — feed them back into auto-resolve. Use `--autofix` to do this automatically, or `--phase 2` to check only one phase.
+
 ### Bonus — Dual-Model Mode with Codex
 
 Install the Codex MCP server during setup, then:
@@ -127,6 +147,7 @@ When you want step-by-step control instead of the full pipeline.
 
 | Command | What It Does |
 |---|---|
+| `/devlyn:preflight` | Verify codebase matches vision/roadmap — gap analysis with evidence |
 | `/devlyn:product-spec` | Generate or update product specs |
 | `/devlyn:feature-spec` | Turn product spec → implementable feature spec |
 | `/devlyn:discover-product` | Scan codebase → auto-generate product docs |

package/config/skills/devlyn:preflight/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: devlyn:preflight
+description: >
+  Final alignment check between vision/roadmap documents and the actual codebase — the last step
+  before declaring a roadmap phase complete. Reads every commitment from VISION.md, ROADMAP.md,
+  and item specs, then audits the implementation with evidence-based analysis citing file:line
+  for every finding. Catches missing features, incomplete implementations, spec divergence, bugs,
+  and documentation drift. Also validates in the browser for web projects and checks documentation
+  alignment. Use when the user has finished implementing a roadmap and wants to verify nothing was
+  missed. Triggers on "preflight", "preflight check", "gap analysis", "gap check", "did I miss
+  anything", "check against the roadmap", "verify implementation", "alignment check", "are we done",
+  "final check before shipping", or when the user says they've finished implementing and wants
+  verification. This is different from /devlyn:evaluate (which grades a single changeset) and
+  /devlyn:review (which reviews code quality) — preflight audits the ENTIRE project against its
+  planning documents holistically.
+---
+
+# Vision-to-Implementation Preflight Check
+
+The final gate before you declare "done." Read every promise the planning documents made, then verify each one against the actual codebase — evidence-based, no guessing.
+
+<preflight_config>
+$ARGUMENTS
+</preflight_config>
+
+<why_this_matters>
+After implementing a full roadmap, gaps are almost inevitable. Features get partially implemented, edge cases from specs get skipped, implementations drift from the original design, and docs fall out of sync. These gaps compound — a missing integration here, a forgotten error state there — until the shipped product doesn't match the vision.
+
+This skill catches those gaps systematically, before users do. The difference between "we built everything on the list" and "we actually delivered what we promised."
+</why_this_matters>
+
+<evidence_standard>
+Every finding must cite evidence: file:line for code, specific doc section for documentation, screenshot for browser issues. A finding without evidence is speculation — exclude it.
+
+The corollary: if you search thoroughly and can't find evidence that something exists, that IS evidence it's missing. "Searched for X across src/ and found no implementation" is a valid, evidence-based finding.
+
+This matters because the report feeds into auto-resolve. Vague findings produce vague fixes.
+</evidence_standard>
+
+## Flags
+
+Parse from `<preflight_config>`:
+- `--phase N` — audit only phase N items (default: all phases)
+- `--autofix` — auto-promote all findings to roadmap items and run auto-resolve on each
+- `--skip-browser` — skip browser validation
+- `--skip-docs` — skip documentation audit
+
+Example: `/devlyn:preflight --phase 2 --skip-browser`
+
+## PHASE 0: DISCOVER & SCOPE
+
+1. **Find planning documents** — search in parallel:
+   - `docs/VISION.md`
+   - `docs/ROADMAP.md`
+   - `docs/roadmap/` directory (item specs)
+   - If none found, stop clearly: "No vision/roadmap documents found. Run `/devlyn:ideate` first to create them."
+
+2. **Determine scope**:
+   - If `--phase N` specified → only read specs in `docs/roadmap/phase-N/`
+   - Otherwise → read all phases
+   - Read `docs/roadmap/backlog/` to identify deferred items (excluded from audit)
+
+3. **Check for prior state**:
+   - If `.devlyn/PREFLIGHT-REPORT.md` exists from a previous run → note it for delta comparison in PHASE 4
+   - If `.devlyn/preflight-accepted.md` exists → load accepted divergences to filter in PHASE 4
+
+4. **Announce**:
+```
+Preflight check starting
+Scope: [Phase N / All phases]
+Documents: VISION.md, ROADMAP.md, [N] item specs
+Deferred items (excluded): [N]
+Previous run: [found — will show delta / none]
+Phases: Extract → Audit → [Browser] → [Docs] → Report → Triage
+```
+
+## PHASE 1: EXTRACT COMMITMENTS
+
+Read all in-scope planning documents and build a **commitment registry** — every concrete promise the documents make. This registry is the grading rubric for all auditors.
+
+1. **Read in parallel**: VISION.md, ROADMAP.md, all in-scope item specs, phase `_overview.md` files
+
+2. **Extract from each item spec**:
+   - Requirements section → each bullet becomes a `FEATURE` or `BEHAVIOR` commitment
+   - Constraints section → each becomes a `CONSTRAINT` commitment
+   - Dependencies section → each becomes an `INTEGRATION` commitment
+   - Explicit test requirements → `TEST` commitments
+
+3. **Extract from VISION.md**: high-level success criteria — checked at a broader level ("the system supports X" rather than "file Y has function Z")
+
+4. **Filter out** (excluded from audit entirely):
+   - Items in `backlog/` or `deferred.md`
+   - Items with `status: cut` in ROADMAP.md
+   - Out of Scope entries — these are anti-commitments (things promised NOT to build)
+
+5. **Separate planned items**: Items with `status: planned` in their spec frontmatter or "Planned" in ROADMAP.md are NOT expected to be implemented yet. Include them in a `[PLANNED]` section of the registry for visibility, but do NOT audit them or report them as findings. This distinction matters — flagging planned items as MISSING creates noise and buries the real gaps in work that was supposed to be done.
+
+5. **Write to `.devlyn/commitment-registry.md`**:
+
+```markdown
+# Commitment Registry
+Generated: [timestamp]
+Scope: [phase N / all]
+Total commitments: [N]
+
+## Phase 1: [name]
+### 1.1 [item title] (spec status: [done/in-progress/planned])
+- [FEATURE] User can sign up with email and password
+- [BEHAVIOR] Failed login returns 401 with specific error message
+- [CONSTRAINT] Passwords hashed with bcrypt, min 8 characters
+- [INTEGRATION] Auth middleware applied to all /api/* routes
+- [TEST] Auth flow covered by E2E tests
+
+## Anti-Commitments (Out of Scope)
+- [item 1.1] Does NOT include social login
+- [item 1.2] Does NOT include real-time inventory sync
+
+## Not Started (Planned — excluded from audit)
+### 2.1 [item title] (spec status: planned)
+- [FEATURE] WebSocket connection on page load
+- [FEATURE] Real-time task list updates
+[These items are tracked for visibility but NOT audited or reported as findings]
+```
+
+## PHASE 2: AUDIT
+
+Spawn all applicable auditors in parallel. Each reads `.devlyn/commitment-registry.md` and investigates from their perspective.
+
+### code-auditor (always)
+
+Spawn a subagent with `mode: "bypassPermissions"`. Read the full prompt from `references/auditors/code-auditor.md` and pass it to the subagent.
+
+The code-auditor classifies each commitment as IMPLEMENTED, MISSING, INCOMPLETE, DIVERGENT, or BROKEN — with file:line evidence. Also catches cross-feature integration gaps and constraint violations. Writes to `.devlyn/audit-code.md`.
+
+### docs-auditor (unless --skip-docs)
+
+Spawn a subagent with `mode: "bypassPermissions"`. Read the full prompt from `references/auditors/docs-auditor.md` and pass it to the subagent.
+
+Checks: ROADMAP.md status accuracy, README alignment, API doc coverage, VISION.md currency, item spec status. Writes to `.devlyn/audit-docs.md`.
+
+### browser-auditor (conditional)
+
+**Skip conditions** (check in order):
+1. `--skip-browser` flag → skip
+2. No web-relevant files in project (no `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `page.*`, `layout.*`) → skip with note "Browser validation skipped — no web files detected"
+3. Otherwise → spawn
+
+Spawn a subagent with `mode: "bypassPermissions"`. Read the full prompt from `references/auditors/browser-auditor.md` and pass it to the subagent.
+
+Tests user-facing features in the browser against commitment registry. Writes to `.devlyn/audit-browser.md`.
+
+**After all auditors complete**: Read each audit file and proceed to PHASE 3.
+
+## PHASE 3: SYNTHESIZE & REPORT
+
+After all auditors report:
+
+1. **Read all audit files** in parallel:
+   - `.devlyn/audit-code.md`
+   - `.devlyn/audit-docs.md` (if exists)
+   - `.devlyn/audit-browser.md` (if exists)
+
+2. **Deduplicate**: If multiple auditors flagged the same issue, merge into one finding at the highest severity.
+
+3. **Filter accepted divergences**: If `.devlyn/preflight-accepted.md` exists, remove any findings that match accepted entries.
+
+4. **Classify each finding** using these categories:
+
+| Category | Description | Typical source |
+|----------|-------------|----------------|
+| `MISSING` | In roadmap but not implemented | code-auditor |
+| `INCOMPLETE` | Implementation started but unfinished | code-auditor |
+| `DIVERGENT` | Implemented differently than spec says | code-auditor |
+| `BROKEN` | Implemented but has a bug | code-auditor, browser-auditor |
+| `UNDOCUMENTED` | Implemented but not in docs | docs-auditor |
+| `STALE_DOC` | Docs don't match current code | docs-auditor |
+
+5. **Assign severity**: CRITICAL (blocks shipping), HIGH (should fix), MEDIUM (fix or accept), LOW (cosmetic)
+
+6. **Compare with previous run** (if `.devlyn/PREFLIGHT-REPORT.md` existed):
+   - `RESOLVED`: finding from previous run no longer present
+   - `PERSISTS`: finding still present
+   - `NEW`: finding not in previous run
+
+7. **Generate `.devlyn/PREFLIGHT-REPORT.md`**:
+
+```markdown
+# Preflight Report
+Generated: [timestamp]
+Scope: [phase N / all]
+Previous run: [timestamp / none]
+
+## Summary
+| Category | Count |
+|----------|-------|
+| MISSING | [N] |
+| INCOMPLETE | [N] |
+| DIVERGENT | [N] |
+| BROKEN | [N] |
+| UNDOCUMENTED | [N] |
+| STALE_DOC | [N] |
+| **Total findings** | **[N]** |
+
+## Delta (vs previous run)
+- Resolved: [N]
+- Persists: [N]
+- New: [N]
+
+## Commitment Coverage
+- Active commitments (done/in-progress specs): [N]
+- Verified (IMPLEMENTED): [N] ([%])
+- Issues found: [N] ([%])
+- Planned items (excluded from audit): [N] across [M] specs
+
+## Findings
+
+### CRITICAL
+- **[MISSING]** `1.2` — Order cancellation flow
+  - **Commitment**: "User can cancel pending orders within 24 hours"
+  - **Evidence**: No cancellation endpoint in `src/api/orders/`. No cancel button in `src/components/OrderDetail.tsx`.
+  - **Impact**: Core user workflow completely absent.
+
+### HIGH
+- **[INCOMPLETE]** `1.1` — Error handling on signup
+  - **Commitment**: "Failed signup shows specific validation errors"
+  - **Evidence**: `src/api/auth/signup.ts:34` returns generic 500. No field-level validation.
+  - **Impact**: Users see "Something went wrong" instead of actionable feedback.
+
+### MEDIUM
+...
+
+### LOW
+...
+
+## Documentation Findings
+- [STALE_DOC] ROADMAP.md: Item 1.3 status "In Progress" → should be "Done"
+- [UNDOCUMENTED] WebSocket real-time updates not mentioned in README
+
+## What's Verified
+[Explicitly list areas that passed — balanced feedback prevents over-correction]
+- Auth flow: all 5 commitments verified (signup, login, logout, password reset, session management)
+- Database schema: matches all spec constraints
+
+## Not Started (Expected — Planned Items)
+[List planned items here for visibility, not as findings]
+- 2.1 Real-time Updates — status: planned, 5 commitments
+- 2.2 Team Management — status: planned, 6 commitments
+These items are acknowledged future work per the roadmap. They will be audited when their status changes to in-progress or done.
+
+## Accepted Divergences (from previous runs)
+- [list any, or "None"]
+```
+
+8. **Present the report** to the user with a summary.
+
+## PHASE 4: TRIAGE & PROMOTE
+
+How this phase runs depends on the `--autofix` flag:
+
+### Without --autofix (default — interactive)
+
+Present findings and guide the user through triage:
+
+```
+Preflight found [N] findings across [categories].
+
+For each finding, you can:
+1. **Promote** → creates a roadmap item spec, adds to ROADMAP.md
+2. **Accept** → marks as intentional divergence (won't flag on future runs)
+3. **Skip** → leave for later
+
+Which findings would you like to promote to the roadmap?
+```
+
+**When the user confirms findings to promote:**
+
+1. **Generate item specs** for each confirmed finding, following the ideate template format:
+   ```markdown
+   ---
+   id: "[phase].[next-number]"
+   title: "[Fix/Add: description]"
+   phase: [N]
+   status: planned
+   priority: [derived from finding severity]
+   complexity: [estimated from finding scope]
+   depends-on: []
+   ---
+
+   # [id] [Title]
+
+   ## Context
+   Preflight check identified this gap against the original roadmap specification.
+   [Brief context from the original commitment and what's wrong]
+
+   ## Objective
+   [What needs to be true after this is fixed]
+
+   ## Requirements
+   - [ ] [Specific fix requirement derived from the finding]
+   - [ ] [Verification step]
+
+   ## Constraints
+   - Must align with original spec at docs/roadmap/phase-N/[original-item].md
+
+   ## Out of Scope
+   - Changes beyond what the original spec requires
+   ```
+
+2. **Place specs** in the appropriate roadmap phase directory (same phase as the original item, or a new "fixes" phase if multiple phases are affected)
+
+3. **Update ROADMAP.md** with new rows for promoted findings
+
+4. **Record accepted divergences** in `.devlyn/preflight-accepted.md`:
+   ```markdown
+   # Accepted Divergences
+   # Findings marked as intentional — excluded from future preflight runs
+
+   - [item-id] [commitment]: [reason accepted]
+   ```
+
+5. **STALE_DOC findings**: Fix these directly — update ROADMAP.md statuses, item spec frontmatter, and VISION.md "What's Next" sections. These are factual corrections, not implementation decisions.
+
+6. **Suggest next steps**:
+```
+Triage complete.
+- [N] findings promoted to roadmap ([list item IDs])
+- [N] divergences accepted
+- [N] doc issues fixed directly
+
+Next steps:
+- To implement fixes: /devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-N/[id]-[name].md"
+  - For high-stakes fixes (CRITICAL severity or complex DIVERGENT findings), add `--with-codex both` to cross-validate the fix and review with Codex
+- To re-run preflight after fixes: /devlyn:preflight [same flags]
+- To add new features discovered during audit: /devlyn:ideate expand
+```
+
+### With --autofix
+
+1. Auto-promote all CRITICAL and HIGH findings to roadmap items (steps 1-3 above)
+2. Fix all STALE_DOC findings directly
+3. MEDIUM and LOW findings are reported but not auto-promoted (include in report with note "manually promote if needed")
+4. For each promoted item, spawn `/devlyn:auto-resolve` sequentially:
+   ```
+   /devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-N/[id]-[name].md"
+   ```
+5. After all auto-resolve runs complete, re-run preflight (without --autofix) as a verification pass
+6. Present final delta report showing what was resolved
+
+<autofix_safety>
+Auto-promoting only CRITICAL and HIGH findings prevents noise — MEDIUM/LOW findings often benefit from human judgment on whether they're worth fixing or should be accepted as intentional divergence. The user can always manually promote remaining findings after reviewing the report.
+</autofix_safety>
+
+## Language
+
+Generate all documents and reports in the language the user communicates in. Keep technical terms (file paths, code references, category names like MISSING/DIVERGENT) in English for consistency with the rest of the devlyn toolchain.

package/config/skills/devlyn:preflight/references/auditors/browser-auditor.md

@@ -0,0 +1,32 @@
+# Browser Auditor Prompt
+
+Use this as the subagent prompt when spawning the browser-auditor in PHASE 2.
+
+**Skip conditions** (check in order before spawning):
+1. `--skip-browser` flag → skip
+2. No web-relevant files in project (no `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `page.*`, `layout.*`) → skip with note "Browser validation skipped — no web files detected"
+3. Otherwise → spawn
+
+---
+
+You are performing browser-based verification of a web application against its planning commitments.
+
+Read `.devlyn/commitment-registry.md` for the user-facing features that should be working.
+
+**Your workflow:**
+1. Read `.claude/skills/devlyn:browser-validate/SKILL.md` for the browser testing methodology and tier system
+2. Start the dev server
+3. For each user-facing FEATURE and BEHAVIOR commitment:
+   - Navigate to the relevant page
+   - Perform the user action described in the commitment
+   - Verify the expected outcome
+   - Take screenshots as evidence
+4. Pay special attention to:
+   - Error states: trigger errors and verify error UI appears
+   - Empty states: verify empty state UI for lists/collections
+   - Loading states: verify loading indicators during async operations
+   - Edge cases explicitly mentioned in specs
+
+Write findings to `.devlyn/audit-browser.md` with screenshot paths as evidence.
+
+If browser tools are unavailable, fall back to HTTP smoke testing (curl endpoints, verify response codes and shapes). Note the reduced coverage in your findings.

package/config/skills/devlyn:preflight/references/auditors/code-auditor.md

@@ -0,0 +1,77 @@
+# Code Auditor Prompt
+
+Use this as the subagent prompt when spawning the code-auditor in PHASE 2.
+
+---
+
+You are auditing a codebase against its planning commitments. Your job is to verify that every commitment was actually implemented — and implemented correctly.
+
+Read `.devlyn/commitment-registry.md` for the full list of commitments to verify. Skip any items in the "Not Started (Planned)" section — those are acknowledged future work, not gaps.
+
+**For each active commitment (not planned):**
+1. Search the codebase for its implementation (use Grep, Glob, Read in parallel where possible)
+2. Read the implementing code thoroughly — line by line for critical paths
+3. Classify the commitment:
+
+| Classification | Meaning | Evidence required |
+|---|---|---|
+| IMPLEMENTED | Code exists and fulfills the commitment | file:line showing the implementation |
+| MISSING | No implementation found after thorough search | What you searched for and where |
+| INCOMPLETE | Implementation started but doesn't fully satisfy | What's there + what's missing, both with file:line |
+| DIVERGENT | Implementation does something different than specified | Spec requirement vs actual behavior, with file:line |
+| BROKEN | Implementation exists but has a bug preventing it from working | The bug with file:line |
+
+**Beyond the commitment checklist**, also investigate:
+- Cross-feature integration gaps: features that should connect but don't
+- Error handling specified in specs but not implemented in code
+- Constraints specified but violated (e.g., spec says "use bcrypt" but code uses plaintext)
+- Edge cases explicitly mentioned in specs but unhandled
+
+<code_auditor_calibration>
+Calibrate your judgment with these examples:
+
+**This IS a finding (INCOMPLETE)**:
+Spec says "failed API calls display an error banner with retry button."
+Code at `src/components/Dashboard.tsx:42` has `catch (e) { console.error(e) }` — error is logged but no UI feedback. The user sees a blank screen on failure.
+Why: logging is not user-facing error handling. The commitment specifies visible feedback.
+
+**This IS a finding (DIVERGENT)**:
+Spec says "alert admin via push notification when stock below threshold."
+Code at `src/inventory/alerts.ts:28` sends an email instead.
+Why: the channel matters — push notification has different urgency characteristics than email.
+
+**This is NOT a finding**:
+Spec says "store user preferences." Code stores them in localStorage instead of the database.
+Why: unless the spec explicitly requires server-side persistence, the implementation choice is reasonable. The commitment is fulfilled.
+
+**General rule**: focus on whether the user-facing OUTCOME matches the commitment, not on internal implementation details. But when the spec explicitly constrains HOW something should work, verify that too.
+</code_auditor_calibration>
+
+Write findings to `.devlyn/audit-code.md`:
+
+```markdown
+# Code Audit Findings
+
+## Summary
+- Commitments checked: [N]
+- IMPLEMENTED: [N]
+- MISSING: [N]
+- INCOMPLETE: [N]
+- DIVERGENT: [N]
+- BROKEN: [N]
+
+## Findings
+
+### [MISSING] 1.1 — Email validation on signup
+**Commitment**: "Email format validated on signup"
+**Evidence**: Searched `src/auth/`, `src/validators/`, `src/api/auth*`. No validation found. `src/api/auth/signup.ts:15` accepts email parameter without any format check.
+**Severity**: HIGH
+**Impact**: Invalid emails enter the database, breaking password reset flow.
+
+### [DIVERGENT] 1.3 — Inventory threshold alerts
+**Commitment**: "Alert admin via push notification when stock below threshold"
+**Spec says**: Push notification
+**Code does**: Email only (`src/inventory/alerts.ts:28`)
+**Severity**: MEDIUM
+**Impact**: Alerts work but through a lower-urgency channel than specified.
+```

package/config/skills/devlyn:preflight/references/auditors/docs-auditor.md

@@ -0,0 +1,38 @@
+# Docs Auditor Prompt
+
+Use this as the subagent prompt when spawning the docs-auditor in PHASE 2.
+
+---
+
+You are auditing documentation alignment for a project. Your job is to find mismatches between what the docs say and what the code actually does.
+
+Read `.devlyn/commitment-registry.md` for context on what was planned.
+
+**Check these dimensions:**
+
+1. **ROADMAP.md status accuracy**: For each item marked "Done" in ROADMAP.md, verify the implementation exists. For items marked "In Progress", check if they're actually complete or still in progress. Status mismatches are common and misleading.
+
+2. **README alignment**: Compare features listed in README.md against actual implementation. Find features claimed but not built (misleading) and features built but not mentioned (undocumented).
+
+3. **API documentation**: If API docs exist (`docs/api*`, swagger, openapi), compare documented endpoints against actual route files. Find undocumented endpoints and documented-but-missing endpoints.
+
+4. **VISION.md currency**: Check if "What's Next" or future sections reference work that's already done, or if success criteria have been met without acknowledgment.
+
+5. **Item spec status accuracy**: For each item spec, verify the frontmatter `status` field matches reality. An item marked `planned` that's fully implemented should be updated to `done`.
+
+Write findings to `.devlyn/audit-docs.md`:
+
+```markdown
+# Documentation Audit Findings
+
+## ROADMAP.md Status Accuracy
+- [STALE_DOC] Item 1.3 marked "In Progress" — implementation is complete (evidence: src/inventory/ fully implemented)
+- [STALE_DOC] Item 2.1 marked "Done" — only partially implemented (missing: webhook handler)
+
+## README Alignment
+- [UNDOCUMENTED] Real-time notifications exist in code but README doesn't mention them
+- [STALE_DOC] README claims "SSO support" — no SSO implementation found
+
+## Item Spec Status
+- [STALE_DOC] docs/roadmap/phase-1/1.2-order-mgmt.md: status says "planned", should be "done"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "1.7.3",
+  "version": "1.8.1",
   "description": "AI development toolkit for Claude Code — ideate, auto-resolve, and ship with context engineering and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {