engineering-intelligence 0.2.0 → 0.4.0

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

@@ -0,0 +1,168 @@
+---
+name: engineering-intelligence-skill
+description: Executes engineering changes with impact analysis, implementation, tests, validation, and incremental synchronization of project intelligence. Use for feature, bugfix, update, refactor, architecture, infrastructure, or security requests.
+version: 3.0.0
+---
+
+# Engineering Intelligence Implementation
+
+The core implementation skill for engineering work. Use after project intelligence has been initialized.
+
+## Inputs
+
+- User request describing the desired change
+- Repository with initialized intelligence (`knowledge-base/`, `.engineering-intelligence/`)
+
+## Request Classification
+
+Classify the incoming request before starting:
+
+| Type | Description | Risk Level |
+|---|---|---|
+| `feature` | New user-facing functionality | Medium–High |
+| `bugfix` | Correction of incorrect behavior | Low–Medium |
+| `update` | Dependency, config, or version updates | Low–Medium |
+| `refactor` | Structural improvement without behavior change | Medium |
+| `architecture` | Boundary, layer, or pattern changes | High |
+| `infrastructure` | CI, deployment, environment changes | Medium–High |
+| `security` | Auth, permissions, vulnerability fixes | High |
+| `documentation` | Knowledge-only changes (no product code) | Low |
+
+## Procedure
+
+### 1. Pre-Flight: Read Intelligence
+
+Read these artifacts and identify relevant context:
+- `knowledge-base/` — architecture, APIs, runtime flow relevant to the change
+- `.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
+
+**If intelligence is missing or stale**: Run `initialize-intelligence-skill` first.
+
+### 2. Impact Analysis: Write Report
+
+Before any code edit, write `.engineering-intelligence/reports/IMP-XXX-<summary>.md`:
+
+```markdown
+# IMP-XXX: <summary>
+
+## Classification
+- Type: <feature|bugfix|update|refactor|architecture|infrastructure|security>
+- Risk: <low|medium|high|critical>
+- Scope: <files and modules affected>
+
+## Analysis
+- Mode: <proposal|diff>
+- Graph inputs consulted: <list>
+- Directly affected: <files, modules, services>
+- Indirectly affected: <downstream consumers, dependent services>
+- Risk factors: <breaking changes, data migration, auth impact>
+
+## Validation Requirements
+- <test types needed>
+- <manual verification needed>
+
+## Intelligence Artifacts Affected
+- <knowledge docs, memory entries, context maps, graph nodes>
+
+## Evidence
+- <file paths supporting each claim>
+
+## Unknowns
+- <areas where impact is uncertain>
+```
+
+### 3. Implement the Change
+
+- Edit only the files necessary for the request
+- Follow existing coding patterns from `.engineering-intelligence/memory/coding-patterns.md`
+- 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
+- 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
+- Run the project's test suite and record actual results
+
+### 5. Validate
+
+- Run linters, type checks, and test suites available in the project
+- **Never claim validation passed unless it actually ran and passed**
+- Record partial or failed validation honestly
+
+### 6. Incremental Sync
+
+Use `incremental-sync-engine` to update only affected artifacts:
+- Knowledge docs reflecting changed behavior
+- Memory entries if decisions/patterns changed
+- Context maps if module/service topology changed
+- Graph nodes/edges if dependencies or services changed
+- Event guidance if API/schema/auth contracts changed
+
+### 7. Record Change
+
+Create `.changes/CHG-XXX-<summary>.md`:
+
+```markdown
+# CHG-XXX: <summary>
+
+## Request
+<original user request>
+
+## Classification
+- Type: <type> | Risk: <level>
+
+## Implementation Summary
+<what was changed and why>
+
+## Files Changed
+- <path> — <description of change>
+
+## Tests
+- <tests added/modified>
+- <test results: passed/failed/skipped>
+
+## Related Reports
+- IMP-XXX: <link to impact report>
+- REV-XXX: <link to review report, if applicable>
+
+## Synchronized Artifacts
+- <list of updated intelligence artifacts>
+
+## Unresolved Risks
+- <any remaining concerns>
+```
+
+### 8. High-Risk Review Gate
+
+For changes classified as `high` or `critical` risk:
+- Run `engineering-change-review` before final reporting
+- Address any blocking findings before marking complete
+
+### 9. Report
+
+Summarize to the user:
+- Code changes made (files, lines)
+- Tests run and results
+- Affected systems and services
+- Synchronized intelligence artifacts
+- Unresolved risks or follow-ups
+
+## Quality Gates
+
+- [ ] Impact report written before any code edit
+- [ ] All changed behavior has corresponding test coverage
+- [ ] Validation was actually executed (not just claimed)
+- [ ] Only affected intelligence artifacts were updated
+- [ ] Change record references the correct impact report
+- [ ] High-risk changes went through review gate
+
+## 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)

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`