engineering-intelligence 0.2.0 → 0.3.0

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

@@ -1,17 +1,86 @@
 ---
 name: knowledge-sync-engine
 description: Incrementally synchronizes the project knowledge base after code changes, updating only documents affected by verified behavior changes. Use after implementation or architectural decisions.
+version: 3.0.0
 ---
 
 # Knowledge Synchronization
 
-Use the persisted impact report and actual diff to update only affected documents:
+Update only the knowledge-base documents affected by a verified behavior change. Preserve accurate existing content — never regenerate entire documents.
 
-- API behavior: `knowledge-base/04-api-documentation.md`
-- persistence/schema: `knowledge-base/05-database.md`
-- authentication/authorization: `knowledge-base/06-authentication.md`
-- runtime flow: `knowledge-base/03-runtime-flow.md`
-- architecture: `knowledge-base/02-architecture.md`
-- frontend/backend/infrastructure/integrations: corresponding knowledge documents
+## Inputs
 
-Preserve accurate existing detail and attach evidence for changed claims.
+- Persisted impact report (`.engineering-intelligence/reports/IMP-XXX-*.md`)
+- Actual diff or change record showing what changed
+- Current `knowledge-base/` documents
+
+## Document-to-Change Mapping
+
+| Change Category | Primary Document | Also Check |
+|---|---|---|
+| API routes, endpoints, payloads | `04-api-documentation.md` | `03-runtime-flow.md` |
+| Database schema, migrations | `05-database.md` | `02-architecture.md` |
+| Auth flows, permissions | `06-authentication.md` | `03-runtime-flow.md`, `11-complex-areas.md` |
+| Frontend components, routing | `07-frontend.md` | `01-repository-structure.md` |
+| Backend services, middleware | `08-backend.md` | `03-runtime-flow.md` |
+| CI/CD, deployment, hosting | `09-infrastructure.md` | — |
+| Third-party integrations | `10-integrations.md` | `01-repository-structure.md` |
+| New complex logic | `11-complex-areas.md` | — |
+| Debt introduced or resolved | `12-technical-debt.md` | — |
+| Dev workflow changes | `13-onboarding.md` | — |
+| New domain terms | `14-glossary.md` | — |
+| Architecture changes | `02-architecture.md` | `01-repository-structure.md`, `03-runtime-flow.md` |
+| New packages or modules | `01-repository-structure.md` | `02-architecture.md` |
+| Project overview changes | `00-project-overview.md` | — |
+
+## Procedure
+
+1. **Read Impact Report** — Identify which knowledge documents are flagged as affected.
+
+2. **Read Affected Documents** — Load only the documents identified in step 1.
+
+3. **Identify Stale Sections** — For each affected document, find the specific sections that reference changed code, APIs, schemas, or behavior.
+
+4. **Update Sections** — For each stale section:
+   - Rewrite with current, accurate information
+   - Add evidence citations: `(evidence: path/to/file:L42)`
+   - Mark uncertain areas: `**Unclear from evidence** — [reason]`
+   - Preserve all unaffected content exactly as-is
+
+5. **Verify Consistency** — Check that updated sections don't contradict other sections in the same document or other knowledge documents.
+
+## Evidence Attachment Format
+
+Every changed claim must include an evidence citation:
+
+```markdown
+The auth middleware now validates JWT tokens using RS256 algorithm
+(evidence: src/middleware/auth.ts:L15-L28)
+```
+
+For removed features:
+```markdown
+~~OAuth2 PKCE flow support~~ — Removed in CHG-015
+(evidence: git diff, src/auth/oauth.ts deleted)
+```
+
+## Rules
+
+- Update only documents and sections identified by the impact report
+- Preserve all accurate existing content unchanged
+- Attach evidence for every changed claim
+- Never regenerate entire documents during incremental sync
+- If unsure whether a claim is stale, flag it rather than silently rewriting
+
+## Quality Gates
+
+- [ ] Only impact-identified documents were modified
+- [ ] Changed sections have evidence citations
+- [ ] Accurate existing content was preserved
+- [ ] No documents were fully regenerated
+
+## Cross-References
+
+- Depends on: `impact-analysis-engine` (identifies affected documents)
+- Used by: `incremental-sync-engine`, `engineering-intelligence-skill`
+- Related: `knowledge-base-validator` (validates after sync)

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

@@ -1,18 +1,80 @@
 ---
 name: memory-sync-engine
 description: Maintains durable engineering memory after architecture, business rule, constraint, convention, or technology decisions change. Use only for long-lived knowledge.
+version: 3.0.0
 ---
 
 # Memory Synchronization
 
-Maintain `.engineering-intelligence/memory/`:
+Maintain durable, long-lived engineering memory. Memory is for decisions and patterns that persist across many changes — never for transient implementation details.
 
-- `architecture-decisions.md`
-- `business-rules.md`
-- `coding-patterns.md`
-- `project-constraints.md`
-- `technology-decisions.md`
+## Inputs
 
-Do not store transient implementation notes or unverified assumptions as durable memory.
+- Impact report and actual change evidence
+- Current `.engineering-intelligence/memory/` documents
 
-Use the associated impact report and actual change evidence to decide whether durable memory is affected. Leave memory unchanged when no long-lived decision, rule, constraint, pattern, or technology choice changed.
+## Memory Categories
+
+| Document | Content | Update Trigger |
+|---|---|---|
+| `architecture-decisions.md` | ADRs, layer definitions, boundary rules, communication patterns | Architecture changes, new service boundaries, pattern adoptions |
+| `business-rules.md` | Domain invariants, validation rules, business logic constraints | Business logic changes, regulatory updates |
+| `coding-patterns.md` | Recurring conventions, idioms, naming rules, file organization | Refactors that establish new patterns, convention changes |
+| `project-constraints.md` | Performance budgets, compatibility requirements, SLA targets, regulatory | Infrastructure changes, new compliance requirements |
+| `technology-decisions.md` | Stack choices, framework versions, deprecation timelines, migration plans | Dependency updates, technology migrations |
+
+## Staleness Detection Rules
+
+A memory entry may be stale if:
+
+1. **Referenced code no longer exists** — The decision references files/modules that were deleted or renamed
+2. **Contradicted by current code** — The pattern described is no longer followed in the codebase
+3. **Superseded by new decision** — A newer decision overrides the documented one
+4. **Evidence outdated** — The evidence citations point to significantly changed code
+
+## Procedure
+
+1. **Check Trigger** — Review the impact report. Does the change affect a durable decision, rule, constraint, pattern, or technology choice? If not, **stop — leave memory unchanged**.
+
+2. **Identify Affected Entries** — Match the change against memory categories above. Only proceed for matching categories.
+
+3. **Update Entry** — For each affected entry:
+   ```markdown
+   ## <Decision/Pattern Title>
+
+   **Status**: Active | Superseded | Deprecated
+   **Decided**: <date or CHG reference>
+   **Last verified**: <date>
+
+   <Description of the decision/pattern>
+
+   **Rationale**: <why this was chosen>
+   **Source**: (evidence: path/to/file)
+   **Alternatives considered**: <if applicable>
+   ```
+
+4. **Verify Durability** — Before adding a new memory entry, confirm it's truly durable:
+   - Will this still be relevant after 5+ more changes?
+   - Is this a decision or just an implementation detail?
+   - Is this captured better elsewhere (knowledge-base, context)?
+
+## Rules
+
+- **Durable only**: Do not store transient implementation notes or unverified assumptions
+- **Evidence required**: Every entry must cite source evidence
+- **Leave unchanged when appropriate**: Most changes do NOT affect durable memory — it's correct to update nothing
+- **Status tracking**: Mark superseded decisions as `Superseded` rather than deleting them — history matters
+- **No product code**: Memory synchronization never modifies product code
+
+## Quality Gates
+
+- [ ] Change was verified to affect durable knowledge before updating
+- [ ] Only affected entries were modified
+- [ ] New entries are truly durable (not transient implementation details)
+- [ ] All entries have evidence citations
+- [ ] Superseded entries are marked, not deleted
+
+## Cross-References
+
+- Used by: `incremental-sync-engine`, `engineering-intelligence-skill`
+- Consumed by: `engineering-orchestrator` (for routing decisions), `change-agent` (for pattern compliance)

package/templates/canonical/skills/refactoring-planner/SKILL.md

@@ -1,10 +1,151 @@
 ---
 name: refactoring-planner
 description: Plans safe refactors by identifying dependencies, migration steps, validation needs, compatibility risk, and rollback strategy. Use before non-trivial refactors.
+version: 3.0.0
 ---
 
 # Refactoring Planner
 
-Identify duplicated logic, unsafe coupling, large or fragile areas, migration boundaries, and tests required to preserve behavior.
+Plan safe, incremental refactoring with clear migration steps, validation checkpoints, and rollback strategies.
 
-For significant proposals, write `knowledge-base/18-refactor-plan.md` with motivation, affected areas, migration steps, risk controls, validation, and rollback guidance.
+## Inputs
+
+- Refactoring goal (described by user or identified by architecture review)
+- `.engineering-intelligence/graph/` (dependency relationships)
+- `knowledge-base/12-technical-debt.md` (existing debt)
+- `.engineering-intelligence/memory/architecture-decisions.md` (constraints)
+
+## Refactoring Categories
+
+| Category | Examples | Risk Level |
+|---|---|---|
+| **Extract** | Extract module, service, function, interface | Medium |
+| **Rename** | Rename module, restructure directories | Low–Medium |
+| **Consolidate** | Merge duplicate logic, unify patterns | Medium |
+| **Decouple** | Break circular deps, introduce interfaces | Medium–High |
+| **Migrate** | Change framework, database, language version | High |
+| **Restructure** | Redefine boundaries, change architecture pattern | High–Critical |
+
+## Risk Scoring
+
+| Factor | Low (1) | Medium (2) | High (3) | Critical (4) |
+|---|---|---|---|---|
+| **Scope** | 1–3 files | 4–10 files | 10–25 files | 25+ files |
+| **Dependents** | 0–2 consumers | 3–5 consumers | 6–10 consumers | 10+ consumers |
+| **Test coverage** | Well-tested | Partial | Sparse | None |
+| **Data impact** | None | Read-only paths | Write paths | Schema changes |
+| **Rollback** | Git revert | Multi-step | Complex | Irreversible |
+
+**Overall Risk** = max(all factors). If any factor is Critical, the refactor is Critical.
+
+## Procedure
+
+1. **Analyze Current State** — Using graphs and knowledge base:
+   - Map the exact scope of the refactor
+   - Identify all dependents of the code to be changed
+   - Note test coverage for affected areas
+   - Check for related technical debt
+
+2. **Design Target State** — Define:
+   - What the code should look like after refactoring
+   - New module/file structure (if changing boundaries)
+   - New interfaces or abstractions (if decoupling)
+   - Migration strategy for data (if applicable)
+
+3. **Plan Migration Steps** — Break into incremental, independently-deployable steps:
+   ```markdown
+   ### Step 1: <name>
+   - Changes: <what to modify>
+   - Validation: <how to verify this step>
+   - Rollback: <how to revert just this step>
+   - Dependencies: <what must be done first>
+   ```
+
+4. **Identify Validation Needs** — For each step:
+   - Existing tests that must pass
+   - New tests to add before refactoring
+   - Integration tests to verify behavior preservation
+   - Performance benchmarks (if applicable)
+
+5. **Define Rollback Strategy** — For the overall refactor:
+   - Can it be reverted with `git revert`?
+   - Are there data migrations that need reverse migrations?
+   - What's the point of no return?
+
+6. **Write Plan** — Generate `knowledge-base/18-refactor-plan.md`
+
+## Output Format
+
+```markdown
+# Refactoring Plan: <title>
+
+## Motivation
+<Why this refactor is needed — link to technical debt or architecture review>
+
+## Current State
+<What exists now, with file paths>
+
+## Target State
+<What should exist after, with proposed structure>
+
+## Risk Assessment
+| Factor | Rating | Justification |
+|---|---|---|
+| Scope | Medium | 8 files affected |
+| Dependents | High | 7 modules import the target |
+
+Overall Risk: **High**
+
+## Migration Steps
+
+### Step 1: Add new interface
+- Files: src/interfaces/auth.ts (new)
+- Validation: Type check passes
+- Rollback: Delete the file
+
+### Step 2: Implement adapter
+- Files: src/auth/adapter.ts (new)
+- Validation: Unit tests pass
+- Rollback: Delete the file, revert imports
+
+### Step 3: Migrate consumers (batch 1)
+- Files: src/routes/users.ts, src/routes/admin.ts
+- Validation: Integration tests pass
+- Rollback: Revert consumer changes
+
+## Validation Plan
+- [ ] All existing tests pass after each step
+- [ ] New tests added before behavior-preserving changes
+- [ ] Integration suite green after full migration
+
+## Rollback Strategy
+- Steps 1-3 are independently revertible via git
+- No data migrations required
+- Point of no return: None — fully reversible
+
+## Timeline Estimate
+- Step 1: ~30 minutes
+- Step 2: ~1 hour
+- Step 3: ~2 hours
+```
+
+## Rules
+
+- Never plan a refactor as a single big-bang change — break into steps
+- Each step must be independently verifiable
+- Add tests BEFORE making behavior-preserving changes
+- Consider backward compatibility during migration
+- This planning skill does not implement the refactor — it plans it
+
+## Quality Gates
+
+- [ ] All dependents are identified (not just direct consumers)
+- [ ] Each step has a validation and rollback strategy
+- [ ] Risk is scored with justification
+- [ ] Migration steps are ordered by dependency
+
+## Cross-References
+
+- Depends on: `graph-engine` (dependency data), `architecture-review-engine` (findings)
+- Used by: `engineering-intelligence-skill` (for refactor-type requests)
+- Triggers: `impact-analysis-engine` (when the refactor is implemented)

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

@@ -1,10 +1,126 @@
 ---
 name: testing-intelligence-engine
 description: Determines risk-based testing needs for engineering changes and identifies coverage gaps in critical runtime flows. Use during implementation and validation.
+version: 3.0.0
 ---
 
-# Testing Intelligence
+# Testing Intelligence Engine
 
-Inspect existing test patterns and identify the smallest sufficient validation for the impacted behavior. Include unit, integration, end-to-end, migration, security, or operational checks when risk requires them.
+Determine the minimum sufficient test coverage for a change based on risk assessment and existing test patterns.
 
-When documenting broad testing posture, update `knowledge-base/17-testing-strategy.md`. For individual changes, record tests run and remaining gaps in the relevant `.changes/` entry.
+## Inputs
+
+- Impact report (`.engineering-intelligence/reports/IMP-XXX-*.md`)
+- Existing test patterns in the repository
+- Change classification (feature, bugfix, refactor, etc.)
+
+## Risk-Based Test Selection Matrix
+
+| Risk Level | Unit Tests | Integration Tests | E2E Tests | Security Tests | Migration Tests | Manual |
+|---|---|---|---|---|---|---|
+| **Low** | Changed functions | — | — | — | — | — |
+| **Medium** | Changed + adjacent | Affected APIs | — | — | — | — |
+| **High** | Changed + adjacent | Affected APIs | Critical paths | If auth touched | If schema touched | Recommended |
+| **Critical** | Comprehensive | All affected | Full suite | Required | Required | Required |
+
+## Procedure
+
+1. **Assess Existing Coverage** — Scan the test suite:
+   - Identify test framework(s) in use (Jest, Mocha, pytest, Go testing, etc.)
+   - Locate test directories and naming patterns
+   - Map tests to source files (by convention or configuration)
+   - Identify untested critical paths
+
+2. **Map Change to Tests** — Using the impact report:
+   - List source files/functions changed
+   - Find existing tests covering those files
+   - Identify tests that should exist but don't (coverage gaps)
+
+3. **Determine Required Tests** — Using the risk matrix above:
+
+   **For `bugfix`**:
+   - Regression test reproducing the original bug (required)
+   - Verify fix doesn't break adjacent behavior
+
+   **For `feature`**:
+   - Unit tests for new functions/methods
+   - Integration tests for new API endpoints or service interactions
+   - Happy path + error path coverage
+
+   **For `refactor`**:
+   - All existing tests must still pass (no new tests needed if behavior unchanged)
+   - Add tests if coverage gaps are discovered during refactoring
+
+   **For `architecture` / `security`**:
+   - Boundary tests between new/changed architectural boundaries
+   - Negative-path and permission tests for security changes
+   - Data migration and rollback tests for schema changes
+
+4. **Identify Coverage Gaps** — Report:
+   - Critical paths with no test coverage
+   - Changed behavior with no corresponding test
+   - Error paths and edge cases not covered
+
+5. **Recommend Test Strategy** — For the specific change, recommend:
+   - Test files to create or modify
+   - Test cases to write (describe what, not write the test code)
+   - Validation commands to run
+
+## Output
+
+### Per-Change Testing (in `.changes/CHG-XXX-*.md`)
+
+```markdown
+## Tests
+- Added: <test file> — <what it tests>
+- Modified: <test file> — <what changed>
+- Run command: `npm test` / `pytest` / etc.
+- Results: X passed, Y failed, Z skipped
+- Coverage gaps: <untested areas remaining>
+```
+
+### Broad Testing Strategy (in `knowledge-base/17-testing-strategy.md`)
+
+Only update when documenting project-wide testing posture:
+
+```markdown
+# Testing Strategy
+
+## Test Framework
+- Framework: <name and version>
+- Configuration: <config file path>
+
+## Test Organization
+| Directory | Type | Coverage |
+|---|---|---|
+| test/unit/ | Unit tests | Core business logic |
+| test/integration/ | Integration | API endpoints |
+
+## Coverage Gaps
+- <critical untested areas>
+
+## Running Tests
+- All tests: `<command>`
+- Specific suite: `<command>`
+- Coverage report: `<command>`
+```
+
+## Rules
+
+- Recommend tests proportional to risk — don't mandate full-suite runs for low-risk changes
+- Always note when validation was not actually run (only recommended)
+- Never claim test coverage without checking existing tests
+- Record test results honestly, including failures
+
+## Quality Gates
+
+- [ ] Impact report was consulted for risk level
+- [ ] Test recommendations match the risk level
+- [ ] Existing test coverage was checked before recommending new tests
+- [ ] Coverage gaps in critical paths are flagged
+
+## Cross-References
+
+- Depends on: `impact-analysis-engine` (for risk assessment)
+- Used by: `engineering-intelligence-skill` (step 4: tests and validation)
+- Updates: `knowledge-base/17-testing-strategy.md` (broad posture only)

package/templates/canonical/workflows/analyze-impact.md

@@ -6,8 +6,30 @@ description: Analyze the impact of a proposed change or existing diff and write
 
 Use `change-detection-engine`, `impact-analysis-engine`, and `graph-engine` when graph intelligence is missing or stale.
 
-Analyze the user-supplied proposed change, working-tree diff, commit/range, or explicit changed paths. If the scope is ambiguous, ask for it instead of assuming.
+## Input
 
-Write `.engineering-intelligence/reports/IMP-XXX-<slug>.md` covering analysis mode and scope, graph inputs, direct and indirect impact, risks, validation needs, intelligence artifacts needing synchronization, evidence, and uncertainties.
+Analyze the user-supplied scope: proposed change description, working-tree diff, commit/range, or explicit changed paths. If the scope is ambiguous, ask for clarification instead of assuming.
 
-This workflow may write intelligence reports or refresh necessary graph context. It must not modify product code.
+## Output
+
+Write `.engineering-intelligence/reports/IMP-XXX-<slug>.md` covering:
+
+| Section | Content |
+|---|---|
+| Analysis mode & scope | `proposal` or `diff`, what was examined |
+| Graph inputs | Graphs consulted, refreshed, or missing |
+| Direct impact | Files and systems directly affected |
+| Indirect impact | Downstream dependencies and consumers |
+| Risk assessment | Risk level with justification |
+| Validation needs | Tests and checks required |
+| Intelligence artifacts | Knowledge, memory, context, events, and graphs needing sync |
+| Evidence | File path citations for all claims |
+| Unknowns | Areas where impact is uncertain |
+
+## Rules
+
+- Ask for scope clarification when ambiguous — never assume
+- Consult graph intelligence before tracing impact manually
+- Score risk with evidence-based justification
+- This workflow may write intelligence reports or refresh necessary graph context
+- It must not modify product code

package/templates/canonical/workflows/engineering-intelligence.md

@@ -4,8 +4,25 @@ description: Implement an engineering request with impact analysis, tests, valid
 
 # Engineering Intelligence
 
-Use the `engineering-intelligence` capability for the user's accompanying request.
+Use the `engineering-intelligence-skill` capability for the user's accompanying request.
 
-Read project intelligence and graph artifacts, write a pre-change `.engineering-intelligence/reports/IMP-XXX-<summary>.md` impact report, implement the requested work, add or update appropriate tests, validate the result, incrementally synchronize affected knowledge/memory/context/event/graph artifacts, and write the next `.changes/CHG-XXX-<summary>.md` entry referencing related reports. Run review responsibility before completion when change risk is high.
+## Pipeline
 
-Finish with changed code, tests and validation, affected systems, synchronized artifacts and graphs, related reports, and unresolved risks.
+1. **Read Intelligence** — Consult `knowledge-base/`, `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, `.engineering-intelligence/graph/`
+2. **Write Impact Report** — Create `.engineering-intelligence/reports/IMP-XXX-<summary>.md` before any code edit
+3. **Implement** — Make the requested code changes following established patterns
+4. **Test** — Add/update tests proportional to risk; execute and record results
+5. **Validate** — Run available linters, type checks, and test suites
+6. **Sync Intelligence** — Incrementally update only affected knowledge, memory, context, event, graph artifacts
+7. **Record Change** — Write `.changes/CHG-XXX-<summary>.md` referencing related reports
+8. **Review Gate** — For high-risk changes, run engineering-change review before completion
+
+## Completion Report
+
+Finish with:
+- Code changes made (files, what changed)
+- Tests run and results (pass/fail counts)
+- Affected systems and services
+- Synchronized intelligence artifacts
+- Related reports (IMP-XXX, REV-XXX)
+- Unresolved risks or follow-ups

package/templates/canonical/workflows/initialize-engineering-intelligence.md

@@ -4,8 +4,35 @@ description: Initialize evidence-based engineering intelligence for the current
 
 # Initialize Engineering Intelligence
 
-Use the `initialize-engineering-intelligence` capability.
+Use the `initialize-intelligence-skill` capability.
 
-Analyze this repository thoroughly without changing product code. Generate `knowledge-base/`, validate it against evidence, generate `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, `.engineering-intelligence/events/`, and build `.engineering-intelligence/graph/` JSON graphs plus `architecture-map.md`. Write `.changes/CHG-000-initialization.md`.
+## What This Does
 
-Do not fabricate details. Mark uncertainty clearly and finish with the created artifacts and human-review items.
+Analyzes this repository thoroughly without changing product code. Produces a complete project intelligence baseline.
+
+## Outputs Generated
+
+| Category | Path | Content |
+|---|---|---|
+| Knowledge Base | `knowledge-base/` | 16 evidence-backed documents (00-15) |
+| Memory | `.engineering-intelligence/memory/` | 5 durable decision/pattern documents |
+| Context | `.engineering-intelligence/context/` | 6 compact navigation maps |
+| Events | `.engineering-intelligence/events/` | 5 change-event guidance documents |
+| Graphs | `.engineering-intelligence/graph/` | 4 JSON graphs + architecture-map.md |
+| History | `.changes/CHG-000-initialization.md` | Initialization record |
+
+## Execution Steps
+
+1. **Discover** — Scan repository for packages, runtimes, build systems, APIs, databases, auth, CI, and tests
+2. **Extract** — Generate knowledge-base documents with evidence citations
+3. **Validate** — Audit claims against source code; write validation report
+4. **Generate Memory** — Extract durable decisions and patterns
+5. **Generate Context** — Create concise AI navigation maps
+6. **Build Graphs** — Generate evidence-backed architecture graphs
+7. **Record** — Write initialization change record
+
+## Important
+
+- Do not fabricate details — mark uncertainty clearly
+- Every claim must cite evidence from the repository
+- Finish with: created artifacts, confidence assessment, and human-review items

package/templates/canonical/workflows/map-architecture.md

@@ -8,10 +8,21 @@ Use the `graph-engine` capability.
 
 Inspect repository evidence and generate or comprehensively refresh:
 
-- `.engineering-intelligence/graph/dependency-graph.json`
-- `.engineering-intelligence/graph/service-graph.json`
-- `.engineering-intelligence/graph/runtime-graph.json`
-- `.engineering-intelligence/graph/business-flow-graph.json`
-- `.engineering-intelligence/graph/architecture-map.md`
+| Artifact | Content |
+|---|---|
+| `.engineering-intelligence/graph/dependency-graph.json` | Module/package dependency relationships |
+| `.engineering-intelligence/graph/service-graph.json` | Service-to-service communication topology |
+| `.engineering-intelligence/graph/runtime-graph.json` | Runtime call flows and middleware chains |
+| `.engineering-intelligence/graph/business-flow-graph.json` | Business process flows across boundaries |
+| `.engineering-intelligence/graph/architecture-map.md` | Mermaid diagrams derived from JSON graphs |
 
-Use stable node IDs, evidence-backed confidence labels, explicit unknowns, and Mermaid diagrams. You may update graph-connected navigation context when necessary. Do not modify product code.
+## Requirements
+
+- Use stable node IDs across updates
+- Mark every edge with `verified`, `inferred`, or `unknown` confidence
+- Back every `verified` edge with evidence file paths
+- List unresolved relationships in the `unknowns` array
+- Derive Mermaid diagrams from JSON graph data — not hand-authored
+- Update graph-connected navigation context when necessary
+
+This workflow may update graph and context intelligence artifacts. It must not modify product code.

package/templates/canonical/workflows/review-engineering-change.md

@@ -6,6 +6,30 @@ description: Review changed engineering work, tests, graphs, and synchronized in
 
 Use `change-detection-engine` and `engineering-change-review`.
 
-Inspect the identified implementation diff or changed scope, associated impact report, test and validation evidence, graph consistency, and documentation/context synchronization.
+## Procedure
 
-Write `.engineering-intelligence/reports/REV-XXX-<slug>.md` with severity-ordered findings, evidence paths, test gaps, and stale-intelligence risks. Do not modify product code or auto-fix findings.
+1. **Detect scope** — Identify the implementation diff or changed scope
+2. **Read context** — Load associated impact report, test evidence, and graph artifacts
+3. **Review** — Inspect across five dimensions:
+
+| Dimension | What to Check |
+|---|---|
+| Implementation | Correctness, request fulfillment, error handling |
+| Tests | Coverage, execution, results, gaps |
+| Architecture | Boundary respect, pattern compliance, dependency direction |
+| Graph consistency | New/changed nodes and edges reflected |
+| Documentation sync | Knowledge, memory, context accuracy |
+
+4. **Write report** — Generate `.engineering-intelligence/reports/REV-XXX-<slug>.md` with:
+   - Severity-ordered findings (🔴 Blocker → 🟢 Positive)
+   - Evidence paths for each finding
+   - Test gaps and coverage concerns
+   - Stale-intelligence risks
+   - Verdict: Approved / Approved with findings / Changes required
+
+## Rules
+
+- Do not modify product code
+- Do not auto-fix findings — report only
+- Include positive observations alongside issues
+- Flag unrun validation honestly

package/templates/canonical/workflows/sync-engineering-intelligence.md

@@ -6,6 +6,24 @@ description: Incrementally synchronize intelligence artifacts for an identified
 
 Use `change-detection-engine`, `impact-analysis-engine`, and `incremental-sync-engine`.
 
-Read the supplied changed scope, diff, or completed change record. Create an impact report first if none exists for that scope. Update only affected knowledge, memory, context, event, graph, and report artifacts.
+## Procedure
 
-Standalone synchronization must not create a `.changes/CHG-XXX-*` implementation record and must not modify product code.
+1. **Detect scope** — Read the supplied changed scope, diff, or completed change record
+2. **Analyze impact** — Create an impact report first if none exists for this scope
+3. **Sync artifacts** — Update only affected intelligence:
+
+| Artifact Type | Engine | Update Rule |
+|---|---|---|
+| Knowledge Base | `knowledge-sync-engine` | Only docs mapped to the change type |
+| Memory | `memory-sync-engine` | Only if durable decisions changed |
+| Context | `context-sync-engine` | Only affected navigation maps |
+| Events | Direct update | Only if API/schema/auth contracts changed |
+| Graphs | `graph-engine` (incremental) | Only affected nodes and edges |
+| Reports | Impact report update | Add sync notes |
+
+## Rules
+
+- Standalone synchronization must not create `.changes/CHG-XXX-*` implementation records
+- Must not modify product code
+- Update only artifacts identified by the impact report
+- Preserve accurate existing content in all artifacts