engineering-intelligence 0.8.1 → 1.1.0

package/templates/canonical/skills/convention-detector/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: convention-detector
+description: Detects and codifies project conventions by analyzing naming patterns, import organization, code structure, API patterns, test patterns, git conventions, and architecture patterns. Produces a conventions document and enhances coding-patterns memory.
+version: 3.0.0
+---
+
+# Convention Detector
+
+Systematically analyze a codebase to detect, classify, and document conventions that are implicitly followed but not explicitly written down. Conventions are inferred from statistical patterns across the codebase — a pattern must appear in >70% of relevant files to be classified as a convention.
+
+This capability does not modify product code.
+
+## Inputs
+
+- Repository root path
+- Optional: scope constraints (specific package, service, or directory)
+- Optional: output from `codebase-discovery-engine` (tech stack, framework, file patterns)
+
+## Procedure
+
+1. **Sample files** — Select a representative sample of at least 20 source files across different modules. Prioritize recently modified files and files by different contributors to capture team-wide conventions (not individual habits).
+
+2. **Detect naming conventions** — Analyze the following naming patterns:
+
+   | Target | What to Detect | Example Patterns |
+   |---|---|---|
+   | Variables | camelCase, snake_case, PascalCase, SCREAMING_SNAKE | `userName` vs `user_name` |
+   | Functions | camelCase, snake_case, verb-first, noun-first | `getUser()` vs `user_get()` |
+   | Classes/Types | PascalCase, suffixes (Service, Controller, Repository) | `UserService`, `AuthMiddleware` |
+   | Files | kebab-case, camelCase, PascalCase, dot-separated | `user-service.ts` vs `UserService.ts` |
+   | Directories | singular, plural, kebab-case, camelCase | `model/` vs `models/` |
+   | Tests | `.test.`, `.spec.`, `_test`, `Test` suffix | `user.test.ts` vs `user.spec.ts` |
+   | Constants | SCREAMING_SNAKE, PascalCase enum members | `MAX_RETRIES`, `HttpStatus.OK` |
+   | Database | snake_case tables, camelCase columns, pluralization | `user_accounts` vs `UserAccount` |
+   | API routes | kebab-case, snake_case, camelCase, plural resources | `/api/user-accounts` vs `/api/userAccounts` |
+
+3. **Detect import organization** — Analyze import blocks for:
+
+   | Pattern | What to Detect |
+   |---|---|
+   | **Grouping** | External → internal → relative? Alphabetical within groups? |
+   | **Path style** | Absolute (`@/components/Button`) vs relative (`../../components/Button`) |
+   | **Path aliases** | `@/`, `~/`, `#/` — check `tsconfig.json` paths, webpack aliases |
+   | **Barrel files** | `index.ts` re-exports? Per-directory or selective? |
+   | **Type imports** | Separate `import type` vs inline `type` keyword |
+   | **Wildcard imports** | `import * as` usage frequency |
+   | **Default vs named** | Preference for default or named exports |
+   | **Side-effect imports** | CSS/style imports, polyfills |
+
+4. **Detect code structure patterns** — Analyze:
+
+   | Pattern | What to Detect |
+   |---|---|
+   | **Paradigm** | Functional vs class-based vs mixed |
+   | **Error handling** | Try-catch, Result/Either types, error-first callbacks, custom error classes |
+   | **Logging** | Logger library, log levels, structured logging, log format |
+   | **Validation** | Zod, Joi, class-validator, manual checks, where validation lives |
+   | **Configuration** | Environment variables, config files, feature flags, config patterns |
+   | **Dependency injection** | Constructor injection, container-based, module-based, manual wiring |
+   | **Async patterns** | async/await, Promises, callbacks, Observables |
+   | **Null handling** | Optional chaining, null checks, Maybe/Option types, assertions |
+   | **Comment style** | JSDoc, docstrings, inline comments, section headers |
+   | **Function length** | Typical function LOC, max observed, decomposition style |
+   | **Module exports** | Single responsibility per file? Multiple exports? |
+
+5. **Detect API patterns** — Analyze API endpoints for:
+
+   | Pattern | What to Detect |
+   |---|---|
+   | **REST conventions** | Resource naming, HTTP method usage, nested resources |
+   | **Response envelope** | `{ data, error, meta }` vs raw responses vs `{ success, result }` |
+   | **Error format** | Error codes, error messages, error detail structure |
+   | **Pagination** | Cursor-based, offset-based, page-based, query params |
+   | **Versioning** | URL path (`/v1/`), header-based, query param |
+   | **Auth headers** | Bearer token, API key, cookie-based |
+   | **Request validation** | Schema validation middleware, manual checks |
+   | **Status codes** | Consistent status code usage patterns |
+   | **Serialization** | camelCase vs snake_case in JSON responses |
+
+6. **Detect test patterns** — Analyze test files for:
+
+   | Pattern | What to Detect |
+   |---|---|
+   | **File placement** | Co-located (`__tests__/`, adjacent), separate `test/` tree, or `spec/` |
+   | **Naming** | `*.test.*`, `*.spec.*`, `*_test.*`, `Test*` prefix |
+   | **Structure** | `describe`/`it` nesting, flat tests, BDD-style, given-when-then |
+   | **Assertion style** | `expect().toBe()`, `assert.*`, `should.*`, custom matchers |
+   | **Mocking** | `jest.mock()`, `vi.mock()`, dependency injection, manual stubs |
+   | **Fixtures** | Factory functions, fixture files, inline data, builders |
+   | **Setup/teardown** | `beforeEach`/`afterEach`, `setup()`/`teardown()`, per-test setup |
+   | **Coverage** | Coverage thresholds, ignored paths, branch vs line coverage |
+   | **Integration tests** | Database setup, API testing, test containers |
+   | **E2E tests** | Page objects, test selectors (`data-testid`), base URLs |
+
+7. **Detect git patterns** — Analyze git history and config for:
+
+   | Pattern | What to Detect |
+   |---|---|
+   | **Commit format** | Conventional commits, free-form, ticket references, emoji |
+   | **Branch naming** | `feature/`, `fix/`, `chore/`, ticket number prefix, kebab-case |
+   | **PR conventions** | PR templates, required reviewers, auto-merge, squash vs merge |
+   | **Release process** | Tags, changelogs, release branches, semantic versioning |
+   | **Hooks** | Husky, lefthook, pre-commit, lint-staged |
+   | **Merge strategy** | Squash merge, merge commits, rebase, linear history |
+
+8. **Detect architecture patterns** — Analyze structural boundaries:
+
+   | Pattern | What to Detect |
+   |---|---|
+   | **Layer boundaries** | Clear separation of presentation/business/data layers |
+   | **Module boundaries** | Feature-based, layer-based, domain-based organization |
+   | **State management** | Redux, Zustand, Jotai, MobX, React Context, Vuex/Pinia, signals |
+   | **Data fetching** | React Query, SWR, tRPC, REST clients, GraphQL clients |
+   | **Middleware chains** | Ordered middleware, decorator patterns, interceptors |
+   | **Event patterns** | Event emitters, pub/sub, event sourcing, domain events |
+   | **Repository pattern** | Data access abstraction, query encapsulation |
+   | **Service pattern** | Business logic isolation, service layer thickness |
+
+9. **Calculate adherence scores** — For each detected convention, calculate:
+   - **Adherence rate**: percentage of relevant files/instances following the convention
+   - **Exceptions**: specific files or modules that deviate (and possible reasons)
+   - **Confidence**: how certain the detection is (based on sample size)
+
+10. **Write conventions document** — Generate `knowledge-base/16-conventions.md` following the output format below.
+
+11. **Enhance coding patterns memory** — Update `.engineering-intelligence/memory/coding-patterns.md` with durable conventions that are unlikely to change.
+
+## Output: `knowledge-base/16-conventions.md`
+
+```markdown
+# Project Conventions
+
+Generated: <timestamp>
+Sample size: <N files analyzed across M modules>
+
+## Naming Conventions
+
+| Target | Convention | Adherence | Exceptions | Evidence |
+|---|---|---|---|---|
+| Variables | camelCase | 98% | None | Sampled 150 variable declarations |
+| Files | kebab-case | 94% | Legacy `utils/` dir uses camelCase | `src/components/user-profile.tsx` |
+| ... | ... | ... | ... | ... |
+
+## Import Organization
+
+<detected import ordering rules, path conventions, barrel file usage>
+
+## Code Structure
+
+<paradigm, error handling, logging, validation patterns>
+
+## API Conventions
+
+<REST conventions, response format, error format>
+
+## Test Conventions
+
+<file placement, naming, assertion style, mocking approach>
+
+## Git Conventions
+
+<commit format, branch naming, merge strategy>
+
+## Architecture Conventions
+
+<layer boundaries, module organization, state management>
+
+## Convention Violations
+
+| Convention | Violation | Location | Severity |
+|---|---|---|---|
+| ... | ... | ... | ... |
+```
+
+## Output: `.engineering-intelligence/memory/coding-patterns.md` (Enhanced)
+
+Add a `## Conventions` section with only durable patterns that pass the durability check: "Will this convention still be relevant after 10+ more changes?"
+
+## Quality Gates
+
+- [ ] At least 20 source files sampled across different modules
+- [ ] Naming convention detection covers files, variables, functions, and types
+- [ ] Import organization patterns are documented with examples
+- [ ] Test patterns include file placement and assertion style
+- [ ] Git conventions are extracted from actual git history (not assumed)
+- [ ] Each convention has an adherence rate and evidence citation
+- [ ] Exceptions to conventions are listed (not hidden)
+- [ ] `knowledge-base/16-conventions.md` exists and follows the output format
+- [ ] `coding-patterns.md` is enhanced with a Conventions section
+- [ ] Only patterns with >70% adherence are classified as conventions
+
+## Cross-References
+
+- Depends on: `codebase-discovery-engine` (tech stack context)
+- Used by: `initialize-intelligence-skill`, `engineering-intelligence-skill`
+- Feeds into: `knowledge-base/16-conventions.md`, `.engineering-intelligence/memory/coding-patterns.md`
+- Consumed by: `ongoing-learning-engine` (for convention drift detection)
+
+This capability does not modify product code.

package/templates/canonical/skills/debugging-engine/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: debugging-engine
+description: Performs structured root cause analysis using graph intelligence, log correlation, error propagation tracing, and reproduction step generation. Produces evidence-backed debug reports with fix suggestions and impact analysis.
+version: 3.0.0
+---
+
+# Debugging Engine
+
+Systematically diagnose issues through evidence-driven root cause analysis, leveraging graph intelligence to trace error propagation and suggest fixes with assessed impact.
+
+## Inputs
+
+- Bug report or error description (symptoms, error messages, stack traces)
+- Repository root path
+- Graph intelligence from `.engineering-intelligence/graph/` (when available)
+- Project intelligence from `knowledge-base/` and `.engineering-intelligence/`
+- Optional: log output, reproduction steps from reporter, environment details
+
+## Procedure
+
+1. **Classify the Issue** — Determine the bug category and initial scope:
+
+   | Category | Indicators |
+   |---|---|
+   | Runtime error | Stack trace, exception, crash |
+   | Logic error | Wrong output, incorrect behavior, data corruption |
+   | Performance | Slowness, timeouts, resource exhaustion |
+   | Integration | API failures, service communication errors |
+   | Concurrency | Race conditions, deadlocks, data inconsistency |
+   | Configuration | Environment-specific failures, missing config |
+
+2. **Root Cause Analysis Workflow** — Follow a structured elimination process:
+
+   a. **Reproduce** — Determine the minimal conditions to trigger the issue:
+      - Identify required inputs, state, and environment
+      - Distinguish deterministic from intermittent failures
+      - Note any timing or ordering dependencies
+
+   b. **Localize** — Narrow the fault location:
+      - Start from the error manifestation point (stack trace, log entry)
+      - Trace backward through the call chain
+      - Use graph intelligence to understand the execution path
+      - Identify the boundary between working and failing behavior
+
+   c. **Identify** — Determine the root cause:
+      - Distinguish symptom from cause — trace to the origin
+      - Check for recent changes in the fault area (correlate with git history)
+      - Verify assumptions about inputs, state, and invariants
+      - Consider environmental factors (config, dependencies, infrastructure)
+
+3. **Log Analysis and Correlation** — When logs are available:
+
+   | Technique | Application |
+   |---|---|
+   | Timeline reconstruction | Order events chronologically across log sources |
+   | Pattern matching | Identify recurring error patterns and frequencies |
+   | Correlation | Link events across services using request IDs or trace IDs |
+   | Anomaly detection | Identify unusual log patterns preceding the failure |
+   | Context extraction | Extract relevant state from surrounding log entries |
+
+4. **Error Propagation Tracing** — Using graph intelligence:
+
+   - Trace the error path through `runtime-graph.json` (call flows)
+   - Identify affected services via `service-graph.json` (communication topology)
+   - Map downstream impact via `dependency-graph.json` (module dependencies)
+   - Assess business impact via `business-flow-graph.json` (affected flows)
+
+   Build an error propagation chain:
+
+   ```
+   Origin → [module/function where fault occurs]
+     ↓ propagates via [mechanism: exception, error return, bad state]
+   Intermediate → [modules that pass through or transform the error]
+     ↓ manifests as [observable symptom]
+   Symptom → [where the user or system observes the failure]
+   ```
+
+5. **Reproduction Step Generation** — Produce minimal, deterministic reproduction steps:
+
+   ```markdown
+   ## Reproduction Steps
+   1. Preconditions: <required state, config, data>
+   2. Action: <specific steps to trigger the issue>
+   3. Expected: <what should happen>
+   4. Actual: <what happens instead>
+   5. Environment: <runtime, OS, versions, config>
+   6. Frequency: deterministic | intermittent (<rate>)
+   ```
+
+6. **Fix Suggestion with Impact Analysis** — Propose fixes with assessed risk:
+
+   | Fix Aspect | Description |
+   |---|---|
+   | Root fix | Address the underlying cause |
+   | Symptom mitigation | Temporary workaround if root fix is complex |
+   | Defensive hardening | Additional checks to prevent recurrence class |
+   | Files to modify | Specific files and functions that need changes |
+   | Risk assessment | Blast radius of the proposed fix |
+   | Test requirements | Tests to add for regression prevention |
+
+   When applicable, invoke `impact-analysis-engine` on the proposed fix to assess its blast radius.
+
+7. **Generate Debug Report** — Write `.engineering-intelligence/reports/DEBUG-XXX-<slug>.md`.
+
+## Output Format
+
+Write `.engineering-intelligence/reports/DEBUG-XXX-<slug>.md`:
+
+```markdown
+# DEBUG-XXX: <descriptive title>
+
+## Meta
+- Generated: <ISO timestamp>
+- Category: <runtime | logic | performance | integration | concurrency | configuration>
+- Severity: <critical | high | medium | low>
+- Status: <diagnosed | investigating | unresolved>
+
+## Symptoms
+- <observable manifestation of the issue>
+- Error message: `<exact error text>`
+- Stack trace: <if available>
+
+## Root Cause Analysis
+- **Root cause**: <concise description>
+- **Origin**: <file:line where the fault originates>
+- **Mechanism**: <how the fault propagates>
+- **Contributing factors**: <environmental or contextual factors>
+
+## Error Propagation
+| Step | Location | Mechanism | Evidence |
+|---|---|---|---|
+| Origin | src/auth/validate.ts:42 | Null reference | Missing null check |
+| Propagation | src/api/middleware.ts:18 | Unhandled exception | No try/catch |
+| Symptom | HTTP 500 response | Error response | Client-reported |
+
+## Reproduction Steps
+1. <minimal reproduction steps>
+
+## Fix Suggestion
+### Root Fix
+- File: <path>
+- Change: <description>
+- Risk: <level>
+
+### Defensive Hardening
+- <additional preventive measures>
+
+### Test Requirements
+- [ ] <regression test to add>
+
+## Impact of Fix
+- Blast radius: <assessment>
+- Affected modules: <list>
+
+## Evidence
+- <file path citations>
+
+## Unknowns
+- <unresolved questions>
+
+---
+*This debug report did not modify product code.*
+```
+
+## Rules
+
+- Never guess the root cause — trace with evidence or mark as `investigating`
+- Distinguish symptoms from causes explicitly
+- Fix suggestions must include impact assessment
+- Log analysis must not expose sensitive data (redact credentials, PII)
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] Issue is classified by category and severity
+- [ ] Root cause is traced with evidence (not assumed)
+- [ ] Error propagation path is documented with graph references
+- [ ] Reproduction steps are minimal and actionable
+- [ ] Fix suggestion includes impact assessment and test requirements
+- [ ] Sensitive data is redacted from logs and traces in the report
+- [ ] Report ends with the "did not modify product code" statement
+
+## Cross-References
+
+- Depends on: `graph-engine` (error propagation tracing), `impact-analysis-engine` (fix impact assessment)
+- Used by: `engineering-intelligence-skill`
+- Consumed by: `engineering-change-review` (when fix is implemented as a change)
+
+This capability is analytical only. It must not modify product code.

package/templates/canonical/skills/engineering-intelligence-skill/SKILL.md

@@ -34,6 +34,7 @@ Classify the incoming request before starting:
 
 Read these artifacts and identify relevant context:
 - `knowledge-base/` — architecture, APIs, runtime flow relevant to the change
+- `.engineering-intelligence/aidlc/` — active AI-DLC state, plan, audit, open questions, construction units
 - `.engineering-intelligence/memory/` — decisions, constraints, patterns that apply
 - `.engineering-intelligence/context/` — module map, critical paths, dangerous areas near the change
 - `.engineering-intelligence/graph/` — dependency and service relationships
@@ -75,14 +76,31 @@ Before any code edit, write `.engineering-intelligence/reports/IMP-XXX-<summary>
 
 ### 3. Implement the Change
 
+- Select the adaptive delivery mode inside the existing Engineering Intelligence workflow:
+  - Standard Agile delivery for normal feature, bugfix, update, and refactor work
+  - Adversarial delivery for auth, payment, public API, secrets, or compliance-sensitive work
+  - TDD delivery for high-reliability business rules and service contracts
+  - Design-first delivery for migrations, new architecture, and broad system boundaries
+  - Hypothesis debugging for unknown-cause defects
+- Update Agile artifacts when product behavior is in scope:
+  - `.engineering-intelligence/aidlc/agile/product-backlog.md`
+  - `.engineering-intelligence/aidlc/agile/sprint-plan.md`
+  - `.engineering-intelligence/aidlc/agile/acceptance-criteria.md`
+  - `.engineering-intelligence/aidlc/agile/definition-of-ready.md`
+  - `.engineering-intelligence/aidlc/agile/definition-of-done.md`
+- Update `.engineering-intelligence/aidlc/execution-plan.md` and `.engineering-intelligence/aidlc/aidlc-state.md`
+- Split broad changes into construction units and keep `.engineering-intelligence/aidlc/construction/cross-unit-discoveries.md` current
 - Edit only the files necessary for the request
 - Follow existing coding patterns from `.engineering-intelligence/memory/coding-patterns.md`
+- Read conventions from `knowledge-base/16-conventions.md` and `.engineering-intelligence/memory/coding-patterns.md` — match naming patterns, import style, error handling patterns, and code structure
+- If conventions document is missing or outdated, run `convention-detector` first
 - Respect architectural boundaries from `.engineering-intelligence/memory/architecture-decisions.md`
 - Consult `dangerous-areas.md` before modifying flagged code
 
 ### 4. Add/Update Tests
 
 - Add tests proportional to the change risk level
+- Map each acceptance criterion to at least one automated test, manual verification step, or explicitly recorded unavailable check
 - For `bugfix`: add a regression test reproducing the original issue
 - For `feature`: add unit tests and integration tests for the new behavior
 - For `architecture`/`security`: add boundary and negative-path tests
@@ -91,6 +109,8 @@ Before any code edit, write `.engineering-intelligence/reports/IMP-XXX-<summary>
 ### 5. Validate
 
 - Run linters, type checks, and test suites available in the project
+- Use environmental backpressure: analyze failed diagnostics, fix, and rerun the relevant command until it passes or a blocker is recorded
+- Write `.engineering-intelligence/aidlc/construction/<unit>/build-and-test/build-and-test-summary.md` for non-trivial units
 - **Never claim validation passed unless it actually ran and passed**
 - Record partial or failed validation honestly
 
@@ -102,6 +122,8 @@ Use `incremental-sync-engine` to update only affected artifacts:
 - Context maps if module/service topology changed
 - Graph nodes/edges if dependencies or services changed
 - Event guidance if API/schema/auth contracts changed
+- AI-DLC lifecycle artifacts if state, plan, NFRs, ADRs, operations readiness, or unit discoveries changed
+- Agile artifacts if backlog, story status, acceptance criteria, Ready/Done gates, or retrospective learning changed
 
 ### 7. Record Change
 
@@ -151,6 +173,7 @@ Summarize to the user:
 - Affected systems and services
 - Synchronized intelligence artifacts
 - Unresolved risks or follow-ups
+- Final AI-DLC breadcrumb: `AI-DLC: <phase> -> <stage> -> <status>`
 
 ## Quality Gates
 
@@ -158,11 +181,17 @@ Summarize to the user:
 - [ ] All changed behavior has corresponding test coverage
 - [ ] Validation was actually executed (not just claimed)
 - [ ] Only affected intelligence artifacts were updated
+- [ ] AI-DLC state, execution plan, and unit artifacts are current for non-trivial work
+- [ ] Story meets Definition of Ready before implementation starts
+- [ ] Story meets Definition of Done before final report
+- [ ] Acceptance criteria are mapped to validation evidence
+- [ ] Environmental backpressure was used for validation failures
 - [ ] Change record references the correct impact report
 - [ ] High-risk changes went through review gate
+- [ ] Generated code follows detected project conventions (naming, imports, structure)
 
 ## Cross-References
 
 - Depends on: `initialize-intelligence-skill` (prerequisite), `change-detection-engine`, `impact-analysis-engine`, `graph-engine`
 - Uses during execution: `testing-intelligence-engine`, `incremental-sync-engine`, `change-history-engine`
-- Optional: `engineering-change-review` (for high-risk), `refactoring-planner` (for refactors)
+- Optional: `engineering-change-review` (for high-risk), `refactoring-planner` (for refactors), `convention-detector` (for convention compliance)

package/templates/canonical/skills/environmental-backpressure-engine/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: environmental-backpressure-engine
+description: Drives compiler, linter, type-check, test, security, and architecture feedback loops until objective validation passes or blockers are recorded.
+version: 1.0.0
+---
+
+# Environmental Backpressure Engine
+
+Use this skill whenever code is generated or modified. The environment, not subjective inspection alone, supplies the feedback loop.
+
+## Procedure
+
+1. Detect available validation commands from package manifests, build files, CI config, and README instructions.
+2. Prefer narrow checks first, then broaden:
+   - formatter or static syntax check
+   - type check or compile
+   - targeted tests
+   - full test suite
+   - linter
+   - security or architecture scanner when relevant
+3. Run the smallest relevant command that can expose the current risk.
+4. Capture raw diagnostics in the active unit's `build-and-test/` artifact.
+5. Fix failures and rerun the relevant check.
+6. Stop only when checks pass, are unavailable, or a blocker is recorded with evidence.
+
+## Build And Test Summary
+
+Write `.engineering-intelligence/aidlc/construction/<unit>/build-and-test/build-and-test-summary.md`:
+
+```markdown
+# Build And Test Summary: <unit>
+
+## Commands
+- `<command>`: <passed|failed|unavailable|skipped> — <why>
+
+## Failures And Corrections
+- <diagnostic summary> -> <fix applied> -> <rerun result>
+
+## Coverage / Performance
+- <available metrics or Not detected>
+
+## Residual Risk
+- <remaining risks, blockers, or manual verification>
+```
+
+## Rules
+
+- Never report validation as passed unless the command actually ran and passed.
+- Do not hide failing output. Summarize it and keep enough detail for reproduction.
+- Human review begins after local backpressure is exhausted, not before.

package/templates/canonical/skills/git-intelligence-engine/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: git-intelligence-engine
+description: Extracts structural intelligence from git history — hotspot analysis, ownership mapping, change coupling, velocity tracking, and drift detection. Feeds graph intelligence and impact analysis with git-derived edges.
+version: 3.0.0
+---
+
+# Git Intelligence Engine
+
+Extract actionable intelligence from git history to reveal hidden dependencies, ownership patterns, and codebase evolution trends.
+
+## Inputs
+
+- Repository root path
+- Mode: `full` (analyze complete history) or `incremental` (analyze since last run)
+- Optional: time window (e.g., last 90 days, last 6 months)
+- Optional: branch filter (specific branches to analyze)
+
+## Procedure
+
+1. **Collect History** — Extract commit log with file-level diffs, authors, timestamps, and branch metadata. For `incremental` mode, scope to commits since the last recorded analysis timestamp.
+
+2. **Hotspot Analysis** — Identify the most frequently changed files and directories:
+
+   | Metric | Description |
+   |---|---|
+   | Change frequency | Number of commits touching each file |
+   | Churn rate | Lines added + deleted per file over the time window |
+   | Complexity trend | Whether hotspot files are growing in size/complexity |
+   | Bug correlation | Commits linked to bugfix keywords touching each file |
+
+   Rank files by composite hotspot score (frequency × churn × bug correlation).
+
+3. **Ownership Mapping** — Determine contributor ownership per module:
+
+   | Field | Description |
+   |---|---|
+   | Primary owner | Contributor with most commits to the module |
+   | Secondary owners | Other significant contributors (>10% of commits) |
+   | Bus factor | Number of contributors with meaningful knowledge |
+   | Last active | Most recent commit date per contributor per module |
+   | Orphaned modules | Modules where all significant contributors are inactive (>90 days) |
+
+4. **Change Coupling Analysis** — Identify files that always change together:
+
+   | Metric | Description |
+   |---|---|
+   | Co-change frequency | Number of commits where both files are modified |
+   | Coupling strength | Co-change frequency / total changes of either file |
+   | Confidence | `verified` if coupling > 0.7, `inferred` if 0.4–0.7, `unknown` below |
+
+   Flag high-coupling pairs that span module boundaries — these indicate hidden dependencies not visible in import graphs.
+
+5. **Velocity Tracking** — Measure change rate per module per time period:
+
+   | Metric | Description |
+   |---|---|
+   | Commits per week | Average commit frequency per module |
+   | Active contributors | Unique contributors per module per period |
+   | Acceleration | Whether velocity is increasing, stable, or declining |
+   | Staleness | Modules with zero commits in the analysis window |
+
+6. **Drift Detection** — Identify branches that have diverged significantly:
+
+   | Metric | Description |
+   |---|---|
+   | Divergence score | Number of commits ahead/behind between branch pairs |
+   | Conflict potential | Files modified in both branches |
+   | Merge complexity | Estimated effort to reconcile (based on overlapping changes) |
+   | Stale branches | Branches with no commits in >30 days |
+
+7. **Feed Graph Intelligence** — Write git-derived edges to `.engineering-intelligence/graph/`:
+   - Add `co-changes-with` edges to `dependency-graph.json` for verified change-coupled pairs
+   - Add `owned-by` metadata to graph nodes based on ownership mapping
+   - Mark edge confidence based on analysis evidence
+
+8. **Generate Report** — Write `.engineering-intelligence/reports/GIT-intelligence.md` with all findings, ranked by actionability.
+
+## Output Format
+
+Write `.engineering-intelligence/reports/GIT-intelligence.md`:
+
+```markdown
+# Git Intelligence Report
+
+## Meta
+- Generated: <ISO timestamp>
+- Mode: full | incremental
+- Time window: <start> to <end>
+- Commits analyzed: <count>
+
+## Hotspots
+| Rank | File | Change Freq | Churn | Bug Correlation | Score |
+|---|---|---|---|---|---|
+| 1 | path/to/file.ts | 47 | 1,240 | 8 | 95.2 |
+
+## Ownership Map
+| Module | Primary Owner | Bus Factor | Orphaned |
+|---|---|---|---|
+| src/auth/ | alice | 3 | No |
+
+## Change Coupling
+| File A | File B | Co-changes | Strength | Cross-module |
+|---|---|---|---|---|
+| src/api/users.ts | src/db/user-repo.ts | 23 | 0.82 | Yes |
+
+## Velocity
+| Module | Commits/Week | Trend | Staleness |
+|---|---|---|---|
+| src/core/ | 12.3 | Accelerating | — |
+
+## Drift
+| Branch | Divergence | Conflict Files | Stale |
+|---|---|---|---|
+| feature/payments | +47 / -12 | 3 | No |
+
+## Graph Updates
+- Edges added: <count>
+- Nodes annotated: <count>
+
+## Evidence
+- <file path citations>
+```
+
+## Rules
+
+- Never fabricate git history — all metrics must derive from actual commit data
+- Ownership mapping must not assume contributor activity from naming conventions alone
+- Change coupling edges added to graphs must include evidence paths
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] All metrics cite commit SHAs or date ranges as evidence
+- [ ] Hotspot ranking uses composite scoring (not single-metric)
+- [ ] Ownership includes bus factor and orphaned module flags
+- [ ] Change coupling distinguishes intra-module from cross-module pairs
+- [ ] Graph edges added carry `confidence` and `evidence` fields
+- [ ] Report ends with graph update summary
+
+## Cross-References
+
+- Depends on: `graph-engine` (for writing git-derived edges)
+- Used by: `impact-analysis-engine`, `graph-engine`
+- Consumed by: `pr-intelligence-engine`
+
+This capability is analytical only. It must not modify product code.