engineering-intelligence 0.8.0 → 1.0.0

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/ongoing-learning-engine/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ongoing-learning-engine
+description: Handles post-initialization continuous learning by detecting uncertainty, logging learning events, triggering targeted re-discovery, updating memory with newly learned patterns, tracking knowledge freshness scores, and enforcing staleness detection rules.
+version: 3.0.0
+---
+
+# Ongoing Learning Engine
+
+Continuously maintain and improve the AI's understanding of a codebase after initial discovery. This engine activates whenever the AI encounters areas it does not understand, when code changes invalidate existing knowledge, or when knowledge freshness degrades below acceptable thresholds.
+
+This capability does not modify product code.
+
+## Inputs
+
+- Current task context (what the AI is trying to do when uncertainty is encountered)
+- Repository root path
+- Existing knowledge base, memory, and context documents
+- Optional: specific module or area to re-learn
+- Optional: trigger event (uncertainty, staleness, explicit request)
+
+## Trigger Conditions
+
+The ongoing learning engine activates under these conditions:
+
+| Trigger | Condition | Action |
+|---|---|---|
+| **Uncertainty encountered** | AI cannot confidently answer a question about the codebase | Log uncertainty event, initiate targeted re-discovery |
+| **Staleness threshold** | Knowledge freshness score drops below 60 for a module | Trigger incremental re-scan of the stale module |
+| **Code change detected** | Files in a module changed since last knowledge update | Queue module for freshness re-evaluation |
+| **Explicit request** | User asks to re-learn or refresh understanding of an area | Full re-discovery of specified scope |
+| **Convention drift** | Detected patterns deviate from documented conventions | Log drift event, update conventions |
+| **New dependency** | A new package/dependency is added to the project | Scan and document the new dependency |
+
+## Procedure
+
+1. **Detect uncertainty** — Monitor for these uncertainty signals during any task:
+   - Unable to locate a file or module referenced in knowledge base
+   - Code structure does not match documented architecture
+   - An import path or API endpoint has changed
+   - A function signature or behavior differs from documentation
+   - A convention violation is found in new code (drift vs intentional change)
+   - Business logic encountered that has no corresponding documentation
+
+2. **Log uncertainty event** — Write to `.engineering-intelligence/events/uncertainty-log.md`:
+
+   ```markdown
+   ## <timestamp> — Uncertainty Event
+
+   - **Trigger**: <what the AI was doing>
+   - **Area**: <module/file/concept>
+   - **Type**: missing | outdated | contradictory | ambiguous
+   - **Severity**: low | medium | high | critical
+   - **Description**: <what is uncertain and why>
+   - **Current knowledge**: <what the existing docs say>
+   - **Observed reality**: <what the code actually shows>
+   - **Resolution**: pending | resolved | deferred
+   ```
+
+3. **Classify the uncertainty** — Determine the appropriate response:
+
+   | Type | Description | Response |
+   |---|---|---|
+   | **Missing** | No documentation exists for this area | Trigger targeted re-discovery |
+   | **Outdated** | Documentation exists but is stale | Trigger incremental sync of affected documents |
+   | **Contradictory** | Documentation contradicts code evidence | Flag for human review, update with code-as-truth |
+   | **Ambiguous** | Multiple interpretations are plausible | Log both interpretations, ask for clarification |
+
+4. **Execute targeted re-discovery** — For the specific area of uncertainty:
+   - Re-scan only the affected module/directory (not the full repository)
+   - Compare new findings against existing documentation
+   - Identify what changed and what is new
+   - Use `codebase-discovery-engine` scanning techniques but scoped to the specific area
+
+5. **Update knowledge** — Apply changes to the appropriate knowledge documents:
+   - Update knowledge base documents with corrected information
+   - Add `Last updated:` timestamp to modified sections
+   - Preserve evidence citations — update with new file paths/line numbers
+   - Record the update in the uncertainty log as `resolved`
+
+6. **Durability check** — Before writing any new pattern or fact to memory, apply these filters:
+   - **Will this still be relevant after 5+ more changes?** If no → do not store in memory
+   - **Is this a project-wide pattern or a local implementation detail?** If local → do not store in memory
+   - **Does this duplicate existing memory?** If yes → merge rather than add
+   - **Is this a transient state or a durable decision?** If transient → log in events, not memory
+
+7. **Track knowledge freshness** — Maintain freshness scores per module:
+
+   ```markdown
+   ## Knowledge Freshness Tracker
+
+   | Module | Last Scanned | Last Code Change | Freshness Score | Status |
+   |---|---|---|---|---|
+   | auth/ | 2024-01-15 | 2024-01-20 | 45 | 🔴 Stale |
+   | api/ | 2024-01-18 | 2024-01-18 | 95 | 🟢 Fresh |
+   | ... | ... | ... | ... | ... |
+   ```
+
+   **Freshness score calculation:**
+   - Start at 100 when a module is scanned
+   - Subtract 5 points per day since last scan if code has changed
+   - Subtract 2 points per day since last scan if code has NOT changed (knowledge can still drift)
+   - Subtract 10 points per file changed in module since last scan
+   - Floor at 0, cap at 100
+
+8. **Staleness detection** — Apply these rules continuously:
+
+   | Rule | Threshold | Action |
+   |---|---|---|
+   | Module freshness < 60 | Score drops below 60 | Queue for targeted re-discovery |
+   | Module freshness < 30 | Score drops below 30 | Flag as critical, prioritize re-discovery |
+   | No scan in 30 days | 30 days elapsed | Flag for freshness check regardless of score |
+   | >10 files changed since scan | File change count | Trigger immediate re-scan |
+   | Architecture document stale | Any architecture doc with freshness < 50 | Trigger full architecture re-assessment |
+
+9. **Generate learning summary** — Periodically (or on request) produce a learning summary:
+
+   ```markdown
+   ## Learning Summary — <date range>
+
+   ### Uncertainty Events
+   - Total events: <N>
+   - Resolved: <N>
+   - Pending: <N>
+   - Deferred: <N>
+
+   ### Knowledge Updates
+   - Documents updated: <list>
+   - Memory entries added: <N>
+   - Memory entries revised: <N>
+   - Memory entries retired: <N>
+
+   ### Freshness Overview
+   - Modules scanned: <N>
+   - Average freshness: <score>
+   - Stale modules (< 60): <list>
+   - Critical modules (< 30): <list>
+
+   ### Patterns Learned
+   - <new patterns discovered this period>
+
+   ### Open Questions
+   - <questions that need human input>
+   ```
+
+## Output Files
+
+| File | Purpose |
+|---|---|
+| `.engineering-intelligence/events/uncertainty-log.md` | Append-only log of all uncertainty events |
+| `.engineering-intelligence/reports/FRESHNESS-report.md` | Current freshness scores per module (shared with `staleness-detector`) |
+| Updated knowledge base documents | Corrected or expanded knowledge |
+| Updated memory documents | New durable patterns and decisions |
+
+## Quality Gates
+
+- [ ] Every uncertainty event is logged before any re-discovery begins
+- [ ] Uncertainty events include type, severity, and description
+- [ ] Targeted re-discovery scopes to the affected module only (not full repo)
+- [ ] Durability check is applied before any memory write
+- [ ] Knowledge freshness scores are calculated using the defined formula
+- [ ] Staleness thresholds trigger appropriate actions
+- [ ] Updated documents preserve evidence citation format
+- [ ] Learning summary is accurate and reflects actual events
+- [ ] No transient implementation details are stored in memory
+- [ ] Contradictory findings are flagged for human review (not silently resolved)
+
+## Cross-References
+
+- Depends on: `codebase-discovery-engine` (for targeted re-discovery techniques)
+- Uses: `staleness-detector` (for freshness scoring), `incremental-sync-engine` (for knowledge updates)
+- Consumed by: `engineering-intelligence-skill`, `engineering-orchestrator`
+- Feeds into: `.engineering-intelligence/events/uncertainty-log.md`, all knowledge base documents
+- Related: `convention-detector` (for convention drift detection)
+
+This capability does not modify product code.