engineering-intelligence 0.2.0 → 0.4.0

package/templates/canonical/skills/change-history-engine/SKILL.md

@@ -1,13 +1,133 @@
 ---
 name: change-history-engine
 description: Records validated engineering work, impacted systems, tests, synchronized documentation, and outstanding risks. Use after initialization and completed engineering changes.
+version: 3.0.0
 ---
 
-# Change History
+# Change History Engine
 
-Store change records in `.changes/`.
+Create structured, traceable change records that document what was done, why, what was tested, and what remains.
 
-- Initialization creates `CHG-000-initialization.md`.
-- Subsequent changes create the next numbered `CHG-XXX-<summary>.md`.
+## Inputs
 
-Include request summary, files or systems affected, related `IMP-*` and `REV-*` reports when present, implementation summary, tests and validation performed, updated graph/intelligence artifacts, and unresolved risk or follow-up.
+- Completed implementation details
+- Impact report reference
+- Test results
+- List of synchronized intelligence artifacts
+- Unresolved risks or follow-ups
+
+## Change Record Format
+
+Store change records in `.changes/`:
+
+- Initialization creates `CHG-000-initialization.md`
+- Subsequent changes create the next numbered `CHG-XXX-<summary>.md`
+
+### Numbering Convention
+
+- `CHG-000` — Reserved for initialization
+- `CHG-001` through `CHG-999` — Sequential, zero-padded
+- Find the highest existing CHG number and increment by 1
+
+### Record Template
+
+```markdown
+# CHG-XXX: <concise summary>
+
+## Meta
+- Date: <ISO timestamp>
+- Type: feature | bugfix | update | refactor | architecture | infrastructure | security
+- Risk: low | medium | high | critical
+- Author: <who requested the change>
+
+## Request
+<Original user request, verbatim or paraphrased>
+
+## Implementation Summary
+<What was changed, in 2-5 sentences>
+
+## Files Changed
+| File | Action | Description |
+|---|---|---|
+| src/auth/middleware.ts | Modified | Added rate limiting check |
+| src/auth/rate-limiter.ts | Created | New rate limiting service |
+| test/auth/rate-limiter.test.ts | Created | Rate limiter unit tests |
+
+## Related Reports
+- Impact: IMP-XXX-<slug>.md
+- Review: REV-XXX-<slug>.md (if applicable)
+
+## Tests & Validation
+| Test | Command | Result |
+|---|---|---|
+| Unit tests | npm test | 42 passed, 0 failed |
+| Type check | npx tsc --noEmit | Clean |
+| Lint | npm run lint | Clean |
+
+## Synchronized Artifacts
+| Artifact | Change |
+|---|---|
+| knowledge-base/04-api-documentation.md | Updated rate limiting section |
+| .engineering-intelligence/graph/runtime-graph.json | Added rate-limiter node |
+| .engineering-intelligence/context/module-map.md | Added rate-limiter entry |
+
+## Unresolved Risks
+- <any remaining concerns, follow-ups, or known limitations>
+
+## Rollback
+- <how to revert this change if needed>
+```
+
+### Initialization Record (`CHG-000-initialization.md`)
+
+```markdown
+# CHG-000: Project Intelligence Initialization
+
+## Meta
+- Date: <ISO timestamp>
+- Type: initialization
+
+## Summary
+Initial engineering intelligence generated for <project name>.
+
+## Generated Artifacts
+| Category | Count | Path |
+|---|---|---|
+| Knowledge Base | 16 documents | knowledge-base/ |
+| Memory | 5 documents | .engineering-intelligence/memory/ |
+| Context | 6 maps | .engineering-intelligence/context/ |
+| Events | 5 guides | .engineering-intelligence/events/ |
+| Graphs | 4 JSON + 1 map | .engineering-intelligence/graph/ |
+
+## Confidence Assessment
+- High confidence areas: <list>
+- Low confidence areas: <list>
+- Needs human review: <list>
+
+## Next Steps
+- Review and verify knowledge-base accuracy
+- Confirm architecture decisions in memory
+- Validate graph completeness
+```
+
+## Rules
+
+- Every completed engineering change must have a change record
+- Records are append-only — never delete or modify past records
+- Reference related impact and review reports by their IMP/REV identifiers
+- Be honest about test results — record failures and skipped tests
+- Include rollback guidance for medium+ risk changes
+
+## Quality Gates
+
+- [ ] Record number is sequential (no gaps, no duplicates)
+- [ ] All sections are filled (use "N/A" rather than omitting)
+- [ ] Related reports are correctly referenced
+- [ ] Test results reflect actual execution (not assumed)
+- [ ] Files changed list is complete
+
+## Cross-References
+
+- Used by: `engineering-intelligence-skill` (step 7), `initialize-intelligence-skill` (step 9)
+- Depends on: `impact-analysis-engine` (for report references)
+- Related: `engineering-change-review` (may trigger a review report)

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

@@ -1,19 +1,126 @@
 ---
 name: context-sync-engine
 description: Maintains compact AI navigation context when modules, services, dependencies, runtime paths, or risk areas change. Use after significant implementation changes.
+version: 3.0.0
 ---
 
 # Context Synchronization
 
-Maintain `.engineering-intelligence/context/`:
+Maintain concise, navigational context maps optimized for AI agent use. Context maps help agents quickly find the right file, module, or service — not replace the knowledge base.
 
-- `module-map.md`
-- `service-map.md`
-- `runtime-map.md`
-- `critical-paths.md`
-- `dangerous-areas.md`
-- `dependency-map.md`
+## Inputs
 
-Keep context concise, navigational, and backed by current project paths.
+- Impact report and graph updates
+- Current `.engineering-intelligence/context/` documents
 
-Use the associated impact report and graph updates to revise only affected maps; do not regenerate unrelated navigation context.
+## Context Maps
+
+Maintain these maps in `.engineering-intelligence/context/`:
+
+### `module-map.md` — Module Navigation
+
+```markdown
+# Module Map
+
+| Module | Path | Responsibility | Key Files |
+|---|---|---|---|
+| auth | src/auth/ | Authentication, JWT, RBAC | middleware.ts, jwt.ts |
+| api | src/routes/ | REST endpoint handlers | users.ts, products.ts |
+```
+
+### `service-map.md` — Service Topology
+
+```markdown
+# Service Map
+
+| Service | Port | Protocol | Dependencies | Health Check |
+|---|---|---|---|---|
+| api-server | 3000 | HTTP | postgres, redis | /health |
+| worker | — | — | rabbitmq, postgres | — |
+```
+
+### `runtime-map.md` — Request Flows
+
+```markdown
+# Runtime Map
+
+## HTTP Request Flow
+Entry → CORS → Auth → Rate Limit → Router → Handler → Response
+
+## Background Job Flow
+Queue → Worker → Process → DB Write → Notify
+```
+
+### `critical-paths.md` — Revenue & Safety Critical Flows
+
+```markdown
+# Critical Paths
+
+| Flow | Entry Point | Risk | Last Verified |
+|---|---|---|---|
+| Payment processing | POST /api/checkout | High | CHG-005 |
+| User registration | POST /api/auth/register | Medium | CHG-003 |
+```
+
+### `dangerous-areas.md` — Fragile & Risky Code
+
+```markdown
+# Dangerous Areas
+
+| Area | Path | Risk | Reason |
+|---|---|---|---|
+| Legacy auth | src/auth/legacy.ts | High | No tests, race conditions |
+| Payment retry | src/payments/retry.ts | High | Complex state machine |
+```
+
+### `dependency-map.md` — External Dependencies
+
+```markdown
+# Dependency Map
+
+| Dependency | Version | Consumers | Risk |
+|---|---|---|---|
+| express | 4.18.x | api-server | Low — stable |
+| stripe | 12.x | payments module | Medium — breaking changes |
+```
+
+## Procedure
+
+1. **Check Impact** — Review the impact report and graph updates. Identify which context maps are affected.
+
+2. **Update Affected Maps** — For each affected map:
+   - Update specific entries, not the entire map
+   - Add new entries for new modules/services/paths
+   - Remove entries for deleted modules/services
+   - Update paths and descriptions for renamed elements
+
+3. **Preserve Conciseness** — Each map should be:
+   - Under 150 lines
+   - Table-formatted where possible
+   - Navigational (paths and quick descriptions), not explanatory
+   - Optimized for AI agent context windows
+
+4. **Verify Accuracy** — Cross-check updated maps against:
+   - Current `.engineering-intelligence/graph/` data
+   - Actual file system paths (do they still exist?)
+
+## Rules
+
+- Keep context concise and navigational — not a knowledge-base duplicate
+- Use tables over prose wherever possible
+- Update only affected maps from the impact report
+- Do not regenerate unrelated context
+- Maps must reflect actual file system state (no phantom paths)
+
+## Quality Gates
+
+- [ ] Each map is under 150 lines
+- [ ] Updated entries reference real, existing paths
+- [ ] Only impact-affected maps were modified
+- [ ] Table format used where appropriate
+
+## Cross-References
+
+- Depends on: `impact-analysis-engine` (identifies affected maps), `graph-engine` (provides topology data)
+- Used by: `incremental-sync-engine`, `engineering-intelligence-skill`
+- Consumed by: All agents (for navigation)

package/templates/canonical/skills/deep-project-knowledge-extractor/SKILL.md

@@ -1,16 +1,182 @@
 ---
 name: deep-project-knowledge-extractor
 description: Analyzes an existing software repository and produces evidence-based architecture, runtime, API, infrastructure, risk, and onboarding documentation. Use when creating or refreshing the project knowledge base.
+version: 3.0.0
 ---
 
 # Deep Project Knowledge Extractor
 
-Inspect package/workspace manifests, source entrypoints, dependency boundaries, routes, schemas, middleware, tests, CI and infrastructure. Generate the structured documents in `knowledge-base/`.
+Produce comprehensive, evidence-backed project documentation by systematic repository analysis. Every material claim must cite a source file path. Silence is never acceptable — use `**Not detected**` for absent features.
 
-Every material statement must be supported by repository evidence. Cite relevant paths in the documents. State `Not detected` or `Unclear from repository evidence` where appropriate.
+## Inputs
 
-Required documents:
+- Repository root path
+- Optional: scope constraints (specific package, service, or directory)
 
-- `00-project-overview.md` through `14-glossary.md`
+## Discovery Checklist
 
-Cover repository structure, architecture, runtime flow, APIs, persistence, authentication, frontend, backend, infrastructure, integrations, complex areas, technical debt, onboarding, and glossary.
+Scan the repository systematically for each category:
+
+| Category | What to Look For |
+|---|---|
+| **Package Management** | `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, workspace configs |
+| **Build System** | `Makefile`, `webpack.config.*`, `vite.config.*`, `tsconfig.json`, `build.gradle` |
+| **Entrypoints** | `main.*`, `index.*`, `app.*`, `server.*`, bin scripts |
+| **Routing** | Express/Koa/Fastify routes, Next.js pages/app dirs, API gateways |
+| **Database** | Migration dirs, schema files, ORM configs, seed scripts |
+| **Auth** | Passport/Auth0/JWT configs, middleware, RBAC definitions |
+| **CI/CD** | `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `Dockerfile` |
+| **Infrastructure** | `docker-compose.yml`, `terraform/`, `k8s/`, `serverless.yml` |
+| **Tests** | `test/`, `__tests__/`, `spec/`, `*.test.*`, `*.spec.*`, test configs |
+| **Environment** | `.env.example`, `.env.sample`, env validation schemas |
+| **Documentation** | `README.md`, `docs/`, `CHANGELOG.md`, `CONTRIBUTING.md` |
+
+## Output Specification
+
+Generate each document in `knowledge-base/` with this structure:
+
+```markdown
+# <Document Title>
+
+<One-paragraph executive summary>
+
+## <Section>
+
+<Content with inline evidence citations>
+
+(evidence: path/to/file:L42-L58)
+
+## Unknowns & Uncertainties
+
+- <what is unclear and why>
+```
+
+### Required Documents
+
+#### `00-project-overview.md`
+- Project name, description, primary purpose
+- Technology stack (languages, frameworks, major libraries)
+- Repository type (monorepo, polyrepo, single-package)
+- High-level architecture summary (1 paragraph)
+- Key entry points and how to run the project
+
+#### `01-repository-structure.md`
+- Annotated directory tree (top 2-3 levels)
+- Package/workspace boundaries
+- Build output directories
+- Generated vs authored code distinction
+
+#### `02-architecture.md`
+- Architectural pattern (monolith, microservices, serverless, modular monolith)
+- Layer definitions (presentation, business, data, infrastructure)
+- Module/package boundaries and their responsibilities
+- Communication patterns (HTTP, gRPC, events, queues)
+- Dependency direction rules
+
+#### `03-runtime-flow.md`
+- Application startup sequence
+- Request lifecycle (from entry to response)
+- Background job / worker flows
+- Shutdown / graceful termination
+- Async processing patterns
+
+#### `04-api-documentation.md`
+- REST endpoints: method, path, auth, request/response shapes
+- GraphQL schemas and resolvers
+- WebSocket channels
+- RPC interfaces
+- API versioning strategy
+
+#### `05-database.md`
+- Database engine(s) and connection configuration
+- Schema overview (tables/collections, key relationships)
+- Migration strategy and tooling
+- Caching layers (Redis, Memcached, in-memory)
+- Data access patterns (repository, active record, query builder)
+
+#### `06-authentication.md`
+- Auth provider and strategy (JWT, session, OAuth, SAML)
+- Login/registration flows
+- Token lifecycle and refresh
+- Role/permission model (RBAC, ABAC)
+- Protected route/middleware patterns
+
+#### `07-frontend.md`
+- UI framework and version
+- Routing strategy (client-side, SSR, SSG)
+- State management approach
+- Component architecture and patterns
+- Styling approach (CSS modules, Tailwind, styled-components)
+- Build and bundling pipeline
+
+#### `08-backend.md`
+- Server framework and version
+- Middleware stack (ordered list)
+- Service/controller pattern
+- Error handling strategy
+- Logging and observability
+
+#### `09-infrastructure.md`
+- Hosting/cloud provider
+- Container orchestration
+- CI/CD pipeline stages
+- Environment management (dev, staging, prod)
+- Secrets management
+- Monitoring and alerting
+
+#### `10-integrations.md`
+- Third-party API integrations
+- Payment processors, email services, SMS
+- Analytics and tracking
+- External data sources
+- Webhook consumers/producers
+
+#### `11-complex-areas.md`
+- High cyclomatic complexity modules
+- Business logic with many edge cases
+- Code with subtle race conditions or timing dependencies
+- Areas with heavy tech debt affecting reliability
+
+#### `12-technical-debt.md`
+- Deprecated patterns still in use
+- Missing test coverage in critical paths
+- Known performance bottlenecks
+- Planned but incomplete migrations
+- Security improvements needed
+
+#### `13-onboarding.md`
+- Prerequisites (tools, accounts, access)
+- Setup steps (clone, install, configure, run)
+- Development workflow (branch, test, PR)
+- Common tasks and commands
+- Troubleshooting common issues
+
+#### `14-glossary.md`
+- Domain-specific terms with definitions
+- Abbreviations and acronyms
+- Naming conventions used in the codebase
+
+#### `15-validation-report.md`
+- Generated by `knowledge-base-validator` after extraction
+
+## Evidence Rules
+
+1. Every architectural claim must cite at least one source file
+2. Use the format: `(evidence: relative/path/to/file:L<line>)` or `(evidence: relative/path/to/file)`
+3. When evidence is indirect (inferred from patterns), use: `(inferred from: path/to/file)`
+4. When no evidence exists: `**Not detected** — no relevant configuration or code found`
+5. When evidence is ambiguous: `**Unclear from evidence** — [explanation of ambiguity]`
+
+## Quality Gates
+
+- [ ] All 16 documents generated (00 through 15)
+- [ ] Every document has an executive summary paragraph
+- [ ] Every material claim has an evidence citation
+- [ ] Absent features use `**Not detected**` — not silence
+- [ ] Ambiguous areas use `**Unclear from evidence**`
+- [ ] No invented implementation details
+
+## Cross-References
+
+- Used by: `initialize-intelligence-skill`
+- Feeds into: `knowledge-base-validator`, all sync engines

package/templates/canonical/skills/engineering-change-review/SKILL.md

@@ -1,18 +1,154 @@
 ---
 name: engineering-change-review
-description: Reviews changed implementation, tests, impact analysis, graph consistency, and synchronized project intelligence without applying fixes. Use after engineering changes or before completion.
+description: Reviews engineering changes for correctness, test coverage, architecture alignment, graph consistency, and documentation accuracy. Use after implementation to validate quality before completion.
+version: 3.0.0
 ---
 
 # Engineering Change Review
 
-Review changed code and tests against the request, impact report, validation evidence, graph artifacts, and synchronized intelligence.
+Review completed engineering work for correctness, completeness, and alignment with project standards. Produce a structured review report with severity-ordered findings.
 
-Write `.engineering-intelligence/reports/REV-XXX-<slug>.md` with:
+## Inputs
 
-- findings first, ordered by severity
-- code and evidence paths
-- regression, validation, graph-staleness, and documentation-staleness risks
-- test gaps and unresolved questions
-- a short reviewed-change summary only after findings
+- Implementation diff or changed scope
+- Impact report (`.engineering-intelligence/reports/IMP-XXX-*.md`)
+- Test and validation evidence
+- Updated graph and intelligence artifacts
 
-This review capability may write its report. It must not modify product code or auto-fix findings.
+## Review Dimensions
+
+### 1. Implementation Correctness
+
+| Check | What to Verify |
+|---|---|
+| Request fulfillment | Does the implementation address the original request? |
+| Logic correctness | Are algorithms and business logic correct? |
+| Edge cases | Are boundary conditions handled? |
+| Error handling | Are errors caught, logged, and reported appropriately? |
+| Resource management | Are connections, files, and memory properly managed? |
+| Concurrency safety | Are shared resources properly synchronized? |
+
+### 2. Test Coverage
+
+| Check | What to Verify |
+|---|---|
+| Happy path | Is the expected behavior tested? |
+| Error path | Are error scenarios tested? |
+| Regression | Does a test prevent the original issue from recurring (bugfix)? |
+| Boundary | Are edge cases and limits tested? |
+| Execution | Were tests actually run? (Not just written) |
+| Results | Did all tests pass? Are failures explained? |
+
+### 3. Architecture Alignment
+
+| Check | What to Verify |
+|---|---|
+| Boundary respect | Does the change respect module/service boundaries? |
+| Pattern compliance | Does it follow established patterns from memory? |
+| Dependency direction | Are dependencies flowing in the correct direction? |
+| Abstraction level | Is the code at the appropriate abstraction level? |
+
+### 4. Graph Consistency
+
+| Check | What to Verify |
+|---|---|
+| Node updates | Are new modules/services reflected in graphs? |
+| Edge updates | Are new dependencies/relationships reflected? |
+| Stale entries | Were removed elements cleaned from graphs? |
+| Map alignment | Does architecture-map.md reflect JSON graph changes? |
+
+### 5. Documentation Accuracy
+
+| Check | What to Verify |
+|---|---|
+| Knowledge sync | Were affected knowledge docs updated? |
+| Memory sync | Were durable decisions captured if needed? |
+| Context sync | Were navigation maps updated? |
+| Change record | Does the CHG record accurately reflect the work? |
+| Impact report | Was the impact report referenced correctly? |
+
+## Finding Severity Scale
+
+| Severity | Symbol | Meaning | Action Required |
+|---|---|---|---|
+| Blocker | 🔴 | Breaks functionality or introduces security risk | Must fix before completion |
+| Major | 🟠 | Significant issue but not immediately breaking | Should fix before completion |
+| Minor | 🟡 | Code quality or style issue | Fix when convenient |
+| Suggestion | 🔵 | Optional improvement | Consider for future |
+| Positive | 🟢 | Good practice or improvement observed | No action needed |
+
+## Procedure
+
+1. **Read Context** — Load the impact report, implementation diff, and test results.
+2. **Review Each Dimension** — Walk through all five review dimensions above.
+3. **Score Findings** — Assign severity to each finding.
+4. **Check Intelligence** — Verify graph, knowledge, memory, and context were appropriately synced.
+5. **Write Report** — Generate the review report.
+
+## Output Format
+
+Write `.engineering-intelligence/reports/REV-XXX-<slug>.md`:
+
+```markdown
+# REV-XXX: <summary>
+
+## Meta
+- Date: <ISO timestamp>
+- Related: IMP-XXX, CHG-XXX
+- Scope: <what was reviewed>
+
+## Summary
+- Total findings: X
+- 🔴 Blocker: Y | 🟠 Major: Z | 🟡 Minor: W | 🔵 Suggestion: V
+
+## Verdict
+- [ ] ✅ Approved — No blocking issues
+- [ ] ⚠️ Approved with findings — Non-blocking issues noted
+- [ ] ❌ Changes required — Blocking issues must be addressed
+
+## Findings
+
+### 🔴 [Finding Title]
+- **Dimension**: Implementation / Testing / Architecture / Graph / Documentation
+- **Location**: <file:line or artifact path>
+- **Description**: <what was found>
+- **Evidence**: <code reference or comparison>
+- **Recommendation**: <how to fix>
+
+### 🟢 [Positive Finding]
+- **Description**: <good practice observed>
+
+## Test Gaps
+- <untested areas that should be tested>
+
+## Intelligence Sync Status
+| Artifact | Status | Notes |
+|---|---|---|
+| knowledge-base/ | ✅ Synced | API docs updated |
+| graph/ | ⚠️ Partial | Missing new service node |
+
+## Stale Intelligence Risks
+- <areas where docs may drift from code>
+```
+
+## Rules
+
+- Review is read-only — do not apply fixes during a review-only workflow
+- Be honest about gaps and risks — sugar-coating helps nobody
+- Include positive findings alongside issues — balanced review
+- All findings must cite specific evidence (file paths, code references)
+- If tests were not actually run, flag it as a major finding
+
+## Quality Gates
+
+- [ ] All five review dimensions were evaluated
+- [ ] Each finding has severity, location, and evidence
+- [ ] Test execution was verified (not assumed)
+- [ ] Intelligence sync status was checked
+- [ ] Report includes verdict (approved/changes required)
+
+## Cross-References
+
+- Depends on: `change-detection-engine` (identifies what to review)
+- Used by: `engineering-intelligence-skill` (high-risk review gate), `review-engineering-change` workflow
+- Reads: Impact reports, change records, graph artifacts