agentflight 0.3.2 → 0.4.0

package/docs/roadmap/v0.4.0-review-intelligence-plan.md

@@ -0,0 +1,882 @@
+# AgentFlight v0.4.0 Review Intelligence Plan
+
+## Product Goal
+
+AgentFlight v0.4.0 should help developers decide where to review first, why those files matter, what proof exists, what proof is missing, and whether the session is ready for human review.
+
+The release should build on the v0.1 through v0.3 arc:
+
+- v0.1: local session recording and proof artifacts.
+- v0.2: real verification evidence.
+- v0.3: snapshots and timelines.
+- v0.4: deterministic review intelligence over the recorded local evidence.
+
+AgentFlight should remain the control room around AI coding agents. It should not become a coding agent, CI system, cloud service, or PR automation product in this release.
+
+## Recommended Scope
+
+Recommendation: **Option B: Review focus ranking + proof gap detection + readiness model + config-driven generated/internal file filters.**
+
+Why this scope:
+
+- Review intelligence is the primary product direction and directly improves `status`, `report`, `replay`, and `resume`.
+- Dogfooding showed generated/internal artifacts can still distort review focus. v0.3.3 fixed AgentFlight runtime artifacts; v0.4.0 should let users configure additional local ignore patterns such as `.projscan-memory/**`.
+- ProjScan enrichment is valuable, but depending on unstable or human-formatted output would make AgentFlight brittle. v0.4.0 should keep the integration defensive and prepare a clean hook for future structured hints.
+
+Do not include ProjScan-enriched ranking in v0.4.0 unless ProjScan exposes a stable machine-readable contract before implementation begins.
+
+## Non-Goals
+
+Do not build these in v0.4.0:
+
+- GitHub PR comments.
+- JSON output.
+- CI integration.
+- Cloud sync.
+- Login.
+- Billing.
+- Pro or Team gating.
+- GitHub App.
+- LLM calls.
+- Source upload.
+- Review automation that claims a human review happened.
+- Broad replay redesign.
+- Full diff capture by default.
+- Hosted dashboards.
+
+Explicitly defer these dogfood findings:
+
+- Interrupted verification cleanup.
+- Long verification heartbeat or progress output.
+- Tool availability messaging alignment.
+- Deeper ProjScan risk enrichment.
+- Larger report/replay design system work beyond surfacing review intelligence.
+
+## User Stories
+
+1. As a developer using Codex or Claude Code, I want AgentFlight to tell me which changed files need review first so I can avoid scanning everything equally.
+2. As a reviewer, I want each review focus item to explain why it matters so I can understand the risk without reading AgentFlight internals.
+3. As an agent operator, I want AgentFlight to tell me which proof is missing so I can run the right command before claiming completion.
+4. As a developer in a repo with generated files, I want to configure local changed-file ignores so generated tool artifacts do not distort risk and review guidance.
+5. As a handoff recipient, I want the resume prompt to include the most important review focus and the exact next verification command.
+6. As a security-conscious user, I want all analysis to stay local and avoid full source diffs by default.
+
+## Current-State Analysis
+
+### Risk Categorisation
+
+Current file: `src/core/risk.ts`
+
+AgentFlight already categorises changed files into:
+
+- `auth`
+- `billing/payments`
+- `database/migrations`
+- `security/secrets`
+- `config`
+- `tests`
+- `docs`
+- `frontend`
+- `backend/api`
+- `dependencies`
+- `unknown`
+
+It computes a session-level risk level and reasons. It does not rank individual files or connect file categories to evidence requirements.
+
+### Changed-File Filtering
+
+Current file: `src/core/changed-files.ts`
+
+AgentFlight v0.3.3 filters its own runtime artifacts:
+
+- `.agentflight/sessions/**`
+- `.agentflight/reports/**`
+- `.agentflight/current/**`
+- `.agentflight/evidence/**`
+
+It intentionally keeps `.agentflight/config.json` visible because it is user-controlled project configuration.
+
+The filter is not yet config-driven. Dogfooding found `.projscan-memory/memory.json` can appear as a normal changed file because it is generated by ProjScan, not AgentFlight.
+
+### Verification Evidence
+
+Current file: `src/core/verification.ts`
+
+AgentFlight records verification runs with command, timestamps, duration, exit code, pass/fail state, and stdout/stderr evidence paths. It builds a basic summary:
+
+- passed count
+- failed count
+- missing configured commands
+- basic gaps
+- readiness
+- next action
+
+The current model does not detect category-specific proof gaps such as "auth files changed but no test evidence was captured."
+
+### Recommendation and Readiness Logic
+
+Current file: `src/core/verification.ts`
+
+Current readiness states are:
+
+- `Ready for review`
+- `Not ready for review`
+- `Blocked`
+- `Unknown`
+
+This is useful but too coarse. v0.4.0 should make readiness explainable with:
+
+- state
+- reason
+- next best action
+- suggested command, when one can be inferred
+
+Suggested v0.4.0 display states:
+
+- `Ready for review`
+- `Needs verification`
+- `Not ready for review`
+- `Blocked by failed verification`
+- `Unknown`
+
+### Reports and Replay
+
+Current files:
+
+- `src/renderers/markdown-report.ts`
+- `src/renderers/html-replay.ts`
+
+Reports and replays already show changed files, risk categories, timelines, verification evidence, and a recommendation. They do not yet show ranked review focus items or proof gaps as first-class sections.
+
+### Resume Prompt
+
+Current file: `src/renderers/resume-prompt.ts`
+
+Resume prompts show changed files, risk reasons, verification gaps, latest snapshot note, verification state, and next action. v0.4.0 should add review focus and make the next command more precise.
+
+### ProjScan Adapter
+
+Current file: `src/adapters/projscan.ts`
+
+The adapter detects availability and runs a baseline command defensively. It captures summary text but does not expose structured hotspot or architecture data. v0.4.0 should not parse unstable human-readable output.
+
+## Proposed Data Model Changes
+
+Add review-intelligence types to `src/types/index.ts`.
+
+```ts
+export type ReviewReadinessState =
+  | "Ready for review"
+  | "Needs verification"
+  | "Not ready for review"
+  | "Blocked by failed verification"
+  | "Unknown";
+
+export interface ReviewFocusItem {
+  rank: number;
+  file: string;
+  category: RiskCategory;
+  riskLevel: RiskLevel;
+  score: number;
+  reasons: string[];
+  proofStatus: "covered" | "missing" | "failed" | "not-required" | "unknown";
+  suggestedCommand?: string;
+}
+
+export interface ProofGap {
+  id: string;
+  severity: "blocking" | "recommended" | "informational";
+  message: string;
+  affectedFiles: string[];
+  suggestedCommand?: string;
+}
+
+export interface ReviewReadinessDecision {
+  state: ReviewReadinessState;
+  reason: string;
+  nextAction: string;
+  suggestedCommand?: string;
+}
+
+export interface ReviewIntelligence {
+  focus: ReviewFocusItem[];
+  proofGaps: ProofGap[];
+  readiness: ReviewReadinessDecision;
+}
+```
+
+These types do not need to be persisted into session files in v0.4.0. They can be computed from current session data, changed files, risk analysis, config, and verification evidence. Avoiding persistence preserves v0.1, v0.2, and v0.3 session compatibility.
+
+## Proposed Config Changes
+
+Extend `AgentFlightConfig` with an optional changed-file filter section:
+
+```ts
+export interface AgentFlightConfig {
+  version: 1;
+  projectName: string;
+  createdAt: string;
+  engines: {
+    projscan: {
+      enabled: boolean;
+      mode: AgentFlightEngineMode;
+    };
+    agentloopkit: {
+      enabled: boolean;
+      mode: AgentFlightEngineMode;
+    };
+  };
+  verification: {
+    commands: string[];
+  };
+  changedFileFilters?: {
+    ignore: string[];
+  };
+  privacy: {
+    localOnly: true;
+    telemetry: false;
+  };
+}
+```
+
+Backwards compatibility:
+
+- Existing v0.1 through v0.3 configs without `changedFileFilters` continue to work.
+- Missing `changedFileFilters.ignore` is treated as an empty list.
+- Built-in AgentFlight runtime filtering remains separate and always active.
+
+Default for new `agentflight init` configs:
+
+```json
+"changedFileFilters": {
+  "ignore": []
+}
+```
+
+Reasoning:
+
+- AgentFlight's own runtime artifacts are always hidden by built-in filters.
+- Generated directories such as `.projscan-memory/**`, `dist/**`, `coverage/**`, and `.next/**` should be documented examples, not default ignores, because some projects intentionally review or commit generated outputs.
+
+Docs should show optional examples:
+
+```json
+"changedFileFilters": {
+  "ignore": [
+    ".projscan-memory/**",
+    "coverage/**",
+    "dist/**",
+    ".next/**"
+  ]
+}
+```
+
+## Affected Commands
+
+### `agentflight status`
+
+Add:
+
+- `Review first` ranked list.
+- `Missing proof` as structured proof gaps.
+- Readiness state with reason.
+- Next action with suggested command when available.
+
+Keep output concise. Show the top 3 to 5 focus items in the terminal.
+
+### `agentflight report`
+
+Add sections:
+
+- `## Review First`
+- `## Proof Gaps`
+- `## Review Readiness`
+
+The report should include all focus items, not just the top 3, because it is a shareable artifact.
+
+### `agentflight replay`
+
+Add:
+
+- Review focus panel near the summary strip.
+- Proof gap panel before or near verification evidence.
+- Readiness reason in the recommendation section.
+
+Keep the v0.3.3 calm developer-review visual direction.
+
+### `agentflight resume`
+
+Add:
+
+- Top review focus items.
+- Proof gaps.
+- Exact next suggested command.
+- Clear instruction to handle the highest-ranked focus item first.
+
+### `agentflight snapshot`
+
+Snapshots should continue capturing current risk and verification summary. v0.4.0 can optionally include a compact review intelligence summary in snapshot metadata:
+
+```json
+"review": {
+  "readiness": "Needs verification",
+  "topFocusFiles": ["src/auth/session.ts"],
+  "proofGapCount": 2
+}
+```
+
+This is optional and should not block the release if it complicates compatibility. The primary outputs can compute review intelligence live.
+
+### `agentflight doctor`
+
+No v0.4.0 behavior change required. Do not use this release to align tool availability messaging unless it falls out naturally from config validation.
+
+## Affected Renderers
+
+### Markdown Report
+
+Modify `src/renderers/markdown-report.ts` input to accept `review: ReviewIntelligence`.
+
+Render:
+
+```md
+## Review First
+
+1. src/auth/session.ts
+   Why: identity/session path; no passing test evidence
+   Suggested proof: npm test
+
+## Proof Gaps
+
+- Auth files changed but no passing test evidence was recorded.
+
+## Review Readiness
+
+Needs verification
+Reason: High-risk files changed without matching proof.
+Next action: Run agentflight verify -- npm test
+```
+
+### HTML Replay
+
+Modify `src/renderers/html-replay.ts` input to accept `review: ReviewIntelligence`.
+
+Render:
+
+- Summary strip: readiness, risk, changed files, proof.
+- Review focus section: ranked rows with file, category, reasons, and proof status.
+- Proof gaps section: compact list with suggested command.
+- Existing timeline and verification sections remain.
+
+### Resume Prompt
+
+Modify `src/renderers/resume-prompt.ts` input to include:
+
+- `reviewFocus: ReviewFocusItem[]`
+- `proofGaps: ProofGap[]`
+- `readiness: ReviewReadinessDecision`
+
+Keep the prompt concise and agent-safe.
+
+## Review Scoring and Ranking Approach
+
+Create `src/core/review-intelligence.ts`.
+
+Inputs:
+
+- changed files after built-in and config-driven filtering
+- `RiskAnalysis`
+- verification summary and runs
+- session verification commands
+- optional ProjScan hints in a future-compatible shape
+
+Algorithm v0:
+
+1. Categorise each changed file with the existing `categorizeFile`.
+2. Assign a base score by category:
+
+| Category              | Base score |
+| --------------------- | ---------- |
+| `auth`                | 100        |
+| `billing/payments`    | 95         |
+| `security/secrets`    | 95         |
+| `database/migrations` | 90         |
+| `config`              | 75         |
+| `backend/api`         | 70         |
+| `dependencies`        | 65         |
+| `unknown`             | 50         |
+| `frontend`            | 35         |
+| `tests`               | 20         |
+| `docs`                | 10         |
+
+3. Add modifiers:
+
+- `+30` if the category has no matching proof and proof is expected.
+- `+40` if any verification failed and the file category is not docs-only.
+- `+20` if dependency files changed and no build or test proof exists.
+- `+15` if config files changed and no lint, typecheck, or build proof exists.
+- `+10` if file category is `unknown`.
+
+4. Sort descending by score.
+5. Tie-break by path name for deterministic output.
+6. Limit terminal status to top 5 items; report/replay can show all.
+
+Review reasons should be exact and human-readable, for example:
+
+- `identity/session path`
+- `backend/API file`
+- `dependency metadata changed`
+- `no passing test evidence`
+- `build evidence missing`
+- `verification failed`
+
+Do not use vague phrases such as "AI confidence" or "probably important."
+
+## Proof Gap Detection Approach
+
+Create deterministic proof classes from verification command strings:
+
+```ts
+type VerificationProofKind = "test" | "build" | "typecheck" | "lint" | "install" | "unknown";
+```
+
+Classify commands by normalized text:
+
+- `test`, `vitest`, `jest`, `mocha`, `playwright`, `cypress` -> `test`
+- `build` -> `build`
+- `typecheck`, `tsc --noEmit`, `tsc` -> `typecheck`
+- `lint`, `eslint` -> `lint`
+- `install`, `npm ci`, `pnpm install`, `yarn install` -> `install`
+- everything else -> `unknown`
+
+Gap rules:
+
+- Failed verification exists: blocking gap, readiness `Blocked by failed verification`.
+- `auth`, `billing/payments`, `security/secrets`, or `database/migrations` changed without passing `test`: blocking or recommended gap depending on whether configured test commands exist.
+- `backend/api` changed without passing `test` or `build`: recommended gap.
+- `dependencies` changed without passing `install`, `build`, or `test`: recommended gap.
+- `config` changed without passing `lint`, `typecheck`, or `build`: recommended gap.
+- `frontend` changed without passing `build` or `test`: recommended gap.
+- docs-only changes with no verification: informational, not blocking.
+- tests-only changes with no verification: recommended gap, suggest running the test suite.
+- no changed files: readiness `Unknown`.
+
+Suggested command selection:
+
+1. Prefer the first configured command that maps to the missing proof kind.
+2. Otherwise infer from package scripts:
+   - `test` -> `npm test`
+   - `build` -> `npm run build`
+   - `typecheck` -> `npm run typecheck`
+   - `lint` -> `npm run lint`
+3. If no script exists, suggest `agentflight verify -- <command>` with a plain explanation instead of inventing a command.
+
+## Review Readiness Model
+
+Readiness should be derived from proof gaps, failed verification, changed files, and risk:
+
+1. `Blocked by failed verification`
+   - Any verification run failed.
+   - Reason: the failed command must be fixed or rerun successfully.
+   - Next action: rerun the failed command after fixing it.
+
+2. `Unknown`
+   - No changed files, or git status could not be read.
+   - Reason: there is not enough changed-file evidence.
+   - Next action: make changes or inspect git status.
+
+3. `Needs verification`
+   - Changed files exist, no failed runs, but required or recommended proof is missing.
+   - Reason: specific proof gaps.
+   - Next action: run the highest-priority suggested command.
+
+4. `Not ready for review`
+   - Proof exists, but high-risk gaps remain or the focus list contains high-risk files without matching proof.
+   - Reason: high-risk changed files still lack targeted evidence.
+   - Next action: run suggested verification and regenerate report/replay.
+
+5. `Ready for review`
+   - No failed runs.
+   - No blocking gaps.
+   - Required proof is present, or the change set is docs-only with no configured proof requirement.
+   - Reason: verification evidence matches the observed risk.
+   - Next action: generate or share report/replay and request scoped review.
+
+## ProjScan Integration Approach
+
+v0.4.0 should keep ProjScan defensive:
+
+- Continue detecting availability through the existing adapter.
+- Continue recording ProjScan status in tooling sections.
+- Do not parse ProjScan human-readable text for ranking.
+- Do not make ProjScan required for review intelligence.
+
+Add a future-compatible extension point:
+
+```ts
+export interface ExternalReviewHint {
+  file: string;
+  reason: string;
+  weight: number;
+  source: "projscan" | "agentloopkit" | "config";
+}
+```
+
+Do not wire ProjScan into this extension point until there is a stable structured output contract. A later v0.4.x release can add ProjScan hotspots or architecture-sensitive file hints.
+
+## Generated/Internal File Filtering Decision
+
+Include config-driven ignore patterns in v0.4.0.
+
+Implementation:
+
+- Keep `filterAgentFlightRuntimePaths` as the built-in non-configurable AgentFlight runtime filter.
+- Add `filterChangedFiles(files, config)` or similar helper that applies:
+  1. built-in AgentFlight runtime filters
+  2. optional `changedFileFilters.ignore` globs from config
+- Use a small dependency-free glob matcher for simple patterns:
+  - exact file path
+  - directory prefix ending in `/**`
+  - basename wildcard such as `*.log` only if simple to test
+- If pattern support becomes complex, use a small well-known package only after checking package cost and maintenance.
+
+Default new config:
+
+- Use an empty `changedFileFilters.ignore` list.
+- Do not include `.projscan-memory/**`, `dist/**`, `coverage/**`, or `.next/**` by default.
+
+Docs:
+
+- Explain that AgentFlight always hides its own runtime evidence from changed-file analysis.
+- Explain that users can add generated/internal artifacts under `changedFileFilters.ignore`.
+- Warn that ignored files do not appear in risk, report, replay, resume, or snapshot summaries.
+
+## Backwards Compatibility Strategy
+
+Sessions:
+
+- Do not require new persisted session fields.
+- Continue supporting sessions without `verificationRuns`.
+- Continue supporting sessions without `events`.
+- Continue synthesizing timeline events for older sessions.
+
+Configs:
+
+- Treat missing `changedFileFilters` as `{ ignore: [] }`.
+- Keep `version: 1` unless a breaking config migration is introduced. This plan does not require one.
+- Do not rewrite existing config files automatically.
+
+Outputs:
+
+- Existing commands keep their names and basic behavior.
+- New review intelligence appears as additional sections and clearer wording.
+- Scripts using current commands should not break because no command arguments are removed.
+
+## Tests Required
+
+### Core Review Intelligence
+
+Create `tests/core/review-intelligence.test.ts`.
+
+Cover:
+
+- ranks auth above docs and tests
+- ranks billing and security as high priority
+- adds missing proof reason when high-risk files lack test evidence
+- marks failed verification as `Blocked by failed verification`
+- marks docs-only changes as ready or low-friction when no proof is configured
+- suggests `npm test` for auth/backend proof gaps when test script is configured
+- suggests `npm run build` for frontend/build gaps when build script is configured
+- keeps output deterministic for equal scores
+- handles empty changed files as `Unknown`
+- handles old sessions without verification runs
+
+### Changed-File Filters
+
+Create or extend `tests/core/changed-files.test.ts`.
+
+Cover:
+
+- built-in AgentFlight runtime paths remain filtered
+- `.agentflight/config.json` remains visible
+- config ignore `.projscan-memory/**` hides `.projscan-memory/memory.json`
+- normal user files are not filtered
+- ignored files do not feed risk analysis
+- Windows-style paths normalize correctly
+
+### Config
+
+Update `tests/core/config.test.ts`.
+
+Cover:
+
+- new configs include an empty `changedFileFilters.ignore` list
+- older configs without the field still load
+
+### Commands
+
+Update command tests:
+
+- `tests/commands/workflow.test.ts`
+- `tests/commands/snapshot.test.ts`
+- `tests/commands/evidence-output.test.ts`
+
+Cover:
+
+- `status` includes `Review first`
+- `status` includes readiness reason and suggested command
+- `report` includes `Review First`, `Proof Gaps`, and `Review Readiness`
+- `replay` includes review focus and proof gaps
+- `resume` includes review focus and exact next command
+- snapshot summaries are not polluted by ignored generated files
+
+### Renderers
+
+Update:
+
+- `tests/renderers/markdown-report.test.ts`
+- `tests/renderers/html-replay.test.ts`
+- `tests/renderers/resume-prompt.test.ts`
+
+Cover:
+
+- report renders ranked review focus
+- report renders proof gaps honestly
+- replay escapes review focus text
+- replay shows readiness reason
+- resume prompt includes top review files and suggested command
+
+### Adapters
+
+Keep existing ProjScan and AgentLoopKit adapter tests. Add tests only if an external hints type is introduced without live adapter wiring.
+
+## Documentation Updates Required
+
+Update:
+
+- `README.md`
+  - Add v0.4.0 review intelligence to current capabilities.
+  - Update sample `status`, `report`, `replay`, and `resume` snippets with review focus and proof gaps.
+- `docs/roadmap/index.md`
+  - Mark review intelligence as current after implementation.
+  - Move PR comments, JSON/CI, and deeper ProjScan enrichment to future sections.
+- `docs/development/verification.md`
+  - Explain how proof gaps are inferred from verification commands.
+- `docs/development/snapshots-and-timelines.md`
+  - Mention optional review summary in snapshot metadata if implemented.
+- `docs/examples/basic-agentflight-session.md`
+  - Add a short example of `Review first` and `Missing proof`.
+- `CHANGELOG.md`
+  - Add v0.4.0 section when release preparation begins.
+- `AGENTFLIGHT_DEVLOG.md`
+  - Record implementation commands, ProjScan checks, AgentLoopKit checks, test results, and dogfood evidence.
+
+Optional new doc:
+
+- `docs/development/review-intelligence.md`
+  - Explain ranking, proof gap detection, readiness states, and generated-file filters.
+
+## Release Checklist
+
+Before release:
+
+- `npm run verify`
+- `npm run format:check`
+- `npm pack --dry-run`
+- `npm audit --audit-level=moderate`
+- `npx projscan@latest preflight --mode before_commit --format json`
+- `npx agentloopkit@latest verify`
+
+Dogfood:
+
+- Start a v0.4.0 dogfood session in AgentFlight.
+- Make a small docs or test change.
+- Capture typecheck, lint, test, and build through `agentflight verify`.
+- Confirm `status` ranks review focus sensibly.
+- Confirm report/replay/resume all include the same review intelligence.
+- Test a generated `.projscan-memory/memory.json` file is hidden when configured.
+- Test `.agentflight/config.json` remains visible.
+
+Package:
+
+- Confirm `npm pack --dry-run` includes built files and docs.
+- Confirm no runtime `.agentflight/sessions`, `.agentflight/reports`, `.agentflight/current`, or `.agentflight/evidence` files are included.
+- Confirm `node dist/cli.js --version` reports the intended version during release prep.
+
+## Risks and Trade-Offs
+
+### Risk: Overstating Review Quality
+
+AgentFlight should not imply it performed a human review. Use wording like `Review first`, `Proof gaps`, and `Ready for review`, not `Approved` or `Safe to merge`.
+
+### Risk: Brittle Proof Mapping
+
+Command names vary by repo. Keep proof-kind mapping simple and transparent. If AgentFlight cannot infer a command, say so.
+
+### Risk: Hiding Important Files
+
+Config-driven ignore patterns can hide files from risk and review analysis. Keep defaults conservative and document the effect clearly.
+
+### Risk: ProjScan Coupling
+
+ProjScan enrichment is attractive but should wait for stable structured output. v0.4.0 should not parse human-formatted output.
+
+### Risk: Terminal Output Becomes Too Long
+
+Limit `status` review focus to top 3 to 5 files. Put fuller detail in report/replay.
+
+## Phased Implementation Steps
+
+### Phase 1: Review Intelligence Core
+
+Files:
+
+- Create `src/core/review-intelligence.ts`
+- Modify `src/types/index.ts`
+- Test `tests/core/review-intelligence.test.ts`
+
+Steps:
+
+1. Add review intelligence types.
+2. Write failing tests for ranking, proof gaps, readiness, and command suggestions.
+3. Implement proof-kind classification.
+4. Implement file scoring and deterministic ranking.
+5. Implement proof gap detection.
+6. Implement readiness decision.
+7. Run `npm test -- tests/core/review-intelligence.test.ts`.
+
+### Phase 2: Config-Driven Generated/Internal Filters
+
+Files:
+
+- Modify `src/types/index.ts`
+- Modify `src/core/config.ts`
+- Modify `src/core/changed-files.ts`
+- Modify changed-file call sites in `src/commands/status.ts`, `report.ts`, `replay.ts`, `resume.ts`, and `snapshot.ts`
+- Test `tests/core/changed-files.test.ts`
+- Test `tests/core/config.test.ts`
+
+Steps:
+
+1. Add optional `changedFileFilters.ignore` to config type.
+2. Seed an empty `changedFileFilters.ignore` list in new configs.
+3. Load config in commands before changed-file analysis.
+4. Apply built-in runtime filters first, then config filters.
+5. Add tests for `.projscan-memory/**`, `.agentflight/config.json`, normal files, and Windows paths.
+6. Run changed-file and config tests.
+
+### Phase 3: Command Integration
+
+Files:
+
+- Modify `src/commands/status.ts`
+- Modify `src/commands/report.ts`
+- Modify `src/commands/replay.ts`
+- Modify `src/commands/resume.ts`
+- Modify `src/commands/snapshot.ts` only if snapshot review metadata is included
+- Test command workflow files
+
+Steps:
+
+1. Compute review intelligence once per command after risk and verification summary.
+2. Add concise `Review first`, `Proof missing`, readiness reason, and next action to `status`.
+3. Pass review intelligence into report, replay, and resume renderers.
+4. Add optional compact review metadata to snapshot events if it remains simple.
+5. Run command tests.
+
+### Phase 4: Renderer Integration
+
+Files:
+
+- Modify `src/renderers/markdown-report.ts`
+- Modify `src/renderers/html-replay.ts`
+- Modify `src/renderers/resume-prompt.ts`
+- Test renderer files
+
+Steps:
+
+1. Add `Review First` and `Proof Gaps` sections to Markdown report.
+2. Add review focus and proof gap sections to HTML replay.
+3. Add top focus files and next command to resume prompt.
+4. Keep replay styling precise, calm, and trustworthy.
+5. Run renderer tests.
+
+### Phase 5: Docs and Dogfood
+
+Files:
+
+- Modify `README.md`
+- Modify `docs/roadmap/index.md`
+- Modify `docs/development/verification.md`
+- Modify `docs/examples/basic-agentflight-session.md`
+- Add `docs/development/review-intelligence.md` if needed
+- Modify `CHANGELOG.md`
+- Modify `AGENTFLIGHT_DEVLOG.md`
+
+Steps:
+
+1. Update public workflow examples.
+2. Document review ranking and proof gap rules.
+3. Document generated/internal filters.
+4. Dogfood in AgentFlight.
+5. Record evidence in the devlog.
+6. Run full verification.
+
+## Option Decision
+
+### Option A: Review Focus Ranking + Proof Gap Detection + Readiness Model
+
+Pros:
+
+- Most focused review-intelligence release.
+- Lowest implementation risk.
+- Directly improves the main workflow.
+
+Cons:
+
+- Does not address generated ProjScan memory noise beyond v0.3.3 AgentFlight runtime filtering.
+
+### Option B: Option A + Config-Driven Generated/Internal File Filters
+
+Pros:
+
+- Addresses dogfood evidence from `.projscan-memory/memory.json`.
+- Keeps filtering local, explicit, and user-controlled.
+- Avoids hardcoding arbitrary generated paths.
+- Still shippable as v0.4.0.
+
+Cons:
+
+- Adds config surface area.
+- Needs careful docs so users understand ignored files disappear from review analysis.
+
+### Option C: Option A + ProjScan-Enriched Review Hints
+
+Pros:
+
+- Moves toward Baseframe Labs strategic architecture.
+- Could make review ranking smarter.
+
+Cons:
+
+- Risky without stable structured ProjScan output.
+- Could make AgentFlight brittle.
+- Adds integration complexity beyond the core review-intelligence release.
+
+### Option D: Option A + B + C
+
+Pros:
+
+- Most ambitious.
+
+Cons:
+
+- Too broad for a clean v0.4.0.
+- Mixes core product logic, config changes, and external enrichment in one release.
+- Higher regression risk.
+
+Final recommendation: **Option B**.
+
+## Implementation Readiness
+
+This plan is ready for implementation after review. The release should start with the core review-intelligence model and tests, then thread that model through existing commands and renderers. Keep ProjScan enrichment as a future extension point unless a stable structured ProjScan output contract is available before implementation starts.