engineering-intelligence 0.8.1 → 1.1.0

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

@@ -68,6 +68,8 @@ Each JSON graph uses this envelope:
 | `devDependency` | Development-only dependency |
 | `peerDependency` | Peer/optional dependency |
 | `configures` | Configuration dependency |
+| `implicit-dependency` | Shared database tables, shared config |
+| `event-coupling` | Event-driven coupling |
 
 ### 2. `service-graph.json` — Service Communication Topology
 
@@ -87,6 +89,8 @@ Each JSON graph uses this envelope:
 | `subscribes` | Event/message consumption |
 | `reads` | Data store read access |
 | `writes` | Data store write access |
+| `shares-data` | Shared database/cache |
+| `feature-flag` | Feature-flag-controlled behavior |
 
 ### 3. `runtime-graph.json` — Runtime Call Flows
 
@@ -123,7 +127,25 @@ Each JSON graph uses this envelope:
 | `on-failure` | Error/failure path |
 | `requires` | Prerequisite relationship |
 
-### 5. `architecture-map.md` — Mermaid Visualization
+### 5. `data-flow-graph.json` — Data Transformation Graph
+
+| Node Kind | Description |
+|---|---|
+| `source` | Data origin |
+| `transform` | Processing step |
+| `store` | Persistence |
+| `sink` | Data output/consumer |
+| `validator` | Validation step |
+
+| Edge Relation | Description |
+|---|---|
+| `feeds` | Data feed |
+| `transforms` | Data transformation |
+| `validates` | Data validation |
+| `persists` | Data persistence |
+| `emits` | Data emission/output |
+
+### 6. `architecture-map.md` — Mermaid Visualization
 
 Derive Mermaid diagrams from the JSON graphs. Include:
 
@@ -131,17 +153,19 @@ Derive Mermaid diagrams from the JSON graphs. Include:
 - **Module Dependencies** — Package/module dependency flow (from dependency-graph)
 - **Request Flow** — Primary request lifecycle (from runtime-graph)
 - **Key Business Flows** — Critical business processes (from business-flow-graph)
+- **Data Flow** — Data transformation pipelines (from data-flow-graph)
 
 ## Procedure
 
 ### Full Mode (initialization or remapping)
 
 1. Scan all package manifests, imports, route definitions, service configs, and infrastructure files
-2. Build all four graphs from scratch
+2. Build all five graphs from scratch
 3. Assign `verified` confidence to edges backed by explicit code evidence
 4. Assign `inferred` confidence to edges derived from patterns or naming conventions
-5. Mark unresolvable relationships as `unknown` and add to `unknowns` array
-6. Generate Mermaid diagrams in `architecture-map.md`
+5. Integrate git change coupling data from `git-intelligence-engine` as `inferred` edges — files that frequently change together suggest hidden dependencies
+6. Mark unresolvable relationships as `unknown` and add to `unknowns` array
+7. Generate Mermaid diagrams in `architecture-map.md`
 
 ### Incremental Mode (post-change update)
 
@@ -163,7 +187,7 @@ Derive Mermaid diagrams from the JSON graphs. Include:
 
 ## Quality Gates
 
-- [ ] All four JSON graphs validate against the schema above
+- [ ] All five JSON graphs (`dependency-graph.json`, `service-graph.json`, `runtime-graph.json`, `business-flow-graph.json`, `data-flow-graph.json`) validate against the schema above
 - [ ] Every `verified` edge has at least one evidence path
 - [ ] No `unknown` relationships are left out of the `unknowns` array
 - [ ] `architecture-map.md` Mermaid diagrams are syntactically valid
@@ -174,5 +198,6 @@ Derive Mermaid diagrams from the JSON graphs. Include:
 - Used by: `initialize-intelligence-skill`, `impact-analysis-engine`, `incremental-sync-engine`
 - Supports: `map-architecture` workflow, `analyze-impact` workflow
 - Feeds context to: `context-sync-engine`
+- Integrates data from: `git-intelligence-engine`
 
 This capability may write intelligence artifacts. It must not modify product code.

package/templates/canonical/skills/greenfield-architect/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: greenfield-architect
+description: Interview-based skill for new greenfield projects. Conducts a structured requirements interview (7-12 questions), generates architecture recommendations with tech stack selection, and scaffolds a complete project with pre-filled knowledge base, memory, context, configuration, CI/CD, and environment setup.
+version: 3.0.0
+---
+
+# Greenfield Architect
+
+Guide a developer from zero to a fully scaffolded, opinionated project with engineering intelligence pre-configured. This skill operates in three phases: requirements interview, architecture generation, and scaffold output.
+
+## Inputs
+
+- Project name
+- Optional: partial requirements (if the user already knows some answers)
+- Optional: preferred tech stack constraints (e.g., "must use Python", "no React")
+
+## Phase 1: Requirements Interview (7–12 Questions)
+
+Ask questions in this order. Skip questions the user has already answered. Present sensible defaults where possible so the user can simply confirm.
+
+### 1.1 Core Questions (Always Ask)
+
+| # | Question | Why It Matters | Default |
+|---|---|---|---|
+| 1 | **What are you building?** Describe the product in 2-3 sentences. | Determines domain, complexity, core features | — |
+| 2 | **Who are the users?** (internal team, B2B, B2C, developers/API consumers) | Determines auth complexity, UI needs, scale expectations | B2C web app |
+| 3 | **What are the 3-5 core features?** List the must-have capabilities for v1. | Scopes the architecture, identifies bounded contexts | — |
+| 4 | **What scale do you expect?** (hobby, startup MVP, growth stage, enterprise) | Determines infrastructure complexity, database choice, caching needs | Startup MVP |
+| 5 | **Where will this run?** (Vercel, AWS, GCP, Azure, self-hosted, edge) | Determines deployment strategy, serverless vs containers | Vercel |
+| 6 | **Solo developer or team?** How many developers, what experience levels? | Determines convention strictness, CI complexity, review process | Solo |
+| 7 | **Any hard tech constraints?** (must use language X, must integrate with Y, must comply with Z) | Constrains tech stack selection | None |
+
+### 1.2 Conditional Questions (Ask Based on Answers)
+
+| # | Condition | Question | Default |
+|---|---|---|---|
+| 8 | Users = B2C or B2B | **Auth requirements?** (email/password, social login, SSO, MFA) | Email/password + social |
+| 9 | Scale ≥ growth | **Real-time features?** (WebSockets, SSE, live updates) | No |
+| 10 | Features include payments | **Payment provider preference?** (Stripe, PayPal, custom) | Stripe |
+| 11 | Team > 1 | **Monorepo or polyrepo?** | Monorepo if > 2 services |
+| 12 | Features include content | **CMS needs?** (headless CMS, built-in, markdown) | Markdown/MDX |
+
+### Interview Rules
+
+- Present each question with the default value: "I'd suggest X because Y — does that work?"
+- Allow batch answers: the user can answer multiple questions at once
+- If the user provides a project brief, extract answers from it before asking remaining questions
+- Never ask more than 12 questions total
+- Confirm the full requirements summary before proceeding to Phase 2
+
+## Phase 2: Architecture Generation
+
+Based on interview answers, generate architecture recommendations.
+
+### 2.1 Tech Stack Selection
+
+Use this decision matrix to recommend a tech stack:
+
+| Requirement | Next.js | Vite+React | Solid.js | Express | FastAPI | Django | Spring Boot |
+|---|---|---|---|---|---|---|---|
+| SSR/SSG needed | ✅ Best | ❌ SPA only | ⚠️ SolidStart | N/A | N/A | ✅ Templates | N/A |
+| API-only backend | ❌ Overkill | N/A | N/A | ✅ Best | ✅ Best | ✅ Good | ✅ Best |
+| Full-stack | ✅ Best | ⚠️ Need backend | ⚠️ Emerging | ⚠️ Need frontend | ⚠️ Need frontend | ✅ Good | ⚠️ Need frontend |
+| Real-time | ⚠️ Via API routes | ⚠️ Need backend | ⚠️ Need backend | ✅ Socket.io | ✅ WebSockets | ⚠️ Channels | ✅ WebSocket |
+| Enterprise/Java team | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ Best |
+| Python team | ❌ | ❌ | ❌ | ❌ | ✅ Best | ✅ Best | ❌ |
+| Rapid prototyping | ✅ Good | ✅ Good | ⚠️ Smaller ecosystem | ✅ Good | ✅ Best | ✅ Good | ❌ Slower |
+| Edge deployment | ✅ Best | ✅ Good | ✅ Good | ⚠️ Node only | ❌ | ❌ | ❌ |
+
+Present the recommendation with reasoning: "I recommend X because [reasons based on your answers]."
+
+### 2.2 Database Selection
+
+| Requirement | PostgreSQL | MySQL | MongoDB | SQLite | DynamoDB |
+|---|---|---|---|---|---|
+| Relational data | ✅ Best | ✅ Good | ❌ | ✅ Good | ❌ |
+| Document-heavy | ⚠️ JSONB | ⚠️ JSON | ✅ Best | ❌ | ✅ Good |
+| Hobby/MVP | ✅ Good | ✅ Good | ✅ Good | ✅ Best | ⚠️ Overkill |
+| Enterprise scale | ✅ Best | ✅ Good | ✅ Good | ❌ | ✅ Best |
+| Serverless | ⚠️ Need pooling | ⚠️ Need pooling | ✅ Atlas | ✅ Turso/Litestream | ✅ Native |
+
+### 2.3 Folder Structure Generation
+
+Generate an opinionated folder structure based on the selected stack. Example for Next.js:
+
+```
+project-root/
+├── src/
+│   ├── app/                    # Next.js App Router pages
+│   │   ├── (auth)/             # Auth route group
+│   │   ├── (dashboard)/        # Dashboard route group
+│   │   ├── api/                # API routes
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── components/
+│   │   ├── ui/                 # Reusable UI primitives
+│   │   └── features/           # Feature-specific components
+│   ├── lib/                    # Shared utilities
+│   ├── server/                 # Server-only code
+│   │   ├── db/                 # Database client & queries
+│   │   ├── auth/               # Auth configuration
+│   │   └── services/           # Business logic
+│   └── types/                  # Shared type definitions
+├── prisma/
+│   └── schema.prisma
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── .github/
+│   └── workflows/
+├── knowledge-base/             # Pre-filled engineering intelligence
+├── .engineering-intelligence/
+│   ├── memory/
+│   ├── context/
+│   ├── events/
+│   ├── graph/
+│   └── reports/
+├── engineering.config.json
+├── .env.example
+└── ...config files
+```
+
+### 2.4 ADR Generation
+
+Generate initial Architectural Decision Records for key choices:
+
+| ADR | Content |
+|---|---|
+| `ADR-001-tech-stack.md` | Why this framework/language was chosen |
+| `ADR-002-database.md` | Why this database and ORM were chosen |
+| `ADR-003-auth.md` | Why this auth strategy was chosen |
+| `ADR-004-deployment.md` | Why this deployment target was chosen |
+| `ADR-005-testing.md` | Why this testing strategy was chosen |
+| `ADR-006-project-structure.md` | Why this folder structure was chosen |
+
+Each ADR follows the format:
+```markdown
+# ADR-NNN: <Title>
+
+## Status: Accepted
+## Date: <date>
+
+## Context
+<what prompted this decision>
+
+## Decision
+<what was decided>
+
+## Consequences
+<positive and negative impacts>
+
+## Alternatives Considered
+<what else was evaluated and why it was rejected>
+```
+
+### 2.5 CI/CD Generation
+
+Generate CI/CD configuration based on deployment target:
+
+| Deployment | CI/CD Tool | Pipeline Stages |
+|---|---|---|
+| Vercel | GitHub Actions + Vercel | Lint → Type Check → Test → Preview Deploy → Prod Deploy |
+| AWS | GitHub Actions + AWS CDK/SAM | Lint → Test → Build → Staging Deploy → Prod Deploy |
+| GCP | GitHub Actions + Cloud Build | Lint → Test → Build → Cloud Run Deploy |
+| Self-hosted | GitHub Actions + Docker | Lint → Test → Build Image → Push → Deploy |
+
+### 2.6 Testing Strategy
+
+| Test Type | Tool | What to Test | Coverage Target |
+|---|---|---|---|
+| Unit | Jest/Vitest/pytest | Business logic, utilities, pure functions | 80% |
+| Integration | Supertest/httpx/Spring Test | API endpoints, database queries, auth flows | Key paths |
+| E2E | Playwright/Cypress | Critical user journeys (signup, core feature, payment) | Happy paths |
+| Component | Testing Library/Storybook | UI components in isolation | Key components |
+
+## Phase 3: Scaffold Output
+
+Generate all files for the new project.
+
+### 3.1 Configuration Files
+
+| File | Content |
+|---|---|
+| `engineering.config.json` | Project metadata, tech stack, conventions, sync settings |
+| `.env.example` | All required environment variables with placeholder values and comments |
+| `tsconfig.json` / `pyproject.toml` / etc. | Language-appropriate config with strict settings |
+| `.eslintrc` / `ruff.toml` / etc. | Linter config matching conventions |
+| `.prettierrc` / etc. | Formatter config |
+| `.gitignore` | Comprehensive gitignore for the selected stack |
+
+### 3.2 Pre-filled Knowledge Base
+
+Generate starter versions of all knowledge base documents (00–16) with:
+- Architecture decisions from Phase 2 as content
+- `**Not yet implemented**` for areas that will be built
+- Evidence citations pointing to generated config files
+- Conventions from Phase 2 decisions pre-populated in `16-conventions.md`
+
+### 3.3 Pre-filled Memory
+
+| Memory File | Pre-filled Content |
+|---|---|
+| `architecture-decisions.md` | ADRs from Phase 2 |
+| `technology-decisions.md` | Tech stack rationale |
+| `coding-patterns.md` | Conventions chosen during scaffold |
+| `project-constraints.md` | Scale, deployment, team constraints from interview |
+| `business-rules.md` | Core features and domain concepts from interview |
+
+### 3.4 Pre-filled Context
+
+| Context File | Pre-filled Content |
+|---|---|
+| `module-map.md` | Planned module structure from folder layout |
+| `critical-paths.md` | Core feature flows identified in interview |
+
+### 3.5 Event Guidance
+
+Generate starter event guidance files with generic templates appropriate for the chosen stack.
+
+### 3.6 Engineering Config
+
+```json
+{
+  "project": "<name>",
+  "version": "0.1.0",
+  "stack": {
+    "language": "<primary language>",
+    "framework": "<framework>",
+    "database": "<database>",
+    "orm": "<orm>",
+    "auth": "<auth solution>",
+    "deployment": "<deployment target>"
+  },
+  "conventions": {
+    "naming": "<chosen naming convention>",
+    "testing": "<chosen test strategy>",
+    "branching": "<chosen git strategy>"
+  },
+  "intelligence": {
+    "initialized": true,
+    "initializedAt": "<timestamp>",
+    "method": "greenfield-architect"
+  }
+}
+```
+
+## Procedure
+
+1. **Greet and assess** — Check if the user has provided any upfront context. Extract answers from any provided brief.
+2. **Run interview** — Ask Phase 1 questions, skipping any already answered. Present defaults.
+3. **Summarize requirements** — Present a complete requirements summary and get confirmation.
+4. **Select tech stack** — Apply Phase 2 decision matrices. Present recommendation with reasoning.
+5. **Get stack approval** — Allow the user to override any recommendation.
+6. **Generate folder structure** — Create the directory layout based on approved stack.
+7. **Generate ADRs** — Write ADR documents for each major decision.
+8. **Generate CI/CD** — Create pipeline configuration for the deployment target.
+9. **Generate configs** — Create all configuration files (linter, formatter, tsconfig, etc.).
+10. **Generate knowledge base** — Pre-fill all knowledge base documents.
+11. **Generate memory** — Pre-fill memory with decisions and constraints.
+12. **Generate context** — Pre-fill context with planned module structure.
+13. **Generate event guidance** — Create starter event guidance templates.
+14. **Write engineering.config.json** — Create the project configuration file.
+15. **Create .env.example** — List all required environment variables.
+16. **Report** — Summarize everything generated and list next steps for the developer.
+
+## Quality Gates
+
+- [ ] Requirements interview asked between 7 and 12 questions
+- [ ] Requirements summary was confirmed before architecture generation
+- [ ] Tech stack recommendation includes reasoning tied to interview answers
+- [ ] At least 5 ADRs are generated for major decisions
+- [ ] Folder structure matches the selected framework's conventions
+- [ ] CI/CD pipeline includes at minimum: lint, test, build, deploy stages
+- [ ] `.env.example` lists all required environment variables with descriptions
+- [ ] Knowledge base documents (00–16) are pre-filled with scaffolded content
+- [ ] Memory files contain only durable decisions (not transient implementation details)
+- [ ] `engineering.config.json` exists with complete project metadata
+- [ ] Testing strategy is defined with tool selection and coverage targets
+- [ ] All generated files use evidence citations pointing to other generated files
+
+## Cross-References
+
+- Uses: `codebase-discovery-engine` (for post-scaffold verification)
+- Feeds into: `initialize-intelligence-skill` (provides the initial knowledge baseline)
+- Consumed by: `engineering-intelligence-skill`, `engineering-orchestrator`
+- Related: `convention-detector` (validates conventions after initial development)

package/templates/canonical/skills/impact-analysis-engine/SKILL.md

@@ -32,9 +32,13 @@ Determine what can break before changing code. Produce a reusable impact report
    - Services communicating with changed services (from service-graph)
    - Runtime flows passing through changed code (from runtime-graph)
    - Business processes affected (from business-flow-graph)
+   - Data pipelines affected (from data-flow-graph)
    - Test suites covering affected code
+   - Cross-reference with git change coupling data from `git-intelligence-engine` for hidden dependencies
 
-5. **Score Risk** — Assign risk based on:
+5. **Trace Transitive Impact** — Follow 2nd and 3rd order effects through the graph. Identify files that are indirectly affected by consumers of the directly affected modules. Walk the dependency chain until impact attenuates or reaches a service boundary.
+
+6. **Score Risk** — Assign risk based on:
 
 | Factor | Low | Medium | High | Critical |
 |---|---|---|---|---|
@@ -43,8 +47,9 @@ Determine what can break before changing code. Produce a reusable impact report
 | **Auth impact** | None | UI changes | Permission logic | Auth flow |
 | **API contract** | None | Additive | Deprecated | Breaking |
 | **Test coverage** | Well-tested | Partial | Sparse | None |
+| **Change coupling** | None | Low (1-2 coupled files) | Medium (3-5 coupled files) | High (6+ coupled files) |
 
-6. **Identify Validation Needs** — Map impact to required validation:
+7. **Identify Validation Needs** — Map impact to required validation:
 
 | Impact Area | Validation Required |
 |---|---|
@@ -55,7 +60,9 @@ Determine what can break before changing code. Produce a reusable impact report
 | UI change | Visual regression, accessibility |
 | Infrastructure | Deploy to staging, smoke test |
 
-7. **Map Intelligence Artifacts** — Determine which intelligence artifacts need synchronization after the change is implemented.
+8. **Map Intelligence Artifacts** — Determine which intelligence artifacts need synchronization after the change is implemented.
+
+> **Surprise Impact Detection**: Flag any dependency discovered during analysis that is NOT in the current graph — these are surprise impacts that should be added to the graph. Surprise impacts indicate missing edges or nodes and must be reported in the Unknowns section of the impact report.
 
 ## Output Format
 
@@ -129,6 +136,7 @@ Write `.engineering-intelligence/reports/IMP-XXX-<slug>.md`:
 
 ## Cross-References
 
-- Depends on: `change-detection-engine`, `graph-engine`
+- Depends on: `change-detection-engine`, `graph-engine`, `git-intelligence-engine`
+- Consults: `data-flow-graph.json` (for data pipeline impact)
 - Used by: `engineering-intelligence-skill`, `incremental-sync-engine`, `analyze-impact` workflow
 - Consumed by: `engineering-change-review`, `testing-intelligence-engine`

package/templates/canonical/skills/incremental-sync-engine/SKILL.md

@@ -30,6 +30,8 @@ Use this matrix to determine which artifact types need updating based on the cha
 | Refactor (no behavior change) | — | `coding-patterns.md` | affected maps | — | dependency-graph | — |
 | Test changes only | — | — | — | — | — | — |
 | Config/env changes | `09-infrastructure.md` | `project-constraints.md` | — | — | — | — |
+| Convention changed | `16-conventions.md` | `coding-patterns.md` | — | — | — | — |
+| Security concern detected | `20-security-assessment.md` | — | — | — | — | — |
 
 ## Procedure
 
@@ -62,6 +64,20 @@ Use this matrix to determine which artifact types need updating based on the cha
 
 8. **Update Impact Report** — Add a synchronization notes section to the original impact report recording what was synced.
 
+9. **Check Freshness** — After sync, update freshness metadata on all modified documents. If any document freshness score drops below 40, flag for full re-verification using `staleness-detector`.
+
+## Confidence Decay
+
+Confidence scores decrease over time without re-verification:
+
+| Changes Since Last Verification | Confidence Level |
+|---|---|
+| 0–9 changes | Maintains current confidence |
+| 10–24 changes | Drops from `verified` to `inferred` |
+| 25+ changes | Drops to `unknown` |
+
+During sync, check how many changes have occurred since each artifact was last verified. Apply decay rules and flag artifacts that have dropped confidence for re-verification.
+
 ## Rules
 
 - **Incremental only**: Update only artifacts identified by the impact report — never regenerate unrelated content
@@ -84,3 +100,4 @@ Use this matrix to determine which artifact types need updating based on the cha
 - Depends on: `change-detection-engine`, `impact-analysis-engine`, `graph-engine`
 - Used by: `engineering-intelligence-skill`, `sync-engineering-intelligence` workflow
 - Delegates to: `knowledge-sync-engine`, `memory-sync-engine`, `context-sync-engine`
+- Integrates with: `staleness-detector` (freshness checks), `convention-detector` (convention sync)

package/templates/canonical/skills/mcp-security-governor/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: mcp-security-governor
+description: Reviews MCP tools and external execution surfaces for scoped authorization, schema integrity, sandboxing, and human approval gates.
+version: 1.0.0
+---
+
+# MCP Security Governor
+
+Use this skill when a project configures MCP servers, external tool execution, CI/CD automation, database access, deployment tools, or any agent-callable side effect.
+
+## Security Model
+
+Check for defense in depth:
+- OAuth 2.1 or equivalent modern authorization for remote servers
+- PKCE for public clients where applicable
+- Server metadata validation before authorization
+- Tool-level permissions rather than server-level blanket permissions
+- Explicit user approval for destructive or irreversible actions
+- Tool schema hashing or pinning to detect schema drift
+- Sandboxed local execution with workspace-scoped filesystem access
+- Secrets kept out of prompts, logs, artifacts, and generated documentation
+
+## MCP Review Artifact
+
+Write `.engineering-intelligence/aidlc/operations/mcp-security-review.md`:
+
+```markdown
+# MCP Security Review
+
+## Configurations Reviewed
+- <path or Not detected>
+
+## Tool Inventory
+| Server | Tool | Capability | Permission Scope | Destructive | Approval Required |
+|---|---|---|---|---|---|
+
+## Risks
+- <risk, evidence, severity>
+
+## Required Controls
+- <control and implementation owner>
+
+## Approval Boundaries
+- <actions that must never run without human confirmation>
+```
+
+## Rules
+
+- Do not grant a tool broader filesystem, network, or deployment permission than the task requires.
+- Treat changed tool definitions as untrusted until revalidated.
+- Destructive actions must expose raw parameters to the user before execution.

package/templates/canonical/skills/nfr-adr-governor/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: nfr-adr-governor
+description: Captures non-functional requirements, maps them to architectural patterns, and governs ADR lifecycle states.
+version: 1.0.0
+---
+
+# NFR And ADR Governor
+
+Use this skill for performance, reliability, security, privacy, compliance, scalability, compatibility, migration, and operational constraints.
+
+## NFR Requirements
+
+Write `.engineering-intelligence/aidlc/construction/<unit>/nfr-requirements.md`:
+
+```markdown
+# NFR Requirements: <unit>
+
+| Dimension | Target | Evidence / Source | Validation Method |
+|---|---|---|---|
+| Latency | <p50/p95/p99> | <source> | <test/monitor> |
+| Throughput | <target> | <source> | <load/perf test> |
+| Reliability | <SLO/SLA> | <source> | <failure test> |
+| Security | <standard/control> | <source> | <scan/review/test> |
+| Data | <volume/retention/migration> | <source> | <migration/test> |
+| Compatibility | <API/browser/runtime> | <source> | <contract test> |
+```
+
+## NFR Design
+
+Write `.engineering-intelligence/aidlc/construction/<unit>/nfr-design/design.md` with concrete patterns. Examples: circuit breaker with exponential backoff, idempotency keys, bulkheads, rate limits, schema expansion/contraction, cache invalidation, trace correlation, policy-based authorization.
+
+## ADR Lifecycle
+
+Create an ADR only when two or more distinct alternatives were considered.
+
+Allowed states:
+- `Proposed`
+- `Accepted`
+- `Rejected`
+- `Superseded`
+
+Accepted ADRs are immutable. To change one, create a new `Proposed` ADR and mark the old accepted ADR as `Superseded by ADR-NNNN` after the new decision is accepted.
+
+ADR path:
+
+```text
+.engineering-intelligence/aidlc/construction/<unit>/nfr-design/decision-records/ADR-NNNN-<slug>.md
+```
+
+ADR template:
+
+```markdown
+# ADR-NNNN: <decision>
+
+## Status
+Proposed
+
+## Context
+<problem, constraints, NFR drivers>
+
+## Options Considered
+- Option A: <tradeoffs>
+- Option B: <tradeoffs>
+
+## Decision
+<chosen option when accepted>
+
+## Consequences
+- Positive: <benefits>
+- Negative: <costs>
+- Validation: <how this will be tested>
+
+## Supersedes / Superseded By
+<links or Not applicable>
+```
+
+## Quality Gates
+
+- [ ] NFRs are measurable where possible
+- [ ] Design patterns map back to NFR targets
+- [ ] ADR exists only when alternatives were considered
+- [ ] ADR state transitions are explicit
+- [ ] Accepted ADRs are not edited except to mark supersession