@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.bf78fdcaa623

package/dist/session/phase-completion.prompts.d.ts

@@ -0,0 +1,14 @@
+import { type CompletionPhase, type DebugCompletionPhase, type DecomposeCompletionGate, type DevelopCompletionPhase, type DraftCompletionGate, type QaCompletionGate } from "./phase-completion.js";
+export declare function completionPromptForPhase(phase: CompletionPhase): string;
+export declare function completionPromptForDevelopCycle(phase: CompletionPhase): string;
+export declare function completionPromptForQaCycle(currentGate?: QaCompletionGate): string;
+export declare function completionPromptForDraftCycle(currentGate?: DraftCompletionGate): string;
+export declare function completionPromptForDecomposeCycle(currentGate?: DecomposeCompletionGate): string;
+export declare function completionPromptForDebugCycle(currentGate?: DebugCompletionPhase): string;
+export declare function nextPhaseAfter(phase: CompletionPhase): DevelopCompletionPhase | null;
+export declare function nextDebugPhaseAfter(phase: DebugCompletionPhase): DebugCompletionPhase | null;
+export declare function completionToolNextInstruction(completedPhase: CompletionPhase, status: string, nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready"): string;
+export declare function completionToolNextInstructionForDraftGate(completedGate: DraftCompletionGate, status: string, nextGate: DraftCompletionGate | null): string;
+export declare function completionToolNextInstructionForQaGate(completedGate: QaCompletionGate, status: string, nextGate: QaCompletionGate | null): string;
+export declare function completionToolNextInstructionForDecomposeGate(completedGate: DecomposeCompletionGate, status: string, nextGate: DecomposeCompletionGate | null): string;
+export declare function completionToolNextInstructionForDebugGate(completedGate: DebugCompletionPhase, status: string, nextGate: DebugCompletionPhase | null): string;

package/dist/session/phase-completion.prompts.js

@@ -0,0 +1,220 @@
+import { completionPhaseOrder, completionToolNamesForPhase, debugCompletionPhaseOrder, expectedCompletionToolName, expectedDebugCompletionToolName, expectedDecomposeCompletionToolName, phaseFiles, toolServerName } from "./phase-completion.js";
+import { isDebugCompletionPhase, isDevelopCompletionPhase } from "./phase-completion.validation.js";
+export function completionPromptForPhase(phase) {
+    const toolName = expectedCompletionToolName(phase);
+    const alias = completionToolNamesForPhase(phase).find((name) => name !== toolName);
+    const artifactName = phaseFiles[phase].jsonFileName;
+    if (phase === "qa") {
+        return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write QA artifacts by hand. When QA is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required structured QA payload.
+That tool writes the durable QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
+Use \`status: "pass"\` only when the validated changes satisfy acceptance criteria with concrete evidence. Use \`status: "needs_rework"\` with actionable in-scope findings, or \`status: "blocked"\` with a concrete blocker_reason.
+Include \`policy_warnings\` for non-blocking Forge policy or scope mismatches that should remain visible after QA.
+Forge will mirror only the tool-written QA artifacts; reporting QA completion in prose is not enough.`;
+    }
+    if (phase === "architect") {
+        return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write Architect artifacts by hand. When the plan is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the full structured Architect planning payload.
+That tool writes \`.forge/work-items/{workItemId}/artifacts/implementation.plan.json\`, \`qa.plan.json\`, \`${artifactName}\`, and \`architect.report.md\`.
+The payload must put \`phases\`, \`tasks\`, \`dependencies\`, and \`phase_gates\` as top-level fields inside \`implementation_plan\`, for example:
+\`{ "status": "pass", "summary": "...", "implementation_plan": { "schema_version": 1, "plan_id": "plan-...", "phases": [{ "id": "phase-1", "tasks": ["task-1"], "gate": "gate-1" }], "tasks": [{ "id": "task-1", "verification_scope": { "schema_version": 1, "surface": ["domain_contract"], "required_evidence": ["unit_tests"], "not_applicable": ["browser_manual", "api_http"], "browser_required": false, "api_required": false, "rationale": "Backend-only child task." }, "tests": [{ "command": "npm test" }] }], "dependencies": [], "phase_gates": [{ "id": "gate-1", "phase": "phase-1" }] }, "qa_plan": { "schema_version": 1, "final_qa": [{ "id": "qa-1", "coverage": "..." }] }, "report_markdown": "# Architect Report" }\`.
+\`implementation_plan.tasks\` are Develop child tasks only: each task should include \`verification_scope\` describing task-level QA evidence, and must require a focused repo/product implementation change. Put parent-story QA, sign-off, child-count/materialization inventory, parent plan artifact checks, and final integrated acceptance proof in \`qa_plan.final_qa\`, not as child Develop tasks.
+Dependency entries use canonical \`before\` and \`after\` task ids, for example \`{ "before": "task-1", "after": "task-2" }\`. Forge accepts \`from\`/\`to\` only as aliases and normalizes them before writing artifacts.
+Use \`status: "pass"\` for a valid pending-approval plan, \`needs_revision\` when story/design input must change, or \`blocked\` with a concrete blocker.
+Forge will mirror only the tool-written Architect artifacts; reporting the plan in prose is not enough.`;
+    }
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write phase artifacts by hand. When the phase is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required evidence payload.
+That tool writes \`.forge/work-items/{workItemId}/artifacts/${artifactName}\` and returns the artifact reference that Forge will mirror through the existing phase-artifact pipeline.
+If the work cannot pass, call the same tool with a non-pass status and explicit blockers instead of reporting completion in prose only.`;
+}
+export function completionPromptForDevelopCycle(phase) {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write phase artifacts by hand. The tool server enforces phase order and starts this run in \`${phase}\`.
+Complete the dev cycle in order inside this same provider session:
+1. Call \`forge.complete_implementation(...)\` when implementation evidence is ready.
+2. Follow the returned self-review instruction, then call \`forge.complete_self_review(...)\`.
+3. Follow the returned validation instruction, then call \`forge.complete_validation(...)\`.
+Each tool writes the canonical artifact under \`.forge/work-items/{workItemId}/artifacts/\` and returns the next-phase instruction Forge expects you to follow.
+If the current phase cannot pass, call the current phase tool with a non-pass status and explicit blockers instead of reporting completion in prose only.`;
+}
+export function completionPromptForQaCycle(currentGate = "qa_plan") {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write QA artifacts by hand. The tool server enforces QA gate order and starts this run at \`${currentGate}\`.
+Complete the QA cycle in order inside this same provider session:
+1. Call \`forge.complete_qa_plan(...)\` after the QA test plan/checklist is ready.
+2. Follow the returned regression instruction, then call \`forge.complete_qa_regression(...)\`.
+3. Follow the returned API/backend instruction, then call \`forge.complete_qa_api(...)\`.
+4. Follow the returned manual web instruction, then call \`forge.complete_qa_manual_web(...)\`.
+5. Follow the returned bug reproduction instruction, then call \`forge.complete_qa_bug_repro(...)\`.
+6. Follow the returned findings instruction, then call \`forge.complete_qa_findings(...)\`.
+7. Follow the returned verdict instruction, then call \`forge.complete_qa_verdict(...)\`.
+Use \`status: "skipped"\` with a reason for gates that are not applicable. If a gate is blocked, keep moving through later gates as skipped due to the blocker and finish with a blocked verdict.
+The final verdict tool writes the canonical QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
+Include \`policy_warnings\` in the final verdict for non-blocking Forge policy or scope mismatches that should remain visible after QA.
+The legacy \`forge.complete_qa\` one-shot tool is not available in normal QA-cycle mode. Reporting QA completion in prose is not enough.`;
+}
+export function completionPromptForDraftCycle(currentGate = "draft_intent") {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not finish Draft by prose or raw JSON. The tool server enforces Draft gate order and starts at \`${currentGate}\`.
+Complete the Draft cycle in order inside this same provider session:
+1. Call \`forge.complete_draft_intent(...)\` after interpreting user intent and non-goals.
+2. Follow the returned repo-context instruction, inspect selected project/repo assumptions, then call \`forge.complete_draft_repo_context(...)\`.
+3. Follow the returned graph-context instruction, account for DAG/dependency placement, then call \`forge.complete_draft_graph_context(...)\`.
+4. Follow the returned product-scope instruction, choose product scope for the selected project, then call \`forge.complete_draft_product_scope(...)\`.
+5. Follow the returned draft-plan instruction, draft the requested final JSON shape for the current Draft kind, then call \`forge.complete_draft_work_order_plan(...)\`.
+6. Follow the returned critic instruction, critique literalism, wrong-project scope, and decomposition quality, then call \`forge.complete_draft_critic(...)\`.
+7. Follow the returned proposal instruction, then call \`forge.complete_draft_proposal(...)\` with the final Draft JSON payload in \`draft_json\`.
+The final proposal tool writes \`draft.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. Reporting Draft completion in prose is not enough.`;
+}
+export function completionPromptForDecomposeCycle(currentGate = "decompose_subject_intake") {
+    return `# Forge Decompose completion cycle
+You must complete the Decompose gates in order using the Forge MCP tools. Reporting progress in prose is not enough.
+
+Current gate: ${currentGate}
+
+Required order:
+1. Call \`forge.complete_decompose_subject_intake(...)\` after identifying the Work Order/Feature subject, scope, and non-goals.
+2. Follow the returned context-review instruction, inspect injected project/repo/dependency context, then call \`forge.complete_decompose_context_review(...)\`.
+3. Follow the returned breakdown-strategy instruction, choose safe Feature/Story boundaries, then call \`forge.complete_decompose_breakdown_strategy(...)\`.
+4. Follow the returned child-items instruction, draft candidate child items, then call \`forge.complete_decompose_child_items(...)\`.
+5. Follow the returned dependency-graph instruction, validate keys/dependencies/order, then call \`forge.complete_decompose_dependency_graph(...)\`.
+6. Follow the returned critic instruction, critique scope, DAG safety, manual reconciliation risk, and missing acceptance detail, then call \`forge.complete_decompose_critic(...)\`.
+7. Follow the returned proposal instruction, then call \`forge.complete_decompose_proposal(...)\` with final JSON in \`proposal_json\`.
+The final proposal tool writes \`decompose.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. The proposal_json object must contain summary, optional blockedReason, and candidates. Work Order-to-Feature candidates may include \`estimated_qa_scope\`; Feature-to-Story candidates should include \`qa_scope\` with schema_version 1 plus scheduleIndex, waveIndex, expectedOutput, handoffSummary, and dependencyReason for dependency handoff.`;
+}
+export function completionPromptForDebugCycle(currentGate = "debug_repro") {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write Debug artifacts by hand. The tool server enforces Debug gate order and starts this run at \`${currentGate}\`.
+Complete the Debug cycle in order inside this same provider session:
+1. Reproduce or tightly characterize the bug, then call \`forge.complete_debug_repro(...)\`.
+2. Follow the returned root-cause instruction, isolate evidence, then call \`forge.complete_debug_root_cause(...)\`.
+3. Follow the returned fix instruction, apply the smallest safe fix with regression coverage when practical, then call \`forge.complete_debug_fix(...)\`.
+4. Follow the returned regression instruction, prove the original repro is negative and the fix is QA-ready, then call \`forge.complete_debug_regression(...)\`.
+Each tool writes a canonical Debug artifact under \`.forge/work-items/{workItemId}/artifacts/\`: \`debug.repro.json\`, \`debug.root-cause.json\`, \`debug.fix.json\`, and \`debug.regression.json\` plus \`debug.report.md\` when report text is provided or generated.
+Use a non-pass status with explicit blockers when the current Debug gate cannot pass. Reporting Debug completion in prose is not enough; the relevant MCP completion tool is the transition request.`;
+}
+export function nextPhaseAfter(phase) {
+    if (!isDevelopCompletionPhase(phase)) {
+        return null;
+    }
+    const index = completionPhaseOrder.indexOf(phase);
+    return index >= 0 ? completionPhaseOrder[index + 1] ?? null : null;
+}
+export function nextDebugPhaseAfter(phase) {
+    const index = debugCompletionPhaseOrder.indexOf(phase);
+    return index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
+}
+export function completionToolNextInstruction(completedPhase, status, nextPhase) {
+    if (completedPhase === "qa") {
+        if (status === "blocked") {
+            return "QA blocked. Forge recorded the blocker reason and will surface the run for human attention.";
+        }
+        if (status === "needs_rework") {
+            return "QA findings recorded. Forge has the structured evidence needed to route this work back for implementation rework.";
+        }
+        return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
+    }
+    if (status !== "pass") {
+        return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
+    }
+    if (isDebugCompletionPhase(completedPhase)) {
+        const debugNext = isDebugCompletionPhase(nextPhase) ? nextPhase : null;
+        return completionToolNextInstructionForDebugGate(completedPhase, status, debugNext);
+    }
+    if (nextPhase === "self_review") {
+        return "Implementation accepted. Begin self-review: inspect the diff, apply safe fixes, and call forge.complete_self_review with review evidence.";
+    }
+    if (nextPhase === "validation") {
+        return "Self-review accepted. Begin validation: run deterministic checks, prove acceptance criteria, and call forge.complete_validation with command evidence.";
+    }
+    return "Validation accepted. Forge has the structured evidence needed to move this work item to QA.";
+}
+export function completionToolNextInstructionForDraftGate(completedGate, status, nextGate) {
+    if (status === "blocked") {
+        return `Stay in ${completedGate}; record the blocker and retry the same Draft gate when unblocked.`;
+    }
+    if (!nextGate) {
+        return "Draft proposal accepted. Forge has the structured Work Order draft JSON needed to populate the form.";
+    }
+    const instructions = {
+        draft_intent: "Capture intent/non-goals, then call forge.complete_draft_intent.",
+        draft_repo_context: "Inspect selected repo/project assumptions, then call forge.complete_draft_repo_context.",
+        draft_graph_context: "Account for DAG dependencies and placement, then call forge.complete_draft_graph_context.",
+        draft_product_scope: "Choose product scope for the selected project, then call forge.complete_draft_product_scope.",
+        draft_work_order_plan: "Draft the current Draft kind's plan fields, then call forge.complete_draft_work_order_plan.",
+        draft_critic: "Critique literalism/wrong-project scope/decomposition risk, then call forge.complete_draft_critic.",
+        draft_proposal: "Submit final draft_json through forge.complete_draft_proposal."
+    };
+    return `${completedGate} accepted. Continue to ${nextGate}. ${instructions[nextGate]}`;
+}
+export function completionToolNextInstructionForQaGate(completedGate, status, nextGate) {
+    if (!nextGate) {
+        if (status === "blocked") {
+            return "QA blocked. Forge recorded the blocker reason and will surface the run for human attention.";
+        }
+        if (status === "needs_rework") {
+            return "QA findings recorded. Forge has the structured evidence needed to route this work back for implementation rework.";
+        }
+        return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
+    }
+    const skipped = status === "skipped";
+    const blocked = status === "blocked";
+    const prefix = blocked
+        ? `${completedGate} recorded a blocker. Continue through ${nextGate} and mark downstream gates skipped if the blocker prevents evidence collection.`
+        : skipped
+            ? `${completedGate} skipped. Continue to ${nextGate}.`
+            : `${completedGate} accepted. Continue to ${nextGate}.`;
+    return `${prefix} ${qaGateInstruction(nextGate)}`;
+}
+export function completionToolNextInstructionForDecomposeGate(completedGate, status, nextGate) {
+    if (status !== "pass") {
+        return `Stay in ${completedGate}, address the recorded blockers/rework, then call ${expectedDecomposeCompletionToolName(completedGate)} again.`;
+    }
+    if (!nextGate) {
+        return "Decompose proposal accepted. Forge has the structured child-item proposal JSON needed to populate the proposal row.";
+    }
+    const nextInstructions = {
+        decompose_subject_intake: "Capture subject/scope, then call forge.complete_decompose_subject_intake.",
+        decompose_context_review: "Review project/repo/dependency context, then call forge.complete_decompose_context_review.",
+        decompose_breakdown_strategy: "Choose safe child boundaries, then call forge.complete_decompose_breakdown_strategy.",
+        decompose_child_items: "Draft child candidates, then call forge.complete_decompose_child_items.",
+        decompose_dependency_graph: "Validate dependency DAG, then call forge.complete_decompose_dependency_graph.",
+        decompose_critic: "Critique the decomposition, then call forge.complete_decompose_critic.",
+        decompose_proposal: "Submit final proposal_json through forge.complete_decompose_proposal."
+    };
+    return `${completedGate} accepted. ${nextInstructions[nextGate]}`;
+}
+export function completionToolNextInstructionForDebugGate(completedGate, status, nextGate) {
+    if (status !== "pass") {
+        return `Stay in ${completedGate}, address the recorded blockers, then call ${expectedDebugCompletionToolName(completedGate)} again.`;
+    }
+    if (nextGate === "debug_root_cause") {
+        return "Debug repro accepted. Begin root-cause analysis: connect the observed failure to code evidence and call forge.complete_debug_root_cause.";
+    }
+    if (nextGate === "debug_fix") {
+        return "Debug root cause accepted. Apply the smallest safe fix with regression coverage where practical, then call forge.complete_debug_fix.";
+    }
+    if (nextGate === "debug_regression") {
+        return "Debug fix accepted. Prove the original repro is negative, run targeted regression checks, and call forge.complete_debug_regression.";
+    }
+    return "Debug regression accepted. Forge has the structured evidence needed to move this bug fix to QA.";
+}
+function qaGateInstruction(gate) {
+    switch (gate) {
+        case "qa_regression":
+            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression.";
+        case "qa_api":
+            return "Run or explicitly skip applicable API/backend contract checks, then call forge.complete_qa_api.";
+        case "qa_manual_web":
+            return "Run or explicitly skip applicable browser/manual web checks, then call forge.complete_qa_manual_web.";
+        case "qa_bug_repro":
+            return "Reproduce or explicitly skip relevant defects/candidate bugs, then call forge.complete_qa_bug_repro.";
+        case "qa_findings":
+            return "Normalize observations into findings and candidate bugs, then call forge.complete_qa_findings.";
+        case "qa_verdict":
+            return "Assemble the final QA verdict from all prior gate evidence, then call forge.complete_qa_verdict.";
+        case "qa_plan":
+            return "Prepare the QA checklist, then call forge.complete_qa_plan.";
+    }
+}

package/dist/session/phase-completion.runtime.d.ts

@@ -0,0 +1,36 @@
+import { type CompletionToolCallResult, type CompletionToolRuntime, type CompletionToolRuntimeOptions, type CompletionToolServerConfig } from "./phase-completion.js";
+export declare function prepareCompletionToolRuntime(options: CompletionToolRuntimeOptions): Promise<CompletionToolRuntime>;
+export declare function buildCompletionToolServerArgs(config: CompletionToolServerConfig): readonly string[];
+export declare function codexMcpConfigArgs(runtime: CompletionToolRuntime): readonly string[];
+export declare function cursorMcpServerConfig(runtime: CompletionToolRuntime): unknown;
+export declare function completionToolNamesForServer(config: CompletionToolServerConfig): readonly string[];
+export declare class CompletionToolServerSession {
+    private readonly config;
+    private currentPhase;
+    private currentQaGate;
+    private currentDraftGate;
+    private currentDecomposeGate;
+    private completed;
+    constructor(config: CompletionToolServerConfig);
+    get instructions(): string;
+    toolDefinitions(): readonly unknown[];
+    callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult>;
+    private callDecomposeGateTool;
+    private callDraftGateTool;
+    private callDebugGateTool;
+    private callQaGateTool;
+    private advanceAfterPass;
+    private advanceAfterDecomposeGate;
+    private advanceAfterDraftGate;
+    private advanceAfterQaGate;
+    private advanceAfterDebugGate;
+}
+export declare function runCompletionMcpServer(config: CompletionToolServerConfig): Promise<void>;
+export declare function parseCompletionMcpArgs(argv: readonly string[]): {
+    readonly ok: true;
+    readonly config: CompletionToolServerConfig;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export declare function completionRedactionEnv(secrets: readonly string[]): Readonly<Record<string, string>>;