engineering-intelligence 0.2.0 → 0.3.0

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

@@ -1,19 +1,24 @@
 ---
 name: graph-engine
-description: Builds and incrementally maintains evidence-backed dependency, service, runtime, and business-flow graph artifacts with a human-readable architecture map. Use during initialization, explicit architecture mapping, or changes that affect relationships.
+description: Builds and maintains evidence-backed JSON architecture graphs and Mermaid architecture maps representing project dependencies, services, runtime flows, and business processes.
+version: 3.0.0
 ---
 
 # Graph Engine
 
-Generate project graph intelligence under `.engineering-intelligence/graph/`:
+Build and maintain structured, evidence-backed architecture graphs that enable impact analysis, dependency tracing, and architectural understanding.
 
-- `dependency-graph.json`: modules, packages, shared libraries, imports, and dependency relationships
-- `service-graph.json`: deployable services, databases, queues, external integrations, and communication links
-- `runtime-graph.json`: startup, request, job, and event execution paths
-- `business-flow-graph.json`: verified business/user workflows and participating code or services
-- `architecture-map.md`: Mermaid diagrams and human-readable interpretation of the JSON graphs
+## Inputs
 
-## Graph JSON Contract
+- Repository root path
+- Mode: `full` (initialization/remapping) or `incremental` (post-change update)
+- Optional: scope constraints for incremental updates
+
+## Graph Artifacts
+
+All graphs are stored in `.engineering-intelligence/graph/`.
+
+### Graph JSON Schema
 
 Each JSON graph uses this envelope:
 
@@ -30,6 +35,7 @@ Each JSON graph uses this envelope:
       "label": "<human name>",
       "path": "<repository path when applicable>",
       "confidence": "verified | inferred | unknown",
+      "metadata": {},
       "evidence": ["<file path or configuration evidence>"]
     }
   ],
@@ -39,6 +45,7 @@ Each JSON graph uses this envelope:
       "to": "<node id>",
       "relation": "<relationship>",
       "confidence": "verified | inferred | unknown",
+      "metadata": {},
       "evidence": ["<file path or configuration evidence>"]
     }
   ],
@@ -46,13 +53,126 @@ Each JSON graph uses this envelope:
 }
 ```
 
+### 1. `dependency-graph.json` — Module/Package Dependencies
+
+| Node Kind | Description |
+|---|---|
+| `package` | npm/pip/cargo/go package |
+| `module` | Internal code module or directory |
+| `config` | Configuration file or env dependency |
+| `external` | Third-party library or service SDK |
+
+| Edge Relation | Description |
+|---|---|
+| `imports` | Direct import/require dependency |
+| `devDependency` | Development-only dependency |
+| `peerDependency` | Peer/optional dependency |
+| `configures` | Configuration dependency |
+
+### 2. `service-graph.json` — Service Communication Topology
+
+| Node Kind | Description |
+|---|---|
+| `service` | Deployable service or process |
+| `database` | Data store (SQL, NoSQL, cache) |
+| `queue` | Message queue or event bus |
+| `gateway` | API gateway or load balancer |
+| `external-api` | Third-party API endpoint |
+
+| Edge Relation | Description |
+|---|---|
+| `http` | HTTP/REST communication |
+| `grpc` | gRPC communication |
+| `publishes` | Event/message publishing |
+| `subscribes` | Event/message consumption |
+| `reads` | Data store read access |
+| `writes` | Data store write access |
+
+### 3. `runtime-graph.json` — Runtime Call Flows
+
+| Node Kind | Description |
+|---|---|
+| `entrypoint` | Application entry point |
+| `middleware` | Request middleware/interceptor |
+| `handler` | Route handler or controller |
+| `service-layer` | Business logic service |
+| `repository` | Data access layer |
+| `background` | Background job or worker |
+
+| Edge Relation | Description |
+|---|---|
+| `calls` | Synchronous function/method call |
+| `delegates` | Async delegation or queue dispatch |
+| `wraps` | Middleware wrapping |
+| `returns` | Response return path |
+
+### 4. `business-flow-graph.json` — Business Process Flows
+
+| Node Kind | Description |
+|---|---|
+| `user-action` | User-initiated action |
+| `system-step` | System processing step |
+| `decision` | Conditional branch point |
+| `integration` | External system interaction |
+| `outcome` | Terminal state or result |
+
+| Edge Relation | Description |
+|---|---|
+| `triggers` | Causal trigger |
+| `on-success` | Happy path flow |
+| `on-failure` | Error/failure path |
+| `requires` | Prerequisite relationship |
+
+### 5. `architecture-map.md` — Mermaid Visualization
+
+Derive Mermaid diagrams from the JSON graphs. Include:
+
+- **System Overview** — High-level service topology (from service-graph)
+- **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)
+
+## 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
+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`
+
+### Incremental Mode (post-change update)
+
+1. Accept changed files/scope from the impact report or diff
+2. Identify affected nodes and edges across all graphs
+3. Update, add, or remove only affected nodes and edges
+4. Preserve stable node IDs — only change an ID if the represented element was renamed
+5. Re-derive affected sections of `architecture-map.md`
+6. Require full remapping only when structural impact cannot be bounded
+
 ## Rules
 
-- Keep node IDs stable across incremental updates while the represented element still exists.
-- Never mark an edge `verified` without evidence paths.
-- Distinguish inferred and unknown relationships clearly.
-- Derive Mermaid diagrams in `architecture-map.md` from the JSON graph content.
-- Rebuild all graphs on initialization, explicit mapping, or when structural impact cannot be bounded.
-- For ordinary changes, update only impacted nodes, edges, maps, and connected context documents.
+- Keep node IDs stable across incremental updates while the represented element still exists
+- Never mark an edge `verified` without evidence paths
+- Distinguish `inferred` and `unknown` relationships clearly
+- Derive Mermaid diagrams in `architecture-map.md` from the JSON graph content — never hand-author diagrams that contradict the JSON
+- For ordinary changes, update only impacted nodes, edges, maps, and connected context documents
+- Rebuild all graphs on initialization, explicit mapping request, or when structural impact cannot be bounded
+
+## Quality Gates
+
+- [ ] All four JSON graphs 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
+- [ ] Node IDs are stable across incremental updates
+
+## Cross-References
+
+- Used by: `initialize-intelligence-skill`, `impact-analysis-engine`, `incremental-sync-engine`
+- Supports: `map-architecture` workflow, `analyze-impact` workflow
+- Feeds context to: `context-sync-engine`
 
 This capability may write intelligence artifacts. It must not modify product code.

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

@@ -1,20 +1,134 @@
 ---
 name: impact-analysis-engine
 description: Determines direct and indirect impact of a proposed or implemented change across modules, APIs, schemas, runtime flows, infrastructure, integrations, and tests. Use before implementation and during synchronization.
+version: 3.0.0
 ---
 
-# Impact Analysis
+# Impact Analysis Engine
 
-Determine what can break before changing code. Analyze imports, callers, routes, data schemas, events, configuration, services, infrastructure, and existing tests.
+Determine what can break before changing code. Produce a reusable impact report that guides implementation, testing, and synchronization decisions.
 
-Read `.engineering-intelligence/graph/` when available. If graphs are missing or stale for the assessed scope, invoke `graph-engine` to establish or refresh the necessary graph context.
+## Inputs
 
-Write a reusable `.engineering-intelligence/reports/IMP-XXX-<slug>.md` impact report containing:
+- Change scope from `change-detection-engine` (proposal description, diff, commit range, or file list)
+- Graph intelligence from `.engineering-intelligence/graph/` (when available)
+- Project intelligence from `knowledge-base/` and `.engineering-intelligence/`
 
-- mode (`proposal` or `diff`) and inspected scope
-- graph inputs consulted or refreshed
-- directly affected files and systems
-- indirect dependencies and risks
-- required validation and tests
-- documentation, memory, context, event, and graph artifacts affected by the change
-- evidence, unknowns, and an explicit statement that impact analysis did not modify product code
+## Procedure
+
+1. **Resolve Scope** — Accept the change scope. If ambiguous, ask for clarification — never assume.
+
+2. **Consult Graphs** — Read `.engineering-intelligence/graph/` for dependency, service, runtime, and business-flow relationships. If graphs are missing or stale for the assessed scope, invoke `graph-engine` to establish or refresh the necessary graph context.
+
+3. **Trace Direct Impact** — Identify:
+   - Files directly modified or proposed for modification
+   - Functions, classes, types, and interfaces changed
+   - API contracts affected (routes, request/response shapes)
+   - Database schemas or migrations affected
+   - Configuration changes
+
+4. **Trace Indirect Impact** — Using graph intelligence, identify:
+   - Downstream consumers of changed modules (from dependency-graph)
+   - Services communicating with changed services (from service-graph)
+   - Runtime flows passing through changed code (from runtime-graph)
+   - Business processes affected (from business-flow-graph)
+   - Test suites covering affected code
+
+5. **Score Risk** — Assign risk based on:
+
+| Factor | Low | Medium | High | Critical |
+|---|---|---|---|---|
+| **Blast radius** | 1–2 files | 3–10 files | 10+ files | Cross-service |
+| **Data impact** | None | Read paths | Write paths | Schema migration |
+| **Auth impact** | None | UI changes | Permission logic | Auth flow |
+| **API contract** | None | Additive | Deprecated | Breaking |
+| **Test coverage** | Well-tested | Partial | Sparse | None |
+
+6. **Identify Validation Needs** — Map impact to required validation:
+
+| Impact Area | Validation Required |
+|---|---|
+| API contract change | Integration tests, contract tests |
+| Schema change | Migration test, rollback test |
+| Auth change | Security test, permission matrix |
+| Runtime flow change | End-to-end test |
+| 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.
+
+## Output Format
+
+Write `.engineering-intelligence/reports/IMP-XXX-<slug>.md`:
+
+```markdown
+# IMP-XXX: <descriptive title>
+
+## Meta
+- Generated: <ISO timestamp>
+- Mode: proposal | diff
+- Scope: <description of what was analyzed>
+- Risk: low | medium | high | critical
+
+## Graph Inputs
+- Consulted: <list of graph artifacts read>
+- Refreshed: <list of graphs rebuilt, if any>
+- Missing: <graphs not available>
+
+## Direct Impact
+| File/Module | Change Type | Risk |
+|---|---|---|
+| path/to/file.ts | Modified function `handleAuth` | high |
+
+## Indirect Impact
+| Affected Area | Relationship | Confidence |
+|---|---|---|
+| UserService | Imports changed module | verified |
+| /api/users endpoint | Calls modified handler | inferred |
+
+## Risk Assessment
+- Overall risk: <level>
+- Key risk factors: <list>
+- Mitigations: <recommended actions>
+
+## Validation Requirements
+- [ ] <specific test or check needed>
+
+## Intelligence Artifacts Affected
+| Artifact | Reason |
+|---|---|
+| knowledge-base/04-api-documentation.md | API contract changed |
+| .engineering-intelligence/graph/service-graph.json | New service dependency |
+
+## Evidence
+- <file path citations>
+
+## Unknowns
+- <uncertain impact areas>
+
+---
+*This impact analysis did not modify product code.*
+```
+
+## Rules
+
+- Never assume scope — ask when ambiguous
+- Always consult available graphs before tracing impact manually
+- Risk scoring must be justified with evidence
+- The output report is reusable by `incremental-sync-engine` and `engineering-change-review`
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] Scope is explicitly stated (not assumed)
+- [ ] Graph inputs are listed (consulted, refreshed, or missing)
+- [ ] Direct and indirect impact are separated
+- [ ] Risk score is justified with evidence
+- [ ] Validation requirements are specific (not generic)
+- [ ] Report ends with the "did not modify product code" statement
+
+## Cross-References
+
+- Depends on: `change-detection-engine`, `graph-engine`
+- 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

@@ -1,21 +1,86 @@
 ---
 name: incremental-sync-engine
 description: Synchronizes only intelligence artifacts affected by a completed change or identified diff, including knowledge, memory, context, events, graphs, and reports. Use for explicit synchronization or after implementation.
+version: 3.0.0
 ---
 
 # Incremental Sync Engine
 
-Read the completed diff, change record, supplied changed scope, and any existing impact report. If no impact report exists for the scope, run impact analysis first and write one under `.engineering-intelligence/reports/`.
+Update only the intelligence artifacts affected by a specific change. Never regenerate unrelated content.
 
-Update only affected:
+## Inputs
 
-- `knowledge-base/` documentation
-- `.engineering-intelligence/memory/`
-- `.engineering-intelligence/context/`
-- `.engineering-intelligence/events/`
-- `.engineering-intelligence/graph/` JSON graphs and `architecture-map.md`
-- the associated impact report synchronization notes
+- Completed diff, change record, or supplied changed scope
+- Existing impact report (`.engineering-intelligence/reports/IMP-XXX-*.md`)
+- If no impact report exists for the scope, run `impact-analysis-engine` first
 
-Use incremental graph changes by default. Require full graph remapping only for broad or unbounded structural changes.
+## Sync Decision Matrix
 
-As a standalone synchronization capability, do not write `.changes/CHG-XXX-*` records and do not modify product code.
+Use this matrix to determine which artifact types need updating based on the change type:
+
+| Change Type | Knowledge Base | Memory | Context | Events | Graphs | Reports |
+|---|---|---|---|---|---|---|
+| API route added/changed | `04-api-documentation.md` | — | `module-map.md` | `api-changed.md` | runtime-graph | IMP update |
+| Database schema changed | `05-database.md` | — | — | `schema-changed.md` | dependency-graph | IMP update |
+| Auth flow changed | `06-authentication.md` | `business-rules.md` | `critical-paths.md` | `auth-changed.md` | runtime-graph | IMP update |
+| New feature added | `07/08-frontend/backend.md` | — | `module-map.md` | `feature-added.md` | dependency-graph | IMP update |
+| Architecture decision | `02-architecture.md` | `architecture-decisions.md` | all maps | — | all graphs | IMP update |
+| Dependency added/removed | `01-repository-structure.md` | `technology-decisions.md` | `dependency-map.md` | — | dependency-graph | IMP update |
+| Infrastructure changed | `09-infrastructure.md` | — | — | `infrastructure-changed.md` | service-graph | IMP update |
+| Refactor (no behavior change) | — | `coding-patterns.md` | affected maps | — | dependency-graph | — |
+| Test changes only | — | — | — | — | — | — |
+| Config/env changes | `09-infrastructure.md` | `project-constraints.md` | — | — | — | — |
+
+## Procedure
+
+1. **Read Impact Report** — Get the list of affected intelligence artifacts from the impact report. If no report exists, run `impact-analysis-engine` to create one.
+
+2. **Classify Changes** — Match each change against the sync decision matrix above.
+
+3. **Update Knowledge Base** — For each affected `knowledge-base/` document:
+   - Read the current document
+   - Identify the specific section(s) affected
+   - Update only those sections with new evidence
+   - Preserve all accurate existing content
+   - Add evidence citations for all changed claims
+
+4. **Update Memory** — Only if a durable decision, rule, constraint, pattern, or technology choice changed:
+   - Update the specific entry in the relevant memory document
+   - Add a `Last updated:` timestamp and reason
+
+5. **Update Context** — Only if module, service, runtime, dependency, critical-path, or risk topology changed:
+   - Update the specific entries in affected map documents
+   - Keep maps concise and navigational
+
+6. **Update Events** — Only if API, schema, auth, feature, or infrastructure contracts changed:
+   - Verify the change-event guidance still reflects the current system
+
+7. **Update Graphs** — Use `graph-engine` in incremental mode:
+   - Update only affected nodes and edges
+   - Preserve stable node IDs
+   - Require full remapping only for unbounded structural changes
+
+8. **Update Impact Report** — Add a synchronization notes section to the original impact report recording what was synced.
+
+## Rules
+
+- **Incremental only**: Update only artifacts identified by the impact report — never regenerate unrelated content
+- **Evidence required**: Attach evidence for every changed claim
+- **Preserve accuracy**: Don't modify correct existing content
+- **Full remap trigger**: Require full graph remapping only for broad structural changes (major refactors, architecture changes)
+- **No change records**: As a standalone synchronization capability, do not write `.changes/CHG-XXX-*` records
+- **No product code**: Must not modify product code
+
+## Quality Gates
+
+- [ ] Impact report was consulted (or created) before syncing
+- [ ] Only affected artifacts were modified
+- [ ] Unrelated content was preserved unchanged
+- [ ] Evidence citations were added for changed claims
+- [ ] Graph updates used incremental mode (unless structural change required full remap)
+
+## Cross-References
+
+- 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`

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

@@ -0,0 +1,130 @@
+---
+name: initialize-intelligence-skill
+description: Initializes project engineering intelligence by analyzing repository evidence and generating knowledge, context, memory, event guidance, architecture graphs, and an initialization change record. Invoke when onboarding a repository or when asked to initialize engineering intelligence.
+version: 3.0.0
+---
+
+# Initialize Engineering Intelligence
+
+Create a trustworthy, evidence-backed project intelligence baseline. Analyze only artifacts present in source code, configuration, tests, infrastructure, and existing documentation. Mark unknowns and uncertainties explicitly — never invent architecture, APIs, schemas, or business rules.
+
+## Inputs
+
+- Repository root path (current working directory by default)
+- Optional: explicit scope constraints (monorepo package, service boundary)
+
+## Outputs
+
+Generate the following artifacts in order:
+
+### Knowledge Base (`knowledge-base/`)
+
+| Document | Purpose |
+|---|---|
+| `00-project-overview.md` | Name, purpose, tech stack, repo structure summary |
+| `01-repository-structure.md` | Directory tree, package boundaries, build artifacts |
+| `02-architecture.md` | Layers, modules, boundaries, communication patterns |
+| `03-runtime-flow.md` | Request lifecycle, startup, shutdown, async flows |
+| `04-api-documentation.md` | Routes, endpoints, GraphQL schemas, RPC interfaces |
+| `05-database.md` | Schemas, migrations, ORMs, data stores, caching |
+| `06-authentication.md` | Auth flows, session management, RBAC, tokens |
+| `07-frontend.md` | UI framework, routing, state management, components |
+| `08-backend.md` | Server framework, middleware, service patterns |
+| `09-infrastructure.md` | CI/CD, containers, cloud, deployment, environments |
+| `10-integrations.md` | Third-party APIs, SDKs, webhooks, message queues |
+| `11-complex-areas.md` | High-complexity modules, tricky logic, footguns |
+| `12-technical-debt.md` | Known debt, deprecated patterns, migration needs |
+| `13-onboarding.md` | Setup guide, dev workflow, common tasks |
+| `14-glossary.md` | Domain terms, abbreviations, naming conventions |
+| `15-validation-report.md` | Evidence audit of all claims made above |
+
+### Durable Memory (`.engineering-intelligence/memory/`)
+
+| Document | Content |
+|---|---|
+| `architecture-decisions.md` | ADRs, architectural choices, rationale |
+| `business-rules.md` | Domain rules, invariants, constraints from code |
+| `coding-patterns.md` | Recurring patterns, conventions, idioms |
+| `project-constraints.md` | Performance budgets, compatibility, regulatory |
+| `technology-decisions.md` | Stack choices, version policies, deprecation plans |
+
+### Navigation Context (`.engineering-intelligence/context/`)
+
+| Document | Content |
+|---|---|
+| `module-map.md` | Module names → paths → responsibilities |
+| `service-map.md` | Services → ports → protocols → dependencies |
+| `runtime-map.md` | Entry points → middleware chains → handlers |
+| `critical-paths.md` | Revenue, auth, data-integrity flows |
+| `dangerous-areas.md` | Fragile code, missing tests, race conditions |
+| `dependency-map.md` | External deps → internal consumers → risk |
+
+### Event Guidance (`.engineering-intelligence/events/`)
+
+| Document | Trigger |
+|---|---|
+| `api-changed.md` | When API routes, payloads, or contracts change |
+| `schema-changed.md` | When database schemas or migrations change |
+| `auth-changed.md` | When auth flows or permissions change |
+| `feature-added.md` | When new user-facing features are introduced |
+| `infrastructure-changed.md` | When CI, deployment, or infra config changes |
+
+### Architecture Graphs (`.engineering-intelligence/graph/`)
+
+| Artifact | Content |
+|---|---|
+| `dependency-graph.json` | Module/package dependency relationships |
+| `service-graph.json` | Service-to-service communication topology |
+| `runtime-graph.json` | Runtime call flows and middleware chains |
+| `business-flow-graph.json` | Business process flows across system boundaries |
+| `architecture-map.md` | Mermaid diagrams derived from JSON graphs |
+
+### Change History
+
+| Artifact | Content |
+|---|---|
+| `.changes/CHG-000-initialization.md` | Record of this initialization run |
+
+## Procedure
+
+1. **Discover** — Scan for: package manifests, workspace configs, runtimes (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, etc.), build systems, entrypoints, CI configs, Dockerfiles, deployment manifests, environment examples, database schemas/migrations, API definitions, auth configs, test suites.
+
+2. **Trace Architecture** — Follow imports, dependency injection, middleware registration, route definitions, event handlers, and service boundaries. Map the critical runtime flows from code evidence, not assumptions.
+
+3. **Write Knowledge Base** — For each document:
+   - Open with a one-paragraph summary
+   - Back every material claim with a file path reference: `(evidence: path/to/file:L42)`
+   - Use `**Not detected**` for absent features, not silence
+   - Use `**Unclear from evidence** — [reason]` for ambiguous areas
+   - Use tables, code blocks, and structured lists — never prose walls
+
+4. **Validate Claims** — Re-read each knowledge document, check major claims against actual files, and write `15-validation-report.md` with findings categorized as: ✅ Supported, ⚠️ Partially Supported, ❌ Unsupported, ❓ Needs Human Review.
+
+5. **Generate Memory** — Extract only durable, long-lived decisions and patterns. Do NOT store transient implementation details. Each entry needs a `Source:` evidence reference.
+
+6. **Generate Context** — Create concise, navigational maps. Each map should fit in ~100 lines. Optimize for an AI agent quickly finding the right file, not for human reading.
+
+7. **Build Graphs** — Invoke `graph-engine` to produce all four JSON graphs and `architecture-map.md`. Every node and edge must have `evidence` and `confidence` fields.
+
+8. **Generate Events** — Write change-event guidance documents that describe what to check and update when specific types of changes occur.
+
+9. **Write History** — Create `CHG-000-initialization.md` with: timestamp, artifacts generated, confidence summary, areas needing human confirmation.
+
+10. **Report** — Summarize: total artifacts created, evidence coverage percentage estimate, high-confidence vs low-confidence areas, explicit list of items requiring human review.
+
+## Quality Gates
+
+- [ ] Every knowledge document has at least one evidence citation
+- [ ] No document contains invented implementation details
+- [ ] Validation report exists and covers all knowledge documents
+- [ ] All four graph JSON files validate against the graph-engine schema
+- [ ] Memory contains only durable, long-lived knowledge
+- [ ] Context maps are concise (< 150 lines each)
+- [ ] CHG-000 record exists and lists all generated artifacts
+
+## Cross-References
+
+- Uses: `deep-project-knowledge-extractor`, `knowledge-base-validator`, `graph-engine`, `change-history-engine`
+- Consumed by: `engineering-intelligence-skill`, all sync engines, `impact-analysis-engine`
+
+This initialization documents and validates the project. It does not implement product changes.

package/templates/canonical/skills/knowledge-base-validator/SKILL.md

@@ -1,17 +1,102 @@
 ---
 name: knowledge-base-validator
 description: Validates project knowledge documentation against source and configuration evidence, identifying stale, unsupported, or uncertain claims. Use after initialization or documentation synchronization.
+version: 3.0.0
 ---
 
 # Knowledge Base Validator
 
-Read `knowledge-base/*.md`, identify significant claims, and verify them against code, config, infrastructure, and tests.
+Systematically audit every significant claim in `knowledge-base/*.md` against actual repository evidence. Produce a structured validation report that identifies exactly what is supported, what is stale, and what needs human review.
 
-Write `knowledge-base/15-validation-report.md` with:
+## Inputs
 
-- supported, partially supported, unsupported, and unclear findings
-- evidence paths
-- confidence and stale-documentation risks
-- areas needing human review
+- Repository root path with `knowledge-base/` present
+- Optional: specific documents to validate (defaults to all)
 
-Do not silently rewrite other knowledge documents; update them only as part of an explicit synchronization workflow.
+## Procedure
+
+1. **Enumerate Claims** — Read each `knowledge-base/*.md` document. Extract every material claim about architecture, APIs, schemas, dependencies, configurations, flows, and behavior.
+
+2. **Verify Against Evidence** — For each claim, check:
+   - Does the referenced file/path still exist?
+   - Does the code at that location still support the claim?
+   - Has the relevant code changed since the claim was written?
+   - Are there new files/patterns that contradict the claim?
+
+3. **Categorize Findings** — Assign each finding a status:
+
+| Status | Symbol | Meaning |
+|---|---|---|
+| Supported | ✅ | Claim verified against current code |
+| Partially Supported | ⚠️ | Claim is partly true but missing nuance or outdated in some aspect |
+| Unsupported | ❌ | Claim contradicted by current code or evidence is missing |
+| Unclear | ❓ | Cannot determine accuracy — needs human review |
+| Stale | 🔄 | Claim references code that has changed significantly |
+
+4. **Assess Confidence** — For each document, calculate:
+   - Total claims examined
+   - Distribution across statuses
+   - Overall document confidence: High (>90% ✅), Medium (70-90% ✅), Low (<70% ✅)
+
+5. **Write Report** — Generate `knowledge-base/15-validation-report.md`
+
+## Output Format
+
+```markdown
+# Validation Report
+
+Generated: <ISO timestamp>
+Scope: <documents validated>
+
+## Summary
+
+| Document | Claims | ✅ | ⚠️ | ❌ | ❓ | Confidence |
+|---|---|---|---|---|---|---|
+| 00-project-overview.md | 12 | 10 | 1 | 0 | 1 | High |
+| ... | ... | ... | ... | ... | ... | ... |
+
+## Detailed Findings
+
+### 00-project-overview.md
+
+#### ✅ Supported
+- "Uses Express.js 4.18" (evidence: package.json:L15)
+
+#### ⚠️ Partially Supported
+- "PostgreSQL is the primary database" — true, but Redis is also used for caching (evidence: docker-compose.yml:L22)
+
+#### ❌ Unsupported
+- "Uses Passport.js for auth" — no Passport dependency found; appears to use custom JWT middleware (evidence: package.json, src/middleware/auth.ts)
+
+#### ❓ Needs Human Review
+- "Supports multi-tenancy" — tenant isolation code exists but completeness is unclear
+
+## Stale Documentation Risks
+
+- <areas where code has diverged from docs>
+
+## Recommended Actions
+
+- <specific documents needing update>
+- <claims needing human confirmation>
+```
+
+## Rules
+
+- Do NOT silently rewrite knowledge documents during validation
+- Update knowledge documents only as part of an explicit synchronization workflow
+- Report honestly — a low-confidence score is valuable information
+- Flag areas where you lack sufficient context to validate
+
+## Quality Gates
+
+- [ ] Every knowledge document (00-14) is covered in the report
+- [ ] Each finding has an evidence path or explicit "no evidence found"
+- [ ] Summary table has accurate counts
+- [ ] Stale documentation risks are identified
+- [ ] Recommended actions are actionable
+
+## Cross-References
+
+- Used by: `initialize-intelligence-skill`, `incremental-sync-engine`
+- Depends on: `deep-project-knowledge-extractor` (produces the docs to validate)