@ai-sdlc/orchestrator 0.14.0 → 0.16.0

package/dist/cli/commands/init-features.d.ts

@@ -298,6 +298,47 @@ export interface FeatureAdapters {
     appendOnce: (path: string, contents: string, sentinel: string) => 'appended' | 'skipped';
     /** mkdir -p. Production = `node:fs.mkdirSync({ recursive: true })`. */
     mkdirp: (path: string) => void;
+    /**
+     * Read a text file, or `null` if it doesn't exist / can't be read.
+     * Production = `node:fs.readFileSync`. AISDLC-555: used to detect whether
+     * a project declares `husky` in package.json before deciding where to
+     * install the attestation-sign pre-push hook.
+     */
+    readTextFile: (path: string) => string | null;
+    /**
+     * chmod the file executable (0o755). Production =
+     * `node:fs.chmodSync(path, 0o755)`. AISDLC-555: a freshly WRITTEN
+     * `.husky/pre-push` or `.git/hooks/pre-push` must be executable or git
+     * silently never runs it — the AC #2 "working hook" requirement.
+     */
+    chmodExecutable: (path: string) => void;
+    /**
+     * Resolve `path` through symlinks, or `null` when it does not exist.
+     * Production = `node:fs.realpathSync`.
+     *
+     * AISDLC-555: `outsideProject` is decided with `path.relative`, which is
+     * purely LEXICAL — a repo that commits `.husky` (or `.husky/pre-push`) as a
+     * symlink pointing out of the tree still looks inside it, so neither the
+     * machine-wide refusal nor any string check fires, while `writeFileSync` and
+     * `chmodSync` happily follow the link. Resolving the real path is the only
+     * way to tell those apart.
+     */
+    realpath: (path: string) => string | null;
+    /**
+     * True when `path` itself is a symlink (does NOT follow it). Production =
+     * `node:fs.lstatSync(path).isSymbolicLink()`, `false` when `path` does not
+     * exist or `lstat` throws for any other reason.
+     *
+     * AISDLC-555 follow-up (dangling-symlink escape): `realpath` alone cannot
+     * distinguish "not a symlink" from "a symlink whose final component does
+     * not exist yet" — `realpathSync` throws ENOENT for the latter too, so the
+     * caller's `realpath(hookPath) ?? realpath(dirname(hookPath))` fallback
+     * silently resolves to the (real, in-project) parent directory and
+     * containment passes even though `hookPath` is a symlink pointing
+     * anywhere. `isSymlink` lets the caller ask the orthogonal question
+     * directly and refuse when a symlink's target can't be resolved at all.
+     */
+    isSymlink: (path: string) => boolean;
     /** Test for path existence. Production = `node:fs.existsSync`. */
     exists: (path: string) => boolean;
     /** Run a shell command (used for `gh api`). Production = `execSync`. */
@@ -411,6 +452,50 @@ export declare function buildProductionAdapters(): FeatureAdapters;
  * exactly the union of features marked true.
  */
 export declare function resolveFeatureSelection(flags: WizardFlags, adapters: Pick<FeatureAdapters, 'prompt' | 'log'>): Promise<FeatureSelection>;
+/** Resolved target for the attestation-sign pre-push hook. */
+export interface HookTarget {
+    /** Absolute path to the hook file. */
+    path: string;
+    /** Path relative to `projectDir`, for logging/result tracking. */
+    relPath: string;
+    /** True when the target is `.husky/pre-push`; false for `.git/hooks/pre-push`. */
+    isHusky: boolean;
+    /**
+     * True when the resolved hook lives OUTSIDE `projectDir` — e.g. a global
+     * `core.hooksPath = ~/.githooks`, which is shared by every repository on the
+     * machine. Callers warn before writing there: silently appending to a
+     * machine-wide hook is not something an adopter running `init` on one repo
+     * would expect.
+     */
+    outsideProject: boolean;
+    /**
+     * How the target was decided. Load-bearing, not cosmetic: `core.hooksPath`
+     * resolving outside the project usually means a GLOBAL or SYSTEM git setting
+     * shared by every repository on the machine, which is refused; a
+     * `git-hooks-dir` outside the project is a linked worktree's or submodule's
+     * common dir, which is still this one repository and is fine.
+     */
+    source: 'core.hooksPath' | 'git-hooks-dir' | 'husky-default';
+}
+/**
+ * Decide whether the attestation-sign hook belongs at `.husky/pre-push` or
+ * `.git/hooks/pre-push` (AISDLC-555 AC #4 — "handle repos that do not use
+ * husky at all... decided explicitly, not left undefined").
+ *
+ * Signal: read `package.json` at the project root and look for a `husky`
+ * entry in `dependencies` or `devDependencies`.
+ *
+ *   - package.json parses AND does NOT declare `husky`  → `.git/hooks/pre-push`
+ *     (git's native hook path — always executed regardless of husky
+ *     configuration; writing `.husky/pre-push` here would be silently inert
+ *     since nothing ever points `core.hooksPath` at `.husky/`).
+ *   - Every other case (package.json missing, unreadable, malformed, or DOES
+ *     declare husky) → `.husky/pre-push` (the historical default — fails
+ *     open to the common case: most repos running `ai-sdlc init
+ *     --with-attestation` are JS/TS projects that already use, or will
+ *     shortly `npm install` and pick up, husky).
+ */
+export declare function resolveHookTarget(projectDir: string, adapters: FeatureAdapters): HookTarget;
 /** Return value of `applyFeatureSelection` — what was actually written. */
 export interface ApplyResult {
     /** Files that were newly created on this run. */

package/dist/cli/commands/init-features.js

@@ -19,8 +19,8 @@
  * up a TTY or shelling out to `gh`. Production callers in `init.ts` pass
  * the real adapters.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, dirname, basename } from 'node:path';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
+import { join, dirname, basename, isAbsolute, relative } from 'node:path';
 import { execFileSync, execSync } from 'node:child_process';
 import { BASELINE_DERIVED_GATES } from '../../compliance/types.js';
 import { ATTESTATION_TEMPLATES, BASELINE_WORKFLOW_TEMPLATES, CLASSIFIER_TEMPLATES, DOR_TEMPLATES, HUSKY_PREPUSH_SIGN_SNIPPET, SIGNAL_INGESTION_TEMPLATES, WORKFLOWS_TEMPLATES, } from './init-templates.js';
@@ -609,6 +609,45 @@ export function buildProductionAdapters() {
         },
         mkdirp: (path) => mkdirSync(path, { recursive: true }),
         exists: (path) => existsSync(path),
+        readTextFile: (path) => {
+            try {
+                return existsSync(path) ? readFileSync(path, 'utf-8') : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        chmodExecutable: (path) => {
+            try {
+                // AISDLC-555 round-1 security review: do NOT force 0o755. That widens
+                // an adopter's deliberately-restrictive mode (0600 → world-readable
+                // and world-executable) on a file that sits in their repo. Add only
+                // the exec bits and preserve everything else they chose.
+                const current = statSync(path).mode & 0o777;
+                chmodSync(path, current | 0o111);
+            }
+            catch {
+                // Best-effort — a chmod failure (e.g. read-only filesystem) should
+                // not abort the whole wizard run; the operator sees the created
+                // file either way and can chmod it themselves if needed.
+            }
+        },
+        realpath: (path) => {
+            try {
+                return realpathSync(path);
+            }
+            catch {
+                return null; // does not exist (or is unreadable) — caller decides.
+            }
+        },
+        isSymlink: (path) => {
+            try {
+                return lstatSync(path).isSymbolicLink();
+            }
+            catch {
+                return false; // does not exist / unreadable — not a symlink to us.
+            }
+        },
         runCommand: (cmd, args) => {
             try {
                 // Use `execFileSync` (no shell) so args are passed as a true
@@ -744,6 +783,161 @@ export async function resolveFeatureSelection(flags, adapters) {
     }
     return sel;
 }
+/**
+ * Decide whether the attestation-sign hook belongs at `.husky/pre-push` or
+ * `.git/hooks/pre-push` (AISDLC-555 AC #4 — "handle repos that do not use
+ * husky at all... decided explicitly, not left undefined").
+ *
+ * Signal: read `package.json` at the project root and look for a `husky`
+ * entry in `dependencies` or `devDependencies`.
+ *
+ *   - package.json parses AND does NOT declare `husky`  → `.git/hooks/pre-push`
+ *     (git's native hook path — always executed regardless of husky
+ *     configuration; writing `.husky/pre-push` here would be silently inert
+ *     since nothing ever points `core.hooksPath` at `.husky/`).
+ *   - Every other case (package.json missing, unreadable, malformed, or DOES
+ *     declare husky) → `.husky/pre-push` (the historical default — fails
+ *     open to the common case: most repos running `ai-sdlc init
+ *     --with-attestation` are JS/TS projects that already use, or will
+ *     shortly `npm install` and pick up, husky).
+ */
+export function resolveHookTarget(projectDir, adapters) {
+    // AISDLC-555 rounds 1-2: ASK git where hooks live rather than guessing.
+    // `rev-parse --git-path hooks` is the only answer that is right in all the
+    // shapes that bit earlier rounds of this task:
+    //
+    //   - it honours `core.hooksPath`, which git consults BEFORE `.git/hooks`
+    //     (lefthook, a global `~/.githooks`, husky v9);
+    //   - it expands a `~`-prefixed value the way git itself does — `isAbsolute`
+    //     says false for `~/.githooks` and `join` would have produced a literal
+    //     `<projectDir>/~/.githooks/pre-push`;
+    //   - it resolves the COMMON dir for linked worktrees and submodules, where
+    //     `.git` is a FILE and `join(dir, '.git/hooks')` fails with ENOTDIR.
+    //
+    // The pre-round-1 docblock claimed `.git/hooks/pre-push` is "always executed
+    // regardless of husky configuration". That is simply false, and believing it
+    // is how this task's own fix shipped a silently-inert hook twice.
+    //
+    // Two git calls, because they answer different questions and conflating them
+    // is itself a bug: `rev-parse --git-path hooks` always returns SOMETHING
+    // (defaulting to `.git/hooks`), so it cannot distinguish "explicitly
+    // configured" from "not configured". A repo that declares husky but has not
+    // run `husky install` yet reports `.git/hooks` — installing there works right
+    // up until husky sets core.hooksPath and git stops reading `.git/hooks` at
+    // all. So: `config --get` decides WHETHER it is set, `rev-parse` RESOLVES it.
+    const configured = adapters.runCommand('git', [
+        '-C',
+        projectDir,
+        'config',
+        '--get',
+        'core.hooksPath',
+    ]);
+    const configuredValue = configured.exitCode === 0 ? configured.stdout.trim() : '';
+    const hooksPathIsSet = configuredValue !== '';
+    if (configured.exitCode === 0 && configuredValue === '') {
+        // `core.hooksPath = ""` — git reports success with an empty value. Treating
+        // it as configured would resolve nowhere; treating it as unset silently is
+        // how an inert hook gets installed. Say so.
+        adapters.log(`  NOTE core.hooksPath is set to an empty value — treating it as unset.` +
+            ` If hooks are not running, unset it explicitly: git config --unset core.hooksPath`);
+    }
+    const probe = adapters.runCommand('git', ['-C', projectDir, 'rev-parse', '--git-path', 'hooks']);
+    const gitHooks = probe.exitCode === 0 ? probe.stdout.trim() : '';
+    if (hooksPathIsSet && gitHooks) {
+        let base = isAbsolute(gitHooks) ? gitHooks : join(projectDir, gitHooks);
+        // husky v9 sets `core.hooksPath = .husky/_` — its own generated internals,
+        // whose `.gitignore` is literally `*`, regenerated by every `husky` run
+        // (i.e. every `npm install`, via the `prepare` script). A hook installed
+        // there works exactly until the next install and then vanishes with no
+        // signal — the precise failure this task exists to eliminate, aimed at the
+        // most common adopter topology.
+        //
+        // The v9 wrapper (`.husky/_/h`) runs `$(dirname $(dirname $0))/<hookname>`
+        // and exits 0 when it is absent, so the durable, adopter-owned target is
+        // the PARENT directory. Verified against husky 9 by executing a real
+        // `git push`, not by reading the wrapper.
+        //
+        // `husky <dir>` supports a custom directory (`core.hooksPath =
+        // .config/husky/_`), and on a fresh clone the `_` internals may not exist
+        // on disk yet — `_/.gitignore` is `*`, so nothing under it is committed.
+        // Neither the `.husky` parent name nor the wrapper files would match, so
+        // also accept "the project declares husky" as evidence of the layout.
+        const looksLikeHuskyInternals = basename(base) === '_' &&
+            (basename(dirname(base)) === '.husky' ||
+                adapters.exists(join(base, 'h')) ||
+                adapters.exists(join(base, 'husky.sh')) ||
+                projectDeclaresHusky(projectDir, adapters, false));
+        if (looksLikeHuskyInternals) {
+            base = dirname(base);
+        }
+        const rel = relative(projectDir, base);
+        const outsideProject = rel.startsWith('..') || isAbsolute(rel);
+        return {
+            path: join(base, 'pre-push'),
+            // Outside the project there is no meaningful relative path to show, so
+            // log the absolute one — an adopter needs to see that it is machine-wide.
+            relPath: outsideProject ? join(base, 'pre-push') : join(rel, 'pre-push'),
+            isHusky: base.includes('husky'),
+            outsideProject,
+            // Distinguished from the common-dir case below because the remedies and
+            // the risks are completely different: a configured hooks path outside the
+            // project is very likely a GLOBAL or SYSTEM setting shared by every repo
+            // on the machine, whereas a common dir is still this one repository.
+            source: 'core.hooksPath',
+        };
+    }
+    const isHusky = projectDeclaresHusky(projectDir, adapters, true);
+    if (isHusky) {
+        // husky is declared but has not configured core.hooksPath yet (no
+        // `husky install` run). `.husky/pre-push` is where husky will look once
+        // it does, and it is the adopter-owned, committed location either way.
+        return {
+            path: join(projectDir, '.husky', 'pre-push'),
+            relPath: '.husky/pre-push',
+            isHusky: true,
+            outsideProject: false,
+            source: 'husky-default',
+        };
+    }
+    // No husky, no core.hooksPath: git's own hooks dir. Prefer the path git
+    // reports over hand-building `<dir>/.git/hooks` — in a linked worktree or
+    // submodule `.git` is a FILE, so the hand-built path fails with ENOTDIR and
+    // aborts init, and the real hooks live in the common dir anyway.
+    const base = gitHooks
+        ? isAbsolute(gitHooks)
+            ? gitHooks
+            : join(projectDir, gitHooks)
+        : join(projectDir, '.git', 'hooks');
+    const rel = relative(projectDir, base);
+    const outsideProject = rel.startsWith('..') || isAbsolute(rel);
+    return {
+        path: join(base, 'pre-push'),
+        relPath: outsideProject ? join(base, 'pre-push') : join(rel, 'pre-push'),
+        isHusky: false,
+        outsideProject,
+        source: 'git-hooks-dir',
+    };
+}
+/**
+ * True when the project declares `husky` as a (dev)dependency.
+ *
+ * Fails OPEN (returns true) when package.json is missing or malformed: the
+ * pre-AISDLC-555 default was `.husky/pre-push`, and an adopter-owned committed
+ * file is a safer place to be wrong than git's internal hooks directory.
+ */
+function projectDeclaresHusky(projectDir, adapters, whenUnknown) {
+    const pkgRaw = adapters.readTextFile(join(projectDir, 'package.json'));
+    if (pkgRaw === null)
+        return whenUnknown;
+    try {
+        const pkg = JSON.parse(pkgRaw);
+        const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+        return 'husky' in deps;
+    }
+    catch {
+        return whenUnknown;
+    }
+}
 /**
  * Write the union of feature templates into the project dir. AC #4 says
  * the BASELINE workflow templates (gate workflow) are always written; the
@@ -819,34 +1013,247 @@ export async function applyFeatureSelection(projectDir, selection, flags, adapte
             }
         }
     }
-    // Husky pre-push sign hook is a separate concern from the
-    // FeatureTemplateSet because it's an APPEND (not a write-from-empty)
-    // — adopters often already have a .husky/pre-push from their existing
-    // tooling and we don't want to clobber it. Only fired when attestation
-    // is on.
+    // Pre-push sign hook is a separate concern from the FeatureTemplateSet
+    // because it's an APPEND (not a write-from-empty) — adopters often
+    // already have a pre-push hook from their existing tooling and we don't
+    // want to clobber it. Only fired when attestation is on.
+    //
+    // AISDLC-555 AC #4: decide the hook TARGET explicitly rather than always
+    // assuming husky. `resolveHookTarget` inspects package.json for a
+    // declared `husky` dependency; when the repo positively does NOT declare
+    // husky, the hook is written straight to `.git/hooks/pre-push` — git's
+    // own native hook path, which git always executes regardless of husky
+    // configuration (writing `.husky/pre-push` into a repo that never wires
+    // `core.hooksPath` there would be silently inert). Every other case
+    // (package.json missing/unreadable, or husky declared) keeps the
+    // pre-AISDLC-555 default of `.husky/pre-push`.
     if (selection.attestation && !flags.dryRun) {
-        const hookPath = join(projectDir, '.husky', 'pre-push');
-        if (!adapters.exists(hookPath)) {
+        const { path: hookPath, relPath: hookRelPath, isHusky: hookIsHusky, outsideProject: hookOutsideProject, source: hookSource, } = resolveHookTarget(projectDir, adapters);
+        // Set when the target is refused; every other feature still applies, only
+        // the hook install is skipped.
+        let refuseHookInstall = false;
+        // Say where the hook landed and why. Round-2 review: the resolution is now
+        // non-obvious (git-reported hooks dir, with a husky-internals step-up), so
+        // an adopter debugging "why did nothing sign?" needs the decision visible.
+        adapters.log(`  hook target ${hookRelPath} (${hookIsHusky ? 'husky' : 'git hooks dir'})`);
+        // Round-3 security review (medium): `git config --get core.hooksPath` reads
+        // ALL scopes, so a GLOBAL or SYSTEM value — `~/.githooks`, an org-mandated
+        // `/etc/team-hooks` — makes this fire for a repo whose own config never
+        // opted in. Appending there puts the key-bearing signer on EVERY push in
+        // EVERY repo on the machine, including untrusted clones, where it would
+        // read that repo's `.active-task` and verdicts and invoke the signer with
+        // the operator's Ed25519 key. A per-repo `init` must not silently become a
+        // machine-wide execution surface, and a warning is not a consent gate when
+        // `init --yes` runs non-interactively. So: refuse, and make the opt-in
+        // explicit and auditable.
+        //
+        // Deliberately scoped to `core.hooksPath`. A linked worktree or submodule
+        // also resolves outside the project (git's common dir), but that is still
+        // this one repository — refusing there would break a legitimate topology.
+        if (hookOutsideProject && hookSource === 'core.hooksPath') {
+            if (process.env.AI_SDLC_ALLOW_GLOBAL_HOOKS === '1') {
+                adapters.log(`  WARNING installing into ${hookRelPath}, which is OUTSIDE this project.` +
+                    ` core.hooksPath is set globally, so the sign block will run on every` +
+                    ` push in every repository on this machine.` +
+                    ` Proceeding because AI_SDLC_ALLOW_GLOBAL_HOOKS=1.`);
+            }
+            else {
+                adapters.log(`  REFUSED to install the attestation hook: core.hooksPath resolves to` +
+                    ` ${hookRelPath}, OUTSIDE this project — almost certainly a global or` +
+                    ` system git setting shared by every repository on this machine.`);
+                adapters.log(`    Installing there would run the attestation signer, with your signing` +
+                    ` key, on every push in every repo — including ones you do not control.`);
+                adapters.log(`    Fix by scoping the hooks path to this repo:` +
+                    ` git -C . config core.hooksPath .husky` +
+                    ` — then re-run. To install machine-wide anyway (rarely what you want):` +
+                    ` AI_SDLC_ALLOW_GLOBAL_HOOKS=1 ai-sdlc init --with-attestation`);
+                result.skipped.push(hookRelPath);
+                refuseHookInstall = true;
+            }
+        }
+        else if (hookOutsideProject) {
+            // Worktree / submodule common dir: real, but a different situation with a
+            // different remedy. Round-3 review flagged the previous shared wording as
+            // factually wrong here — it named core.hooksPath, which is not set.
+            adapters.log(`  NOTE ${hookRelPath} is outside this working tree — it is this` +
+                ` repository's shared git hooks directory (linked worktree or submodule),` +
+                ` so the sign block also applies to sibling worktrees of the same repo.`);
+        }
+        // Symlink containment. Only meaningful when we BELIEVE the target is
+        // inside the project: the worktree-common-dir and explicit
+        // AI_SDLC_ALLOW_GLOBAL_HOOKS cases are knowingly outside and already
+        // handled above. Here the lexical check said "inside", so if the real path
+        // says otherwise, something in the repo is redirecting us — refuse rather
+        // than append a shell snippet to, and set the exec bit on, a file outside
+        // the tree (`~/.bashrc` being the obvious target).
+        if (!refuseHookInstall && !hookOutsideProject) {
+            const realProject = adapters.realpath(projectDir);
+            const hookDir = dirname(hookPath);
+            // Permissive when `realProject` itself can't be resolved (mirrors the
+            // pre-existing fallback's `realProject !== null` gate): we can only
+            // flag a candidate as "definitely outside" when we actually know what
+            // "inside" means. A NULL `real` here always means "dangling" and is
+            // handled as its own, unconditional refusal below — this helper is
+            // only ever called with a non-null resolved path.
+            const isDefinitelyOutside = (real) => {
+                if (realProject === null)
+                    return false;
+                const rel = relative(realProject, real);
+                return rel.startsWith('..') || isAbsolute(rel);
+            };
+            // Check `hookPath` and its parent directory (`.husky` itself may be the
+            // symlink) EXPLICITLY for symlink-ness, rather than only resolving the
+            // "deepest existing component" as a fallback. A DANGLING final-component
+            // symlink — `.husky/pre-push` (or `.husky` itself) pointing at a path
+            // that does not exist YET — makes `realpath(hookPath)` throw ENOENT just
+            // like "not a symlink at all" does, so falling straight to
+            // `realpath(dirname(hookPath))` silently resolves to the real,
+            // in-project parent and containment passes even though the final
+            // component redirects somewhere unknown. `isSymlink` lets us ask "is
+            // this a symlink" independently of whether it currently resolves, so a
+            // dangling link is refused UNCONDITIONALLY — a symlink we cannot
+            // resolve at all is never treated as "probably fine".
+            const candidates = [
+                { path: hookPath, relPath: hookRelPath },
+                { path: hookDir, relPath: relative(projectDir, hookDir) || '.' },
+            ];
+            for (const { path: candidatePath, relPath: candidateRelPath } of candidates) {
+                if (refuseHookInstall)
+                    break;
+                if (!adapters.isSymlink(candidatePath))
+                    continue;
+                const realCandidate = adapters.realpath(candidatePath);
+                if (realCandidate === null) {
+                    adapters.log(`  REFUSED to install the attestation hook: ${candidateRelPath} is a symlink` +
+                        ` whose target does not exist (a "dangling" symlink). Refusing rather than` +
+                        ` following it — writing through a dangling symlink would create a new file` +
+                        ` (with the exec bit set) at whatever path the link names, anywhere on disk.` +
+                        ` Remove the symlink and re-run.`);
+                }
+                else if (isDefinitelyOutside(realCandidate)) {
+                    adapters.log(`  REFUSED to install the attestation hook: ${candidateRelPath} resolves to` +
+                        ` ${realCandidate}, outside this project. A symlink in the repository is` +
+                        ` redirecting the hook path.`);
+                    adapters.log(`    Refusing rather than appending a shell snippet to a file outside the` +
+                        ` project and marking it executable. Remove the symlink and re-run.`);
+                }
+                else {
+                    continue; // resolves, and stays inside the project — fine.
+                }
+                result.skipped.push(hookRelPath);
+                refuseHookInstall = true;
+            }
+            // Fallback for the case where neither `hookPath` nor its immediate
+            // parent is itself a symlink, but some other already-existing component
+            // resolves outside the project (e.g. a symlink further up the tree).
+            // Resolve the deepest existing component and check containment.
+            if (!refuseHookInstall) {
+                const realTarget = adapters.realpath(hookPath) ?? adapters.realpath(hookDir) ?? null;
+                if (realTarget !== null && isDefinitelyOutside(realTarget)) {
+                    adapters.log(`  REFUSED to install the attestation hook: ${hookRelPath} resolves to` +
+                        ` ${realTarget}, outside this project. A symlink in the repository is` +
+                        ` redirecting the hook path.`);
+                    adapters.log(`    Refusing rather than appending a shell snippet to a file outside the` +
+                        ` project and marking it executable. Remove the symlink and re-run.`);
+                    result.skipped.push(hookRelPath);
+                    refuseHookInstall = true;
+                }
+            }
+        }
+        if (refuseHookInstall) {
+            // Refused above — nothing further to do for the hook.
+        }
+        else if (!adapters.exists(hookPath)) {
             // No existing hook — write a minimal one with the sign block.
-            adapters.mkdirp(dirname(hookPath));
-            adapters.writeFile(hookPath, `#!/usr/bin/env bash\nset -euo pipefail\n\n${HUSKY_PREPUSH_SIGN_SNIPPET}`);
-            result.created.push('.husky/pre-push');
-            adapters.log(`  created .husky/pre-push`);
+            //
+            // Defense-in-depth: the symlink-containment check above should already
+            // have refused a dangling `.husky` (or `.husky/pre-push`) symlink before
+            // we get here, but `mkdirp` on a path whose parent is a dangling symlink
+            // throws EEXIST (the symlink itself exists; what it points at does not).
+            // Wrap the create sequence so a gap in that check — or a TOCTOU race
+            // where the symlink appears between the check and this write — aborts
+            // only the hook install, not the entire wizard with an unhandled
+            // exception.
+            try {
+                adapters.mkdirp(dirname(hookPath));
+                // POSIX `sh`, not bash: husky v9 runs hooks via its `_/pre-push`
+                // wrapper with `sh -e "$hook"`, IGNORING the shebang. On adopters
+                // whose `/bin/sh` is dash (Debian/Ubuntu/CI default), `set -o pipefail`
+                // is not a valid option, so a bash-style `set -euo pipefail` preamble
+                // aborts the hook on line 2 — before the sign block runs — and the
+                // attestation is silently never signed (AISDLC-565). The snippet body
+                // is pure POSIX and never pipes, so `set -eu` under `sh` is correct in
+                // both dash and bash. For the `.git/hooks/pre-push` path git honours
+                // the shebang directly, and `sh` works there too.
+                adapters.writeFile(hookPath, `#!/usr/bin/env sh\nset -eu\n\n${HUSKY_PREPUSH_SIGN_SNIPPET}`);
+                adapters.chmodExecutable(hookPath);
+                result.created.push(hookRelPath);
+                adapters.log(`  created ${hookRelPath}`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                adapters.log(`  REFUSED to install the attestation hook: could not create ${hookRelPath}` +
+                    ` (${message}). This usually means a path component (e.g. \`.husky\`) is a` +
+                    ` symlink pointing at a target that does not exist. Remove it and re-run.`);
+                result.skipped.push(hookRelPath);
+            }
         }
         else {
+            // AISDLC-555 round-1 security review: appending lands at EOF, so an
+            // existing hook that ends in a top-level `exit 0` — an extremely common
+            // shape — makes our block permanently unreachable while init happily
+            // reports "appended sign block". Warn rather than silently succeed;
+            // rewriting someone else's hook is not ours to do.
+            const existing = adapters.readTextFile(hookPath) ?? '';
+            if (!existing.includes('# ai-sdlc:attestation-sign-block')) {
+                const hasTopLevelExit = existing
+                    .split('\n')
+                    // Best-effort: covers `exit 0`, indented, `;`-terminated, commented,
+                    // and CRLF (`\s` eats the trailing `\r`). Deliberately does NOT try
+                    // to parse shell — `exit $rc`, `exec other-hook` and same-line
+                    // `if ...; then exit 0; fi` are known misses. A missed warning is a
+                    // worse hook than it could be; a false one would train adopters to
+                    // ignore it.
+                    .some((line) => /^\s*exit\s+0\s*;?\s*(#.*)?$/.test(line));
+                if (hasTopLevelExit) {
+                    adapters.log(`  WARNING ${hookRelPath} contains a top-level \`exit 0\` — the appended` +
+                        ` sign block will never be reached. Move the block above that line,` +
+                        ` or the attestation will silently never be signed.`);
+                }
+            }
             const status = adapters.appendOnce(hookPath, HUSKY_PREPUSH_SIGN_SNIPPET, '# ai-sdlc:attestation-sign-block');
+            // AC #2 requires a WORKING hook: even when the hook file pre-existed
+            // (append path), make sure it's executable — an adopter's hand-authored
+            // pre-push script may not have had the bit set, and git silently
+            // never runs a non-executable hook.
+            adapters.chmodExecutable(hookPath);
             if (status === 'appended') {
-                adapters.log(`  updated .husky/pre-push (appended sign block)`);
+                adapters.log(`  updated ${hookRelPath} (appended sign block)`);
             }
             else {
-                result.skipped.push('.husky/pre-push');
-                adapters.log(`  skip .husky/pre-push (sign block already present)`);
+                result.skipped.push(hookRelPath);
+                adapters.log(`  skip ${hookRelPath} (sign block already present)`);
             }
         }
     }
     else if (selection.attestation && flags.dryRun) {
-        result.wouldCreate.push('.husky/pre-push');
-        adapters.log('  would update .husky/pre-push (sign block)');
+        const { relPath: hookRelPath, outsideProject: hookOutsideProject, source: hookSource, } = resolveHookTarget(projectDir, adapters);
+        // Round-4 review (security + code, independently): the preview must mirror
+        // the refusal. Reporting "would update <machine-wide path>" for a run that
+        // will actually refuse is exactly backwards — the point of refusing is to
+        // make this decision legible before anything happens.
+        if (hookOutsideProject &&
+            hookSource === 'core.hooksPath' &&
+            process.env.AI_SDLC_ALLOW_GLOBAL_HOOKS !== '1') {
+            result.skipped.push(hookRelPath);
+            adapters.log(`  would REFUSE the attestation hook: core.hooksPath resolves to` +
+                ` ${hookRelPath}, OUTSIDE this project (set AI_SDLC_ALLOW_GLOBAL_HOOKS=1` +
+                ` to install machine-wide anyway).`);
+        }
+        else {
+            result.wouldCreate.push(hookRelPath);
+            adapters.log(`  would update ${hookRelPath} (sign block)`);
+        }
     }
     // Branch protection (always last — depends on the gate workflow being
     // present so the required check exists when the rule is applied).

package/dist/cli/commands/init-templates.d.ts

@@ -42,16 +42,56 @@ export declare const AI_SDLC_GATE_WORKFLOW = "name: AI-SDLC PR Ready Gate\n\n# S
  */
 export declare const VERIFY_ATTESTATION_WORKFLOW = "name: AI-SDLC Verify Review Attestation\n\n# Reads the DSSE attestation at .ai-sdlc/attestations/<head-sha>.dsse.json\n# and verifies the signature against any-of-N pubkeys in\n# .ai-sdlc/trusted-reviewers.yaml.\n#\n# AUDIT-ONLY: this workflow logs verification results (success/failure with\n# reason) for forensic purposes but does NOT post a required commit status.\n# The single merge gate is `ai-sdlc/pr-ready` from ai-sdlc-gate.yml.\n\non:\n  pull_request:\n    types: [opened, synchronize, reopened]\n    branches: [main]\n    paths-ignore:\n      - 'docs/**'\n      - '*.md'\n  merge_group:\n    types: [checks_requested]\n\nconcurrency:\n  group: verify-attestation-${{ github.event.pull_request.number || github.event.merge_group.head_sha }}\n  cancel-in-progress: true\n\njobs:\n  verify:\n    name: Verify attestation\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n    steps:\n      - name: Resolve subject SHA + base SHA from event payload\n        id: resolve\n        run: |\n          if [ \"${{ github.event_name }}\" = \"merge_group\" ]; then\n            echo \"head_sha=${{ github.event.merge_group.head_sha }}\" >> \"$GITHUB_OUTPUT\"\n            echo \"base_sha=${{ github.event.merge_group.base_sha }}\" >> \"$GITHUB_OUTPUT\"\n          else\n            echo \"head_sha=${{ github.event.pull_request.head.sha }}\" >> \"$GITHUB_OUTPUT\"\n            echo \"base_sha=${{ github.event.pull_request.base.sha }}\" >> \"$GITHUB_OUTPUT\"\n          fi\n\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n          ref: ${{ steps.resolve.outputs.head_sha }}\n\n      - name: Log audit result\n        env:\n          HEAD_SHA: ${{ steps.resolve.outputs.head_sha }}\n        run: |\n          if [ -f \".ai-sdlc/attestations/${HEAD_SHA}.dsse.json\" ]; then\n            echo \"::notice::ai-sdlc attestation AUDIT \u2014 envelope present at ${HEAD_SHA}\"\n          else\n            echo \"::notice::ai-sdlc attestation AUDIT \u2014 no envelope on ${HEAD_SHA} (audit-only, not blocking)\"\n          fi\n";
 /**
- * `.husky/pre-push` snippet that signs an attestation when one is missing
- * for the current HEAD. Installed when `--with-attestation` is opted in;
- * the actual `sign-attestation.mjs` script ships separately with the
- * orchestrator and is referenced by the canonical command stub here.
+ * `.husky/pre-push` (or `.git/hooks/pre-push` for non-husky repos) snippet
+ * that signs an attestation when one is missing for the current HEAD.
+ * Installed when `--with-attestation` is opted in.
+ *
+ * AISDLC-555: pre-fix, this snippet checked ONLY `./scripts/check-attestation-
+ * sign.sh` — a path that exists in the ai-sdlc monorepo (where the hook is
+ * hand-authored, not wizard-generated) but NEVER in an adopter repo, because
+ * nothing ever copied that script there. The `[ -x ... ]` guard silently
+ * failed forever, so `--with-attestation` produced a hook that looked
+ * complete but never signed anything — the exact bug this task exists to
+ * fix. `check-attestation-sign.sh` now also ships under
+ * `ai-sdlc-plugin/scripts/` (AISDLC-555), so this snippet resolves it from
+ * the PLUGIN INSTALL ONLY: `$CLAUDE_PLUGIN_ROOT` / `$CLAUDE_PLUGIN_DIR` (the
+ * zero-config path when `git push` runs inside a Claude Code session), then a
+ * read-only plugin-cache probe (bare-terminal `git push`, which never inherits
+ * those env vars).
+ *
+ * There is deliberately NO repo-local tier — see item 2 below. An earlier
+ * revision of this docblock described one, which contradicted the code and,
+ * worse, advertised a resolution order that was removed for security.
+ *
+ * Review round 1 (AISDLC-555) — TWO deliberate changes here, both correcting
+ * the first version of this fix:
+ *
+ * 1. **It is no longer silent when nothing resolves.** The original ended in a
+ *    bare `if [ -n "$HOOK" ]; then bash ...; fi` with no else, so an adopter
+ *    who installed via `npm i -g @ai-sdlc/orchestrator` (the documented
+ *    getting-started path) and never installed the Claude Code plugin got a
+ *    hook that could never fire and never said so — reproducing the exact
+ *    defect this task exists to close, for a whole adopter persona.
+ *    `ai-sdlc-plugin/` is not published to npm and orchestrator's `files` is
+ *    `["dist"]`, so none of the tiers can resolve in that setup.
+ *
+ *    Silence is still correct when there is nothing to sign, so the diagnostic
+ *    fires only when `.ai-sdlc/verdicts/` is non-empty: reviewers ran, an
+ *    envelope is owed, and none will be produced. That is the state an
+ *    operator must never discover months later.
+ *
+ * 2. **The repo-relative tier was removed.** It previously preferred
+ *    `./scripts/check-attestation-sign.sh` from the working tree, which put
+ *    repo-tracked content on the push-time execution path with the operator's
+ *    Ed25519 signing key in scope — a contributor could land that file and
+ *    have it run as the maintainer on their next push. Resolution is now only
+ *    from the plugin install (env vars, then the read-only cache probe).
  *
  * Adopters typically already have a `.husky/pre-push` from their existing
  * tooling; the wizard appends our snippet behind a sentinel so we can
  * extend an existing hook without trampling user content.
  */
-export declare const HUSKY_PREPUSH_SIGN_SNIPPET = "# ai-sdlc:attestation-sign-block\n# Signs the DSSE attestation envelope for the current HEAD when verdict\n# files exist. Skip with AI_SDLC_SKIP_ATTESTATION_SIGN=1.\nif [ -z \"${AI_SDLC_SKIP_ATTESTATION_SIGN:-}\" ] && [ -x \"./scripts/check-attestation-sign.sh\" ]; then\n  ./scripts/check-attestation-sign.sh\nfi\n# end ai-sdlc:attestation-sign-block\n";
+export declare const HUSKY_PREPUSH_SIGN_SNIPPET = "# ai-sdlc:attestation-sign-block\n# Signs the DSSE attestation envelope for the current HEAD when verdict\n# files exist. Skip with AI_SDLC_SKIP_ATTESTATION_SIGN=1.\nif [ -z \"${AI_SDLC_SKIP_ATTESTATION_SIGN:-}\" ]; then\n  AI_SDLC_ATTESTATION_HOOK=\"\"\n  if [ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && [ -f \"${CLAUDE_PLUGIN_ROOT}/scripts/check-attestation-sign.sh\" ]; then\n    AI_SDLC_ATTESTATION_HOOK=\"${CLAUDE_PLUGIN_ROOT}/scripts/check-attestation-sign.sh\"\n  elif [ -n \"${CLAUDE_PLUGIN_DIR:-}\" ] && [ -f \"${CLAUDE_PLUGIN_DIR}/scripts/check-attestation-sign.sh\" ]; then\n    AI_SDLC_ATTESTATION_HOOK=\"${CLAUDE_PLUGIN_DIR}/scripts/check-attestation-sign.sh\"\n  else\n    for _ai_sdlc_dir in \"$HOME\"/.claude/plugins/cache/*/ai-sdlc/*/; do\n      if [ -f \"${_ai_sdlc_dir}scripts/check-attestation-sign.sh\" ]; then\n        AI_SDLC_ATTESTATION_HOOK=\"${_ai_sdlc_dir}scripts/check-attestation-sign.sh\"\n        break\n      fi\n    done\n  fi\n  if [ -n \"$AI_SDLC_ATTESTATION_HOOK\" ]; then\n    echo \"[ai-sdlc] attestation signer: $AI_SDLC_ATTESTATION_HOOK\" >&2\n    bash \"$AI_SDLC_ATTESTATION_HOOK\"\n  elif [ -n \"$(ls -A .ai-sdlc/verdicts 2>/dev/null)\" ]; then\n    echo \"[ai-sdlc] ERROR: reviewer verdicts exist under .ai-sdlc/verdicts/ but NO attestation signer\" >&2\n    echo \"[ai-sdlc]   could be found \u2014 this push will carry no attestation.\" >&2\n    echo \"[ai-sdlc]   Searched CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DIR, and\" >&2\n    echo \"[ai-sdlc]   ~/.claude/plugins/cache/*/ai-sdlc/*/scripts/check-attestation-sign.sh\" >&2\n    echo \"[ai-sdlc]   Install the ai-sdlc Claude Code plugin, or set CLAUDE_PLUGIN_ROOT.\" >&2\n  fi\nfi\n# end ai-sdlc:attestation-sign-block\n";
 /**
  * `.ai-sdlc/trusted-reviewers.yaml` stub — empty allowlist with operator
  * instructions. The wizard scaffolds this so adopters have a single file

package/dist/cli/commands/init-templates.js

@@ -207,10 +207,50 @@ jobs:
           fi
 `;
 /**
- * `.husky/pre-push` snippet that signs an attestation when one is missing
- * for the current HEAD. Installed when `--with-attestation` is opted in;
- * the actual `sign-attestation.mjs` script ships separately with the
- * orchestrator and is referenced by the canonical command stub here.
+ * `.husky/pre-push` (or `.git/hooks/pre-push` for non-husky repos) snippet
+ * that signs an attestation when one is missing for the current HEAD.
+ * Installed when `--with-attestation` is opted in.
+ *
+ * AISDLC-555: pre-fix, this snippet checked ONLY `./scripts/check-attestation-
+ * sign.sh` — a path that exists in the ai-sdlc monorepo (where the hook is
+ * hand-authored, not wizard-generated) but NEVER in an adopter repo, because
+ * nothing ever copied that script there. The `[ -x ... ]` guard silently
+ * failed forever, so `--with-attestation` produced a hook that looked
+ * complete but never signed anything — the exact bug this task exists to
+ * fix. `check-attestation-sign.sh` now also ships under
+ * `ai-sdlc-plugin/scripts/` (AISDLC-555), so this snippet resolves it from
+ * the PLUGIN INSTALL ONLY: `$CLAUDE_PLUGIN_ROOT` / `$CLAUDE_PLUGIN_DIR` (the
+ * zero-config path when `git push` runs inside a Claude Code session), then a
+ * read-only plugin-cache probe (bare-terminal `git push`, which never inherits
+ * those env vars).
+ *
+ * There is deliberately NO repo-local tier — see item 2 below. An earlier
+ * revision of this docblock described one, which contradicted the code and,
+ * worse, advertised a resolution order that was removed for security.
+ *
+ * Review round 1 (AISDLC-555) — TWO deliberate changes here, both correcting
+ * the first version of this fix:
+ *
+ * 1. **It is no longer silent when nothing resolves.** The original ended in a
+ *    bare `if [ -n "$HOOK" ]; then bash ...; fi` with no else, so an adopter
+ *    who installed via `npm i -g @ai-sdlc/orchestrator` (the documented
+ *    getting-started path) and never installed the Claude Code plugin got a
+ *    hook that could never fire and never said so — reproducing the exact
+ *    defect this task exists to close, for a whole adopter persona.
+ *    `ai-sdlc-plugin/` is not published to npm and orchestrator's `files` is
+ *    `["dist"]`, so none of the tiers can resolve in that setup.
+ *
+ *    Silence is still correct when there is nothing to sign, so the diagnostic
+ *    fires only when `.ai-sdlc/verdicts/` is non-empty: reviewers ran, an
+ *    envelope is owed, and none will be produced. That is the state an
+ *    operator must never discover months later.
+ *
+ * 2. **The repo-relative tier was removed.** It previously preferred
+ *    `./scripts/check-attestation-sign.sh` from the working tree, which put
+ *    repo-tracked content on the push-time execution path with the operator's
+ *    Ed25519 signing key in scope — a contributor could land that file and
+ *    have it run as the maintainer on their next push. Resolution is now only
+ *    from the plugin install (env vars, then the read-only cache probe).
  *
  * Adopters typically already have a `.husky/pre-push` from their existing
  * tooling; the wizard appends our snippet behind a sentinel so we can
@@ -219,8 +259,30 @@ jobs:
 export const HUSKY_PREPUSH_SIGN_SNIPPET = `# ai-sdlc:attestation-sign-block
 # Signs the DSSE attestation envelope for the current HEAD when verdict
 # files exist. Skip with AI_SDLC_SKIP_ATTESTATION_SIGN=1.
-if [ -z "\${AI_SDLC_SKIP_ATTESTATION_SIGN:-}" ] && [ -x "./scripts/check-attestation-sign.sh" ]; then
-  ./scripts/check-attestation-sign.sh
+if [ -z "\${AI_SDLC_SKIP_ATTESTATION_SIGN:-}" ]; then
+  AI_SDLC_ATTESTATION_HOOK=""
+  if [ -n "\${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "\${CLAUDE_PLUGIN_ROOT}/scripts/check-attestation-sign.sh" ]; then
+    AI_SDLC_ATTESTATION_HOOK="\${CLAUDE_PLUGIN_ROOT}/scripts/check-attestation-sign.sh"
+  elif [ -n "\${CLAUDE_PLUGIN_DIR:-}" ] && [ -f "\${CLAUDE_PLUGIN_DIR}/scripts/check-attestation-sign.sh" ]; then
+    AI_SDLC_ATTESTATION_HOOK="\${CLAUDE_PLUGIN_DIR}/scripts/check-attestation-sign.sh"
+  else
+    for _ai_sdlc_dir in "$HOME"/.claude/plugins/cache/*/ai-sdlc/*/; do
+      if [ -f "\${_ai_sdlc_dir}scripts/check-attestation-sign.sh" ]; then
+        AI_SDLC_ATTESTATION_HOOK="\${_ai_sdlc_dir}scripts/check-attestation-sign.sh"
+        break
+      fi
+    done
+  fi
+  if [ -n "$AI_SDLC_ATTESTATION_HOOK" ]; then
+    echo "[ai-sdlc] attestation signer: $AI_SDLC_ATTESTATION_HOOK" >&2
+    bash "$AI_SDLC_ATTESTATION_HOOK"
+  elif [ -n "$(ls -A .ai-sdlc/verdicts 2>/dev/null)" ]; then
+    echo "[ai-sdlc] ERROR: reviewer verdicts exist under .ai-sdlc/verdicts/ but NO attestation signer" >&2
+    echo "[ai-sdlc]   could be found — this push will carry no attestation." >&2
+    echo "[ai-sdlc]   Searched CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DIR, and" >&2
+    echo "[ai-sdlc]   ~/.claude/plugins/cache/*/ai-sdlc/*/scripts/check-attestation-sign.sh" >&2
+    echo "[ai-sdlc]   Install the ai-sdlc Claude Code plugin, or set CLAUDE_PLUGIN_ROOT." >&2
+  fi
 fi
 # end ai-sdlc:attestation-sign-block
 `;
@@ -857,6 +919,18 @@ export const ATTESTATION_TEMPLATES = {
         // first PR's envelope lands cleanly without "directory does not exist"
         // errors from the signing script.
         '.ai-sdlc/attestations/.gitkeep': '',
+        // AISDLC-555 (partial AC #7): the pre-push hook's gate condition reads
+        // `.ai-sdlc/verdicts/<task-id>.json` — tightly coupled to attestation,
+        // so it's scaffolded here rather than deferred to a separate
+        // init-orchestration task. Dispatch Board directories + dispatch-
+        // config.yaml (the rest of the widened AC #7 scope) are NOT scaffolded
+        // here, and — confirmed by round-2 review — NO backlog task currently
+        // owns them: nothing under `backlog/tasks/` mentions dispatch-config.yaml.
+        // An earlier revision of this comment cited AISDLC-560; that task covers
+        // attestation enforcement/doctor and says nothing about the Dispatch
+        // Board, so the citation was wrong. Left explicitly unowned rather than
+        // pointed at a task that would not deliver it.
+        '.ai-sdlc/verdicts/.gitkeep': '',
     },
 };
 export const CLASSIFIER_TEMPLATES = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdlc/orchestrator",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "AI-SDLC Orchestrator — long-running runtime that drives issues through the complete SDLC with AI agents",
   "license": "Apache-2.0",
   "repository": {
@@ -37,6 +37,10 @@
       "types": "./dist/state/index.d.ts",
       "import": "./dist/state/index.js"
     },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
     "./cli": {
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js"
@@ -48,7 +52,7 @@
     "commander": "^15.0.0",
     "franc": "^6.2.0",
     "yaml": "^2.9.0",
-    "@ai-sdlc/reference": "0.14.0"
+    "@ai-sdlc/reference": "0.16.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",