@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/runtime/attestations.js

@@ -0,0 +1,460 @@
+/**
+ * Cryptographic review attestations (AISDLC-74).
+ *
+ * `/ai-sdlc execute` runs three reviewer subagents (code/test/security) locally
+ * before pushing. CI then re-ran the same reviewers via `Post Review Results` —
+ * burning tokens on duplicate work.
+ *
+ * This module provides the primitives `/ai-sdlc execute` and the
+ * `verify-attestation.yml` workflow share to skip CI review when a valid local
+ * attestation exists. The shape is a DSSE envelope (in-toto / SLSA pattern)
+ * carrying a versioned predicate that commits to the commit SHA, diff hash,
+ * policy hash, and reviewer agent file hashes — so CI can reject envelopes
+ * after force-push, after a policy edit, or after a reviewer agent change.
+ *
+ * ## Threat model (in-scope)
+ *
+ *  - Lazy contributor faking attestation         → signature mismatch
+ *  - Copy-pasted attestation from another PR     → subject digest mismatch
+ *  - Replay after diff changed (force-push)      → diffHash mismatch
+ *  - Attestation issued before a policy edit     → policyHash mismatch
+ *  - Stale reviewer-agent attestation            → agentFileHash mismatch
+ *  - Schema drift / forward-compat smuggling     → schemaVersion enforcement
+ *
+ * Out of scope: compromised dev machine, compromised CI runner, collusion.
+ *
+ * ## Why ed25519 + Node's built-in crypto (no Sigstore)
+ *
+ * The keys are project-controlled, committed in `.ai-sdlc/trusted-reviewers.yaml`,
+ * and small (32-byte). Sigstore would add Fulcio + Rekor + transparency log
+ * infrastructure for no benefit at this scale. ed25519 is what `ssh-keygen
+ * -t ed25519` and `git commit -S` already use; Node's `crypto.sign(null, ...)`
+ * supports it natively.
+ */
+import { createHash, generateKeyPairSync, sign, verify } from 'node:crypto';
+/**
+ * The currently-accepted predicate schema versions. CI rejects any envelope
+ * whose `payload.schemaVersion` is not in this allowlist — this is the
+ * forward-compatibility hatch (we add a new version here when we change the
+ * predicate shape, and CI keeps accepting v1 until we explicitly remove it).
+ *
+ * Exported so the `verify-attestation` workflow can `import`/inline it.
+ */
+export const ACCEPTED_SCHEMA_VERSIONS = ['v1'];
+/**
+ * The DSSE PAE payload type for our predicate. DSSE spec mandates a payload
+ * type URI — we use a project-controlled vendor URI rather than the
+ * in-toto Statement format (which would force us to shape the predicate
+ * around `_type` + `subject` at the envelope layer instead of the predicate).
+ */
+export const DSSE_PAYLOAD_TYPE = 'application/vnd.ai-sdlc.attestation+json';
+// ─── Schema validation ────────────────────────────────────────────
+//
+// Defense-in-depth against GITHUB_OUTPUT injection (and any other
+// downstream consumer that interpolates predicate fields into a
+// structured format). Every field that the verifier ever interpolates
+// into a `reason` string MUST be regex-validated to a known-safe
+// charset BEFORE the rest of `verifyAttestation` runs. If validation
+// fails, we return a FIXED reason string that does not embed the bad
+// value — never give the attacker a way to smuggle their payload past
+// us by burying it in our reason text.
+//
+// Mirror of `.ai-sdlc/schemas/attestation.v1.schema.json` — kept in
+// sync by the `validatePredicateShape` test ('schema mirror in sync').
+/** sha1 git commit (40 lowercase hex chars). */
+const SHA1_HEX = /^[0-9a-f]{40}$/;
+/** sha256 hex (64 lowercase hex chars). */
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/** ISO 8601 timestamp — permissive enough for `new Date().toISOString()`. */
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+/** Free-form short identifier — letters, digits, dot, dash, underscore. */
+const SHORT_ID = /^[A-Za-z0-9._-]+$/;
+/**
+ * `harnessNote` is the only field the operator can put long-form text
+ * in. We allow letters/digits/punctuation/whitespace but reject CR/LF
+ * (which is what attackers need to inject newline-key=value pairs).
+ */
+const SAFE_TEXT = /^[^\r\n]*$/;
+/**
+ * Validate a parsed predicate against the v1 schema regex patterns.
+ *
+ * Returns `null` when the predicate is shape-valid; otherwise returns
+ * a static failure reason that does NOT embed any user-controlled
+ * value (just the field path). This is the load-bearing property:
+ * the malicious value never reaches the `reason` string, so it can't
+ * propagate to GITHUB_OUTPUT or commit-status descriptions.
+ */
+export function validatePredicateShape(parsed) {
+    if (parsed === null || typeof parsed !== 'object') {
+        return 'schema validation failed: predicate must be an object';
+    }
+    const p = parsed;
+    // schemaVersion — string from the accepted enum.
+    if (typeof p['schemaVersion'] !== 'string') {
+        return 'schema validation failed: schemaVersion must be a string';
+    }
+    if (!ACCEPTED_SCHEMA_VERSIONS.includes(p['schemaVersion'])) {
+        // Bounded set — safe to surface the version. We also re-check this
+        // in `verifyAttestation` after shape validation so the error
+        // surface is consistent between schema-rejection and allowlist.
+        return 'schema validation failed: schemaVersion not in accepted enum';
+    }
+    // subject.digest.sha1 — 40 hex chars.
+    const subject = p['subject'];
+    if (subject === null || typeof subject !== 'object') {
+        return 'schema validation failed: subject must be an object';
+    }
+    const digest = subject['digest'];
+    if (digest === null || typeof digest !== 'object') {
+        return 'schema validation failed: subject.digest must be an object';
+    }
+    const sha1 = digest['sha1'];
+    if (typeof sha1 !== 'string' || !SHA1_HEX.test(sha1)) {
+        return 'schema validation failed: subject.digest.sha1 does not match pattern';
+    }
+    // diffHash + policyHash — 64 hex chars each.
+    for (const field of ['diffHash', 'policyHash']) {
+        const v = p[field];
+        if (typeof v !== 'string' || !SHA256_HEX.test(v)) {
+            return `schema validation failed: ${field} does not match pattern`;
+        }
+    }
+    // pluginVersion — short ID (no CR/LF, no `=`).
+    const pluginVersion = p['pluginVersion'];
+    if (typeof pluginVersion !== 'string' ||
+        pluginVersion.length === 0 ||
+        !SHORT_ID.test(pluginVersion)) {
+        return 'schema validation failed: pluginVersion does not match pattern';
+    }
+    // iterationCount — positive integer.
+    const iterationCount = p['iterationCount'];
+    if (typeof iterationCount !== 'number' ||
+        !Number.isInteger(iterationCount) ||
+        iterationCount < 1) {
+        return 'schema validation failed: iterationCount must be a positive integer';
+    }
+    // harnessNote — free-form, but no CR/LF (else it can inject
+    // newlines into a downstream key=value writer).
+    const harnessNote = p['harnessNote'];
+    if (typeof harnessNote !== 'string' || !SAFE_TEXT.test(harnessNote)) {
+        return 'schema validation failed: harnessNote contains forbidden characters';
+    }
+    // signedAt — ISO 8601.
+    const signedAt = p['signedAt'];
+    if (typeof signedAt !== 'string' || !ISO_8601.test(signedAt)) {
+        return 'schema validation failed: signedAt does not match ISO 8601 pattern';
+    }
+    // reviewers — array of objects, each with regex-validated fields.
+    const reviewers = p['reviewers'];
+    if (!Array.isArray(reviewers) || reviewers.length === 0) {
+        return 'schema validation failed: reviewers must be a non-empty array';
+    }
+    for (let i = 0; i < reviewers.length; i++) {
+        const r = reviewers[i];
+        if (r === null || typeof r !== 'object') {
+            return 'schema validation failed: reviewer entry must be an object';
+        }
+        const rec = r;
+        const agentId = rec['agentId'];
+        if (typeof agentId !== 'string' || agentId.length === 0 || !SHORT_ID.test(agentId)) {
+            return 'schema validation failed: reviewer agentId does not match pattern';
+        }
+        const agentFileHash = rec['agentFileHash'];
+        if (typeof agentFileHash !== 'string' || !SHA256_HEX.test(agentFileHash)) {
+            return 'schema validation failed: reviewer agentFileHash does not match pattern';
+        }
+        const harness = rec['harness'];
+        if (typeof harness !== 'string' || harness.length === 0 || !SHORT_ID.test(harness)) {
+            return 'schema validation failed: reviewer harness does not match pattern';
+        }
+        if (typeof rec['approved'] !== 'boolean') {
+            return 'schema validation failed: reviewer approved must be a boolean';
+        }
+        const findings = rec['findings'];
+        if (findings === null || typeof findings !== 'object') {
+            return 'schema validation failed: reviewer findings must be an object';
+        }
+        for (const sev of ['critical', 'major', 'minor', 'suggestion']) {
+            const n = findings[sev];
+            if (typeof n !== 'number' || !Number.isInteger(n) || n < 0) {
+                return 'schema validation failed: reviewer findings count must be a non-negative integer';
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The set of reviewer agent IDs the verifier expects to see in every
+ * attestation. Exported so callers (verify-attestation.mjs) can
+ * cross-check that all three reviewers are present + match.
+ *
+ * Frozen to discourage callers from mutating it.
+ */
+export const REQUIRED_REVIEWER_AGENT_IDS = Object.freeze([
+    'code-reviewer',
+    'test-reviewer',
+    'security-reviewer',
+]);
+/**
+ * Compute a sha256 hex digest. Single source of truth for the hashing
+ * algorithm — every predicate field that ends in `Hash` flows through here.
+ */
+export function sha256Hex(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+/** Compute a sha1 hex digest (used for git commit SHAs in the subject). */
+export function sha1Hex(input) {
+    return createHash('sha1').update(input).digest('hex');
+}
+/**
+ * Build the predicate payload from raw inputs. Pure function — no I/O,
+ * no signing. The caller (`/ai-sdlc execute` Step 10) reads files and git
+ * output, then hands them here.
+ */
+export function buildPredicate(inputs) {
+    if (!/^[0-9a-f]{40}$/i.test(inputs.commitSha)) {
+        throw new Error(`buildPredicate: commitSha must be a 40-char hex SHA-1, got ${inputs.commitSha}`);
+    }
+    return {
+        schemaVersion: 'v1',
+        subject: { digest: { sha1: inputs.commitSha.toLowerCase() } },
+        diffHash: sha256Hex(inputs.diff),
+        policyHash: sha256Hex(inputs.policy),
+        reviewers: inputs.reviewers.map((r) => ({
+            agentId: r.agentId,
+            agentFileHash: sha256Hex(r.agentFileContent),
+            harness: r.harness,
+            approved: r.approved,
+            findings: { ...r.findings },
+        })),
+        pluginVersion: inputs.pluginVersion,
+        iterationCount: inputs.iterationCount,
+        harnessNote: inputs.harnessNote,
+        signedAt: inputs.signedAt ?? new Date().toISOString(),
+    };
+}
+/**
+ * DSSE Pre-Authentication Encoding. Per the spec
+ * (https://github.com/secure-systems-lab/dsse/blob/master/protocol.md):
+ *
+ *   PAE(type, body) = "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+ *
+ * Lengths are decimal ASCII byte-counts of the UTF-8 encoding. Signing the
+ * PAE — not the raw payload — is what gives DSSE its domain separation:
+ * a signature over a payload of one `payloadType` cannot be replayed onto
+ * a payload of a different type.
+ */
+export function paeEncode(payloadType, payload) {
+    const typeBuf = Buffer.from(payloadType, 'utf-8');
+    const prefix = Buffer.from(`DSSEv1 ${typeBuf.length} ${payloadType} ${payload.length} `, 'utf-8');
+    return Buffer.concat([prefix, payload]);
+}
+/** Generate a fresh ed25519 keypair as PEM strings (for `/ai-sdlc init-signing-key`). */
+export function generateSigningKeyPair() {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    return {
+        privateKeyPem: privateKey.export({ format: 'pem', type: 'pkcs8' }).toString(),
+        publicKeyPem: publicKey.export({ format: 'pem', type: 'spki' }).toString(),
+    };
+}
+/**
+ * Sign a predicate, producing a DSSE envelope.
+ *
+ * Throws if `predicate.schemaVersion` is not in `ACCEPTED_SCHEMA_VERSIONS` —
+ * we don't want to issue an envelope that we'd reject ourselves.
+ */
+export function signAttestation(opts) {
+    if (!ACCEPTED_SCHEMA_VERSIONS.includes(opts.predicate.schemaVersion)) {
+        throw new Error(`signAttestation: schemaVersion '${opts.predicate.schemaVersion}' is not in the accepted allowlist [${ACCEPTED_SCHEMA_VERSIONS.join(', ')}]`);
+    }
+    const payloadJson = Buffer.from(JSON.stringify(opts.predicate), 'utf-8');
+    const pae = paeEncode(DSSE_PAYLOAD_TYPE, payloadJson);
+    const signature = sign(null, pae, opts.privateKeyPem);
+    return {
+        payloadType: DSSE_PAYLOAD_TYPE,
+        payload: payloadJson.toString('base64'),
+        signatures: [
+            {
+                keyid: opts.keyid,
+                sig: signature.toString('base64'),
+            },
+        ],
+    };
+}
+/**
+ * Verify a DSSE envelope. Returns a discriminated union — `{ valid: true }`
+ * with the parsed predicate + matched trusted reviewer, or `{ valid: false }`
+ * with a single human-readable reason string.
+ *
+ * The reason string is what gets posted to the commit status
+ * (`ai-sdlc/attestation: invalid (<reason>)`), so keep it short and specific.
+ */
+export function verifyAttestation(opts) {
+    const allowlist = opts.acceptedSchemaVersions ?? ACCEPTED_SCHEMA_VERSIONS;
+    // ── Parse the envelope ────────────────────────────────────────
+    if (opts.envelope.payloadType !== DSSE_PAYLOAD_TYPE) {
+        return {
+            valid: false,
+            reason: `payloadType mismatch: expected ${DSSE_PAYLOAD_TYPE}, got ${opts.envelope.payloadType}`,
+        };
+    }
+    if (!Array.isArray(opts.envelope.signatures) || opts.envelope.signatures.length === 0) {
+        return { valid: false, reason: 'envelope has no signatures' };
+    }
+    // Node's `Buffer.from(s, 'base64')` does NOT throw on invalid input —
+    // it silently drops non-base64 chars. We round-trip through .toString
+    // ('base64') below as part of the JSON-parse step; PAE re-encoding then
+    // catches any tampering at signature-verify time.
+    if (typeof opts.envelope.payload !== 'string' || opts.envelope.payload.length === 0) {
+        return { valid: false, reason: 'envelope payload is empty or non-string' };
+    }
+    const payloadJson = Buffer.from(opts.envelope.payload, 'base64');
+    let parsed;
+    try {
+        parsed = JSON.parse(payloadJson.toString('utf-8'));
+    }
+    catch {
+        return { valid: false, reason: 'payload is not valid JSON' };
+    }
+    // ── Schema validation (REGEX-BOUND) ───────────────────────────
+    // This MUST run before any predicate field is interpolated into a
+    // reason string. The shape validator returns a fixed (non-interpolated)
+    // reason on failure so a malicious value cannot smuggle CR/LF or
+    // `=` into our output. See validatePredicateShape for rationale.
+    const shapeError = validatePredicateShape(parsed);
+    if (shapeError !== null) {
+        return { valid: false, reason: shapeError };
+    }
+    const predicate = parsed;
+    // ── Schema version allowlist (post-shape) ─────────────────────
+    // Belt-and-braces: the shape validator already enforced membership in
+    // ACCEPTED_SCHEMA_VERSIONS, but callers can override the allowlist via
+    // opts.acceptedSchemaVersions for forward-compat tests, so re-check here.
+    if (!allowlist.includes(predicate.schemaVersion)) {
+        return {
+            valid: false,
+            reason: `schemaVersion '${predicate.schemaVersion}' not in allowlist [${allowlist.join(', ')}]`,
+        };
+    }
+    // ── Signature (any-of-N pubkeys) ──────────────────────────────
+    const pae = paeEncode(DSSE_PAYLOAD_TYPE, payloadJson);
+    let matchedReviewer = null;
+    for (const sig of opts.envelope.signatures) {
+        let sigBytes;
+        try {
+            sigBytes = Buffer.from(sig.sig, 'base64');
+        }
+        catch {
+            continue;
+        }
+        for (const reviewer of opts.trustedReviewers) {
+            try {
+                if (verify(null, pae, reviewer.pubkey, sigBytes)) {
+                    matchedReviewer = reviewer;
+                    break;
+                }
+            }
+            catch {
+                // Bad pubkey PEM — skip, try next.
+            }
+        }
+        if (matchedReviewer)
+            break;
+    }
+    if (!matchedReviewer) {
+        return {
+            valid: false,
+            reason: 'signature did not match any trusted reviewer pubkey',
+        };
+    }
+    // ── Bind to PR state ──────────────────────────────────────────
+    // Note: every field interpolated into a reason below has already been
+    // regex-bounded by validatePredicateShape (sha1/sha256 hex, SHORT_ID
+    // for agentId), so embedding them in reason strings cannot inject
+    // CR/LF or `=` into downstream key=value writers.
+    const expectedSha = opts.expected.commitSha.toLowerCase();
+    if (predicate.subject.digest.sha1.toLowerCase() !== expectedSha) {
+        return {
+            valid: false,
+            reason: `subject digest mismatch (envelope was signed for a different commit)`,
+        };
+    }
+    if (predicate.diffHash !== opts.expected.diffHash) {
+        return { valid: false, reason: 'diffHash mismatch (PR diff changed since attestation)' };
+    }
+    if (predicate.policyHash !== opts.expected.policyHash) {
+        return {
+            valid: false,
+            reason: 'policyHash mismatch (.ai-sdlc/review-policy.md changed since attestation)',
+        };
+    }
+    for (const r of predicate.reviewers) {
+        const expectedHash = opts.expected.expectedAgentFileHashes[r.agentId];
+        if (expectedHash && expectedHash !== r.agentFileHash) {
+            return {
+                valid: false,
+                reason: `agentFileHash mismatch for reviewer '${r.agentId}' (agent file changed since attestation)`,
+            };
+        }
+    }
+    // ── Reviewer-set completeness ────────────────────────────────
+    // Every attestation MUST cover all three required reviewers (code,
+    // test, security). Without this, a contributor could ship an
+    // attestation containing only `code-reviewer` and bypass the test
+    // and security review entirely.
+    const present = new Set(predicate.reviewers.map((r) => r.agentId));
+    for (const required of REQUIRED_REVIEWER_AGENT_IDS) {
+        if (!present.has(required)) {
+            return {
+                valid: false,
+                reason: `reviewer set incomplete: missing required reviewer '${required}'`,
+            };
+        }
+    }
+    return { valid: true, predicate, trustedReviewer: matchedReviewer };
+}
+/**
+ * Validate the shape of a parsed `.ai-sdlc/trusted-reviewers.yaml` document.
+ * Throws on malformed input with a specific reason. Acceptance criterion #4.
+ *
+ * Accepts the parsed YAML (as `unknown`) and returns the typed array.
+ */
+export function validateTrustedReviewers(parsed) {
+    if (parsed === null || parsed === undefined)
+        return [];
+    if (typeof parsed !== 'object') {
+        throw new Error('trusted-reviewers.yaml: root must be an object with a `reviewers` list');
+    }
+    const root = parsed;
+    const list = root['reviewers'];
+    if (list === undefined || list === null)
+        return [];
+    if (!Array.isArray(list)) {
+        throw new Error('trusted-reviewers.yaml: `reviewers` must be a list');
+    }
+    const out = [];
+    for (let i = 0; i < list.length; i++) {
+        const entry = list[i];
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`trusted-reviewers.yaml: reviewers[${i}] must be an object`);
+        }
+        const r = entry;
+        for (const field of ['identity', 'machine', 'pubkey', 'addedAt', 'addedBy']) {
+            if (typeof r[field] !== 'string' || r[field].length === 0) {
+                throw new Error(`trusted-reviewers.yaml: reviewers[${i}].${field} must be a non-empty string`);
+            }
+        }
+        if (!r['pubkey'].includes('BEGIN PUBLIC KEY')) {
+            throw new Error(`trusted-reviewers.yaml: reviewers[${i}].pubkey must be a PEM-encoded public key`);
+        }
+        out.push({
+            identity: r['identity'],
+            machine: r['machine'],
+            pubkey: r['pubkey'],
+            addedAt: r['addedAt'],
+            addedBy: r['addedBy'],
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=attestations.js.map

package/dist/runtime/git-env.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Helpers for safely invoking `git` subprocesses inside isolated working
+ * directories.
+ *
+ * ## Why this exists (AISDLC-68 → AISDLC-72)
+ *
+ * When a husky pre-push hook (or any nested git invocation) runs commands
+ * from inside `.worktrees/<id>/`, git exports `GIT_DIR`, `GIT_WORK_TREE`,
+ * and `GIT_INDEX_FILE` into the child process environment so subprocesses
+ * "stay" in the calling worktree's git context. That's the right behavior
+ * for normal subprocesses — but it's catastrophic for code that creates
+ * its own throwaway repository in a temp directory.
+ *
+ * Without sanitizing the environment:
+ *   - `execSync('git init', { cwd: tmpDir })` initializes the *parent*
+ *     worktree's index, not tmpDir's.
+ *   - `execSync('git commit', { cwd: tmpDir })` writes a commit onto the
+ *     *parent's* current branch using files from tmpDir — silently
+ *     corrupting the feature branch with leaked test artifacts.
+ *   - The pre-push hook that triggered this whole cascade then sees
+ *     unexpected commits and either fails or worse, ships them.
+ *
+ * The fix is uniform: strip `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE`
+ * from the inherited env at every site that runs `git` against an explicit
+ * `cwd`. PR #78 patched the tokens-studio adapter; AISDLC-72 sweeps the
+ * orchestrator + remaining test sites.
+ */
+/**
+ * Return a copy of `process.env` with the git-context env vars removed.
+ *
+ * Use this for any subprocess that runs `git` against an explicit `cwd`
+ * different from the calling process's CWD (temp repos, sibling repos,
+ * worktree-pool clones).
+ */
+export declare function cleanGitEnv(): NodeJS.ProcessEnv;
+/**
+ * Promisified `execFile('git', args, opts)` wrapper that strips the git
+ * context env vars before invocation. Use whenever the caller passes
+ * `cwd` (i.e. running git in a directory other than the parent process's
+ * CWD).
+ *
+ * Caller-supplied `opts.env` takes precedence — it's already explicit
+ * about what to inherit. We only inject `cleanGitEnv()` when no env was
+ * provided.
+ */
+export declare function gitExecFile(args: string[], opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+//# sourceMappingURL=git-env.d.ts.map

package/dist/runtime/git-env.js

@@ -0,0 +1,60 @@
+/**
+ * Helpers for safely invoking `git` subprocesses inside isolated working
+ * directories.
+ *
+ * ## Why this exists (AISDLC-68 → AISDLC-72)
+ *
+ * When a husky pre-push hook (or any nested git invocation) runs commands
+ * from inside `.worktrees/<id>/`, git exports `GIT_DIR`, `GIT_WORK_TREE`,
+ * and `GIT_INDEX_FILE` into the child process environment so subprocesses
+ * "stay" in the calling worktree's git context. That's the right behavior
+ * for normal subprocesses — but it's catastrophic for code that creates
+ * its own throwaway repository in a temp directory.
+ *
+ * Without sanitizing the environment:
+ *   - `execSync('git init', { cwd: tmpDir })` initializes the *parent*
+ *     worktree's index, not tmpDir's.
+ *   - `execSync('git commit', { cwd: tmpDir })` writes a commit onto the
+ *     *parent's* current branch using files from tmpDir — silently
+ *     corrupting the feature branch with leaked test artifacts.
+ *   - The pre-push hook that triggered this whole cascade then sees
+ *     unexpected commits and either fails or worse, ships them.
+ *
+ * The fix is uniform: strip `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE`
+ * from the inherited env at every site that runs `git` against an explicit
+ * `cwd`. PR #78 patched the tokens-studio adapter; AISDLC-72 sweeps the
+ * orchestrator + remaining test sites.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Return a copy of `process.env` with the git-context env vars removed.
+ *
+ * Use this for any subprocess that runs `git` against an explicit `cwd`
+ * different from the calling process's CWD (temp repos, sibling repos,
+ * worktree-pool clones).
+ */
+export function cleanGitEnv() {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    return env;
+}
+/**
+ * Promisified `execFile('git', args, opts)` wrapper that strips the git
+ * context env vars before invocation. Use whenever the caller passes
+ * `cwd` (i.e. running git in a directory other than the parent process's
+ * CWD).
+ *
+ * Caller-supplied `opts.env` takes precedence — it's already explicit
+ * about what to inherit. We only inject `cleanGitEnv()` when no env was
+ * provided.
+ */
+export async function gitExecFile(args, opts = {}) {
+    const env = opts.env ?? cleanGitEnv();
+    const { stdout, stderr } = await execFileAsync('git', args, { ...opts, env });
+    return { stdout, stderr };
+}
+//# sourceMappingURL=git-env.js.map

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+export { deterministicPort, allocatePort, allocateContiguousPorts, isPortFree, PortAllocationError, DEFAULT_BASE_PORT, PORT_RANGE_OFFSET_MIN, PORT_RANGE_OFFSET_MAX, type AllocatePortOptions, type AllocateContiguousOptions, } from './port-allocator.js';
+export { slugifyBranch, worktreePath, verifyOwnership, assertOwnership, isExistingWorktree, WorktreeOwnershipError, type OwnershipResult, } from './worktree.js';
+export { WorktreePoolManager, WorktreePoolError, DEFAULT_POOL_ROOT, DEFAULT_STALE_THRESHOLD_DAYS, type WorktreePoolSpec, type WorktreePoolManagerDeps, type AllocateOptions, type WorktreeHandle, } from './worktree-pool.js';
+export { readParallelismMode, isParallelismEnabled, FLAG_NAME as PARALLELISM_FLAG, type ParallelismMode, } from './parallelism-flag.js';
+export { cleanGitEnv, gitExecFile } from './git-env.js';
+export { ACCEPTED_SCHEMA_VERSIONS, DSSE_PAYLOAD_TYPE, buildPredicate, generateSigningKeyPair, paeEncode, sha1Hex, sha256Hex, signAttestation, validateTrustedReviewers, verifyAttestation, type AttestationPredicate, type DsseEnvelope, type DsseSignature, type ReviewerEntry, type SchemaVersion, type SubjectDigest, type TrustedReviewer, type VerifyResult, } from './attestations.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -0,0 +1,7 @@
+export { deterministicPort, allocatePort, allocateContiguousPorts, isPortFree, PortAllocationError, DEFAULT_BASE_PORT, PORT_RANGE_OFFSET_MIN, PORT_RANGE_OFFSET_MAX, } from './port-allocator.js';
+export { slugifyBranch, worktreePath, verifyOwnership, assertOwnership, isExistingWorktree, WorktreeOwnershipError, } from './worktree.js';
+export { WorktreePoolManager, WorktreePoolError, DEFAULT_POOL_ROOT, DEFAULT_STALE_THRESHOLD_DAYS, } from './worktree-pool.js';
+export { readParallelismMode, isParallelismEnabled, FLAG_NAME as PARALLELISM_FLAG, } from './parallelism-flag.js';
+export { cleanGitEnv, gitExecFile } from './git-env.js';
+export { ACCEPTED_SCHEMA_VERSIONS, DSSE_PAYLOAD_TYPE, buildPredicate, generateSigningKeyPair, paeEncode, sha1Hex, sha256Hex, signAttestation, validateTrustedReviewers, verifyAttestation, } from './attestations.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/parallelism-flag.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Feature-flag gate for RFC-0010 parallelism. While Phases 1-4 land, the worker-pool
+ * conversion in execute.ts is gated behind AI_SDLC_PARALLELISM=experimental. Phase 5
+ * (hardening) flips the default to on after a soak window.
+ */
+export declare const FLAG_NAME = "AI_SDLC_PARALLELISM";
+export type ParallelismMode = 'off' | 'experimental' | 'on';
+export declare function readParallelismMode(env?: NodeJS.ProcessEnv): ParallelismMode;
+export declare function isParallelismEnabled(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=parallelism-flag.d.ts.map

package/dist/runtime/parallelism-flag.js

@@ -0,0 +1,18 @@
+/**
+ * Feature-flag gate for RFC-0010 parallelism. While Phases 1-4 land, the worker-pool
+ * conversion in execute.ts is gated behind AI_SDLC_PARALLELISM=experimental. Phase 5
+ * (hardening) flips the default to on after a soak window.
+ */
+export const FLAG_NAME = 'AI_SDLC_PARALLELISM';
+export function readParallelismMode(env = process.env) {
+    const raw = env[FLAG_NAME]?.trim().toLowerCase();
+    if (raw === 'experimental')
+        return 'experimental';
+    if (raw === 'on' || raw === 'true' || raw === '1')
+        return 'on';
+    return 'off';
+}
+export function isParallelismEnabled(env) {
+    return readParallelismMode(env) !== 'off';
+}
+//# sourceMappingURL=parallelism-flag.js.map

package/dist/runtime/port-allocator.d.ts

@@ -0,0 +1,21 @@
+export declare const DEFAULT_BASE_PORT = 3190;
+export declare const PORT_RANGE_OFFSET_MIN = 100;
+export declare const PORT_RANGE_OFFSET_MAX = 999;
+export interface AllocatePortOptions {
+    basePort?: number;
+    envOverride?: string | undefined;
+    isPortFree?: (port: number) => Promise<boolean>;
+}
+export interface AllocateContiguousOptions extends AllocatePortOptions {
+    count: number;
+}
+export declare class PortAllocationError extends Error {
+    readonly worktreePath: string;
+    readonly attemptedPorts: number[];
+    constructor(message: string, worktreePath: string, attemptedPorts: number[]);
+}
+export declare function deterministicPort(worktreePath: string, basePort?: number): number;
+export declare function allocatePort(worktreePath: string, options?: AllocatePortOptions): Promise<number>;
+export declare function allocateContiguousPorts(worktreePath: string, options: AllocateContiguousOptions): Promise<number[]>;
+export declare function isPortFree(port: number): Promise<boolean>;
+//# sourceMappingURL=port-allocator.d.ts.map