xcoder-dna 0.0.0-stage → 1.3.1

package/dist/orchestrator/task-factory.js

@@ -0,0 +1,176 @@
+import { getStageRole, classifyIntake } from "../sdlc-runtime/sdlc-skill.js";
+import { shortId } from "../util/ids.js";
+export function deliverableFor(stage) {
+    const map = {
+        requirements: "A requirements document: goal, non-goals, constraints, first-pass acceptance criteria.",
+        design: "A design document: components, interfaces/contracts, and stated tradeoffs.",
+        code: "Working implementation matching the design, with files_touched listing every file written.",
+        refactor: "A corrected implementation targeting the specific defect, with files_touched listed.",
+        test: "A test suite plus a run of it, with pass/fail counts in self_check.",
+        ui_api_test: "A test run result: which steps passed/failed against the live URL.",
+        fix_defect: "Confirmation the original defect no longer reproduces, via a real test run.",
+        document: "Human-readable documentation of what was built/changed and why.",
+        deploy: "A deployment result plus an independent verification (health check, smoke test).",
+        conversation: "A direct answer. No further deliverable contract.",
+        quality_gate: "A pass/fail verdict with a reason: { passed: boolean, reason: string }.",
+    };
+    return map[stage];
+}
+export function acceptanceCriteriaFor(stage) {
+    const base = {
+        requirements: [
+            { id: "AC1", type: "rubric", description: "Goal is stated as a concrete, checkable outcome, not a restatement of the input." },
+            { id: "AC2", type: "rubric", description: "Non-goals and constraints are explicit." },
+            { id: "AC3", type: "file-exists", description: "A detailed technical requirement document was persisted to .xcoder/backlog/", pathGlob: ".xcoder/backlog/*requirements*.md" },
+        ],
+        design: [
+            { id: "AC1", type: "rubric", description: "Every component named in requirements has a defined interface." },
+            { id: "AC2", type: "rubric", description: "At least one tradeoff is stated explicitly, not left implicit." },
+        ],
+        code: [
+            { id: "AC1", type: "schema", description: "Every file referenced in the design was actually written (files_touched is non-empty)." },
+            { id: "AC2", type: "command", description: "The project's own build/typecheck command exits 0.", command: "npm run typecheck" },
+        ],
+        refactor: [
+            { id: "AC1", type: "command", description: "The project's own build/typecheck command exits 0.", command: "npm run typecheck" },
+            { id: "AC2", type: "command", description: "The project's own test command exits 0, including a case for the reported defect.", command: "npm test" },
+        ],
+        test: [
+            { id: "AC1", type: "schema", description: "self_check.ran === true." },
+            { id: "AC2", type: "schema", description: "self_check.passed === true." },
+            { id: "AC3", type: "command", description: "The full regression suite passes independently.", command: "npm run regression" },
+        ],
+        ui_api_test: [
+            { id: "AC1", type: "schema", description: "Every declared step reported ok === true." },
+        ],
+        fix_defect: [
+            { id: "AC1", type: "command", description: "A targeted re-run confirms the original defect no longer reproduces.", command: "npm test" },
+        ],
+        document: [
+            { id: "AC1", type: "rubric", description: "Documentation references concrete specifics from upstream context, not generic boilerplate." },
+        ],
+        deploy: [
+            { id: "AC1", type: "rubric", description: "An independent post-deploy check (not the deploy command's own exit code) confirms health." },
+        ],
+        conversation: [],
+        quality_gate: [
+            { id: "AC1", type: "schema", description: "deliverable contains passed: boolean and reason: string" },
+        ],
+    };
+    return base[stage];
+}
+/**
+ * Builds the initial DAG for a non-conversation task. Deliberately linear
+ * for v1 (matching the brief's stage sequences) rather than inventing
+ * parallel branches Xcoder SDLC has no evidence justify — the swarm dispatcher
+ * (see `orchestrator/swarm.ts`) is what actually gives you fan-out, once a
+ * `replan` action splits a stage into independent nodes (e.g. multiple
+ * files to implement in parallel). Nodes are fully self-contained: a Sub
+ * Agent needs nothing beyond the node it's handed.
+ */
+export function buildInitialPlan(spec) {
+    const rule = classifyIntake(spec.inputs);
+    const nodes = [];
+    let previousId = null;
+    for (const stage of rule.sequence) {
+        const id = `${stage}-${shortId("st")}`;
+        const role = getStageRole(stage, spec.inputs);
+        const node = {
+            id,
+            stage,
+            role,
+            engine: "react-v1",
+            dependsOn: previousId ? [previousId] : [],
+            goal: buildGoalText(stage, spec),
+            upstreamContext: {},
+            deliverableSpec: deliverableFor(stage),
+            acceptanceCriteria: acceptanceCriteriaFor(stage),
+            status: previousId ? "pending" : "ready",
+            healing: { attempts: 0, maxAttempts: spec.constraints.maxHealingAttempts, log: [] },
+        };
+        nodes.push(node);
+        previousId = id;
+    }
+    // If any code or refactor stages are present, ensure the document stage
+    // also covers the blueprint update requirement
+    const hasCode = nodes.some((n) => n.stage === "code" || n.stage === "refactor");
+    if (hasCode) {
+        const existingDoc = nodes.find((n) => n.stage === "document");
+        if (existingDoc) {
+            // Extend existing document node's goal to include blueprint update
+            existingDoc.goal = `${existingDoc.goal}. Also update .xcoder/blueprint.md with the current architecture, workflow, and features.`;
+        }
+        else {
+            const id = `document-${shortId("st")}`;
+            const docNode = {
+                id,
+                stage: "document",
+                role: "architect",
+                engine: "react-v1",
+                dependsOn: previousId ? [previousId] : [],
+                goal: "Update .xcoder/blueprint.md with the current architecture, workflow, and features. Document what was changed in this task.",
+                upstreamContext: {},
+                deliverableSpec: deliverableFor("document"),
+                acceptanceCriteria: [
+                    ...acceptanceCriteriaFor("document"),
+                    { id: "BP1", type: "file-exists", description: "Blueprint doc exists", pathGlob: ".xcoder/blueprint.md" },
+                ],
+                status: previousId ? "pending" : "ready",
+                healing: { attempts: 0, maxAttempts: spec.constraints.maxHealingAttempts, log: [] },
+            };
+            nodes.push(docNode);
+        }
+    }
+    return nodes;
+}
+function buildGoalText(stage, spec, defectPath, upstreamFolders) {
+    const { inputs } = spec;
+    switch (stage) {
+        case "requirements":
+            return `Explore and write requirements for: ${spec.goal}`;
+        case "design":
+            return `Design a solution for: ${spec.goal}${inputs.design ? `\n\nStarting point/reference: ${inputs.design}` : ""}`;
+        case "code":
+            return `Implement: ${spec.goal}${inputs.design ? `\n\nDesign to implement against: ${inputs.design}` : ""}`;
+        case "refactor":
+            return `Fix the following defect in the existing code at "${inputs.code}":\n${inputs.defectDetail}\n\nGoal: ${spec.goal}`;
+        case "test": {
+            const base = `Write and run unit tests for the code at "${inputs.code}". Goal: ${spec.goal}`;
+            if (upstreamFolders && upstreamFolders.length > 0) {
+                const vitestArgs = upstreamFolders
+                    .map((f) => `"src/${f}/**/*.test.ts"`)
+                    .join(" ");
+                const scopeLine = `FOLDER_SCOPE: Run tests only for these top-level src/ folders: ${upstreamFolders.join(", ")}. Use npx vitest with per-folder file paths: npx vitest run --config vitest.config.ts ${vitestArgs}. Per-folder timeout 60s.`;
+                return `${scopeLine}\n\n${base}`;
+            }
+            return base;
+        }
+        case "ui_api_test":
+            return `Run UI/API validation against ${inputs.url}. Goal: ${spec.goal}${inputs.credentialRef ? ` (credential available via ref "${inputs.credentialRef}")` : ""}`;
+        case "fix_defect":
+            if (defectPath) {
+                return `Confirm the defect described in ${defectPath} no longer reproduces, via a real test run.`;
+            }
+            return `Confirm the defect fixed in the prior stage no longer reproduces.`;
+        case "document":
+            return `Document what was built/changed for: ${spec.goal}`;
+        case "deploy":
+            return `Deploy and verify: ${spec.goal}`;
+        case "conversation":
+            return spec.goal;
+        case "quality_gate":
+            return spec.goal; // quality-gate nodes have their own goal from DAG builder
+    }
+}
+export function isConversation(spec) {
+    return classifyIntake(spec.inputs).startStage === "conversation";
+}
+export function buildTaskSpec(rawTask, cliInputs, constraints) {
+    return {
+        taskId: shortId("task"),
+        goal: rawTask,
+        inputs: { freeText: rawTask, ...cliInputs },
+        constraints,
+        createdAt: new Date().toISOString(),
+    };
+}

package/dist/orchestrator/validation-gate.d.ts

@@ -0,0 +1,23 @@
+import type { SubtaskNode, SubtaskResult } from "../types.js";
+export interface ValidationOutcome {
+    passed: boolean;
+    report: string;
+    perCriterion: {
+        id: string;
+        passed: boolean;
+        detail: string;
+    }[];
+}
+/**
+ * Deliberately validates against THIS SUBTASK's own acceptance criteria —
+ * never the overall task goal. A "write unit tests" subtask can't be
+ * judged against "build a REST API"; it has its own local spec (see
+ * `task-factory.ts`'s `acceptanceCriteriaFor`), and that's what this checks.
+ * Task-level rollup (did the whole thing satisfy the original goal) is a
+ * separate, later step — see `sdlc-orchestrator.ts`'s summarize step.
+ *
+ * Also deliberately independent of the Sub Agent's own `self_check` — an
+ * agent grading its own homework is exactly the failure mode a validation
+ * gate exists to catch.
+ */
+export declare function validateSubtask(node: SubtaskNode, result: SubtaskResult, workspaceRoot: string): Promise<ValidationOutcome>;

package/dist/orchestrator/validation-gate.js

@@ -0,0 +1,155 @@
+// xcoder:version 5 | xcoder:task task-f1ac77 | xcoder:updated 2026-10-17T04:10:33.907Z | xcoder:subtask code-st-1d0003
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { runCommandTool } from "../tools/shell-tool.js";
+import { inferLayers } from "../skills/secure-architect.bylaws.js";
+import { reviewDeliverable, describeReview } from "../skills/bylaw-review.js";
+/**
+ * Deliberately validates against THIS SUBTASK's own acceptance criteria —
+ * never the overall task goal. A "write unit tests" subtask can't be
+ * judged against "build a REST API"; it has its own local spec (see
+ * `task-factory.ts`'s `acceptanceCriteriaFor`), and that's what this checks.
+ * Task-level rollup (did the whole thing satisfy the original goal) is a
+ * separate, later step — see `sdlc-orchestrator.ts`'s summarize step.
+ *
+ * Also deliberately independent of the Sub Agent's own `self_check` — an
+ * agent grading its own homework is exactly the failure mode a validation
+ * gate exists to catch.
+ */
+export async function validateSubtask(node, result, workspaceRoot) {
+    const perCriterion = [];
+    for (const ac of node.acceptanceCriteria) {
+        perCriterion.push(await checkCriterion(ac, result, workspaceRoot, node.goal));
+    }
+    const passed = perCriterion.every((c) => c.passed);
+    const report = passed
+        ? "all acceptance criteria met"
+        : `failed: ${perCriterion
+            .filter((c) => !c.passed)
+            .map((c) => `[${c.id}] ${c.detail}`)
+            .join("; ")}`;
+    return { passed, report, perCriterion };
+}
+async function checkCriterion(ac, result, workspaceRoot, goal = "") {
+    if (result.deliverable === null && result.raoTrace.length === 0) {
+        return { id: ac.id, passed: false, detail: "subtask produced no deliverable at all" };
+    }
+    switch (ac.type) {
+        case "schema": {
+            // A conservative structural check: does the subtask claim to have
+            // produced *something* concrete for this criterion (a non-empty
+            // files_touched, or a self_check that actually ran)?
+            if (ac.description.toLowerCase().includes("files_touched")) {
+                const ok = result.filesTouched.length > 0;
+                return { id: ac.id, passed: ok, detail: ok ? "files_touched is non-empty" : "no files were reported written" };
+            }
+            if (ac.description.toLowerCase().includes("self_check.passed")) {
+                const ok = result.selfCheck?.passed === true;
+                return { id: ac.id, passed: ok, detail: ok ? "self_check reported passed" : "self_check missing or not passed" };
+            }
+            // Generic structural fallback: deliverable must be present and non-empty.
+            const ok = result.deliverable !== null && result.deliverable !== undefined && result.deliverable !== "";
+            return { id: ac.id, passed: ok, detail: ok ? "deliverable present" : "deliverable is empty/null" };
+        }
+        case "command": {
+            if (!ac.command) {
+                // No explicit re-check command declared on the node — fall back to
+                // trusting the agent's own self_check ran, but flag that this is
+                // weaker than an independent re-run.
+                const ran = result.selfCheck?.ran === true;
+                const passed = ran && result.selfCheck?.passed === true;
+                return {
+                    id: ac.id,
+                    passed,
+                    detail: passed
+                        ? "no independent command configured; agent-reported self_check passed"
+                        : "no independent command configured and self_check did not report a pass",
+                };
+            }
+            const cmdResult = await runCommandTool(ac.command, workspaceRoot, 120_000);
+            return {
+                id: ac.id,
+                passed: cmdResult.ok,
+                detail: cmdResult.ok
+                    ? `\`${ac.command}\` exited 0`
+                    : `\`${ac.command}\` exited ${cmdResult.exitCode}: ${cmdResult.stderr.slice(0, 300)}`,
+            };
+        }
+        case "file-exists": {
+            if (!ac.pathGlob) {
+                return { id: ac.id, passed: false, detail: "file-exists criterion missing pathGlob" };
+            }
+            const pattern = path.resolve(workspaceRoot, ac.pathGlob);
+            const globResult = await globFiles(pattern);
+            if (globResult.length > 0) {
+                return {
+                    id: ac.id,
+                    passed: true,
+                    detail: `Found ${globResult.length} file(s) matching "${ac.pathGlob}": ${globResult[0]}`,
+                };
+            }
+            return {
+                id: ac.id,
+                passed: false,
+                detail: `No files found matching "${ac.pathGlob}" in workspace`,
+            };
+        }
+        case "bylaw-review": {
+            // Deliberately independent of the agent's own `passed` flag: the
+            // verdict is computed by the bylaws module from the findings the
+            // agent reported. A gate that grades its own homework is not a gate.
+            const layers = ac.bylawLayers ?? inferLayers(goal);
+            const review = reviewDeliverable(result.deliverable, layers);
+            return {
+                id: ac.id,
+                passed: review.approved,
+                detail: review.approved
+                    ? "bylaw review approved (" + layers.join(", ") + ")"
+                    : describeReview(review),
+            };
+        }
+        case "rubric": {
+            // A lightweight heuristic rubric check for v1: the deliverable must
+            // be non-trivial (not a one-word non-answer) and the summary must
+            // reference the criterion's own key terms loosely. A true LLM-critic
+            // rubric pass (a separate model call judging semantic correctness)
+            // is a documented extension point — see README "Extending validation".
+            const text = JSON.stringify(result.deliverable ?? "") + " " + result.summary;
+            const ok = text.trim().length > 20;
+            return { id: ac.id, passed: ok, detail: ok ? "heuristic rubric check passed (non-trivial deliverable)" : "deliverable too thin to satisfy rubric" };
+        }
+    }
+}
+/**
+ * Minimal glob resolver using Node.js fs — avoids pulling in a heavy glob
+ * dependency for the straightforward wildcard patterns we need here.
+ */
+async function globFiles(pattern) {
+    const dir = path.dirname(pattern);
+    const base = path.basename(pattern);
+    // Convert glob wildcards to a regex: * → .*, ? → .
+    const escaped = base.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp("^" + escaped.replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+    const matches = [];
+    try {
+        const entries = await fs.readdir(dir);
+        for (const entry of entries) {
+            if (re.test(entry)) {
+                try {
+                    const full = path.join(dir, entry);
+                    const stat = await fs.stat(full);
+                    if (stat.isFile()) {
+                        matches.push(full);
+                    }
+                }
+                catch {
+                    // skip unreadable entries
+                }
+            }
+        }
+    }
+    catch {
+        // directory doesn't exist — no matches
+    }
+    return matches;
+}

package/dist/protocol/react-contract.d.ts

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import type { SubtaskNode } from "../types.js";
+import type { ToolManifestEntry } from "../tools/tool-registry.js";
+import { type EnvironmentInfo } from "../util/env-info.js";
+import { type DetectedCommands } from "../tools/project-detect.js";
+export interface AgentSystemPromptOptions {
+    agentName: string;
+    roleDescription: string;
+    directive: string;
+    skills: string[];
+    tools: ToolManifestEntry[];
+    environment: EnvironmentInfo;
+    detectedCommands: DetectedCommands;
+    goal?: string;
+    upstreamContext?: string;
+    protocolOverride?: string;
+    isStandalone?: boolean;
+    /** Injected between skills and tools — loaded from .xcoder/lesson.md. */
+    lessonContext?: string;
+    /** Injected immediately after the role directive, before the tool manifest.
+     *  Rendered per-subtask by src/skills/bylaw-context.ts. Absent => prompt unchanged. */
+    bylawContext?: string;
+}
+/**
+ * THE CONTRACT.
+ *
+ * Every turn, in both directions, is exactly this shape. No prose outside
+ * the JSON, no partial objects, no both-action-and-final_answer. A message
+ * that doesn't parse against this schema is never silently "interpreted" —
+ * it's bounced back to the model as a typed protocol_error observation, and
+ * that costs it an iteration. This is what "protocol to adhere to" means in
+ * practice: the parser is the enforcement mechanism, not the prompt wording.
+ */
+export declare const ReactMessageSchema: z.ZodObject<{
+    thought: z.ZodString;
+    action: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        tool: z.ZodString;
+        input: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+    final_answer: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        summary: z.ZodString;
+        deliverable: z.ZodUnknown;
+        files_touched: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        self_check: z.ZodOptional<z.ZodObject<{
+            ran: z.ZodBoolean;
+            passed: z.ZodBoolean;
+            detail: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ReactMessage = z.infer<typeof ReactMessageSchema>;
+export type ParsedReactMessage = {
+    ok: true;
+    message: ReactMessage;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Layer 1: Strip outermost XML envelope tags from model output.
+ * Handles tags like <thought>, <thinking>, <response>, <answer>
+ * (case-insensitive, outer-tags only). This prevents "Unexpected token '<'"
+ * parse errors when the model wraps JSON inside XML-style tags.
+ */
+export declare function stripXmlTags(raw: string): string;
+/**
+ * Layer 1.5: Escape raw control characters (newline, tab, CR, etc.) that
+ * appear *inside* JSON string literals.
+ *
+ * Root cause this repairs: the JSON spec forbids literal U+0000–U+001F
+ * inside a string value — they must be written as `\n`, `\t`, `\uXXXX`,
+ * etc. Models very frequently violate this when a string value itself
+ * contains multi-line content (e.g. `action.input.content` for a
+ * write_file call carrying markdown/code). `JSON.parse` rejects the whole
+ * payload with "Bad control character in string literal" and none of the
+ * other layers repair it — XML-stripping and outermost-extraction only
+ * fix structural wrapping, not the string contents. Left unrepaired, the
+ * model has to reproduce the *entire* (often large) payload again with
+ * manual escaping, and frequently fails repeatedly, burning tokens each
+ * retry.
+ *
+ * Uses the same string-aware, escape-aware single pass as
+ * extractOutermostJson so it never touches control characters that sit
+ * outside of a string literal (e.g. the newlines a model puts between
+ * prose and the JSON block, which are harmless and should be left alone).
+ */
+export declare function sanitizeControlCharacters(raw: string): string;
+/**
+ * Layer 2: Extract the outermost balanced {...} JSON block from a string.
+ * Uses a single-pass O(n) brace counter with string-awareness (handles
+ * escaped quotes inside strings). Returns the JSON substring, or empty
+ * string if no balanced braces are found.
+ */
+export declare function extractOutermostJson(raw: string): string;
+/**
+ * Layer 3: Normalize known LLM JSON-shape drifts before Zod validation.
+ * Operates on the already-parsed (but not yet schema-validated) object.
+ *
+ * Four drifts repaired, in fixed order:
+ *   1. Missing top-level `thought` — backfilled from prose preceding the JSON.
+ *   2. Bare `{tool, input}` — auto-wrapped as `{action: {tool, input}}`.
+ *   3. `thought` nested inside `action` — hoisted to top level.
+ *   4. Legacy `command` key inside `action` — renamed to `tool` (only when `tool` is absent).
+ *
+ * @param raw   - The post-Layer-1 string (still contains prose prefix if present).
+ * @param json  - The parsed JSON `unknown` object from Layer 2.
+ * @returns     - `{ normalized: unknown; applied: boolean; steps: string[] }`
+ */
+export declare function normalizeReactShape(raw: string, json: unknown): {
+    normalized: unknown;
+    applied: boolean;
+    steps: string[];
+};
+export declare function parseReactMessage(raw: string): ParsedReactMessage;
+/**
+ * Build a system prompt for any agent (Sub Agent or Samurai) from a common
+ * set of inputs. The prompt format is shared across both agent types — only
+ * the identity block, goal/context section, and framing differ.
+ */
+export declare function buildAgentSystemPrompt(opts: AgentSystemPromptOptions): string;
+/**
+ * Thin wrapper around buildAgentSystemPrompt that maps a SubtaskNode onto
+ * the generic AgentSystemPromptOptions shape. Kept for backward
+ * compatibility with the existing SubAgent caller.
+ */
+export declare function buildSystemPrompt(opts: {
+    role: string;
+    directive: string;
+    skills: string[];
+    tools: ToolManifestEntry[];
+    subtask: SubtaskNode;
+    environment: EnvironmentInfo;
+    detectedCommands: DetectedCommands;
+    /** Optional workspace-level protocol section injected into the prompt. */
+    protocolOverride?: string;
+}): string;