@rsaglobaltech/specgate 0.24.0 → 0.26.0

package/dist/scripts/cli/commands/harness/RunCommand.js

@@ -81,6 +81,8 @@ const prompt_1 = require("../../../harness/prompt");
 const init_1 = require("../../../harness/init");
 const in_flight_1 = require("../../../lib/in-flight");
 const harness_events_1 = require("../../../lib/harness-events");
+const clarification_1 = require("../../../lib/clarification");
+const screen_requirements_1 = require("../../../lib/screen-requirements");
 const harness_guard_1 = require("../../../lib/harness-guard");
 const HarnessEvents_1 = require("../../../../packages/core/src/domain/HarnessEvents");
 /**
@@ -170,6 +172,8 @@ function usage() {
         "Runs the plan → agent → verify → done loop for every pending requirement.\n\n" +
         "  --agent <cmd>          Agent command; must contain the {prompt_file} placeholder.\n" +
         '                         e.g. --agent "claude -p < {prompt_file}"\n' +
+        "  --profile <name>       Run this profile's agent from .harness/profiles.yaml instead\n" +
+        "                         of the configured one, for this run only.\n" +
         "  --test-cmd <cmd>       Project test command run as part of the gate (optional).\n" +
         "                         Substitutes {req}, {scenario} and {feature_file}, so the\n" +
         "                         gate can run the scenario under test.\n" +
@@ -251,6 +255,7 @@ function parseArgs(argv) {
         prCmd: "",
         setupCmd: "",
         chain: false,
+        profile: "",
     };
     for (let i = 0; i < argv.length; i += 1) {
         const token = argv[i];
@@ -260,6 +265,9 @@ function parseArgs(argv) {
         else if (token === "--agent") {
             args.agent = argv[++i] || "";
         }
+        else if (token === "--profile") {
+            args.profile = argv[++i] || "";
+        }
         else if (token === "--test-cmd") {
             args.testCmd = argv[++i] || "";
         }
@@ -397,6 +405,14 @@ function runPlan(projectDir) {
         // `JSON.parse` only ever throws a SyntaxError.
         throw new Error(`plan produced invalid JSON: ${err.message}`);
     }
+    // Read on the project itself: the judged copy has every open change
+    // archived into it, and no longer says which requirements were modified.
+    const modified = new Set((0, in_flight_1.inFlightRequirements)(projectDir)
+        .filter((r) => r.op === "modified")
+        .map((r) => r.id));
+    if (modified.size > 0 && Array.isArray(parsed.requirements)) {
+        parsed.requirements = (0, RequirementPlan_1.withRework)(parsed.requirements, modified);
+    }
     return parsed;
 }
 // Generous maxBuffer for captured subprocess output — Maven/Gradle first runs
@@ -502,6 +518,21 @@ function runGate(worktreeDir, testCmd, timeoutMs, req = {}, settings = {}, repor
             hint: "",
         };
     }
+    // REQ-199: a requirement used on a screen needs an end-to-end test that
+    // names it, when the project says where those live.
+    if (settings.e2eDir && req.requirement && (0, screen_requirements_1.onScreen)(worktreeDir, req.requirement)) {
+        const named = (0, screen_requirements_1.e2eTestsNaming)(worktreeDir, settings.e2eDir, req.requirement);
+        report("e2e test", named.length ? "pass" : "fail");
+        if (named.length === 0) {
+            return {
+                ok: false,
+                stage: "e2e test",
+                output: `No file under ${settings.e2eDir} names ${req.requirement}.`,
+                hint: `${req.requirement} is used on a screen: add an end-to-end test under ` +
+                    `${settings.e2eDir} that names it, driving the screen its scenarios describe.`,
+            };
+        }
+    }
     // ADR-0028: the architecture check runs between validation and the tests,
     // and its failure goes back to the agent like any other gate failure.
     const archCmd = String(settings.archCmd || "").trim();
@@ -529,7 +560,10 @@ function runGate(worktreeDir, testCmd, timeoutMs, req = {}, settings = {}, repor
         // Where the message stream will be, if there is one to have.
         let reportPath = settings.messageReport || "";
         if (!reportPath && (0, CucumberMessages_1.invokesCucumberDirectly)(resolved)) {
-            reportPath = path.join(".harness", `messages-${req.requirement || "run"}-${crypto.randomBytes(3).toString("hex")}.ndjson`);
+            // Forward slashes on every platform: Cucumber reads `message:.harness\x`
+            // on Windows as a path it does not write, and the gate then had no
+            // stream to check and passed a run of no scenarios.
+            reportPath = path.posix.join(".harness", `messages-${req.requirement || "run"}-${crypto.randomBytes(3).toString("hex")}.ndjson`);
             fs.mkdirSync(path.join(worktreeDir, ".harness"), { recursive: true });
             resolved = (0, CucumberMessages_1.withMessageReport)(resolved, reportPath);
         }
@@ -951,7 +985,7 @@ function attemptRequirement(req, ctx) {
             event({
                 type: "attempt",
                 state: "end",
-                result: stage === "pass" ? "pass" : "fail",
+                result: stage === "pass" ? "pass" : stage === "question" ? "question" : "fail",
                 ...(stage === "pass" ? {} : { stage }),
             });
             attemptLog.push({
@@ -987,6 +1021,9 @@ function attemptRequirement(req, ctx) {
                     // commit — the precedent must be work already accepted, not a
                     // sibling requirement this same run happens to be writing.
                     withPrecedents: settings.promptPrecedents === true,
+                    e2eDir: settings.e2eDir && (0, screen_requirements_1.onScreen)(worktreeDir, req.requirement)
+                        ? settings.e2eDir
+                        : undefined,
                 }));
                 const promptFile = path.join(os.tmpdir(), `specgate-harness-prompt-${req.requirement}-${crypto.randomBytes(4).toString("hex")}.md`);
                 fs.writeFileSync(promptFile, prompt, "utf8");
@@ -1082,6 +1119,21 @@ function attemptRequirement(req, ctx) {
             break;
         if (stepFailed)
             continue;
+        // The agent asked instead of guessing (REQ-189): another attempt would
+        // meet the same question, and the gate has nothing to judge.
+        const asked = questionAsked(eventsFile, attempt, attemptStart);
+        if (asked) {
+            warn(`${req.requirement}: the agent asked — ${asked}`);
+            record("question");
+            discardWorktreeChanges(worktreeDir);
+            return {
+                result: "question",
+                attempts: attempt - firstAttempt + 1,
+                attemptLog,
+                question: asked,
+                error: `Needs clarification: ${asked}`,
+            };
+        }
         // Before the gate: an agent that wrote nothing cannot have implemented
         // anything, and the gate would approve it. See `producedNothing` (H19).
         if (producedNothing(worktreeDir)) {
@@ -1242,6 +1294,55 @@ function attemptRequirement(req, ctx) {
         attemptLog,
     };
 }
+/** The question the agent recorded with `specgate ask` during this attempt, if any (REQ-189). */
+function questionAsked(eventsFile, attempt, startedMs) {
+    let text = "";
+    try {
+        text = fs.readFileSync(eventsFile, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const since = Math.floor(startedMs / 1000) - 1;
+    let asked = null;
+    for (const line of text.split("\n")) {
+        try {
+            const e = JSON.parse(line);
+            if (e.type === "question" && e.attempt === attempt && Number(e.t) >= since && e.text) {
+                asked = String(e.text);
+            }
+        }
+        catch {
+            /* a line being written */
+        }
+    }
+    return asked;
+}
+/**
+ * The questions the run's agents asked, written into the project and
+ * committed (REQ-189): the agent could not edit the specification, so the
+ * harness does, in one commit per question, and the requirement waits.
+ */
+function recordQuestions(projectDir, results) {
+    for (const r of results) {
+        if (r.result !== "question" || !r.question)
+            continue;
+        const asked = (0, clarification_1.ask)(projectDir, r.requirement, r.question);
+        if (!asked.ok) {
+            warn(`${r.requirement}: could not record its question — ${asked.message}`);
+            continue;
+        }
+        git(projectDir, ["add", "-A", "--", "docs/specs", "spec.md"]);
+        git(projectDir, [
+            "commit",
+            "-q",
+            "-m",
+            `docs(specs): ${r.requirement} needs clarification — ${asked.question}\n\n${r.question}`,
+        ]);
+        r.error = `Needs clarification: ${asked.question} in ${asked.file} — specgate answer ${asked.question} "…"`;
+        info(`${r.requirement}: ${asked.question} recorded in ${asked.file}; answer it with specgate answer`);
+    }
+}
 /** Where a run's record lands. Local to the machine — see `writeRunRecord`. */
 exports.RUNS_DIR = path.join(".harness", "runs");
 /**
@@ -1887,13 +1988,20 @@ function printReport(results, format, recorded) {
         fail: `${ui.c.bad}${ui.sym.fail}${ui.c.reset}`,
         blocked: `${ui.c.warn}${ui.sym.warn}${ui.c.reset}`,
         skipped: `${ui.c.muted}${ui.sym.empty}${ui.c.reset}`,
+        question: `${ui.c.warn}?${ui.c.reset}`,
+    };
+    const COLOR = {
+        pass: ui.c.ok,
+        fail: ui.c.bad,
+        blocked: ui.c.warn,
+        skipped: ui.c.muted,
+        question: ui.c.warn,
     };
-    const COLOR = { pass: ui.c.ok, fail: ui.c.bad, blocked: ui.c.warn, skipped: ui.c.muted };
     const idWidth = Math.max(9, ...results.map((r) => String(r.requirement).length));
     process.stdout.write("\n" + ui.section("Harness report"));
     for (const r of results) {
         process.stdout.write(`  ${MARK[r.result] || MARK.fail}  ${ui.c.bold}${ui.pad(String(r.requirement), idWidth)}${ui.c.reset} ` +
-            `${COLOR[r.result] || ""}${ui.pad(r.result, 8)}${ui.c.reset}` +
+            `${COLOR[r.result] || ""}${ui.pad(r.result, 9)}${ui.c.reset}` +
             ui.muted(`${r.attempts} attempt${r.attempts === 1 ? "" : "s"}`) +
             `   ${ui.c.accent}${ui.sym.arrow} ${r.branch}${ui.c.reset}\n`);
         const sub = (t) => process.stdout.write(`       ${t}\n`);
@@ -2014,6 +2122,14 @@ async function runChain(pending, ctx, hintByReq) {
                 results.push(notAttempted(rest, rest.requirement, reason));
             }
         };
+        // REQ-209: a stop asked while the last requirement ran starts no other.
+        if (i > 0 && (0, harness_guard_1.takeStop)(projectDir)) {
+            for (const rest of pending.slice(i)) {
+                results.push(notAttempted(rest, rest.requirement, "a stop was asked"));
+            }
+            info(`stopped as asked: ${pending.length - i} requirement(s) not attempted`);
+            break;
+        }
         const [result] = await runLevels([req], ctx, {
             concurrency: 1,
             hintByReq,
@@ -2319,6 +2435,11 @@ async function runLevels(pending, ctx, opts) {
             mayStart: () => {
                 if (stoppedBy)
                     return false;
+                // REQ-209: a stop asked while a requirement ran starts no other.
+                if (started > 0 && (0, harness_guard_1.takeStop)(ctx.projectDir)) {
+                    stoppedBy = { stop: true, code: "stop_asked", reason: "a stop was asked" };
+                    return false;
+                }
                 const verdict = (0, RunBudget_1.budgetVerdict)(limits, { startedAt: budgetStartedAt, started }, Date.now());
                 if (verdict.stop) {
                     stoppedBy = verdict;
@@ -2378,6 +2499,9 @@ class RunCommand extends command_1.BaseCommand {
             const args = parseArgs(this.args);
             setJsonMode(args.format === "json");
             const projectDir = (0, project_root_1.resolveProjectDir)(args.projectDir, { requireSentinel: true });
+            // REQ-211: a profile chosen for this run is its agent, ahead of the file's.
+            if (args.profile && !args.agent)
+                args.agent = (0, HarnessConfigFile_1.resolveProfileAgent)(projectDir, args.profile);
             const fileConfig = (0, HarnessConfigFile_1.readHarnessConfig)(projectDir);
             const settings = (0, HarnessConfigFile_1.resolveHarnessSettings)(fileConfig, args);
             // A fresh worktree has no dependencies. Unless told, install what the
@@ -2390,7 +2514,7 @@ class RunCommand extends command_1.BaseCommand {
             // may declare profiles without ever writing a `harness.config.yaml`.
             // Reaching them through the config reader made them silently absent
             // there — the same gap the cost hints had, found the same way.
-            if (settings.profileRules.length === 0) {
+            if (settings.profileRules.length === 0 && !args.profile) {
                 const rules = (0, HarnessConfigFile_1.readProfileRules)(projectDir);
                 if (rules.length > 0) {
                     settings.profileRules = rules;
@@ -2441,6 +2565,7 @@ class RunCommand extends command_1.BaseCommand {
             const hintByReq = new Map((plan.next_steps || []).map((s) => [s.requirement, s.hint]));
             if (args.dryRun) {
                 process.stdout.write(ui.header("harness run", `dry run · ${pending.length} requirement(s) would be processed`) +
+                    (settings.agent ? ui.kv("Agent", settings.agent, 14) : "") +
                     ui.kv("Setup", settings.setupCmd || "none", 14) +
                     (args.chain ? ui.kv("Chain", "each green requirement merged into this branch", 14) : ""));
                 for (const req of pending) {
@@ -2537,6 +2662,8 @@ class RunCommand extends command_1.BaseCommand {
                         (holder ? ` on ${holder.reqs.join(", ")}` : "") +
                         `. Wait for it to finish: its post-merge gate runs in this working copy.`);
                 }
+                // A stop left from an earlier run is not this run's (REQ-209).
+                (0, harness_guard_1.takeStop)(projectDir);
             }
             // What the live view lists as up next (REQ-182).
             if (!process.env.SPECGATE_HARNESS_WORKER) {
@@ -2550,6 +2677,9 @@ class RunCommand extends command_1.BaseCommand {
                     hintByReq,
                     runOne: dispatchLevel,
                 });
+            // What the agents asked goes into the project, once the run is done (REQ-189).
+            if (!process.env.SPECGATE_HARNESS_WORKER)
+                recordQuestions(projectDir, results);
             // Only the run that a person started writes a record. A worker is one
             // slice of that run, and its own record would be a second copy of the
             // same requirement — `harness report` reads every file in the directory,