@dzhechkov/harness-core 0.3.111 → 0.3.113

package/dist/rake-analyzer.js

@@ -0,0 +1,249 @@
+/**
+ * MR rake analyzer (feature mr-rake-analyzer, ADR-001).
+ *
+ * Mines a project's review corpus for RECURRING mistakes ("rakes") and closes them into self-learning.
+ * The parse/normalize/detect/render functions are PURE + deterministic (sorted, no clock/random) so the
+ * same corpus yields a byte-identical report; the load/scan helpers do disk I/O with TOP-LEVEL node:fs
+ * imports (harness-core is ESM — a lazy require() is undefined at runtime; the R1 footgun).
+ *
+ * Signature is DETERMINISTIC (ADR-001 §1): a rule table of known rake classes, with an unmatched finding
+ * falling to a normalized-text bucket so novel recurrences still cluster. LLM classification is an optional
+ * amplifier, never in this core.
+ *
+ * SAFETY PROPERTY (ADR-001 §3, load-bearing): a finding whose signature appears in fewer than
+ * `thresholds.candidate` DISTINCT sources is a one-off — it is NEVER a rake and never reaches teach/critic.
+ */
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+const SEVERITY_RANK = { blocker: 4, high: 3, medium: 2, low: 1, unknown: 0 };
+export const DEFAULT_RAKE_THRESHOLDS = { candidate: 2, confirmed: 3 };
+/**
+ * Known rake classes (extensible, data-only). Seeded from the classes that actually recur in this repo's
+ * QE reports — that IS the dogfood. First match in order wins; unmatched → normalized-text bucket.
+ */
+export const RAKE_SIGNATURES = [
+    { id: 'esm-require-footgun', label: 'ESM lazy require() undefined at runtime', patterns: [/require\(['"]node:/, /\besm\b.*require/i, /lazy require/i] },
+    { id: 'untested-adr-property', label: 'ADR-named safety property left untested', patterns: [/load-bearing.*(untested|not\s+tested|no\s+test)/i, /adr.*names.*(property|test)/i, /safety property.*test/i] },
+    { id: 'claim-check-fp', label: 'claim-check false positive / untagged count', patterns: [/claim-check.*(false positive|\bfp\b)/i, /untagged.*(count|claim)/i, /metric term/i] },
+    // "traversal" alone over-matches (AST/tree traversal); require a filesystem-scope token to CO-OCCUR
+    // (or a literal `../`) — cross-model QE caught the over-match.
+    { id: 'path-traversal', label: 'path not constrained to the repo (traversal)', patterns: [/\.\.\//, /(?=.*travers)(?=.*(repo|root|\bpath\b|director|\/etc\/))/i, /escapes.{0,12}repo/i] },
+    { id: 'silent-drop-or-inject', label: 'silent drop / silent injection (no report)', patterns: [/silent(ly)?\s+(drop|inject|discard|dropped)/i, /no silent (injection|caps|drop)/i] },
+    { id: 'swallow-generic-exception', label: 'generic except/catch swallows real bugs', patterns: [/except\s+Exception/i, /catch.*swallow/i, /generic (exception|catch)/i] },
+    { id: 'determinism-hole', label: 'non-deterministic output (unsorted/clock/random)', patterns: [/non-determinis/i, /determinism hole/i, /unsorted|not sorted/i] },
+    { id: 'cross-model-self-qe', label: 'coder self-QE instead of cross-model', patterns: [/self-qe/i, /coder.*(review|qe).*(itself|self)/i, /cross-model/i] },
+    { id: 'malformed-input-bypass', label: 'malformed input bypasses validation', patterns: [/array.*(pass|bypass)/i, /malformed.*(bypass|pass|manifest)/i, /typeof.*object/i] },
+];
+// Deep-freeze so an external caller can't inject a `/g`-flag regex whose `.test()` mutates lastIndex and
+// makes signatureOf non-deterministic (cross-model QE). None of the patterns above use `g`/`y`.
+for (const s of RAKE_SIGNATURES) {
+    Object.freeze(s.patterns);
+    Object.freeze(s);
+}
+Object.freeze(RAKE_SIGNATURES);
+const byStr = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const uniqSorted = (xs) => [...new Set(xs)].sort(byStr);
+const maxSeverity = (a, b) => (SEVERITY_RANK[a] >= SEVERITY_RANK[b] ? a : b);
+const STOPWORDS = new Set(['the', 'a', 'an', 'and', 'or', 'to', 'of', 'in', 'on', 'is', 'it', 'that', 'this', 'for', 'with', 'as', 'at', 'by', 'be', 'not', 'no', 'its', 'when', 'if', 'was', 'are', 'но', 'и', 'в', 'на', 'что', 'это', 'не', 'из', 'за', 'для']);
+/** Normalize a finding's text to a stable clustering key: lowercase, strip sites/numbers/punct, top significant words. */
+export function normalizeText(text) {
+    const cleaned = text
+        .toLowerCase()
+        .replace(/[\w./-]+:\d+/g, ' ') // drop file:line
+        .replace(/`[^`]*`/g, ' ') // drop code literals
+        .replace(/[^a-zа-я\s]/gi, ' '); // drop digits/punct
+    const words = cleaned.split(/\s+/).filter((w) => w.length >= 4 && !STOPWORDS.has(w));
+    return uniqSorted(words).slice(0, 6).join(' ');
+}
+const SEV_MAP = {
+    blocker: 'blocker', critical: 'blocker', crit: 'blocker',
+    high: 'high', hi: 'high',
+    medium: 'medium', med: 'medium',
+    low: 'low', nit: 'low',
+};
+const toSeverity = (raw) => SEV_MAP[raw.trim().toLowerCase()] ?? 'unknown';
+const SITE_RE = /([\w./-]+\.(?:ts|js|tsx|jsx|py|go|md|json|yml|yaml):\d+)/;
+/** The signature of a finding: first matching rule, else the normalized-text bucket. */
+export function signatureOf(finding) {
+    for (const s of RAKE_SIGNATURES) {
+        if (s.patterns.some((p) => p.test(finding.text)))
+            return { id: s.id, label: s.label };
+    }
+    const key = normalizeText(finding.text);
+    if (key !== '')
+        return { id: `text:${key}`, label: key };
+    // No significant words (code-only / very short). Key on the LITERAL text so two DIFFERENT such findings
+    // never merge into a false "unclassified ×N" rake (cross-model QE) — but two IDENTICAL ones still cluster.
+    const literal = finding.text.toLowerCase().replace(/\s+/g, ' ').trim().slice(0, 80);
+    return { id: `literal:${literal}`, label: literal === '' ? 'unclassified finding' : literal };
+}
+/**
+ * Parse one markdown artifact into findings. Handles (a) severity table rows `| … | High | <text> | … |`,
+ * (b) inline markers `[High]` / `**High —**` / `Sev — <text>`. Deterministic; unknown formats yield nothing.
+ */
+export function extractFindings(markdown, source) {
+    const out = [];
+    const push = (severity, text) => {
+        const t = text.replace(/\s+/g, ' ').trim();
+        if (t.length < 8)
+            return; // too short to be a finding
+        const site = SITE_RE.exec(t)?.[1];
+        out.push(site ? { source, severity, text: t, site } : { source, severity, text: t });
+    };
+    for (const line of markdown.split('\n')) {
+        // (a) table row: | ... | <sev> | <finding> | ...
+        const cells = line.includes('|') ? line.split('|').map((c) => c.trim()) : null;
+        if (cells && cells.length >= 4) {
+            const sevCell = cells.find((c) => SEV_MAP[c.toLowerCase()] !== undefined);
+            if (sevCell) {
+                const sevIdx = cells.indexOf(sevCell);
+                const finding = cells.slice(sevIdx + 1).find((c) => c.length >= 8 && !/^-+$/.test(c));
+                if (finding) {
+                    push(toSeverity(sevCell), finding);
+                    continue;
+                }
+            }
+        }
+        // (b) inline `[High] text` / `**High —** text` / `- High: text`. The bracketed form `[High] text`
+        // needs no separator (the brackets delimit); the bare form `High: text` requires one so prose like
+        // "high latency" doesn't register (cross-model QE: a missing separator silently dropped findings).
+        const bracketed = /^[\s\-*>]*\**\[(blocker|critical|high|medium|med|low)\]\**\s*[—:\-]?\s*(.+)$/i.exec(line);
+        const bare = /^[\s\-*>]*\**(blocker|critical|high|medium|med|low)\**\s*[—:]\s*(.+)$/i.exec(line);
+        const m = bracketed ?? bare;
+        if (m && m[1] && m[2])
+            push(toSeverity(m[1]), m[2]);
+    }
+    return out;
+}
+/**
+ * Detect rakes: group findings by signature, count DISTINCT sources, keep only groups at/above the candidate
+ * threshold (a below-threshold group is a one-off, NEVER a rake — the load-bearing anti-noise property).
+ * PURE + deterministic (ADR-001 §1): rakes sorted by (count desc, severity desc, signature asc).
+ */
+export function detectRakes(findings, thresholds = DEFAULT_RAKE_THRESHOLDS) {
+    const groups = new Map();
+    for (const f of findings) {
+        const sig = signatureOf(f);
+        const g = groups.get(sig.id);
+        if (g)
+            g.findings.push(f);
+        else
+            groups.set(sig.id, { label: sig.label, findings: [f] });
+    }
+    const rakes = [];
+    let oneOffs = 0;
+    for (const [signature, g] of groups) {
+        const sources = uniqSorted(g.findings.map((f) => f.source));
+        const count = sources.length;
+        if (count < thresholds.candidate) {
+            oneOffs++;
+            continue;
+        }
+        const severity = g.findings.reduce((m, f) => maxSeverity(m, f.severity), 'unknown');
+        const examples = [...g.findings]
+            .sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] || byStr(a.source, b.source))
+            .slice(0, 3);
+        rakes.push({ signature, label: g.label, sources, count, severity, examples, status: count >= thresholds.confirmed ? 'confirmed' : 'candidate' });
+    }
+    rakes.sort((a, b) => b.count - a.count || SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] || byStr(a.signature, b.signature));
+    return { rakes, totalFindings: findings.length, oneOffs };
+}
+/** Human render of the rake report. Deterministic. */
+export function renderRakeReport(report) {
+    if (report.rakes.length === 0) {
+        return `mr-rakes: no recurring rakes (${report.totalFindings} finding(s), ${report.oneOffs} one-off signature(s) below threshold).`;
+    }
+    const lines = [`mr-rakes: ${report.rakes.length} rake(s) from ${report.totalFindings} finding(s) (${report.oneOffs} one-off(s) dropped):`, ''];
+    for (const r of report.rakes) {
+        lines.push(`  [${r.status}] ${r.severity.toUpperCase()} ×${r.count} — ${r.label}  (${r.signature})`);
+        lines.push(`      sources: ${r.sources.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+/** The teachable rule text for a rake (fed to `dz teach`). Deterministic. */
+export function rakeAsLesson(rake) {
+    return `Project rake (recurred in ${rake.count} reviews): ${rake.label}. First seen: ${rake.examples[0]?.site ?? rake.sources[0]}. Watch for this class before it ships again.`;
+}
+/** Severity → teach reward. Higher-severity rakes are higher-signal lessons. */
+export function rakeReward(rake) {
+    return { blocker: 0.95, high: 0.9, medium: 0.8, low: 0.7, unknown: 0.7 }[rake.severity];
+}
+/** Render the CONFIRMED rakes as a project-critic SKILL.md section (sink B). Deterministic; confirmed only. */
+export function renderCriticSection(report) {
+    const confirmed = report.rakes.filter((r) => r.status === 'confirmed');
+    const lines = [
+        '## Recurring mistakes (auto-mined by `dz mr-rakes`)',
+        '',
+        confirmed.length === 0
+            ? '_No confirmed recurring rakes yet._'
+            : 'These classes of mistake have recurred across this project\'s reviews. Flag them before they ship again:',
+        '',
+    ];
+    for (const r of confirmed) {
+        lines.push(`- **${r.label}** (${r.severity}, ×${r.count}) — e.g. ${r.examples[0]?.site ?? r.sources[0]}.`);
+    }
+    return lines.join('\n');
+}
+// ── Thin I/O (top-level fs; never throws) ────────────────────────────────────────────────────────────
+/** Find review artifacts: each `features/<slug>/08_qe_report.md` plus any `REVIEW`-named markdown. Sorted. */
+export function findReviewArtifacts(repoRoot) {
+    if (typeof repoRoot !== 'string' || repoRoot === '')
+        return []; // fail-open on bad runtime input (cross-model QE)
+    const candidates = [];
+    const featuresDir = join(repoRoot, 'features');
+    try {
+        if (existsSync(featuresDir)) {
+            for (const slug of readdirSync(featuresDir)) {
+                const qe = join(featuresDir, slug, '08_qe_report.md');
+                if (existsSync(qe))
+                    candidates.push(`features/${slug}/08_qe_report.md`);
+            }
+        }
+    }
+    catch { /* ignore */ }
+    // Shallow scan of the repo root for REVIEW-named markdown (mr-review outputs land there).
+    try {
+        for (const entry of readdirSync(repoRoot)) {
+            if (/REVIEW.*\.md$/i.test(entry)) {
+                try {
+                    if (statSync(join(repoRoot, entry)).isFile())
+                        candidates.push(entry);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch { /* ignore */ }
+    // Dedupe by PHYSICAL identity (realpath), not path string — two paths (e.g. a symlinked feature dir)
+    // pointing at ONE file must count as ONE source, else a single review fakes a rake (cross-model QE:
+    // the real load-bearing breach). Keep the first (sorted) relative path per physical file.
+    const seenReal = new Set();
+    const out = [];
+    for (const rel of uniqSorted(candidates)) {
+        let real;
+        try {
+            real = realpathSync(join(repoRoot, rel));
+        }
+        catch {
+            real = join(repoRoot, rel);
+        }
+        if (seenReal.has(real))
+            continue;
+        seenReal.add(real);
+        out.push(rel);
+    }
+    return out;
+}
+/** Analyze the whole repo corpus. Impure wrapper: find artifacts → extract → detect. Never throws. */
+export function analyzeCorpus(repoRoot, thresholds = DEFAULT_RAKE_THRESHOLDS) {
+    const findings = [];
+    for (const rel of findReviewArtifacts(repoRoot)) {
+        try {
+            const md = readFileSync(join(repoRoot, rel), 'utf8');
+            findings.push(...extractFindings(md, rel));
+        }
+        catch { /* skip unreadable artifact */ }
+    }
+    return detectRakes(findings, thresholds);
+}
+//# sourceMappingURL=rake-analyzer.js.map

package/dist/rake-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rake-analyzer.js","sourceRoot":"","sources":["../src/rake-analyzer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-core",
-  "version": "0.3.111",
+  "version": "0.3.113",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",
@@ -33,10 +33,10 @@
     "@dzhechkov/adapter-agents-md": "0.1.1",
     "@dzhechkov/adapter-copilot": "0.1.1",
     "@dzhechkov/adapter-gemini": "0.1.1",
+    "@dzhechkov/adapter-windsurf": "0.1.1",
     "@dzhechkov/core": "0.2.14",
-    "@dzhechkov/adapter-cursor": "0.1.1",
     "@dzhechkov/memory": "0.2.9",
-    "@dzhechkov/adapter-windsurf": "0.1.1"
+    "@dzhechkov/adapter-cursor": "0.1.1"
   },
   "peerDependenciesMeta": {
     "@ruvector/rvf": {

package/src/index.ts

@@ -264,3 +264,5 @@ export type {
 } from './usage.js';
 export * from './safla-delta.js';
 export * from './architecture.js';
+export * from './project-skills.js';
+export * from './rake-analyzer.js';

package/src/project-skills.ts

@@ -0,0 +1,281 @@
+/**
+ * Polymorphic feature-adr (feature polymorphic-feature-adr, ADR-001).
+ *
+ * A COMMITTED per-project manifest (`architecture/project-skills.json`) declares the project-specific
+ * skills feature-adr should fold into its pipeline — so a generic pipeline becomes project-aware WITHOUT
+ * editing pipeline code (the Copilot `Orchestrates:` anti-pattern) and WITHOUT the skill self-declaring
+ * where it attaches (orchestration is the parent's job). Hybrid model: a CLOSED core-role enum with a
+ * fixed role→stage map, plus an open `extra` list. Guidance injection only in this release; `extra-phase`
+ * is accepted but skipped (fail-open, forward-compatible).
+ *
+ * The build/plan/render functions are PURE + deterministic (sorted, no clock/random) so the same manifest
+ * yields byte-identical plans; the load/resolve helpers do the disk I/O with TOP-LEVEL node:fs imports
+ * (harness-core is ESM — a lazy require() is undefined at runtime; the R1 footgun).
+ *
+ * SAFETY PROPERTY (ADR-001 Decision 3, load-bearing): with NO manifest the plan is empty and
+ * `guidanceForStage` returns '' — so `prompt + guidanceForStage(...)` is byte-identical to today. Every
+ * injection that DOES happen is named in the report (no silent injection).
+ */
+
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve, isAbsolute, sep } from 'node:path';
+
+/** The injectable pipeline stages a project skill can target. */
+export type Stage = 'design' | 'code' | 'qe';
+
+/** The CLOSED core-role enum (each has a fixed stage mapping). */
+export type CoreRole = 'product-vision' | 'critic' | 'brand' | 'impl-bar';
+
+export const CORE_ROLES: readonly CoreRole[] = ['product-vision', 'critic', 'brand', 'impl-bar'];
+
+/** Fixed role→stage map (FR-3). product-vision informs design + QE; impl-bar the code; critic the QE; brand the code. */
+export const ROLE_STAGES: Readonly<Record<CoreRole, readonly Stage[]>> = {
+  'product-vision': ['design', 'qe'],
+  'impl-bar': ['code'],
+  'critic': ['qe'],
+  'brand': ['code'],
+};
+
+/** Default doc for the product-vision role when the manifest omits it (the R1 seam). */
+export const PRODUCT_VISION_DEFAULT = 'architecture/vision.md';
+
+export interface ExtraSkill {
+  readonly skill: string;                 // repo-relative path to a doc / SKILL.md
+  readonly phase: Stage;
+  readonly as: 'guidance' | 'extra-phase';
+  readonly position?: 'before' | 'after';  // extra-phase only (deferred)
+}
+
+export interface ProjectSkillManifest {
+  readonly version: number;
+  readonly roles?: Partial<Record<CoreRole, string>>;
+  readonly extra?: readonly ExtraSkill[];
+}
+
+/** A validated manifest + the entries that were dropped (fail-open, NFR-2). */
+export interface ValidatedManifest {
+  readonly manifest: ProjectSkillManifest | null;
+  readonly errors: readonly string[];
+}
+
+/** A source path resolved to its on-disk content, tagged with what it fills. */
+export interface ResolvedItem {
+  readonly source: string;                 // repo-relative path
+  readonly role: CoreRole | 'extra';
+  readonly stages: readonly Stage[];       // stages this item feeds
+  readonly content: string;
+}
+
+/** One concrete guidance injection for one stage. */
+export interface Injection {
+  readonly stage: Stage;
+  readonly source: string;
+  readonly role: CoreRole | 'extra';
+  readonly content: string;
+}
+
+export interface InjectionPlan {
+  readonly injections: readonly Injection[];
+  readonly skipped: readonly { readonly entry: string; readonly reason: string }[];
+}
+
+const byStr = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+const isStage = (s: unknown): s is Stage => s === 'design' || s === 'code' || s === 'qe';
+
+const realOrNull = (p: string): string | null => { try { return realpathSync(p); } catch { return null; } };
+const isContained = (root: string, abs: string): boolean => abs === root || abs.startsWith(root + sep);
+
+/**
+ * Resolve a manifest-declared path to a SAFE absolute path inside repoRoot, or null if it escapes
+ * (absolute path, `../` traversal, or a symlink pointing outside). The manifest is committed, but a
+ * hostile/careless entry must never make the pipeline read `/etc/passwd` (cross-model QE High finding).
+ */
+function safeResolve(repoRoot: string, relPath: string): string | null {
+  if (isAbsolute(relPath)) return null;
+  const abs = resolve(repoRoot, relPath);
+  if (!isContained(repoRoot, abs)) return null;                 // lexical `../` escape
+  if (existsSync(abs)) {                                         // symlink-aware escape (only checkable when it exists)
+    const real = realOrNull(abs);
+    const rootReal = realOrNull(repoRoot) ?? repoRoot;
+    if (real !== null && !isContained(rootReal, real)) return null;
+  }
+  return abs;
+}
+
+/**
+ * Validate a parsed manifest object. FAIL-OPEN (NFR-2): a bad top-level shape → null + errors; a bad
+ * entry (unknown role key, missing fields, bad stage) is DROPPED with a reason, the rest survive. A
+ * config typo must never brick a run.
+ */
+export function validateManifest(raw: unknown): ValidatedManifest {
+  const errors: string[] = [];
+  // An ARRAY is `typeof 'object'` but is NOT a valid manifest — reject it, else `[]` would sanitize to an
+  // empty manifest and silently activate the product-vision default (cross-model QE High finding).
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { manifest: null, errors: ['manifest must be a JSON object'] };
+  }
+  const obj = raw as Record<string, unknown>;
+
+  const roles: Partial<Record<CoreRole, string>> = {};
+  if (obj.roles !== undefined) {
+    if (obj.roles === null || typeof obj.roles !== 'object') {
+      errors.push('roles: not an object — ignored');
+    } else {
+      for (const [key, val] of Object.entries(obj.roles as Record<string, unknown>)) {
+        if (!CORE_ROLES.includes(key as CoreRole)) { errors.push(`roles.${key}: unknown role — skipped`); continue; }
+        if (typeof val !== 'string' || val.trim() === '') { errors.push(`roles.${key}: path must be a non-empty string — skipped`); continue; }
+        roles[key as CoreRole] = val;
+      }
+    }
+  }
+
+  const extra: ExtraSkill[] = [];
+  if (obj.extra !== undefined) {
+    if (!Array.isArray(obj.extra)) {
+      errors.push('extra: not an array — ignored');
+    } else {
+      obj.extra.forEach((e, i) => {
+        if (e === null || typeof e !== 'object') { errors.push(`extra[${i}]: not an object — skipped`); return; }
+        const ent = e as Record<string, unknown>;
+        if (typeof ent.skill !== 'string' || ent.skill.trim() === '') { errors.push(`extra[${i}].skill: missing path — skipped`); return; }
+        if (!isStage(ent.phase)) { errors.push(`extra[${i}].phase: must be design|code|qe — skipped`); return; }
+        if (ent.as !== 'guidance' && ent.as !== 'extra-phase') { errors.push(`extra[${i}].as: must be guidance|extra-phase — skipped`); return; }
+        if (ent.as === 'extra-phase') { errors.push(`extra[${i}] (${String(ent.skill)}): extra-phase is not supported yet (guidance-only release) — skipped`); return; }
+        const item: ExtraSkill = { skill: ent.skill, phase: ent.phase, as: 'guidance' };
+        extra.push(item);
+      });
+    }
+  }
+
+  return { manifest: { version: typeof obj.version === 'number' ? obj.version : 1, roles, extra }, errors };
+}
+
+/**
+ * Resolve each manifest entry to its on-disk content. Impure I/O (top-level fs; never throws). A missing
+ * file is DROPPED with a reason (fail-open). product-vision defaults to `architecture/vision.md` (FR-4)
+ * when the role is unset and the default exists.
+ */
+export function resolveInjections(
+  repoRoot: string,
+  manifest: ProjectSkillManifest,
+): { resolved: ResolvedItem[]; skipped: { entry: string; reason: string }[] } {
+  const resolved: ResolvedItem[] = [];
+  const skipped: { entry: string; reason: string }[] = [];
+
+  // Read a manifest path SAFELY (contained in repoRoot). Returns {content} or a skip reason.
+  const read = (relPath: string): { content: string } | { reason: string } => {
+    const abs = safeResolve(repoRoot, relPath);
+    if (abs === null) return { reason: 'path escapes the repo — rejected' };
+    try {
+      return existsSync(abs) ? { content: readFileSync(abs, 'utf8') } : { reason: 'file not found' };
+    } catch { return { reason: 'unreadable' }; }
+  };
+
+  // Core roles (incl. the product-vision default).
+  for (const role of CORE_ROLES) {
+    const explicit = manifest.roles?.[role];
+    const path = explicit ?? (role === 'product-vision' ? PRODUCT_VISION_DEFAULT : undefined);
+    if (path === undefined) continue;                                   // role not configured, no default
+    const r = read(path);
+    if (!('content' in r)) { skipped.push({ entry: `${role} → ${path}`, reason: r.reason }); continue; }
+    resolved.push({ source: path, role, stages: ROLE_STAGES[role], content: r.content });
+  }
+
+  // Extra guidance entries.
+  for (const e of manifest.extra ?? []) {
+    const r = read(e.skill);
+    if (!('content' in r)) { skipped.push({ entry: `extra → ${e.skill}`, reason: r.reason }); continue; }
+    resolved.push({ source: e.skill, role: 'extra', stages: [e.phase], content: r.content });
+  }
+
+  return { resolved, skipped };
+}
+
+/**
+ * Build the injection plan. PURE + deterministic: one Injection per (item, stage), sorted by
+ * (stage, source). The same resolved set always yields a byte-identical plan (ADR-001 §1).
+ */
+export function buildInjectionPlan(
+  resolved: readonly ResolvedItem[],
+  skipped: readonly { entry: string; reason: string }[] = [],
+): InjectionPlan {
+  const injections: Injection[] = [];
+  for (const item of resolved) {
+    for (const stage of item.stages) {
+      injections.push({ stage, source: item.source, role: item.role, content: item.content });
+    }
+  }
+  injections.sort((a, b) => byStr(a.stage, b.stage) || byStr(a.source, b.source) || byStr(String(a.role), String(b.role)));
+  const skippedSorted = [...skipped].sort((a, b) => byStr(a.entry, b.entry));
+  return { injections, skipped: skippedSorted };
+}
+
+/**
+ * The guidance suffix for one stage — a concat of every injection targeting it, each with a provenance
+ * header. Returns '' when nothing targets the stage, so `prompt + guidanceForStage(...)` is byte-identical
+ * to the bare prompt on a no-manifest run (FR-7, load-bearing).
+ */
+export function guidanceForStage(plan: InjectionPlan, stage: Stage): string {
+  const items = plan.injections.filter((i) => i.stage === stage);
+  if (items.length === 0) return '';
+  const blocks = items.map((i) => {
+    const tag = i.role === 'extra' ? `project skill ${i.source}` : `project ${i.role} (${i.source})`;
+    return `\n\n### Project-specific guidance — ${tag} (apply to this ${stage} step; injected via architecture/project-skills.json):\n${i.content.trim()}`;
+  });
+  return blocks.join('');
+}
+
+/** Human "who injected what" report (FR-6 — no silent injection). Deterministic. */
+export function renderInjectionReport(plan: InjectionPlan): string {
+  if (plan.injections.length === 0 && plan.skipped.length === 0) {
+    return 'project-skills: no manifest / nothing injected (generic run).';
+  }
+  const lines: string[] = ['project-skills injections:'];
+  if (plan.injections.length === 0) lines.push('  (none applied)');
+  for (const i of plan.injections) {
+    const who = i.role === 'extra' ? `extra ${i.source}` : `${i.role} (${i.source})`;
+    lines.push(`  • ${i.stage} ← ${who}`);
+  }
+  if (plan.skipped.length > 0) {
+    lines.push('  skipped:');
+    for (const s of plan.skipped) lines.push(`    ⚠ ${s.entry} — ${s.reason}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Load + validate the project manifest (`architecture/project-skills.json`). Impure; returns null when
+ * absent OR unparseable OR top-level-invalid (fail-open) — a null means "generic run" (FR-7). Entry-level
+ * problems are kept on the returned manifest's implicit skip path (via validateManifest at resolve time).
+ */
+export function loadProjectSkills(repoRoot: string): ProjectSkillManifest | null {
+  try {
+    const p = join(repoRoot, 'architecture', 'project-skills.json');
+    if (!existsSync(p)) return null;
+    const parsed = JSON.parse(readFileSync(p, 'utf8')) as unknown;
+    return validateManifest(parsed).manifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One-shot convenience for the pipeline: load → validate → resolve → plan. Returns an EMPTY plan when
+ * there is no manifest file (FR-7 byte-identical). Validation problems (unknown role / bad entry) AND
+ * missing-file skips both surface in `plan.skipped` so the report hides nothing (FR-6). Impure.
+ */
+export function planProjectSkills(repoRoot: string): InjectionPlan {
+  let parsed: unknown;
+  try {
+    const p = join(repoRoot, 'architecture', 'project-skills.json');
+    if (!existsSync(p)) return { injections: [], skipped: [] };   // no manifest file → generic run
+    parsed = JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    return { injections: [], skipped: [{ entry: 'architecture/project-skills.json', reason: 'unreadable/invalid JSON' }] };
+  }
+  const { manifest, errors } = validateManifest(parsed);
+  const validationSkips = errors.map((reason) => ({ entry: 'manifest', reason }));
+  if (manifest === null) return { injections: [], skipped: validationSkips };
+  const { resolved, skipped } = resolveInjections(repoRoot, manifest);
+  return buildInjectionPlan(resolved, [...skipped, ...validationSkips]);
+}