@momentiq/dark-factory-cli 2.0.0 → 2.2.0

package/dist/commands/onboard.js

@@ -0,0 +1,323 @@
+// `df onboard` — cycles 15 Phase A (analysis) + Phase B (LLM tailoring) +
+// Phase C (deterministic seeders, merged via `cmdOnboard`).
+//
+// Two exported entry points:
+//
+// - **`cmdOnboard(opts)`** — the orchestrator. Runs the pipeline
+//   `analyze → generatePlan (Phase B) → runSeeders (Phase C) → mergeScaffoldPlan`
+//   and returns a typed result. The MCP `df_onboard` tool (Task 6) and the
+//   sage3c reproduction harness (Task 5) call this directly.
+// - **`cmdOnboardCli(rest, io)`** — the CLI shim. Parses argv, validates
+//   credentials at the surface, delegates to `cmdOnboard`, then formats the
+//   structured result for stdout/stderr per --json / --analysis-only / etc.
+//
+// Phase A surface (preserved): `df onboard --analysis-only [--json] [target]`.
+// Phase B/C surface: `df onboard [--dry-run | --apply | --pr]
+//   [--template <ref>] [--api-key <k>] [--model <id>] [--profile local|cloud]
+//   [--include-runtime-infra] [--force] [--json] [target]`.
+//
+// Mode flags are mutually exclusive; default is --dry-run when none set.
+// --include-runtime-infra is a loud rejection (deferred to v2).
+import { createHash } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { analyze } from "../onboard/analyze.js";
+import { loadTemplate } from "../onboard/template-loader.js";
+import { generatePlan } from "../onboard/generate-plan.js";
+import { applyPlan, ScaffoldApplyError } from "../onboard/apply-plan.js";
+import { runPrMode, preflightPr, defaultRunner } from "../onboard/writers/pr-writer.js";
+import { autoProfile } from "../onboard/auto-profile.js";
+import { ALL_SEEDERS_DEFAULT, runSeeders } from "../onboard/seeders/index.js";
+import { ScaffoldPlanSchema, } from "../onboard/scaffold-schema.js";
+const DEFAULT_TEMPLATE = "gh:momentiq-ai/sage-blueprint@latest";
+const DEFAULT_MODEL = "claude-3-7-sonnet-latest";
+const HELP = [
+    "df onboard — Cycle 15: deterministic analyzer (Phase A) + LLM-tailored scaffolding (Phase B) + deterministic seeders (Phase C).",
+    "",
+    "Usage:",
+    "  df onboard [--analysis-only | --dry-run | --apply | --pr] [target-dir]",
+    "             [--template <ref>] [--api-key <k>] [--model <id>]",
+    "             [--profile local|cloud] [--force] [--json]",
+    "",
+    "Modes (mutually exclusive; default --dry-run):",
+    "  --analysis-only   Phase A only — runs the Stage A scanner, emits RepoAnalysis.",
+    "  --dry-run         Render the tailored ScaffoldPlan as a diff preview (no writes).",
+    "  --apply           Write the tailored scaffold to the target directory.",
+    "  --pr              Branch + commit + open a PR via gh CLI.",
+    "",
+    "Stage B/C flags (apply / pr / dry-run):",
+    "  --template <ref>          Template source. Default: " + DEFAULT_TEMPLATE,
+    "                            Ref shape: gh:<owner>/<repo>@<sha|tag|branch|latest>",
+    "                                       file:///<abs-path>@<ref>",
+    "  --api-key <key>           Anthropic API key. Defaults to ANTHROPIC_API_KEY env.",
+    "  --model <id>              LLM model id. Default: " + DEFAULT_MODEL,
+    "  --profile local|cloud     Critic profile for the generated .agent-review/config.json.",
+    "                            Default: auto-detect (cloud if DF gate already present).",
+    "  --force                   On --apply, overwrite existing emit-targets without prompting;",
+    "                            on --pr, recreate the df/onboard-<sha8> branch (-C vs -c).",
+    "  --json                    JSON output. With --analysis-only: RepoAnalysis.",
+    "                            With --dry-run: merged ScaffoldPlan (Phase B + Phase C seeders).",
+    "",
+    "Rejected:",
+    "  --include-runtime-infra   Deferred to v2 (Cycle 15 D5: outside the agent-context-set bar).",
+    "",
+    "Exit codes:",
+    "  0  success",
+    "  1  runtime failure (missing API key, write error, gh-auth missing, etc.)",
+    "  2  usage error",
+    "",
+].join("\n");
+function parseOnboardArgs(rest) {
+    let analysisOnly = false, dryRun = false, apply = false, pr = false;
+    let json = false, force = false, includeRuntimeInfra = false;
+    let template = DEFAULT_TEMPLATE;
+    let apiKey;
+    let modelId = DEFAULT_MODEL;
+    let profile;
+    let targetDir = null;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i] ?? "";
+        if (a === "--analysis-only") {
+            analysisOnly = true;
+            continue;
+        }
+        if (a === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (a === "--apply") {
+            apply = true;
+            continue;
+        }
+        if (a === "--pr") {
+            pr = true;
+            continue;
+        }
+        if (a === "--json") {
+            json = true;
+            continue;
+        }
+        if (a === "--force") {
+            force = true;
+            continue;
+        }
+        if (a === "--include-runtime-infra") {
+            includeRuntimeInfra = true;
+            continue;
+        }
+        if (a === "--template") {
+            template = rest[++i] ?? "";
+            continue;
+        }
+        if (a === "--api-key") {
+            apiKey = rest[++i];
+            continue;
+        }
+        if (a === "--model") {
+            modelId = rest[++i] ?? DEFAULT_MODEL;
+            continue;
+        }
+        if (a === "--profile") {
+            const v = rest[++i];
+            if (v !== "local" && v !== "cloud")
+                return { error: `--profile must be local|cloud, got "${v}"` };
+            profile = v;
+            continue;
+        }
+        if (a.startsWith("--"))
+            return { error: `unknown flag: ${a}` };
+        if (targetDir !== null)
+            return { error: `unexpected positional arg: ${a}` };
+        targetDir = a;
+    }
+    if (includeRuntimeInfra) {
+        return {
+            error: "--include-runtime-infra is deferred to v2 (Cycle 15 D5: " +
+                "Generating runtime infrastructure (Terraform, Helm) is outside the agent-context-set bar).",
+        };
+    }
+    const modes = [analysisOnly, dryRun, apply, pr].filter(Boolean).length;
+    if (modes > 1) {
+        return { error: "mode flags are mutually exclusive (pass one of --analysis-only / --dry-run / --apply / --pr)" };
+    }
+    const mode = analysisOnly ? "analysis-only" :
+        apply ? "apply" :
+            pr ? "pr" :
+                "dry-run";
+    const resolvedApiKey = apiKey ?? process.env["ANTHROPIC_API_KEY"];
+    return {
+        mode,
+        template,
+        ...(resolvedApiKey !== undefined ? { apiKey: resolvedApiKey } : {}),
+        modelId,
+        ...(profile !== undefined ? { profile } : {}),
+        force,
+        json,
+        targetDir: targetDir ?? process.cwd(),
+    };
+}
+function sha8(input) {
+    return createHash("sha256").update(input).digest("hex").slice(0, 8);
+}
+async function listExistingAdrs(target) {
+    try {
+        return (await readdir(join(target, "docs", "ADR"))).filter((n) => n.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Merge Phase B's LLM-emitted `ScaffoldPlan` with Phase C's seeder-emitted
+ * `FilePlan[]`. Phase B wins on path collision — the LLM tailoring is
+ * authoritative for any file the LLM chose to emit. The result is re-parsed
+ * through `ScaffoldPlanSchema` as the structural canary (per-file 16KB cap,
+ * 100-file cap, discriminated-union constraints) so caps applied to the
+ * Phase B half don't silently leak.
+ */
+export function mergeScaffoldPlan(phaseBPlan, seederFiles) {
+    const phaseBPaths = new Set(phaseBPlan.files.map((f) => f.path));
+    const nonColliding = seederFiles.filter((s) => !phaseBPaths.has(s.path));
+    const merged = {
+        ...phaseBPlan,
+        files: [...phaseBPlan.files, ...nonColliding],
+    };
+    return ScaffoldPlanSchema.parse(merged);
+}
+/**
+ * The orchestrator. Runs analyze → generatePlan → runSeeders →
+ * mergeScaffoldPlan, then optionally writes to the working tree (apply) or
+ * opens a PR (pr). Returns a structured result the CLI shim and MCP tool
+ * both consume.
+ *
+ * Analysis-only mode skips Phase B + Phase C; it returns `{ analysis }`
+ * alone for the no-LLM preview path.
+ */
+export async function cmdOnboard(opts) {
+    const analysis = await analyze(opts.target);
+    if (opts.mode === "analysis-only") {
+        return { analysis };
+    }
+    const profile = opts.profile ?? autoProfile(analysis);
+    const template = await loadTemplate(opts.templateRef ?? DEFAULT_TEMPLATE);
+    const phaseBPlan = await generatePlan(analysis, template, {
+        modelId: opts.modelId ?? DEFAULT_MODEL,
+        profile,
+        ...(opts.apiKey !== undefined ? { apiKey: opts.apiKey } : {}),
+    });
+    const existingAdrs = await listExistingAdrs(opts.target);
+    const seederFiles = await runSeeders({ analysis, existingAdrs, now: new Date(), profile }, ALL_SEEDERS_DEFAULT);
+    const plan = mergeScaffoldPlan(phaseBPlan, seederFiles);
+    let branchName = null;
+    let applied = false;
+    const force = opts.force ?? false;
+    if (opts.mode === "apply") {
+        await applyPlan(opts.target, plan, { mode: "apply", force });
+        applied = true;
+    }
+    else if (opts.mode === "pr") {
+        const analysisSha8 = sha8(JSON.stringify(analysis));
+        const r = await runPrMode(opts.target, plan, analysisSha8, {
+            canonicalName: analysis.canonicalName || "unknown/unknown",
+            defaultBranch: analysis.git.defaultBranch,
+            force,
+        });
+        branchName = r.branch;
+        applied = true;
+    }
+    // dry-run: orchestrator returns the merged plan; the CLI shim renders it.
+    return { analysis, plan, branchName, applied };
+}
+export async function cmdOnboardCli(rest, io) {
+    if (rest.includes("--help") || rest.includes("-h")) {
+        io.stdout(HELP);
+        return 0;
+    }
+    const parsed = parseOnboardArgs(rest);
+    if ("error" in parsed) {
+        io.stderr(`df onboard: ${parsed.error}\nRun \`df onboard --help\` for usage.\n`);
+        return 2;
+    }
+    if (parsed.mode === "analysis-only") {
+        try {
+            const out = await cmdOnboard({ target: parsed.targetDir, mode: "analysis-only" });
+            const analysisResult = out;
+            io.stdout(parsed.json
+                ? JSON.stringify(analysisResult.analysis) + "\n"
+                : renderAnalysisSummary(analysisResult.analysis));
+            return 0;
+        }
+        catch (e) {
+            io.stderr(`df onboard: ${e instanceof Error ? e.message : String(e)}\n`);
+            return 1;
+        }
+    }
+    if (!parsed.apiKey || !parsed.apiKey.trim()) {
+        io.stderr("df onboard: ANTHROPIC_API_KEY is required for Phase B (--dry-run, --apply, --pr). " +
+            "Set the env var (or pass --api-key) and re-run. Use --analysis-only for a no-LLM preview.\n");
+        return 1;
+    }
+    try {
+        if (parsed.mode === "pr") {
+            await preflightPr(defaultRunner, parsed.targetDir);
+        }
+        const out = await cmdOnboard({
+            target: parsed.targetDir,
+            mode: parsed.mode,
+            templateRef: parsed.template,
+            apiKey: parsed.apiKey,
+            modelId: parsed.modelId,
+            ...(parsed.profile !== undefined ? { profile: parsed.profile } : {}),
+            force: parsed.force,
+        });
+        const planResult = out;
+        const plan = planResult.plan;
+        if (parsed.mode === "dry-run") {
+            if (parsed.json) {
+                io.stdout(JSON.stringify(plan) + "\n");
+            }
+            else {
+                const r = await applyPlan(parsed.targetDir, plan, { mode: "dry-run" });
+                if (r.rendered)
+                    io.stdout(r.rendered);
+            }
+            return 0;
+        }
+        if (parsed.mode === "apply") {
+            const profile = parsed.profile ?? autoProfile(planResult.analysis);
+            io.stdout(`df onboard: applied ${plan.files.length} files (profile=${profile}).\n`);
+            return 0;
+        }
+        // pr mode
+        io.stdout(`df onboard: opened PR on branch ${planResult.branchName ?? "(unknown)"}\n`);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof ScaffoldApplyError) {
+            io.stderr(`df onboard: ${e.message}\n`);
+            return 1;
+        }
+        io.stderr(`df onboard: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+}
+function renderAnalysisSummary(a) {
+    const lines = [];
+    lines.push(`Repo: ${a.canonicalName || "(unknown)"} at ${a.repoRoot}`);
+    lines.push(`Stacks: ${a.stacks.map((s) => `${s.language}@${s.versionPin ?? "?"}`).join(", ") || "(none detected)"}`);
+    lines.push(`Services: ${a.services.length}`);
+    lines.push(`Workflows: ${a.ci.workflows.length}; deploy: ${a.ci.deployStory?.target ?? "(none)"}`);
+    const hooks = a.dfPresence.hooks ? "v" : "x";
+    const config = a.dfPresence.configJson ? "v" : "x";
+    const workflow = a.dfPresence.prWorkflow ? "v" : "x";
+    lines.push(`DF gate: ${hooks}husky ${config}config ${workflow}workflow` +
+        (a.dfPresence.cliPin ? ` (cli pin: ${a.dfPresence.cliPin})` : ""));
+    lines.push(`Agent context set: ${a.docs.agentContextSetPresent ? "present" : "MISSING (df onboard target)"}`);
+    if (a.analyzerErrors.length > 0) {
+        lines.push(`Analyzer errors: ${a.analyzerErrors.length}`);
+        for (const e of a.analyzerErrors)
+            lines.push(`  - ${e.name}: ${e.error}`);
+    }
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=onboard.js.map

package/dist/commands/onboard.js.map

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

package/dist/cycle-doc-validator/validate_cycle_doc.py

@@ -134,7 +134,17 @@ def _resolve_repo_root() -> Path:
 
 
 REPO_ROOT = _resolve_repo_root()
+# Cycle-doc lookup paths in priority order. Legacy `docs/roadmap/cycles/` is
+# tried first for backward compatibility with sage3c / dark-factory-platform;
+# `docs/cycles/` is the newer dark-factory-dashboard convention (PR #105
+# moved it there to align with the eventual upstream convention). Consumers
+# that have moved to the new path get a working validator without
+# configuration; consumers still on the legacy path are unchanged.
+CYCLE_DOC_DIRS: tuple[str, ...] = ("docs/roadmap/cycles", "docs/cycles")
 CYCLES_DIR = REPO_ROOT / "docs" / "roadmap" / "cycles"
+# Glob and the singular `CYCLES_DIR` retained for backward compatibility with
+# downstream tooling that imports them. New code should prefer `CYCLE_DOC_DIRS`
+# + `_is_cycle_doc_path()` which check both layouts.
 CYCLE_DOC_GLOB = "docs/roadmap/cycles/cycle*.md"
 
 # Trailers we recognize. ``git-interpret-trailers`` defines a trailer as
@@ -238,14 +248,27 @@ def normalize_cycle_id(raw: str) -> str | None:
 
 
 def find_cycle_doc(cycle_id: str) -> CycleDoc | None:
-    """Locate ``docs/roadmap/cycles/cycle<id>*.md`` and read its status."""
-    matches = sorted(CYCLES_DIR.glob(f"cycle{cycle_id}-*.md")) + sorted(
-        CYCLES_DIR.glob(f"cycle{cycle_id}.md")
-    )
+    """Locate ``<cycle_dir>/cycle<id>*.md`` and read its status.
+
+    Searches every candidate dir in ``CYCLE_DOC_DIRS`` (legacy
+    ``docs/roadmap/cycles/`` first, then ``docs/cycles/``) so consumers
+    that have moved get a working lookup without configuration. If the
+    same cycle exists in both dirs (transitional state), prefers the
+    longer-named match across all hits — same disambiguation rule as
+    before, just over a wider candidate set.
+    """
+    matches: list[Path] = []
+    for cycle_dir in CYCLE_DOC_DIRS:
+        dir_path = REPO_ROOT / cycle_dir
+        if not dir_path.exists():
+            continue
+        matches.extend(sorted(dir_path.glob(f"cycle{cycle_id}-*.md")))
+        matches.extend(sorted(dir_path.glob(f"cycle{cycle_id}.md")))
     if not matches:
         return None
-    # If multiple matches exist (legacy ``cycle318.md`` + new ``cycle318-foo.md``),
-    # prefer the one with the longer name (more descriptive slug).
+    # If multiple matches exist (legacy ``cycle318.md`` + new ``cycle318-foo.md``,
+    # or one in each layout), prefer the one with the longer name (more
+    # descriptive slug).
     path = max(matches, key=lambda p: len(p.name))
     status, superseded_by = read_cycle_frontmatter(path)
     return CycleDoc(path=path, status=status, superseded_by=superseded_by)
@@ -332,50 +355,89 @@ def base_cycle_doc(
     if gh_token:
         env["GH_TOKEN"] = gh_token
 
-    try:
-        listing_result = subprocess.run(
-            [
-                "gh",
-                "api",
-                f"repos/{repo}/contents/docs/roadmap/cycles?ref={base_ref}",
-            ],
-            check=True,
-            capture_output=True,
-            text=True,
-            env=env,
-            timeout=60,
+    # Collect candidates across EVERY candidate cycle-doc dir on the base
+    # ref — DON'T break on the first successful listing. A consumer can
+    # have BOTH layouts present (transitional state — e.g. dark-factory-
+    # dashboard pre-#105 had cycle1-5 at legacy + cycle6 at the new path
+    # for one PR's worth of overlap), and a legacy dir that exists but
+    # lacks the cited cycle (sage3c with cycle331.x at legacy + a new
+    # cycle 6 at the new path) must fall through to the next dir. Per-dir
+    # 404 is the normal "consumer has not moved (or has moved fully) to
+    # this layout" signal; only fail if EVERY dir 404s or any dir hits a
+    # non-404 error.
+    pattern = re.compile(rf"^cycle{re.escape(cycle_id)}(?:-.+)?\.md$")
+    candidates: list[dict] = []
+    dirs_listed: list[str] = []
+    last_404: BaseCycleDocFetchError | None = None
+    for cycle_dir in CYCLE_DOC_DIRS:
+        try:
+            listing_result = subprocess.run(
+                [
+                    "gh",
+                    "api",
+                    f"repos/{repo}/contents/{cycle_dir}?ref={base_ref}",
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+                env=env,
+                timeout=60,
+            )
+        except FileNotFoundError as exc:
+            # gh CLI itself missing — environmental, fail loud regardless
+            # of which cycle_dir we were probing.
+            raise BaseCycleDocFetchError(
+                "gh CLI not on PATH; cannot read cycle docs from base ref."
+            ) from exc
+        except subprocess.CalledProcessError as exc:
+            # Treat 404 (or "not found") as "this dir doesn't exist on
+            # base ref; keep trying the others". Any other non-zero exit
+            # (auth, rate-limit, server error) escapes immediately —
+            # don't silently swallow a real failure as a missing-dir.
+            if _is_gh_not_found_error(exc):
+                last_404 = BaseCycleDocFetchError(
+                    f"gh api repos/{repo}/contents/{cycle_dir} returned 404 "
+                    f"(exit {exc.returncode}): {(exc.stderr or '').strip()}"
+                )
+                continue
+            raise BaseCycleDocFetchError(
+                f"gh api repos/{repo}/contents/{cycle_dir} failed "
+                f"(exit {exc.returncode}): {(exc.stderr or '').strip()}"
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise BaseCycleDocFetchError(
+                f"gh api repos/{repo}/contents/{cycle_dir} timed out after {exc.timeout}s"
+            ) from exc
+
+        dirs_listed.append(cycle_dir)
+        try:
+            entries = json.loads(listing_result.stdout)
+        except json.JSONDecodeError as exc:
+            raise BaseCycleDocFetchError(
+                f"GitHub contents API returned malformed JSON for {cycle_dir} listing."
+            ) from exc
+
+        candidates.extend(
+            entry
+            for entry in entries
+            if isinstance(entry, dict)
+            and entry.get("type") == "file"
+            and isinstance(entry.get("name"), str)
+            and pattern.match(entry["name"])
         )
-    except FileNotFoundError as exc:
-        raise BaseCycleDocFetchError(
-            "gh CLI not on PATH; cannot read cycle docs from base ref."
-        ) from exc
-    except subprocess.CalledProcessError as exc:
-        raise BaseCycleDocFetchError(
-            f"gh api repos/{repo}/contents/docs/roadmap/cycles failed "
-            f"(exit {exc.returncode}): {exc.stderr.strip()}"
-        ) from exc
-    except subprocess.TimeoutExpired as exc:
-        raise BaseCycleDocFetchError(
-            f"gh api repos/{repo}/contents/docs/roadmap/cycles timed out after {exc.timeout}s"
-        ) from exc
 
-    try:
-        entries = json.loads(listing_result.stdout)
-    except json.JSONDecodeError as exc:
-        raise BaseCycleDocFetchError(
-            "GitHub contents API returned malformed JSON for cycle docs listing."
-        ) from exc
+    if not dirs_listed:
+        # EVERY candidate dir 404'd — no cycle docs anywhere on base ref.
+        # Surface the last 404 so consumers see a concrete actionable error
+        # naming what was tried.
+        raise last_404 or BaseCycleDocFetchError(
+            "no candidate cycle-doc directory found on base ref "
+            f"(tried: {', '.join(CYCLE_DOC_DIRS)})"
+        )
 
-    pattern = re.compile(rf"^cycle{re.escape(cycle_id)}(?:-.+)?\.md$")
-    candidates = [
-        entry
-        for entry in entries
-        if isinstance(entry, dict)
-        and entry.get("type") == "file"
-        and isinstance(entry.get("name"), str)
-        and pattern.match(entry["name"])
-    ]
     if not candidates:
+        # At least one dir existed but doesn't hold the cited cycle —
+        # treat as "new cycle, OK to proceed" (the doc lands in this PR).
         return None
 
     chosen = max(candidates, key=lambda entry: len(entry["name"]))
@@ -657,18 +719,22 @@ def _parse_paginated_commit_messages(raw: str) -> str:
 
 
 def _is_cycle_doc_path(path: str) -> bool:
-    """Match ``docs/roadmap/cycles/cycle<id>(-<slug>)?.md``.
+    """Match ``<cycle_dir>/cycle<id>(-<slug>)?.md`` under any layout.
 
-    The classifier counts only files whose basename starts with
-    ``cycle`` followed by an id character. Sibling files like
-    ``docs/roadmap/cycles/README.md`` are index/meta content and do
-    NOT trigger the plan-PR contract.
+    Accepts both legacy ``docs/roadmap/cycles/`` and the newer
+    ``docs/cycles/`` per ``CYCLE_DOC_DIRS``. The classifier counts only
+    files whose basename starts with ``cycle`` followed by an id
+    character. Sibling files like ``<cycle_dir>/README.md`` are
+    index/meta content and do NOT trigger the plan-PR contract.
     """
-    prefix = "docs/roadmap/cycles/cycle"
-    if not path.startswith(prefix) or not path.endswith(".md"):
+    if not path.endswith(".md"):
         return False
-    next_char = path[len(prefix) : len(prefix) + 1]
-    return next_char.isdigit()
+    for cycle_dir in CYCLE_DOC_DIRS:
+        prefix = f"{cycle_dir}/cycle"
+        if path.startswith(prefix):
+            next_char = path[len(prefix) : len(prefix) + 1]
+            return next_char.isdigit()
+    return False
 
 
 def is_plan_pr(
@@ -731,7 +797,9 @@ def status_completion_in_diff(diff: str) -> list[str]:
             in_frontmatter = False
             seen_completed_in_frontmatter = False
             continue
-        if not current_file or not current_file.startswith("docs/roadmap/cycles/"):
+        if not current_file or not any(
+            current_file.startswith(f"{d}/") for d in CYCLE_DOC_DIRS
+        ):
             continue
         # Naive frontmatter tracking inside the diff hunk: ``---`` delimiters
         # toggle the flag. False positives are acceptable here — the goal
@@ -789,7 +857,7 @@ def cycle_docs_transitioned_to_terminal(
     cycle_paths = [
         p
         for p in changed_files
-        if p.startswith("docs/roadmap/cycles/cycle") and p.endswith(".md")
+        if any(p.startswith(f"{d}/cycle") for d in CYCLE_DOC_DIRS) and p.endswith(".md")
     ]
     if not cycle_paths:
         return []
@@ -1030,8 +1098,9 @@ def validate(
         if doc is None:
             errors.append(
                 f"[cycle-doc] FAIL ({pr_type}): cycle `{cycle_id}` not found in "
-                f"`docs/roadmap/cycles/`. Either fix the trailer or open a plan "
-                "PR that creates the cycle doc first."
+                f"any of: {', '.join(f'`{d}/`' for d in CYCLE_DOC_DIRS)}. "
+                "Either fix the trailer or open a plan PR that creates the "
+                "cycle doc first."
             )
             return errors
 
@@ -1056,7 +1125,9 @@ def validate(
         # PR that doesn't touch its cycle's doc is mis-labelled.
         assert doc is not None  # plan PR without cycle_id already returned
         cycle_paths = [
-            f for f in changed_files if f.startswith("docs/roadmap/cycles/")
+            f
+            for f in changed_files
+            if any(f.startswith(f"{d}/") for d in CYCLE_DOC_DIRS)
         ]
         doc_relative = doc.path.relative_to(REPO_ROOT).as_posix()
         if doc_relative not in cycle_paths:

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM9D,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,gCAAgC,CAAC;AAIxC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAK1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAO5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA4L9E;AAuBD,eAAO,MAAM,iBAAiB,qFAKpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CAYnB;AAiPD,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,cAAc,GACd,IAAI,CAAC;AAET,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;;;OAMG;IACH,eAAe,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,iBAAiB,CAAC;IACzB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,kBAAkB,CAiDpB;AA0BD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAwDjE;AAoED,eAAO,MAAM,2BAA2B,QACQ,CAAC;AA8GjD,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA6F3E"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAO9D,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,gCAAgC,CAAC;AAIxC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAK1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAO5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAkN9E;AAuBD,eAAO,MAAM,iBAAiB,qFAKpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CAYnB;AAiPD,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,cAAc,GACd,IAAI,CAAC;AAET,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;;;OAMG;IACH,eAAe,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,iBAAiB,CAAC;IACzB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,kBAAkB,CAiDpB;AA0BD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAwDjE;AAoED,eAAO,MAAM,2BAA2B,QACQ,CAAC;AA8GjD,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA6F3E"}

package/dist/doctor.js

@@ -30,6 +30,7 @@ import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, } from "node:fs";
 import { resolve } from "node:path";
 import { gitCommonDir, gitDir } from "./git.js";
+import { checkAgentContextSet } from "./onboard/validate.js";
 import { applyProfileAuth, resolveProfileWithConfig, } from "./policy/profile.js";
 const HOOK_FILES = ["post-commit", "pre-push"];
 export async function runDoctor(options) {
@@ -158,6 +159,25 @@ export async function runDoctor(options) {
     // envs via Doppler / env vars.
     const cloudEnv = detectCloudEnv();
     checks.push(cloudEnvCheck(cloudEnv));
+    // 7b. Agent-context-set validation (cycle 15 Phase C). The required-files
+    //     walk (cycle 15 D3 floor: CLAUDE.md, AGENTS.md, .claude/settings.json,
+    //     docs/PRINCIPLES.md, docs/roadmap/cycles/cycle1-*.md,
+    //     .agent-review/config.json) runs UNCONDITIONALLY — if any of those is
+    //     missing, doctor fails loudly. The `context.guidanceFiles` field gates
+    //     ONLY the additional per-path walk (which is opt-in; the required-files
+    //     set is not opt-in). Per Decision #7 round-1 revision.
+    //
+    //     Note: the `context.guidanceFiles` field may not yet exist on the
+    //     AgentReviewConfig Zod schema in @momentiq/dark-factory-schemas — the
+    //     schemas-package PR is a follow-up. Until then, we read the field via a
+    //     runtime cast so this doctor patch lands first (additive-field pattern
+    //     precedent: cycle 5 / cycle 13 cloud-env detection).
+    const guidanceFiles = loaded.config.context?.guidanceFiles;
+    const agentContextChecks = await checkAgentContextSet({
+        repoRoot: root,
+        guidanceFiles,
+    });
+    checks.push(...agentContextChecks);
     // 8. per-adapter doctor() — this is where subscription-auth verification
     // actually lives. Each adapter's doctor() checks ITS own credentials
     // (env var, ~/.cursor auth, ~/.codex auth, etc.). When a profile is