gaia-framework 1.65.1 → 1.83.2

package/_gaia/lifecycle/knowledge/brownfield/test-execution-scan.md

@@ -0,0 +1,209 @@
+# Test Execution Scan — Brownfield Subagent Prompt
+
+> **Version:** 1.0.0
+> **Story:** E11-S9
+> **Traces to:** FR-110, US-37, ADR-021
+> **Category:** runtime-behavior (test failures map to runtime-behavior per gap-entry-schema.md)
+> **Output format:** Standardized gap entry schema (`_gaia/lifecycle/templates/gap-entry-schema.md`)
+
+## Objective
+
+Run the existing test suite at `{project-path}` during brownfield discovery. Capture test failures as gap entries conforming to the gap schema. This scan is **non-blocking** — failures do not halt the brownfield workflow.
+
+## Test Runner Auto-Detection
+
+Detect the test runner by checking for the following files at `{project-path}`. Use the **priority order** below — select the first matching runner. For monorepo/polyglot projects, detect **all** matching runners and execute them sequentially.
+
+### Detection Priority Order
+
+| Priority | File Check | Condition | Runner Command |
+|----------|-----------|-----------|----------------|
+| 1 | `package.json` | Has `scripts.test` defined AND value is not `"echo \"Error: no test specified\""` | `npm test` |
+| 2 | `pytest.ini` / `pyproject.toml` / `setup.cfg` | `pytest.ini` exists, OR `pyproject.toml` contains `[tool.pytest]`, OR `setup.cfg` contains `[tool:pytest]` | `pytest` |
+| 3 | `pom.xml` | File exists | `mvn test` |
+| 4 | `build.gradle` / `build.gradle.kts` | Either file exists | `gradle test` |
+| 5 | `go.mod` | File exists | `go test ./...` |
+| 6 | `pubspec.yaml` | File exists | `flutter test` |
+
+### No Test Suite Detected (AC6)
+
+If no test runner is detected at `{project-path}`, produce a single info-level gap entry:
+
+```yaml
+id: "GAP-TEST-INFO-001"
+category: "runtime-behavior"
+severity: "info"
+title: "No test suite detected"
+description: "No recognized test runner configuration found at {project-path}. The project has no automated tests or uses an unsupported test framework."
+evidence:
+  file: "{project-path}"
+  line: 0
+recommendation: "Add a test framework (Jest, pytest, JUnit, etc.) and write initial unit tests for critical paths."
+verified_by: "machine-detected"
+confidence: "high"
+```
+
+Proceed without error after logging this gap.
+
+## Test Execution with Timeout (AC3)
+
+Execute each detected runner with a configurable timeout (default **5 minutes** / 300 seconds).
+
+```bash
+timeout 300 npm test 2>&1
+```
+
+### Timeout Behavior
+
+- If the timeout is exceeded, terminate the process gracefully
+- Capture partial results from stdout/stderr up to the timeout point
+- Log a warning-level gap entry noting the timeout:
+
+```yaml
+id: "GAP-TEST-{seq}"
+category: "runtime-behavior"
+severity: "medium"
+title: "Test suite timed out after 5 minutes"
+description: "Test execution exceeded the 300s timeout. Partial results captured: {N} tests ran before timeout."
+evidence:
+  file: "{test-config-file}"
+  line: 0
+recommendation: "Investigate slow tests. Consider splitting the test suite or increasing the timeout for CI."
+verified_by: "machine-detected"
+confidence: "medium"
+```
+
+### Sequential Execution for Multiple Runners (AC9)
+
+For monorepo or polyglot projects with multiple test runners detected:
+1. Execute each detected runner sequentially (not in parallel)
+2. Aggregate results across all runners
+3. Include the runner name in the `description` field of each gap entry (e.g., "npm test: ...")
+4. Use a shared sequence counter across all runners for gap entry IDs
+
+## Output Parsing (AC4)
+
+After each test run completes (or times out), parse the output to extract metrics:
+- **Total** test count
+- **Passing** count
+- **Failing** count
+- **Skipped** count
+- **Error messages** for each failing test
+
+### Parsing Patterns by Runner
+
+**Jest/Mocha/Vitest:**
+- Summary line: `Tests: N passed, N failed, N total` (Jest) or `Tests N passed | N failed` (Vitest)
+- Individual: `FAIL src/path/to/test.js` / `PASS src/path/to/test.js`
+- Exit code 1 = failures present
+
+**pytest:**
+- Summary line: `N passed, N failed, N error`
+- Individual: `FAILED test_file.py::test_name`
+
+**Maven Surefire:**
+- Summary in `target/surefire-reports/` XML files
+- Console: `Tests run: N, Failures: N, Errors: N, Skipped: N`
+
+**Go test:**
+- Per-test: `--- FAIL: TestName` / `--- PASS: TestName`
+- Summary: `FAIL` or `ok` per package
+
+**Flutter test:**
+- Summary: `All tests passed!` or `N tests failed`
+- Per-test: `FAILED: test description`
+
+## Infrastructure Error Detection (AC8)
+
+Before converting failures to gap entries, check if the error is an infrastructure dependency failure rather than an actual test failure.
+
+**Infrastructure error heuristics:**
+- Pattern match stderr/stdout for: `ECONNREFUSED`, `connection refused`, `missing environment variable`, `ENOENT`, `docker`, `database connection`, `redis`, `ETIMEDOUT`, `EHOSTUNREACH`
+- Exit codes indicating non-test errors (e.g., process crash, missing binary)
+
+If an infrastructure error is detected:
+- Do NOT convert to test failure gap entries
+- Instead, log a **warning-level** gap entry:
+
+```yaml
+id: "GAP-TEST-{seq}"
+category: "runtime-behavior"
+severity: "medium"
+title: "Test infrastructure dependency unavailable"
+description: "Test execution failed due to infrastructure dependency: {detected_pattern}. This is not a test logic failure."
+evidence:
+  file: "{test-config-file}"
+  line: 0
+recommendation: "Ensure required infrastructure (databases, caches, external services) is available before running tests. Consider using test doubles for external dependencies."
+verified_by: "machine-detected"
+confidence: "medium"
+```
+
+## Gap Entry Conversion (AC5)
+
+For each failing test, produce a gap entry conforming to the standardized gap schema:
+
+### ID Format
+
+- `GAP-TEST-{seq}` where `{seq}` is a zero-padded 3-digit sequence (001, 002, ...)
+- Example: `GAP-TEST-001`, `GAP-TEST-002`
+
+### Severity Mapping by Test Type
+
+Infer test type from file path patterns:
+
+| File Path Pattern | Test Type | Severity |
+|-------------------|-----------|----------|
+| `test/unit/`, `tests/unit/`, `__tests__/`, `*.unit.test.*` | unit | medium |
+| `test/integration/`, `tests/integration/`, `*.integration.test.*` | integration | high |
+| `test/e2e/`, `tests/e2e/`, `test/end-to-end/`, `*.e2e.test.*` | e2e | critical |
+| Cannot be determined | default | medium |
+
+### Gap Entry Template
+
+```yaml
+id: "GAP-TEST-{seq}"
+category: "runtime-behavior"
+severity: "{severity_from_test_type}"
+title: "{test_name} — failing"
+description: "{runner_name}: {error_message}"
+evidence:
+  file: "{test_file_path}"
+  line: "{line_number_if_available}"
+recommendation: "Fix the failing test or update the test to match current behavior."
+verified_by: "machine-detected"
+confidence: "high"
+```
+
+## Token Budget Control (AC7)
+
+Per NFR-024, the total output must stay within the 40K token framework budget.
+
+- Each gap entry averages ~100 tokens
+- If test output produces more than 70 gap entries, truncate:
+  - Keep the first 70 gap entries (prioritized by severity: critical > high > medium > low)
+  - Add a summary line: `<!-- TRUNCATED: {N} additional test failures omitted to stay within NFR-024 token budget -->`
+- If raw test output exceeds budget before parsing, truncate the raw output and parse what is available
+
+## Output File
+
+Write all gap entries to: `{planning_artifacts}/brownfield-scan-test-execution.md`
+
+Format:
+```markdown
+# Brownfield Scan: Test Execution
+
+> Scan type: test-execution
+> Runner(s): {detected_runners}
+> Date: {date}
+
+## Test Metrics
+
+| Runner | Total | Passed | Failed | Skipped |
+|--------|-------|--------|--------|---------|
+| {runner} | {n} | {n} | {n} | {n} |
+
+## Gap Entries
+
+{YAML gap entries here}
+```

package/_gaia/lifecycle/skills/document-rulesets.md

@@ -1,17 +1,35 @@
 ---
 name: document-rulesets
-version: '1.0'
+version: '1.1'
 applicable_agents: [validator]
-description: 'Document-specific validation rulesets for artifact type detection, structural quality checks per artifact type, and two-pass validation logic.'
-sections: [type-detection, prd-rules, arch-rules, ux-rules, test-plan-rules, epics-rules, two-pass-logic]
+description: 'Document-specific validation rulesets for artifact type detection (path and frontmatter), structural quality checks per artifact type (application, infrastructure, platform PRDs), and two-pass validation logic.'
+sections: [type-detection, prd-rules, infra-prd-rules, platform-prd-rules, arch-rules, ux-rules, test-plan-rules, epics-rules, two-pass-logic]
 ---
 
 <!-- SECTION: type-detection -->
 ## Artifact Type Detection
 
-### Path-to-Ruleset Mapping
+### Frontmatter-Based Detection (Higher Priority)
 
-Detect the artifact type from the file path basename. Match against these patterns:
+Check frontmatter first before falling back to filename detection. If the artifact has YAML frontmatter with a `template` field, use the frontmatter mapping table below. Frontmatter detection takes higher priority than filename detection because it is explicit and unambiguous.
+
+| Frontmatter `template` Value | Ruleset ID(s) | Description |
+|------------------------------|---------------|-------------|
+| `'prd'` | prd-rules | Application Product Requirements Document |
+| `'infra-prd'` | infra-prd-rules | Infrastructure PRD |
+| `'platform-prd'` | prd-rules + infra-prd-rules | Platform PRD (both rulesets applied) |
+
+### Frontmatter Detection Algorithm
+
+1. Parse the artifact's YAML frontmatter (content between opening `---` and closing `---`)
+2. Check for a `template` field in the frontmatter
+3. If `template` field exists, match against the frontmatter mapping table above
+4. If a match is found, return the corresponding ruleset ID(s). For `'platform-prd'`, return both `prd-rules` and `infra-prd-rules` — both rulesets are applied sequentially
+5. If `template` field is absent or does not match, fall through to path-based detection below
+
+### Path-to-Ruleset Mapping (Fallback)
+
+If no frontmatter match is found, detect the artifact type from the file path basename. Match against these patterns:
 
 | File Pattern | Ruleset ID | Description |
 |-------------|------------|-------------|
@@ -21,7 +39,7 @@ Detect the artifact type from the file path basename. Match against these patter
 | `test-plan.md` | test-plan-rules | Test Plan |
 | `epics-and-stories.md` | epics-rules | Epics and Stories |
 
-### Detection Algorithm
+### Path-Based Detection Algorithm
 
 1. Extract the basename from the artifact path (e.g., `docs/planning-artifacts/prd.md` -> `prd.md`)
 2. Match basename against the mapping table above (case-insensitive)
@@ -30,6 +48,7 @@ Detect the artifact type from the file path basename. Match against these patter
 
 ### Edge Cases and Fallback
 
+- **Frontmatter takes priority**: If both frontmatter and filename match, frontmatter wins
 - **Nested directories**: Only the basename matters — `any/nested/path/prd.md` still matches prd-rules
 - **Custom paths**: Files with non-standard names (e.g., `custom-doc.md`) fall back to unknown/unrecognized type
 - **Case sensitivity**: Match is case-insensitive (`PRD.md` and `prd.md` both match prd-rules)
@@ -66,6 +85,72 @@ Verify user personas referenced in requirements match personas defined in the pe
 Verify terminology is used consistently across sections. Cross-reference all sections for contradictions. Flag inconsistencies as WARNING.
 <!-- END SECTION -->
 
+<!-- SECTION: infra-prd-rules -->
+## Infra PRD Validation Rules
+
+Structural quality checks for Infrastructure Product Requirements Documents. This ruleset validates infra PRDs per ADR-022 section 10.16.7 (FR-126).
+
+### Section Presence Check
+
+Verify all 13 required infrastructure PRD sections exist and are non-empty. Flag missing sections as CRITICAL.
+
+Required sections:
+1. Overview & Scope
+2. Goals and Non-Goals
+3. Platform Capabilities
+4. Resource Specifications
+5. Operational SLOs
+6. Security Posture
+7. Environment Strategy & Developer Experience
+8. Dependencies & Provider Constraints
+9. Cost Model
+10. Verification Strategy
+11. Operational Runbooks
+12. Requirements Summary
+13. Open Questions
+
+### IR/OR/SR ID Uniqueness
+
+Verify requirement IDs use the infrastructure ID scheme (IR-###, OR-###, SR-###). Check ID uniqueness within each prefix family — no duplicate IR-001 entries, no duplicate OR-001 entries, no duplicate SR-001 entries. Flag duplicate IDs as WARNING.
+
+### Security Posture Non-Empty
+
+The Security Posture section is mandatory and must be non-empty for all infrastructure PRDs. An empty or placeholder-only Security Posture section is a CRITICAL finding. This section must contain substantive content covering IAM/RBAC, network segmentation, secrets management, or compliance mapping.
+
+### Cost Model Per-Environment Estimates
+
+The Cost Model section must include per-environment cost estimates. At minimum, dev, staging, and prod environments must have cost projections. Flag missing per-environment estimates as WARNING.
+
+### Verification Strategy Policy-as-Code Reference
+
+The Verification Strategy section must reference at least one policy-as-code tool. Recognized tools include: OPA, Rego, Checkov, tfsec, Sentinel, or equivalent. Flag missing policy-as-code references as WARNING.
+
+### Platform Capabilities Format Validation
+
+Each entry in the Platform Capabilities section must follow the format: "Enable {team/service} to {capability} with {SLO}". Entries that do not match this pattern should be flagged as WARNING with a suggestion to reformat.
+<!-- END SECTION -->
+
+<!-- SECTION: platform-prd-rules -->
+## Platform PRD Validation Rules
+
+Platform PRDs represent hybrid projects that combine application and infrastructure concerns. A platform PRD must pass both the `prd-rules` (application) and `infra-prd-rules` (infrastructure) validation rulesets.
+
+### Composite Validation
+
+When validating a platform PRD (detected via `template: 'platform-prd'` in frontmatter):
+1. Run all checks from `prd-rules` — application structural rules apply
+2. Run all checks from `infra-prd-rules` — infrastructure structural rules apply
+3. Merge findings from both rulesets into a single report
+
+### Dual ID Scheme Validation
+
+Platform PRDs use both application and infrastructure requirement ID schemes:
+- Application requirements: FR-### (functional) and NFR-### (non-functional)
+- Infrastructure requirements: IR-### (infrastructure), OR-### (operational), SR-### (security)
+
+Both ID namespaces must be validated for uniqueness within their respective prefix families. No collisions between FR-001 and IR-001 because the prefix disambiguates.
+<!-- END SECTION -->
+
 <!-- SECTION: arch-rules -->
 ## Architecture Validation Rules
 

package/_gaia/lifecycle/templates/brownfield-scan-doc-code-prompt.md

@@ -0,0 +1,219 @@
+# Documentation-Code Mismatch Scanner — Subagent Prompt
+
+> Brownfield deep analysis scan subagent for detecting documentation-code drift: stale docs, undocumented features, version mismatches, and config option drift.
+> Reference: Architecture ADR-021, Section 10.15.2, 10.15.3, 10.15.5
+
+## Subagent Invocation
+
+**Input variables:**
+- `{tech_stack}` — Detected technology stack from Step 1 discovery (e.g., "Java/Spring", "Node/Express", "Python/Django", "Go/Gin")
+- `{project-path}` — Absolute path to the project source code directory
+
+**Output file:** `{planning_artifacts}/brownfield-scan-doc-code.md`
+
+**Invocation model:** Spawned via Agent tool in a single message alongside the other deep analysis scan subagents (parallel execution per architecture 10.15.2).
+
+## Subagent Prompt
+
+```
+You are a Documentation-Code Mismatch Scanner for brownfield project analysis. Your task is to verify documentation claims against the actual codebase — detecting stale documentation, undocumented features, version mismatches, and configuration option drift — then produce gap entries using the standardized gap schema.
+
+### Inputs
+- Tech stack: {tech_stack}
+- Project path: {project-path}
+- Gap schema reference: Read _gaia/lifecycle/templates/gap-entry-schema.md for the output format
+
+### Phase 1: Documentation File Discovery
+
+Scan the project for all discoverable documentation files. Apply both generic and stack-specific discovery patterns.
+
+**Generic documentation files (all stacks):**
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| `README.md` | Project root | Primary project documentation |
+| `CONTRIBUTING.md` | Project root | Contributor guidelines |
+| `CHANGELOG.md` | Project root | Version history |
+| `docs/` directory | Project root | Dedicated documentation directory |
+| `*.md` in project root | Project root | Any markdown files at top level |
+| `openapi.yaml`, `openapi.json` | Project root, `api/` | OpenAPI 3.x specification |
+| `swagger.yaml`, `swagger.json` | Project root, `api/` | Swagger 2.x specification |
+
+**Stack-Aware Documentation Patterns:**
+
+#### Java/Spring
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| Javadoc comments (`/** ... */`) | Source files | Inline API documentation and docstrings |
+| `application.yml` / `application.properties` comments | `src/main/resources/` | Configuration documentation |
+| `pom.xml` `<description>` elements | Project root | Maven project metadata |
+| Spring REST Docs output | `build/generated-snippets/`, `target/generated-snippets/` | Auto-generated API documentation |
+| `src/main/resources/static/docs/` | Resources | Bundled documentation |
+
+#### Node/Express
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| JSDoc comments (`/** ... */`) | Source files | Inline API documentation and docstrings |
+| `package.json` `description`, `scripts` | Project root | Package metadata and available commands |
+| `typedoc.json` or JSDoc config | Project root | Documentation generator config |
+| `.env.example` | Project root | Documented environment variables |
+| `docs/api/` | Documentation dir | API documentation files |
+
+#### Python/Django
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| Docstrings (`"""..."""`) | Source files | Inline documentation and docstrings |
+| `pyproject.toml` `[project]` section | Project root | Package metadata |
+| `requirements.txt` | Project root | Dependency documentation |
+| Sphinx `conf.py` | `docs/` | Documentation generator config |
+| Django `urls.py` docstrings | App directories | Route-level documentation |
+| `setup.py` / `setup.cfg` metadata | Project root | Legacy package metadata |
+
+#### Go/Gin
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| Go doc comments (`// Package ...`) | Source files | Package-level documentation and docstrings |
+| `go.mod` module declaration | Project root | Module metadata |
+| `Makefile` targets and comments | Project root | Build command documentation |
+| `cmd/` directory README files | `cmd/` subdirs | CLI command documentation |
+| `internal/` package docs | `internal/` | Internal package documentation |
+
+**Edge Case: Empty/Stub Documentation**
+Skip documentation files with fewer than 2 non-empty lines after the header (title line). These are stub files that provide no actionable claims to verify. Do not generate false-positive gap entries for empty or stub documentation files.
+
+**Edge Case: Non-UTF-8 Encoding**
+Attempt to read each documentation file as UTF-8. If a decode error occurs, log a warning ("Skipping {file}: non-UTF-8 encoding detected") and skip the file gracefully without crashing. Do not generate gap entries for files that cannot be decoded.
+
+### Phase 2: Claim Extraction
+
+For each discovered documentation file, extract verifiable claims organized by type:
+
+**Claim Type 1: Endpoint Claims**
+Extract documented API endpoints — method, path, description. Sources: README API sections, OpenAPI/Swagger specs, inline JSDoc/docstring route annotations.
+
+**Claim Type 2: Configuration Option Claims**
+Extract documented configuration options — environment variables, config keys, default values. Sources: README configuration sections, `.env.example` files, config documentation.
+
+**Claim Type 3: Dependency Claims**
+Extract documented dependencies — package names, version constraints, runtime requirements. Sources: README prerequisites/installation sections, documented system requirements.
+
+**Claim Type 4: Build/Run Command Claims**
+Extract documented build, test, and run commands — script names, CLI invocations, make targets. Sources: README getting started sections, CONTRIBUTING.md, Makefile documentation.
+
+### Phase 3: Code Verification
+
+For each extracted claim, verify it against the actual codebase:
+
+**Endpoint Verification:**
+- Grep for route definitions matching documented paths (e.g., `app.get('/api/v1/users')`, `@GetMapping("/api/v1/users")`, `path('api/v1/users/')`, `router.GET("/api/v1/users")`)
+- Match HTTP method + path pattern
+- Flag documented endpoints not found in code as stale documentation
+- Flag route definitions not found in documentation as undocumented features that are not documented
+
+**Configuration Option Verification:**
+- Grep for documented config key usage in source files (e.g., `process.env.MAX_RETRIES`, `@Value("${max.retries}")`, `os.environ.get('MAX_RETRIES')`, `os.Getenv("MAX_RETRIES")`)
+- Check if documented defaults match actual defaults in code
+- Flag documented config options not referenced anywhere in source as stale documentation
+
+**Dependency Verification:**
+- Compare documented dependencies against entries in package manifests: `package.json`, `pom.xml`, `go.mod`, `requirements.txt`, `pyproject.toml`
+- Check version constraints: if README says "requires Node 16" but `engines` field says `>=20`, flag as version mismatch
+- Flag documented dependencies not in manifests as stale documentation
+- Flag manifest dependencies not mentioned in docs as missing documentation (low severity)
+
+**Build Command Verification:**
+- Verify documented build/run commands exist: check `scripts` in `package.json`, `Makefile` targets, `Dockerfile` commands, management commands in Django
+- Flag documented commands that do not exist as stale documentation
+- Flag undocumented scripts/targets as missing documentation (low severity)
+
+### Phase 4: OpenAPI/Swagger Auto-Generated Spec Detection
+
+When an OpenAPI or Swagger spec file is found, determine whether it is auto-generated or hand-written:
+
+**Auto-generated spec indicators:**
+- `x-generator` field in spec root (e.g., `x-generator: swagger-codegen`)
+- `info.x-generated-by` field in spec info section
+- Known generator tool signatures in comments or metadata: `swagger-codegen`, `openapi-generator`, `tsoa`, `springdoc-openapi`, `drf-spectacular`, `swag` (Go)
+- Presence of `@Generated` or similar annotations in companion files
+
+**Treatment of auto-generated specs:**
+- Flag auto-generated specs with lower confidence findings (INFO severity instead of WARNING/MEDIUM)
+- Add a note in the gap entry description: "Source is auto-generated spec — lower confidence for drift detection"
+- Still verify claims from auto-generated specs, but do not treat mismatches as high severity since the spec may be stale due to regeneration lag rather than intentional drift
+
+### Phase 5: Mismatch Detection and Classification
+
+Classify each verified claim into one of three categories:
+
+**Category A: Stale Documentation (documented but not in code)**
+Features, endpoints, config options, or commands that appear in documentation but no longer exist in the codebase. These represent documentation that was not updated when code changed.
+- **Default severity: medium**
+
+**Category B: Missing Documentation (in code but not documented)**
+Features, endpoints, config options, or commands that exist in the codebase but are not mentioned in any documentation file. These represent undocumented functionality.
+- **Default severity: low** (unless the undocumented item is a public API endpoint, then medium)
+
+**Category C: Version Mismatches**
+Version numbers, runtime requirements, or dependency constraints in documentation that conflict with actual values in package files or code.
+- **Default severity: medium**
+
+### Phase 6: Gap Entry Generation
+
+For each mismatch, produce a gap entry following the standardized gap schema:
+
+- **id:** `GAP-DOC-CODE-{seq}` where seq is zero-padded 3-digit (e.g., GAP-DOC-CODE-001, GAP-DOC-CODE-002)
+- **category:** `doc-code-drift`
+- **severity:** See severity mapping in Phase 5 (default medium for stale docs and version mismatches, low for missing docs, INFO for auto-generated spec findings)
+- **title:** Short summary (max 80 characters)
+- **description:** Include the claim type, source documentation file, and what specifically mismatches
+- **evidence:** `file` (relative path to the documentation or code file) and `line` (line number or range)
+- **recommendation:** Actionable guidance — update docs, remove stale references, add missing documentation
+- **verified_by:** `machine-detected`
+- **confidence:** `high` (exact match/mismatch confirmed), `medium` (partial match, needs human review), `low` (heuristic detection, may be false positive)
+
+### Token Budget Compliance (NFR-024)
+
+Each gap entry must average approximately 100 tokens in structured YAML format:
+- Use structured YAML, not prose paragraphs
+- Keep `title` under 80 characters
+- Keep `description` to 1-2 sentences
+- Keep `recommendation` to 1-2 sentences
+- Reference source via `evidence` instead of embedding code snippets
+
+**Maximum:** 70 gap entries per scan output file.
+
+**Truncation logic:** If total gap entries exceed 70, retain highest-severity entries first (critical > high > medium > low > info). Truncate the lowest-severity entries. Append a summary at the end of the output file:
+"Truncated {N} entries of severity {severity} — {total} total doc-code mismatches found, {kept} entries retained."
+
+### Output Format
+
+Write all gap entries to `{planning_artifacts}/brownfield-scan-doc-code.md` using this format:
+
+```markdown
+# Brownfield Scan: Documentation-Code Mismatch Analysis
+
+> Generated by: Documentation-Code Mismatch Scanner
+> Tech stack: {tech_stack}
+> Date: {date}
+> Total findings: {count}
+
+## Gap Entries
+
+\`\`\`yaml
+- id: "GAP-DOC-CODE-001"
+  category: "doc-code-drift"
+  severity: "medium"
+  title: "README documents /api/v1/legacy endpoint that does not exist"
+  description: "README.md references endpoint GET /api/v1/legacy but no matching route definition found in codebase. Stale documentation."
+  evidence:
+    file: "README.md"
+    line: 47
+  recommendation: "Remove /api/v1/legacy reference from README.md or restore the endpoint if removal was unintentional."
+  verified_by: "machine-detected"
+  confidence: "high"
+\`\`\`
+```