@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/backlog-adapter.js

@@ -20,6 +20,139 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { normalizeBacklogPriority } from './admission-score.js';
+// ── Code-area extraction ────────────────────────────────────────────
+/**
+ * Extract a code-area string from a list of file/path references.
+ *
+ * Algorithm:
+ *   1. Filter references down to path-like strings (not URLs, not AISDLC-N
+ *      IDs, not RFC-NNNN IDs) — the path-like entries are the ones that
+ *      carry blast-radius signal.
+ *   2. Compute the deepest common path prefix across all filtered paths
+ *      at the directory level (e.g. `pipeline-cli/src/orchestrator/filters/x.ts`
+ *      + `pipeline-cli/src/orchestrator/loop.ts` → `pipeline-cli/src/orchestrator`).
+ *   3. Return the prefix, or `undefined` when there are no path references.
+ *
+ * The caller uses the result to populate `EnrichmentContext.codeArea` so
+ * `buildCodeAreaQuality()` can look up per-area metrics instead of the
+ * uniform Eρ variance of 0.30.
+ *
+ * @param references  Raw reference strings from frontmatter `references:` AND
+ *                    any `## References` body section — callers are responsible
+ *                    for merging both sources before calling here.
+ */
+export function extractCodeAreaFromReferences(references) {
+    // Strip leading/trailing backtick pairs, parentheses, brackets and whitespace
+    // (common in `## References` bullet items like `` `path/to/file.ts` ``).
+    const cleaned = references.map((r) => r
+        .replace(/^[`(['"]*/, '')
+        .replace(/[`)\]'"]*$/, '')
+        .trim());
+    // Keep only path-like references. Exclude:
+    //   - URLs (http://, https://, ...)
+    //   - AISDLC-N IDs
+    //   - RFC-NNNN IDs
+    //   - Plain words with no path separator
+    //   - Empty strings
+    const pathRefs = cleaned.filter((r) => {
+        if (!r)
+            return false;
+        if (/^https?:\/\//i.test(r))
+            return false;
+        if (/^aisdlc-\d+$/i.test(r))
+            return false;
+        if (/^rfc-\d{4}/i.test(r))
+            return false;
+        // Must contain at least one path separator to be treated as a file path.
+        // Also accept paths that look like `dir/file.ext` with an extension.
+        return r.includes('/');
+    });
+    if (pathRefs.length === 0)
+        return undefined;
+    if (pathRefs.length === 1) {
+        return pathPrefix(pathRefs[0]);
+    }
+    // Compute the deepest common directory prefix.
+    const segments = pathRefs.map((r) => pathPrefix(r).split('/'));
+    let common = segments[0];
+    for (let i = 1; i < segments.length; i++) {
+        common = commonPrefix(common, segments[i]);
+    }
+    if (common.length === 0)
+        return undefined;
+    return common.join('/');
+}
+/**
+ * Return the directory portion of a path reference.
+ * `pipeline-cli/src/foo.ts` → `pipeline-cli/src`
+ * `pipeline-cli/src/orchestrator/` → `pipeline-cli/src/orchestrator`
+ * `pipeline-cli/src/orchestrator` → `pipeline-cli/src`  (no trailing slash → treat as file)
+ */
+function pathPrefix(ref) {
+    const stripped = ref.replace(/\/$/, ''); // remove trailing slash
+    const lastSlash = stripped.lastIndexOf('/');
+    // If the last segment looks like a file (has an extension) or the path has a
+    // trailing slash (already a directory reference), take the parent. Otherwise
+    // treat the whole thing as a directory.
+    const lastSegment = lastSlash >= 0 ? stripped.slice(lastSlash + 1) : stripped;
+    if (lastSlash < 0)
+        return stripped; // bare filename with no directory
+    // Has a dot in the last segment AND it's not a hidden dir like `.ai-sdlc` → file
+    if (lastSegment.includes('.') && !lastSegment.startsWith('.')) {
+        return stripped.slice(0, lastSlash);
+    }
+    return stripped; // already a directory path
+}
+/**
+ * Longest common prefix of two string arrays (segment-by-segment).
+ */
+function commonPrefix(a, b) {
+    const result = [];
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] !== b[i])
+            break;
+        result.push(a[i]);
+    }
+    return result;
+}
+/**
+ * Parse file-path references from a `## References` markdown section.
+ *
+ * The body format is a bullet list where each item may be a bare path,
+ * a backtick-quoted path, a description with an inline path, or a mix.
+ * We extract the first backtick-quoted segment or the first slash-
+ * containing word from each bullet.
+ */
+export function parseBodyReferences(body) {
+    // Split the body by `## ` headings (preserving each section in its entirety)
+    // then find the `## References` section specifically. This avoids regex
+    // backtracking issues with greedy vs lazy quantifiers when the body contains
+    // multiple `## ` headings.
+    const sections = body.split(/\n(?=##\s)/);
+    const section = sections.find((s) => /^##\s+References\b/i.test(s));
+    if (!section)
+        return [];
+    const out = [];
+    for (const line of section.split(/\r?\n/)) {
+        // Must be a bullet item.
+        if (!/^\s*-\s/.test(line))
+            continue;
+        const content = line.replace(/^\s*-\s+/, '');
+        // Prefer backtick-quoted path.
+        const btMatch = content.match(/`([^`]+)`/);
+        if (btMatch) {
+            out.push(btMatch[1]);
+            continue;
+        }
+        // Fall back to the first slash-containing token.
+        const tokens = content.split(/\s+/);
+        const pathToken = tokens.find((t) => t.includes('/'));
+        if (pathToken)
+            out.push(pathToken);
+    }
+    return out;
+}
 // ── Parser ──────────────────────────────────────────────────────────
 /**
  * Parse a Backlog.md task markdown file into `BacklogTaskSnapshot`.
@@ -38,6 +171,10 @@ export function parseBacklogTask(content, sourcePath) {
     const dependencies = normaliseStringArray(fm.dependencies);
     const description = extractSection(content, 'Description');
     const acceptanceCriteria = extractAcceptanceCriteria(content);
+    // Strip frontmatter block before parsing body sections (the `---` block
+    // can contain `## References`-like content that would confuse body parsing).
+    const bodyOnly = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+    const bodyReferences = parseBodyReferences(bodyOnly);
     return {
         id,
         numericId,
@@ -51,6 +188,7 @@ export function parseBacklogTask(content, sourcePath) {
         createdBy: fm.created_by ? String(fm.created_by).trim() : undefined,
         acceptanceCriteria,
         references,
+        bodyReferences,
         dependencies,
         sourcePath,
     };
@@ -308,6 +446,12 @@ export function mapBacklogTaskToAdmissionInput(snap, options = {}) {
             status: snap.status,
         },
     };
+    // ── Code-area extraction ─────────────────────────────────────────
+    // Merge frontmatter references + body references and compute the deepest
+    // common path prefix. The result is forwarded to EnrichmentContext.codeArea
+    // so admission scoring can use per-area Eρ variance instead of 0.30.
+    const allReferences = [...snap.references, ...snap.bodyReferences];
+    const codeArea = extractCodeAreaFromReferences(allReferences);
     const priorityInputOverrides = {};
     if (soulAlignment !== 0.5)
         priorityInputOverrides.soulAlignment = soulAlignment;
@@ -329,7 +473,7 @@ export function mapBacklogTaskToAdmissionInput(snap, options = {}) {
         priorityInputOverrides.defectRiskFactor = defectRiskFactor;
     if (qualityFlags.length > 0)
         priorityInputOverrides.qualityFlags = qualityFlags;
-    return { input, priorityInputOverrides, qualityFlags };
+    return { input, priorityInputOverrides, qualityFlags, codeArea };
 }
 function buildAdmissionBody(snap, complexity) {
     const parts = [];

package/dist/calibration.d.ts

@@ -10,6 +10,12 @@
  *
  * Per v1.1 note: this adjusts the multiplicative Cκ term, NOT SA-2
  * directly. Per-dimension calibration lands in PPA v1.1 §17.
+ *
+ * RFC-0009 Phase 2.2 extension: `buildSoulCalibrationMatrix` aggregates
+ * Cκ coefficients per-soul × per-dimension (N×M cells). Feedback events
+ * tagged with a soul slug as their `category` and a SA dimension drive
+ * the matrix cells. Souls × dimensions with insufficient data are omitted
+ * from the matrix (callers fall back to the scalar coefficient or 1.0).
  */
 import type { SaDimension } from './state/types.js';
 import type { SAFeedbackStore } from './sa-scoring/feedback-store.js';
@@ -40,4 +46,79 @@ export interface BuildCategoryCoefficientsInput {
  * scalar fallback applies to them.
  */
 export declare function buildCategoryCoefficients(feedback: SAFeedbackStore, input?: BuildCategoryCoefficientsInput): Record<string, number>;
+/**
+ * Input options for `buildSoulCalibrationMatrix`.
+ */
+export interface BuildSoulCalibrationMatrixInput {
+    /**
+     * Soul slugs to include in the matrix (N axis).
+     * Feedback events whose `category` matches a slug are collected.
+     */
+    souls: readonly string[];
+    /**
+     * SA dimensions to include in the matrix (M axis).
+     * When absent, all SA dimensions are sampled.
+     */
+    dimensions?: readonly SaDimension[];
+    /** Trailing-window filter (ISO timestamp). */
+    since?: string;
+    /**
+     * Minimum feedback event count per (soul, dimension) cell before a
+     * coefficient is emitted. Cells below this threshold are omitted from
+     * the matrix — callers should fall back to 1.0 (neutral) for absent cells.
+     */
+    minSampleSize?: number;
+}
+/**
+ * The N×M Cκ calibration matrix for a tessellated platform.
+ *
+ *   cells[soulSlug][dimension] = calibration coefficient in [0.7, 1.3]
+ *
+ * Cells omitted from the map have insufficient feedback data.
+ * Callers treat absent cells as 1.0 (neutral, no calibration adjustment).
+ */
+export interface SoulCalibrationMatrix {
+    /**
+     * N×M map: `{ soulSlug: { saDimension: coefficient } }`.
+     * Only cells with sufficient data are present.
+     */
+    cells: Record<string, Record<string, number>>;
+    /**
+     * Souls (N axis) included in this matrix — equal to `input.souls`.
+     * Useful for distinguishing "soul has data but coefficient is neutral"
+     * from "soul was not included in the query".
+     */
+    souls: readonly string[];
+    /**
+     * SA dimensions (M axis) sampled — equal to `input.dimensions` when
+     * provided, or all dimensions found in the feedback window.
+     */
+    dimensions: readonly string[];
+}
+/**
+ * Aggregate Cκ calibration coefficients per-soul × per-dimension (N×M cells).
+ *
+ * Feedback events tagged with:
+ *   - `category = <soul-slug>` (identifies which soul the feedback is for)
+ *   - `dimension = <SA-1 | SA-2>` (SA dimension the feedback applies to)
+ *
+ * ...drive the per-cell coefficient using the same formula as
+ * `computeCalibrationCoefficient`.
+ *
+ * Usage in tessellated admission scoring (RFC-0009 §6):
+ *   - Look up `matrix.cells[targetSoul][dimension]` for the effective Cκ
+ *   - Fall back to 1.0 (neutral) when the cell is absent (insufficient data)
+ *   - Cross-soul aggregate: apply `crossSoulScoringRule` over per-soul cells
+ *
+ * @example
+ * ```ts
+ * const matrix = buildSoulCalibrationMatrix(feedback, {
+ *   souls: ['soul-a', 'soul-b', 'soul-c'],
+ *   dimensions: ['SA-1', 'SA-2'],
+ *   minSampleSize: 5,
+ * });
+ * const ckSoulA = matrix.cells['soul-a']?.['SA-1'] ?? 1.0;
+ * ```
+ */
+export declare function buildSoulCalibrationMatrix(feedback: SAFeedbackStore, input: BuildSoulCalibrationMatrixInput): SoulCalibrationMatrix;
 //# sourceMappingURL=calibration.d.ts.map

package/dist/calibration.js

@@ -10,6 +10,12 @@
  *
  * Per v1.1 note: this adjusts the multiplicative Cκ term, NOT SA-2
  * directly. Per-dimension calibration lands in PPA v1.1 §17.
+ *
+ * RFC-0009 Phase 2.2 extension: `buildSoulCalibrationMatrix` aggregates
+ * Cκ coefficients per-soul × per-dimension (N×M cells). Feedback events
+ * tagged with a soul slug as their `category` and a SA dimension drive
+ * the matrix cells. Souls × dimensions with insufficient data are omitted
+ * from the matrix (callers fall back to the scalar coefficient or 1.0).
  */
 export const CALIBRATION_MIN = 0.7;
 export const CALIBRATION_MAX = 1.3;
@@ -73,4 +79,74 @@ export function buildCategoryCoefficients(feedback, input = {}) {
     }
     return result;
 }
+/** All recognized SA dimensions for default matrix columns. */
+const ALL_SA_DIMENSIONS = ['SA-1', 'SA-2'];
+/**
+ * Aggregate Cκ calibration coefficients per-soul × per-dimension (N×M cells).
+ *
+ * Feedback events tagged with:
+ *   - `category = <soul-slug>` (identifies which soul the feedback is for)
+ *   - `dimension = <SA-1 | SA-2>` (SA dimension the feedback applies to)
+ *
+ * ...drive the per-cell coefficient using the same formula as
+ * `computeCalibrationCoefficient`.
+ *
+ * Usage in tessellated admission scoring (RFC-0009 §6):
+ *   - Look up `matrix.cells[targetSoul][dimension]` for the effective Cκ
+ *   - Fall back to 1.0 (neutral) when the cell is absent (insufficient data)
+ *   - Cross-soul aggregate: apply `crossSoulScoringRule` over per-soul cells
+ *
+ * @example
+ * ```ts
+ * const matrix = buildSoulCalibrationMatrix(feedback, {
+ *   souls: ['soul-a', 'soul-b', 'soul-c'],
+ *   dimensions: ['SA-1', 'SA-2'],
+ *   minSampleSize: 5,
+ * });
+ * const ckSoulA = matrix.cells['soul-a']?.['SA-1'] ?? 1.0;
+ * ```
+ */
+export function buildSoulCalibrationMatrix(feedback, input) {
+    const dims = input.dimensions ?? ALL_SA_DIMENSIONS;
+    const cells = {};
+    for (const soul of input.souls) {
+        const soulCells = {};
+        for (const dim of dims) {
+            const window = { dimension: dim, since: input.since };
+            const events = feedback.list(window).filter((e) => e.category === soul);
+            if (events.length === 0)
+                continue;
+            const bucket = {
+                accepts: 0,
+                dismisses: 0,
+                escalates: 0,
+                overrides: 0,
+            };
+            for (const e of events) {
+                switch (e.signal) {
+                    case 'accept':
+                        bucket.accepts++;
+                        break;
+                    case 'dismiss':
+                        bucket.dismisses++;
+                        break;
+                    case 'escalate':
+                        bucket.escalates++;
+                        break;
+                    case 'override':
+                        bucket.overrides = (bucket.overrides ?? 0) + 1;
+                        break;
+                }
+            }
+            const sampleSize = bucket.accepts + bucket.dismisses + bucket.escalates;
+            if (sampleSize < (input.minSampleSize ?? 1))
+                continue;
+            soulCells[dim] = computeCalibrationCoefficient(bucket);
+        }
+        if (Object.keys(soulCells).length > 0) {
+            cells[soul] = soulCells;
+        }
+    }
+    return { cells, souls: input.souls, dimensions: dims };
+}
 //# sourceMappingURL=calibration.js.map

package/dist/cli/commands/git-remote.d.ts

@@ -39,6 +39,31 @@ export interface DetectRemoteOptions {
  * Detect the GitHub-style org/repo from the project's git origin remote.
  * Returns FALLBACK with detected=false when no remote is configured or
  * when the URL cannot be parsed.
+ *
+ * The git invocation is hardened against two failure modes (AISDLC-104):
+ *
+ *  1. **cwd inheritance race under parallel test workers.** Every git
+ *     command uses `git -C <cwd>` so the working dir is pinned at the
+ *     git argv level rather than relying solely on `child_process`
+ *     honouring the `cwd:` spawn option. Both should agree, but `git -C`
+ *     is a git-internal contract independent of any subprocess cwd
+ *     inheritance race that can happen when `process.chdir()` is
+ *     interleaved with subprocess spawn under thread/fork pools.
+ *
+ *  2. **Host-repo origin bleed via parent-directory walk-up.** If `cwd`
+ *     contains an invalid `.git` (e.g. an empty directory left by an
+ *     init test setup) git normally walks UP looking for a real `.git`
+ *     and can resolve to an ancestor repository — i.e. when run from
+ *     inside the ai-sdlc-framework checkout the test would silently see
+ *     the framework's own origin rather than the fallback. We defend by
+ *     calling `git rev-parse --show-toplevel` first and confirming the
+ *     reported toplevel matches `cwd` (after symlink resolution). When
+ *     it doesn't, we treat the directory as not-a-repo and return the
+ *     fallback rather than reporting the ancestor's remote. This was
+ *     preferred over `GIT_CEILING_DIRECTORIES` because the ceiling-list
+ *     semantics only block walking INTO the listed dirs, not up FROM
+ *     them — empirically `GIT_CEILING_DIRECTORIES=<cwd>` did not stop
+ *     git from finding a parent repo.
  */
 export declare function detectGitRemote(opts?: DetectRemoteOptions): RemoteInfo;
 /**

package/dist/cli/commands/git-remote.js

@@ -9,6 +9,7 @@
  * remote is configured (e.g. a brand-new local-only repo).
  */
 import { execSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 const FALLBACK = { org: 'your-org', repo: 'your-repo', detected: false };
 /**
  * Parse a single remote URL into org/repo. Supports:
@@ -50,13 +51,65 @@ export function parseRemoteUrl(url) {
  * Detect the GitHub-style org/repo from the project's git origin remote.
  * Returns FALLBACK with detected=false when no remote is configured or
  * when the URL cannot be parsed.
+ *
+ * The git invocation is hardened against two failure modes (AISDLC-104):
+ *
+ *  1. **cwd inheritance race under parallel test workers.** Every git
+ *     command uses `git -C <cwd>` so the working dir is pinned at the
+ *     git argv level rather than relying solely on `child_process`
+ *     honouring the `cwd:` spawn option. Both should agree, but `git -C`
+ *     is a git-internal contract independent of any subprocess cwd
+ *     inheritance race that can happen when `process.chdir()` is
+ *     interleaved with subprocess spawn under thread/fork pools.
+ *
+ *  2. **Host-repo origin bleed via parent-directory walk-up.** If `cwd`
+ *     contains an invalid `.git` (e.g. an empty directory left by an
+ *     init test setup) git normally walks UP looking for a real `.git`
+ *     and can resolve to an ancestor repository — i.e. when run from
+ *     inside the ai-sdlc-framework checkout the test would silently see
+ *     the framework's own origin rather than the fallback. We defend by
+ *     calling `git rev-parse --show-toplevel` first and confirming the
+ *     reported toplevel matches `cwd` (after symlink resolution). When
+ *     it doesn't, we treat the directory as not-a-repo and return the
+ *     fallback rather than reporting the ancestor's remote. This was
+ *     preferred over `GIT_CEILING_DIRECTORIES` because the ceiling-list
+ *     semantics only block walking INTO the listed dirs, not up FROM
+ *     them — empirically `GIT_CEILING_DIRECTORIES=<cwd>` did not stop
+ *     git from finding a parent repo.
  */
 export function detectGitRemote(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const exec = opts.execImpl ?? defaultExec;
+    // Step 1: confirm cwd is a real git repo whose toplevel IS cwd.
+    // If `git rev-parse --show-toplevel` errors OR returns an ancestor,
+    // treat as not-a-repo and return FALLBACK. This is the host-repo
+    // bleed defense: an empty/invalid `.git/` in cwd causes git to walk
+    // UP to a parent repo, and `--show-toplevel` then reports the parent
+    // — comparing realpaths catches it.
+    let toplevel;
+    try {
+        toplevel = exec(`git -C ${shellQuote(cwd)} rev-parse --show-toplevel`, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return FALLBACK;
+    }
+    if (!sameDir(toplevel, cwd)) {
+        // git resolved to an ancestor repository — host-repo bleed. The
+        // operator is in a directory that isn't itself a real git root, so
+        // we deliberately do NOT report the ancestor's origin; emit
+        // FALLBACK so init prints the explicit "no git origin remote
+        // detected" message and substitutes `your-org`.
+        return FALLBACK;
+    }
+    // Step 2: ask for the origin URL. If unset (no remote configured)
+    // or unparseable, fall back.
     let url;
     try {
-        url = exec('git remote get-url origin', {
+        url = exec(`git -C ${shellQuote(cwd)} remote get-url origin`, {
             cwd,
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
@@ -68,6 +121,32 @@ export function detectGitRemote(opts = {}) {
     const parsed = parseRemoteUrl(url);
     return parsed ?? FALLBACK;
 }
+/**
+ * Compare two filesystem paths after symlink + canonicalization to
+ * decide whether they refer to the same directory. macOS aliases /tmp
+ * to /private/tmp, so a string compare of `cwd` against the toplevel
+ * git reports would otherwise fail spuriously. Falls back to literal
+ * compare when realpath isn't available (deleted dir, permission).
+ */
+function sameDir(a, b) {
+    const norm = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    return norm(a) === norm(b);
+}
+/**
+ * Quote a path for safe single-token interpolation into a shell command.
+ * Wraps in single quotes and escapes any embedded single quotes by
+ * closing the quote, emitting an escaped quote, then reopening.
+ */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
 function defaultExec(cmd, opts) {
     return execSync(cmd, {
         cwd: opts.cwd,