engineering-intelligence 0.8.1 → 1.0.0

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

@@ -0,0 +1,156 @@
+---
+name: performance-analysis-engine
+description: Identifies performance issues through static analysis of database query patterns, frontend bundle size, render performance, API response patterns, and caching opportunities. Use during initialization, before releases, or when performance-sensitive changes are detected.
+version: 3.0.0
+---
+
+# Performance Analysis Engine
+
+Identify performance risks and optimization opportunities through evidence-based static analysis of code patterns, queries, bundles, and caching strategies.
+
+## Inputs
+
+- Repository root path
+- Mode: `full` (comprehensive analysis) or `targeted` (specific area or post-change)
+- Optional: scope constraints (specific modules, change diff)
+- Optional: previous assessment (`knowledge-base/21-performance-assessment.md`) for delta comparison
+
+## Procedure
+
+1. **Database Query Pattern Analysis** — Scan data access layers for:
+
+   | Pattern | Risk | Detection Method |
+   |---|---|---|
+   | N+1 queries | High | Loop containing query calls, ORM eager/lazy loading misuse |
+   | Missing indexes | Medium | Queries filtering/sorting on non-indexed columns |
+   | Unbounded queries | High | SELECT without LIMIT, missing pagination |
+   | Full table scans | Medium | Queries without WHERE clauses on large tables |
+   | Unnecessary joins | Low | Joins fetching unused columns |
+   | Missing connection pooling | Medium | New connection per request pattern |
+
+   Cross-reference with schema definitions and ORM configuration.
+
+2. **Bundle Size Analysis** (frontend projects) — Assess:
+
+   | Check | Description |
+   |---|---|
+   | Bundle composition | Identify largest dependencies by size contribution |
+   | Tree-shaking gaps | Imports that prevent effective tree-shaking |
+   | Code splitting | Missing dynamic imports for route-level splitting |
+   | Duplicate dependencies | Same library bundled at multiple versions |
+   | Dead code | Exported modules never imported elsewhere |
+   | Asset optimization | Uncompressed images, unminified resources |
+
+   Read build configuration (webpack, vite, esbuild, etc.) to understand current optimization setup.
+
+3. **Render Performance Patterns** (frontend projects) — Identify:
+
+   | Pattern | Risk | Detection Method |
+   |---|---|---|
+   | Unnecessary re-renders | High | Components without memoization receiving stable props |
+   | Missing `useMemo`/`useCallback` | Medium | Expensive computations in render path |
+   | Large component trees | Medium | Deeply nested components without virtualization |
+   | Layout thrashing | High | DOM reads interleaved with writes |
+   | Missing virtualization | High | Lists rendering >100 items without windowing |
+   | Unoptimized images | Medium | Missing lazy loading, no responsive sizes |
+
+4. **API Response Time Patterns** — Analyze:
+
+   | Check | Description |
+   |---|---|
+   | Waterfall requests | Sequential API calls that could be parallelized |
+   | Over-fetching | Endpoints returning significantly more data than consumed |
+   | Under-fetching | Multiple requests needed where one could suffice |
+   | Missing pagination | List endpoints without page size limits |
+   | Synchronous heavy operations | Long-running tasks blocking request handlers |
+   | Missing timeouts | External API calls without timeout configuration |
+
+5. **Caching Opportunities** — Identify:
+
+   | Opportunity | Evidence |
+   |---|---|
+   | Repeated identical queries | Same query executed multiple times per request |
+   | Static data fetched dynamically | Configuration or reference data loaded on every request |
+   | Missing HTTP cache headers | Responses for stable resources without Cache-Control |
+   | Computation-heavy endpoints | Endpoints with expensive but deterministic calculations |
+   | Missing CDN utilization | Static assets served from application server |
+   | Session/user-level caching | Per-user data re-fetched on every request |
+
+   Review existing caching infrastructure (Redis, Memcached, in-memory, HTTP) and identify gaps.
+
+6. **Generate Assessment** — Write findings to `knowledge-base/21-performance-assessment.md`.
+
+## Output Format
+
+Write `knowledge-base/21-performance-assessment.md`:
+
+```markdown
+# Performance Assessment
+
+## Meta
+- Generated: <ISO timestamp>
+- Mode: full | targeted
+- Scope: <what was examined>
+- Overall risk: low | medium | high | critical
+
+## Database Query Patterns
+| Issue | Location | Risk | Recommendation |
+|---|---|---|---|
+| N+1 query | src/users/service.ts:45 | High | Add eager loading for user.posts |
+
+## Bundle Analysis
+| Metric | Value | Status |
+|---|---|---|
+| Total bundle size | 1.2 MB | concern |
+| Largest dependency | moment.js (320 KB) | Replace with date-fns |
+
+## Render Performance
+| Issue | Component | Risk | Recommendation |
+|---|---|---|---|
+| Missing memoization | UserList | Medium | Wrap with React.memo |
+
+## API Patterns
+| Issue | Endpoint | Risk | Recommendation |
+|---|---|---|---|
+| Waterfall requests | /dashboard | High | Parallelize data fetching |
+
+## Caching Opportunities
+| Opportunity | Location | Impact |
+|---|---|---|
+| Static config fetched per request | src/config/loader.ts | High |
+
+## Recommendations
+1. <prioritized optimization actions with estimated impact>
+
+## Evidence
+- <file path citations for all findings>
+
+---
+*This performance assessment did not modify product code.*
+```
+
+## Rules
+
+- Every finding must cite a specific file path and line number or code pattern
+- Risk assessment must consider actual usage patterns, not theoretical worst cases
+- Bundle analysis findings must reference build configuration evidence
+- Do not recommend premature optimization — prioritize by measured or evidenced impact
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] All findings cite specific file paths or code patterns
+- [ ] Database query issues distinguish between ORM-generated and raw queries
+- [ ] Bundle analysis references build configuration
+- [ ] Render performance findings are framework-aware (React, Vue, Angular, etc.)
+- [ ] Caching recommendations consider existing infrastructure
+- [ ] Recommendations are prioritized by estimated impact
+- [ ] Report ends with the "did not modify product code" statement
+
+## Cross-References
+
+- Depends on: `deep-project-knowledge-extractor` (project structure and technology understanding)
+- Used by: `engineering-intelligence-skill`, `impact-analysis-engine` (performance risk scoring)
+- Updates: `knowledge-base/21-performance-assessment.md`
+
+This capability is analytical only. It must not modify product code.

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

@@ -0,0 +1,127 @@
+---
+name: pr-intelligence-engine
+description: Generates intelligent PR descriptions, reviewer suggestions, impact summaries, and split recommendations from change records and git intelligence. Use before submitting or reviewing pull requests.
+version: 3.0.0
+---
+
+# PR Intelligence Engine
+
+Produce evidence-backed PR artifacts that accelerate review cycles and improve change quality.
+
+## Inputs
+
+- Change records from `.changes/CHG-XXX-*.md`
+- Git diff or commit range for the PR
+- Ownership mapping from `git-intelligence-engine` (`.engineering-intelligence/reports/GIT-intelligence.md`)
+- Impact report from `impact-analysis-engine` (when available)
+- Architecture decisions from `knowledge-base/`
+
+## Procedure
+
+1. **Analyze Change Scope** — Parse the diff or commit range to determine:
+   - Files modified, added, deleted
+   - Total lines changed (additions + deletions)
+   - Modules touched (distinct top-level directories or packages)
+   - Change classification (feature, bugfix, refactor, infrastructure, docs)
+
+2. **Generate PR Description** — From change records and diff, produce:
+
+   ```markdown
+   ## What
+   <concise summary of what changed and why>
+
+   ## Why
+   <link to change record CHG-XXX, issue/ticket if available>
+
+   ## How
+   <technical approach summary — key design decisions>
+
+   ## Impact
+   <blast radius summary from impact analysis>
+
+   ## Testing
+   <tests added/modified, validation performed>
+
+   ## Migration / Rollback
+   <if applicable — schema changes, feature flags, rollback steps>
+   ```
+
+3. **Suggest Reviewers** — Using ownership mapping from `git-intelligence-engine`:
+
+   | Priority | Criteria |
+   |---|---|
+   | Required | Primary owner of any modified module |
+   | Recommended | Secondary owner with recent activity in modified files |
+   | Optional | Contributors to change-coupled files not in the diff |
+   | Domain expert | Owner of upstream/downstream modules from impact analysis |
+
+   Flag when no active owner exists for a modified module (orphaned module risk).
+
+4. **Generate Impact Summary** — Produce a reviewer-focused impact digest:
+   - Risk level (from impact report or assessed from diff)
+   - Breaking changes (API contracts, schema migrations)
+   - Cross-service effects (if any)
+   - Intelligence artifacts that will need sync after merge
+
+5. **Evaluate PR Size and Suggest Split** — If the PR exceeds thresholds:
+
+   | Metric | Threshold | Action |
+   |---|---|---|
+   | Total lines changed | >500 | Suggest split |
+   | Modules touched | >3 | Suggest split |
+   | Mixed concerns | Feature + refactor | Suggest split |
+   | Schema + code | Migration + logic | Suggest split |
+
+   When suggesting split, propose concrete split boundaries:
+   - Group by module or concern
+   - Identify which changes can land independently
+   - Suggest merge order if dependencies exist between splits
+
+6. **Check Architecture Compliance** — Compare changes against:
+   - `knowledge-base/05-architecture-decisions.md` (ADRs)
+   - `knowledge-base/06-conventions-and-standards.md`
+   - Module boundary rules from `dependency-graph.json`
+
+   Flag violations with evidence:
+
+   | Violation Type | Example |
+   |---|---|
+   | Dependency direction | Service A importing from Service B's internals |
+   | Convention breach | Naming pattern, file structure deviation |
+   | ADR contradiction | Change conflicts with recorded architecture decision |
+   | Missing ADR | Architectural change without corresponding decision record |
+
+## Output Format
+
+Generate the following artifacts (do not write to the repository — present to the user):
+
+- **PR description** — Markdown ready to paste into PR body
+- **Reviewer suggestions** — Ranked list with rationale
+- **Impact summary** — Reviewer-focused digest
+- **Split recommendations** — Only if thresholds are exceeded
+- **Architecture flags** — Only if violations are detected
+
+## Rules
+
+- PR descriptions must reference change records (CHG-XXX) when available
+- Reviewer suggestions must cite ownership evidence, not guess from file paths
+- Never suppress architecture violations — always surface them
+- Split suggestions must include concrete boundaries, not vague advice
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] PR description covers what, why, how, impact, and testing
+- [ ] Reviewer suggestions cite ownership data with evidence
+- [ ] Impact summary includes risk level and blast radius
+- [ ] Split recommendations (if any) propose concrete boundaries
+- [ ] Architecture violations cite specific ADRs or conventions breached
+- [ ] All claims reference change records, diffs, or intelligence artifacts
+
+## Cross-References
+
+- Depends on: `git-intelligence-engine` (ownership mapping), `impact-analysis-engine` (impact reports), `change-detection-engine` (change records)
+- Used by: `engineering-intelligence-skill`
+- Consumed by: `engineering-change-review`
+
+This capability is analytical only. It must not modify product code.

package/templates/canonical/skills/security-audit-engine/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: security-audit-engine
+description: Performs evidence-based security audits covering dependency vulnerabilities, auth/authz patterns, secrets detection, OWASP Top 10 compliance, and input validation. Use during initialization, before releases, or when security-sensitive changes are detected.
+version: 3.0.0
+---
+
+# Security Audit Engine
+
+Identify security risks through systematic, evidence-backed analysis of dependencies, authentication patterns, secrets hygiene, and input handling.
+
+## Inputs
+
+- Repository root path
+- Mode: `full` (comprehensive audit) or `targeted` (specific area or post-change)
+- Optional: scope constraints (specific modules, change diff)
+- Optional: previous assessment (`knowledge-base/20-security-assessment.md`) for delta comparison
+
+## Procedure
+
+1. **Dependency Vulnerability Scanning** — Parse lock files and manifests:
+
+   | File | Ecosystem |
+   |---|---|
+   | `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` | npm |
+   | `Pipfile.lock` / `requirements.txt` | Python |
+   | `Cargo.lock` | Rust |
+   | `go.sum` | Go |
+   | `Gemfile.lock` | Ruby |
+   | `composer.lock` | PHP |
+
+   For each dependency:
+   - Check version against known CVE databases (cite CVE IDs)
+   - Flag dependencies with no updates in >12 months (abandonment risk)
+   - Identify transitive dependencies with known vulnerabilities
+   - Note severity: critical, high, medium, low
+
+2. **Auth/Authz Pattern Review** — Analyze authentication and authorization:
+
+   | Check | What to Look For |
+   |---|---|
+   | Auth mechanism | JWT, session, OAuth, API keys — identify which is used |
+   | Token handling | Storage (cookies, localStorage), expiration, refresh flow |
+   | Password handling | Hashing algorithm, salt usage, strength validation |
+   | Permission model | RBAC, ABAC, ACL — identify and assess |
+   | Route protection | Unprotected endpoints that should require auth |
+   | Privilege escalation | Missing authorization checks on sensitive operations |
+   | Session management | Fixation prevention, timeout, invalidation |
+
+3. **Secrets Detection** — Scan for exposed credentials:
+
+   | Pattern | Risk |
+   |---|---|
+   | Hardcoded API keys / tokens | Critical |
+   | Database connection strings with passwords | Critical |
+   | Private keys committed to repository | Critical |
+   | `.env` files without `.gitignore` coverage | High |
+   | Secrets in CI/CD configuration | High |
+   | Default/test credentials in non-test code | Medium |
+   | Comments containing sensitive URLs or tokens | Medium |
+
+   Check `.gitignore` for adequate secret file exclusions.
+
+4. **OWASP Top 10 Checklist** — Assess against current OWASP Top 10:
+
+   | # | Category | Assessment |
+   |---|---|---|
+   | A01 | Broken Access Control | Check route guards, CORS, directory traversal |
+   | A02 | Cryptographic Failures | Check TLS, hashing, encryption at rest |
+   | A03 | Injection | Check SQL, NoSQL, OS command, LDAP injection |
+   | A04 | Insecure Design | Check business logic flaws, missing rate limits |
+   | A05 | Security Misconfiguration | Check default configs, verbose errors, headers |
+   | A06 | Vulnerable Components | Cross-ref with dependency scan results |
+   | A07 | Auth Failures | Cross-ref with auth/authz review |
+   | A08 | Data Integrity Failures | Check deserialization, CI/CD pipeline integrity |
+   | A09 | Logging Failures | Check audit logging, sensitive data in logs |
+   | A10 | SSRF | Check URL handling, outbound request validation |
+
+   Rate each as: `pass`, `concern`, `fail`, or `not-applicable`.
+
+5. **Input Validation Pattern Review** — Assess input handling:
+
+   | Check | Description |
+   |---|---|
+   | Schema validation | Are API inputs validated against schemas? |
+   | Sanitization | Is user input sanitized before use? |
+   | File upload | Are uploads validated (type, size, content)? |
+   | Query parameters | Are query params validated and typed? |
+   | Output encoding | Is output encoded to prevent XSS? |
+   | Rate limiting | Are endpoints rate-limited? |
+
+6. **Generate Assessment** — Write findings to `knowledge-base/20-security-assessment.md`.
+
+## Output Format
+
+Write `knowledge-base/20-security-assessment.md`:
+
+```markdown
+# Security Assessment
+
+## Meta
+- Generated: <ISO timestamp>
+- Mode: full | targeted
+- Scope: <what was examined>
+- Overall risk: low | medium | high | critical
+
+## Dependency Vulnerabilities
+| Dependency | Version | CVE | Severity | Fix Available |
+|---|---|---|---|---|
+| lodash | 4.17.15 | CVE-2020-8203 | High | Yes (4.17.21) |
+
+## Auth/Authz Assessment
+- Mechanism: <description>
+- Findings: <issues found>
+- Risk: <level>
+
+## Secrets Scan
+| Finding | File | Risk | Remediation |
+|---|---|---|---|
+| Hardcoded API key | src/config.ts:42 | Critical | Move to env variable |
+
+## OWASP Top 10
+| # | Category | Status | Evidence |
+|---|---|---|---|
+| A01 | Broken Access Control | concern | <finding> |
+
+## Input Validation
+| Area | Status | Evidence |
+|---|---|---|
+| API schema validation | pass | Uses Zod on all endpoints |
+
+## Recommendations
+1. <prioritized remediation actions>
+
+## Evidence
+- <file path citations for all findings>
+
+---
+*This security assessment did not modify product code.*
+```
+
+## Rules
+
+- Never assume a vulnerability exists without evidence — cite file paths and line numbers
+- Flag severity honestly — do not inflate or suppress findings
+- Secrets detection must not log or expose the actual secret values in reports
+- Mark `not-applicable` for OWASP categories genuinely irrelevant to the project
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] All dependency vulnerabilities cite CVE IDs and affected versions
+- [ ] Auth/authz review covers both authentication and authorization
+- [ ] Secrets scan does not expose actual secret values in the report
+- [ ] OWASP Top 10 items each have a status with evidence or rationale
+- [ ] Input validation assessment covers API boundaries
+- [ ] Recommendations are prioritized by severity
+- [ ] Report ends with the "did not modify product code" statement
+
+## Cross-References
+
+- Depends on: `deep-project-knowledge-extractor` (project structure understanding)
+- Used by: `engineering-intelligence-skill`, `impact-analysis-engine` (security risk scoring)
+- Updates: `knowledge-base/20-security-assessment.md`
+
+This capability is analytical only. It must not modify product code.

package/templates/canonical/skills/staleness-detector/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: staleness-detector
+description: Compares knowledge-base document timestamps against related source file modification times, scores each document 0-100 for freshness, triggers incremental sync when freshness drops below threshold, and adds freshness metadata to document headers.
+version: 3.0.0
+---
+
+# Staleness Detector
+
+Monitor the freshness of all engineering intelligence documents by comparing their last-updated timestamps against the modification times of the source files they describe. Produce a freshness report and trigger incremental sync for stale documents.
+
+This capability does not modify product code.
+
+## Inputs
+
+- Repository root path
+- Knowledge base directory (`knowledge-base/`)
+- Memory directory (`.engineering-intelligence/memory/`)
+- Context directory (`.engineering-intelligence/context/`)
+- Optional: specific document or module to check
+- Optional: custom freshness threshold (default: 60)
+
+## Procedure
+
+1. **Inventory knowledge documents** — Enumerate all documents in:
+   - `knowledge-base/*.md` (00 through 16)
+   - `.engineering-intelligence/memory/*.md`
+   - `.engineering-intelligence/context/*.md`
+   - `.engineering-intelligence/graph/*.json`
+
+   For each document, extract:
+   - Document path
+   - Last modified timestamp (from filesystem or frontmatter `last_updated` field)
+   - Evidence citations within the document (file paths referenced)
+
+2. **Extract evidence dependencies** — For each knowledge document, parse all evidence citations to build a dependency map:
+
+   ```markdown
+   ## Document Dependencies
+
+   | Document | Depends On (Source Files) |
+   |---|---|
+   | `02-architecture.md` | `src/app/`, `src/server/`, `next.config.mjs` |
+   | `05-database.md` | `prisma/schema.prisma`, `src/db/`, `migrations/` |
+   | `06-authentication.md` | `src/auth/`, `auth.config.ts`, `middleware.ts` |
+   ```
+
+3. **Check source file modification times** — For each source file referenced by a knowledge document:
+   - Get the file's last modification time via `git log -1 --format=%cI -- <path>` (preferred) or filesystem mtime
+   - Compare against the knowledge document's last-updated timestamp
+   - Track files that no longer exist (deleted or moved)
+
+4. **Calculate freshness score** — Score each document 0–100 using this formula:
+
+   ```
+   base_score = 100
+
+   For each referenced source file:
+     days_since_doc_update = (now - document_last_updated).days
+     days_since_file_change = (now - file_last_modified).days
+
+     if file was modified AFTER document was last updated:
+       staleness_penalty = min(30, (file_modified - doc_updated).days * 3)
+       base_score -= staleness_penalty
+
+     if file no longer exists:
+       base_score -= 25  (major structural change)
+
+     if file was renamed/moved (detected via git):
+       base_score -= 15  (references are broken)
+
+   age_penalty = min(20, days_since_doc_update * 0.5)
+   base_score -= age_penalty
+
+   freshness_score = max(0, base_score)
+   ```
+
+   **Score interpretation:**
+
+   | Score | Status | Meaning |
+   |---|---|---|
+   | 80–100 | 🟢 Fresh | Document is current and reliable |
+   | 60–79 | 🟡 Aging | Document may have minor inaccuracies |
+   | 40–59 | 🟠 Stale | Document likely has outdated information |
+   | 20–39 | 🔴 Very Stale | Document is unreliable, needs re-generation |
+   | 0–19 | ⛔ Obsolete | Document may be misleading, urgent refresh needed |
+
+5. **Add freshness metadata** — Inject or update a frontmatter block at the top of each knowledge document:
+
+   ```markdown
+   <!-- freshness: score=75, status=aging, last_checked=2024-01-20T14:30:00Z -->
+   <!-- stale_sources: src/auth/middleware.ts (modified 5 days after doc update) -->
+   ```
+
+   Rules for metadata injection:
+   - If a `<!-- freshness: -->` comment already exists, update it in place
+   - If no freshness comment exists, add it after the document title (first `#` heading)
+   - Never modify document content — only metadata comments
+
+6. **Determine sync actions** — Based on freshness scores, determine required actions:
+
+   | Condition | Action |
+   |---|---|
+   | Score < threshold (default 60) | Queue for incremental sync via `incremental-sync-engine` |
+   | Score < 30 | Flag as critical in report, recommend full re-generation |
+   | Referenced file deleted | Flag structural change, recommend manual review |
+   | Referenced file moved | Update evidence citations, re-verify claims |
+   | Multiple documents stale for same module | Recommend module-level re-discovery |
+
+7. **Generate FRESHNESS-report.md** — Write to `.engineering-intelligence/reports/FRESHNESS-report.md`:
+
+   ```markdown
+   # Freshness Report
+
+   Generated: <timestamp>
+   Threshold: <score>
+   Documents scanned: <N>
+
+   ## Summary
+
+   | Status | Count | Percentage |
+   |---|---|---|
+   | 🟢 Fresh (80-100) | <N> | <N%> |
+   | 🟡 Aging (60-79) | <N> | <N%> |
+   | 🟠 Stale (40-59) | <N> | <N%> |
+   | 🔴 Very Stale (20-39) | <N> | <N%> |
+   | ⛔ Obsolete (0-19) | <N> | <N%> |
+
+   ## Document Scores
+
+   | Document | Score | Status | Stale Sources | Last Updated | Action Needed |
+   |---|---|---|---|---|---|
+   | `02-architecture.md` | 45 | 🟠 Stale | `src/app/layout.tsx` (+3d) | 2024-01-10 | Incremental sync |
+   | `05-database.md` | 90 | 🟢 Fresh | — | 2024-01-18 | None |
+   | ... | ... | ... | ... | ... | ... |
+
+   ## Structural Changes
+
+   | Type | File | Affected Documents |
+   |---|---|---|
+   | Deleted | `src/old-auth/handler.ts` | `06-authentication.md` |
+   | Moved | `src/utils.ts` → `src/lib/utils.ts` | `01-repository-structure.md` |
+
+   ## Recommended Actions
+
+   1. **Critical** — Re-generate: <list of documents with score < 30>
+   2. **High** — Incremental sync: <list of documents with score < 60>
+   3. **Medium** — Review: <list of documents with score 60-79>
+   4. **Structural** — Manual review needed: <list of deleted/moved file impacts>
+
+   ## Module-Level Freshness
+
+   | Module | Avg Document Score | Documents Below Threshold |
+   |---|---|---|
+   | auth | 42 | `06-authentication.md`, `context/critical-paths.md` |
+   | api | 88 | — |
+   | ... | ... | ... |
+   ```
+
+8. **Trigger incremental sync** — For documents below the threshold, invoke `incremental-sync-engine` with:
+   - The specific document to update
+   - The list of changed source files
+   - The staleness reason (file modified, file deleted, file moved, age)
+
+## Quality Gates
+
+- [ ] All knowledge base, memory, and context documents are inventoried
+- [ ] Evidence citations are parsed from every document
+- [ ] Source file modification times are checked against document timestamps
+- [ ] Freshness scores follow the defined calculation formula
+- [ ] Score interpretation matches the defined status table
+- [ ] Freshness metadata is injected without modifying document content
+- [ ] FRESHNESS-report.md exists at `.engineering-intelligence/reports/FRESHNESS-report.md`
+- [ ] Structural changes (deleted/moved files) are detected and reported
+- [ ] Documents below threshold are queued for incremental sync
+- [ ] Module-level aggregation is included in the report
+
+## Cross-References
+
+- Used by: `ongoing-learning-engine` (for freshness monitoring)
+- Uses: `incremental-sync-engine` (to refresh stale documents)
+- Consumed by: `engineering-intelligence-skill`, `engineering-orchestrator`
+- Feeds into: `.engineering-intelligence/reports/FRESHNESS-report.md`
+- Related: `knowledge-base-validator` (validates content accuracy; staleness-detector validates currency)
+
+This capability does not modify product code.