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

package/dist/session/phase-completion.js

@@ -482,7 +482,7 @@ Complete the Draft cycle in order inside this same provider session:
 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 work-order-plan instruction, draft the requested final JSON shape and any candidate boundaries, then call \`forge.complete_draft_work_order_plan(...)\`.
+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.`;
@@ -501,7 +501,7 @@ Required order:
 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.`;
+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}\`.
@@ -1666,7 +1666,7 @@ function completionToolNextInstructionForDraftGate(completedGate, status, nextGa
         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 Work Order fields and candidate Feature boundaries, then call forge.complete_draft_work_order_plan.",
+        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."
     };
@@ -2098,8 +2098,8 @@ function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
             items: commandEvidenceSchema()
         },
         acceptance_criteria: acceptanceCriteriaSchema(),
-        build_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
-        test_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
+        build_status: { type: "string", description: "Required for pass and must be pass." },
+        test_status: { type: "string", description: "Required for pass and must be pass." },
         lint_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
         design_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
         drift_checks: {
@@ -2137,6 +2137,18 @@ function decomposeGateToolInputSchema(gate, baseProperties) {
             acceptanceCriteria: { type: "string" },
             planningPacket: { type: "string" },
             sortOrder: { type: "number" },
+            scheduleIndex: { type: "number", description: "Feature-to-Story total schedule order for dependency-safe execution." },
+            schedule_index: { type: "number", description: "Snake_case alias for scheduleIndex." },
+            waveIndex: { type: "number", description: "Feature-to-Story parallel wave number." },
+            wave_index: { type: "number", description: "Snake_case alias for waveIndex." },
+            featureScheduleIndex: { type: "number", description: "Optional ordering within the Feature." },
+            feature_schedule_index: { type: "number", description: "Snake_case alias for featureScheduleIndex." },
+            expectedOutput: { type: "string", description: "Durable output this Story should produce for dependents." },
+            expected_output: { type: "string", description: "Snake_case alias for expectedOutput." },
+            handoffSummary: { type: "string", description: "How dependent Stories should consume this Story output." },
+            handoff_summary: { type: "string", description: "Snake_case alias for handoffSummary." },
+            dependencyReason: { type: "string", description: "Why this Story depends on its dependsOn predecessors." },
+            dependency_reason: { type: "string", description: "Snake_case alias for dependencyReason." },
             points: { type: "number" },
             dependsOn: { type: "array", items: { type: "string" } },
             estimatedQaScope: qaScopeSchema("Work Order-to-Feature planning QA estimate. This is not dispatch-authoritative QA scope."),
@@ -2500,6 +2512,10 @@ function validatePayloadShape(phase, payload) {
     requireField(payload, "test_status");
     requireField(payload, "lint_status");
     requireField(payload, "design_status");
+    requireAllowedStatus(payload, "build_status", ["pass"]);
+    requireAllowedStatus(payload, "test_status", ["pass"]);
+    requireAllowedStatus(payload, "lint_status", ["pass", "not_applicable"]);
+    requireAllowedStatus(payload, "design_status", ["pass", "not_applicable"]);
     requireArray(payload, "drift_checks");
     requireBoolean(payload, "ready_for_dev_test");
     if (payload.ready_for_dev_test !== true) {

package/dist/session/provider-cli/provider-cli.service.js

@@ -2363,6 +2363,7 @@ Work item: ${dispatch.workItem.id} — ${dispatch.workItem.title}
 Plan only. Do not implement source changes, do not create Develop phase artifacts, and do not mark the spec approved.
 Read injected Forge context under .forge plus the repository shape, then produce a repo-grounded implementation DAG with task tests, phase gates, final QA coverage, and a pending-approval spec.
 Implementation DAG tasks are Develop child tasks only: include focused repo/product implementation changes. Do not create child Develop tasks for parent-story QA, sign-off, materialized child inventory, child-count evidence, parent plan artifact checks, or final integrated acceptance proof; put those checks in qa_plan.final_qa.
+${architectDependencyInstruction(dispatch)}
 ${architectRevisionInstruction(dispatch)}
 Forge owns protocol files: write Architect artifacts only through the completion MCP tool.
 
@@ -2370,6 +2371,39 @@ ${completionPromptForPhase("architect")}
 
 Finish only after calling forge.complete_architect_plan with implementation_plan, qa_plan, status, summary, and report/report_markdown.`;
 }
+function architectDependencyInstruction(dispatch) {
+    if (!dispatch.architectDependencies || dispatch.architectDependencies.prerequisites.length === 0) {
+        return "";
+    }
+    const dependencies = dispatch.architectDependencies.prerequisites
+        .map((dependency, index) => {
+        const schedule = dependency.scheduleIndex === null || dependency.scheduleIndex === undefined
+            ? "schedule index unknown"
+            : `schedule index ${dependency.scheduleIndex}`;
+        const wave = dependency.waveIndex === null || dependency.waveIndex === undefined
+            ? "wave unknown"
+            : `wave ${dependency.waveIndex}`;
+        const featureSchedule = dependency.featureScheduleIndex === null || dependency.featureScheduleIndex === undefined
+            ? ""
+            : `, feature schedule ${dependency.featureScheduleIndex}`;
+        const outputSource = dependency.pullRequestNumber === null || dependency.pullRequestNumber === undefined
+            ? `manual completion on ${dependency.targetBranch}`
+            : `merged PR ${dependency.pullRequestNumber} into ${dependency.targetBranch}`;
+        return `${index + 1}. ${dependency.title} (${dependency.storyId}, ${schedule}, ${wave}${featureSchedule})
+   - Expected output: ${dependency.expectedOutput ?? "Predecessor output recorded by Work Order dependency graph."}
+   - Handoff summary: ${dependency.handoffSummary ?? "Use the predecessor implementation as the foundation for this story."}
+   - Dependency reason: ${dependency.dependencyReason ?? "This story depends on predecessor output."}
+   - Output source: ${outputSource}`;
+    })
+        .join("\n");
+    return `
+Dependency Schedule Context:
+This story is scheduled after predecessor work that should already be available on base branch ${dispatch.architectDependencies.baseBranch}.
+
+${dependencies}
+
+Use this predecessor output as foundation. Do not redesign or recreate predecessor scope. If the expected output is unavailable in the checkout/base branch, stop and report dependency_output_unavailable.`;
+}
 function architectRevisionInstruction(dispatch) {
     if (!dispatch.architectRevision) {
         return "";

package/dist/session/session.types.d.ts

@@ -16,6 +16,7 @@ export interface RunOnceDispatchPacket {
     readonly qaScope?: DispatchQaScope | null;
     readonly qaRework?: DispatchQaReworkContext | null;
     readonly architectRevision?: DispatchArchitectRevisionContext | null;
+    readonly architectDependencies?: DispatchArchitectDependencyContext | null;
     readonly storyDevelop?: DispatchStoryDevelopContext | null;
     readonly storyQa?: DispatchStoryQaContext | null;
     readonly draft?: DispatchDraftPrompt | null;
@@ -69,6 +70,22 @@ export interface DispatchArchitectRevisionContext {
     readonly priorContentHash: string;
     readonly feedback: string;
 }
+export interface DispatchArchitectDependencyContext {
+    readonly baseBranch: string;
+    readonly prerequisites: readonly DispatchArchitectDependencyItemContext[];
+}
+export interface DispatchArchitectDependencyItemContext {
+    readonly storyId: string;
+    readonly title: string;
+    readonly scheduleIndex?: number | null;
+    readonly waveIndex?: number | null;
+    readonly featureScheduleIndex?: number | null;
+    readonly expectedOutput?: string | null;
+    readonly handoffSummary?: string | null;
+    readonly dependencyReason?: string | null;
+    readonly pullRequestNumber?: number | null;
+    readonly targetBranch: string;
+}
 export interface DispatchStoryDevelopContext {
     readonly storyWorkItemId: string;
     readonly planId: string;

package/dist/session/session.types.js

@@ -23,6 +23,7 @@ export function parseRunOnceDispatchPacket(value) {
         qaScope: parseQaScope(packet.qaScope ?? packet.qa_scope),
         qaRework: parseQaRework(packet.qaRework),
         architectRevision: parseArchitectRevision(packet.architectRevision),
+        architectDependencies: parseArchitectDependencies(packet.architectDependencies),
         storyDevelop: parseStoryDevelop(packet.storyDevelop),
         storyQa: parseStoryQa(packet.storyQa),
         draft: parseDraftPrompt(packet.draft)
@@ -282,6 +283,34 @@ function parseArchitectRevision(value) {
         feedback: requiredString(revision, "feedback")
     };
 }
+function parseArchitectDependencies(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const context = asObject(value, "architectDependencies");
+    const prerequisites = context.prerequisites;
+    if (!Array.isArray(prerequisites)) {
+        throw new Error("architectDependencies.prerequisites must be an array.");
+    }
+    return {
+        baseBranch: requiredString(context, "baseBranch").trim(),
+        prerequisites: prerequisites.map((entry, index) => {
+            const prerequisite = asObject(entry, `architectDependencies.prerequisites[${index}]`);
+            return {
+                storyId: requiredString(prerequisite, "storyId").trim(),
+                title: requiredString(prerequisite, "title").trim(),
+                scheduleIndex: optionalNonNegativeInteger(prerequisite, "scheduleIndex"),
+                waveIndex: optionalNonNegativeInteger(prerequisite, "waveIndex"),
+                featureScheduleIndex: optionalNonNegativeInteger(prerequisite, "featureScheduleIndex"),
+                expectedOutput: optionalString(prerequisite, "expectedOutput"),
+                handoffSummary: optionalString(prerequisite, "handoffSummary"),
+                dependencyReason: optionalString(prerequisite, "dependencyReason"),
+                pullRequestNumber: optionalPositiveInteger(prerequisite, "pullRequestNumber"),
+                targetBranch: requiredString(prerequisite, "targetBranch").trim()
+            };
+        })
+    };
+}
 function parseStoryDevelop(value) {
     if (value === undefined || value === null) {
         return null;
@@ -481,6 +510,16 @@ function optionalPositiveInteger(source, key) {
     }
     return value;
 }
+function optionalNonNegativeInteger(source, key) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${key} must be a non-negative integer when provided.`);
+    }
+    return value;
+}
 function requiredNumber(source, key) {
     const value = source[key];
     if (typeof value !== "number" || !Number.isFinite(value)) {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.3-dev.b6be5e7f9668";
+export declare const forgeBridgeVersion = "0.1.3-dev.bd0c67bbf352";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.3-dev.b6be5e7f9668";
+export const forgeBridgeVersion = "0.1.3-dev.bd0c67bbf352";

package/dist/worktree/artifact-injector.js

@@ -36,19 +36,29 @@ const DRAFT_OPERATIONAL_SKILLS = new Set([
     "draft-repo-context",
     "draft-graph-context",
     "draft-product-scope",
-    "draft-work-order-plan",
     "draft-critic",
     "draft-proposal"
 ]);
+const DRAFT_WORK_ITEM_OPERATIONAL_SKILLS = new Set([
+    "draft-work-item-plan"
+]);
+const DRAFT_WORK_ORDER_OPERATIONAL_SKILLS = new Set([
+    "draft-work-order-plan"
+]);
 const DRAFT_OPERATIONAL_HOOKS = new Set([
     "draft-intent",
     "draft-repo-context",
     "draft-graph-context",
     "draft-product-scope",
-    "draft-work-order-plan",
     "draft-critic",
     "draft-proposal"
 ]);
+const DRAFT_WORK_ITEM_OPERATIONAL_HOOKS = new Set([
+    "draft-work-item-plan"
+]);
+const DRAFT_WORK_ORDER_OPERATIONAL_HOOKS = new Set([
+    "draft-work-order-plan"
+]);
 export async function injectWorktreeArtifacts(worktreePath, artifacts) {
     for (const artifact of artifacts) {
         await writeArtifact(worktreePath, artifact);
@@ -64,7 +74,7 @@ export function filterArtifactsForLane(artifacts, lane, phase) {
         return artifacts.filter((artifact) => shouldInjectArchitectArtifact(artifact, commandSlug));
     }
     if (normalizedLane === "draft") {
-        return artifacts.filter((artifact) => shouldInjectDraftArtifact(artifact, commandSlug));
+        return artifacts.filter((artifact) => shouldInjectDraftArtifact(artifact, commandSlug, phase));
     }
     return artifacts;
 }
@@ -142,7 +152,7 @@ function shouldInjectArchitectArtifact(artifact, commandSlug) {
             return false;
     }
 }
-function shouldInjectDraftArtifact(artifact, commandSlug) {
+function shouldInjectDraftArtifact(artifact, commandSlug, phase) {
     if (artifact.scope.trim().toLowerCase() !== "operational") {
         return false;
     }
@@ -151,13 +161,36 @@ function shouldInjectDraftArtifact(artifact, commandSlug) {
         case "command":
             return slug === commandSlug;
         case "skill":
-            return DRAFT_OPERATIONAL_SKILLS.has(slug);
+            return DRAFT_OPERATIONAL_SKILLS.has(slug) || draftPhaseSkills(phase).has(slug);
         case "hook":
-            return DRAFT_OPERATIONAL_HOOKS.has(slug);
+            return DRAFT_OPERATIONAL_HOOKS.has(slug) || draftPhaseHooks(phase).has(slug);
         default:
             return false;
     }
 }
+function draftPhaseSkills(phase) {
+    switch (normalizeDraftPhase(phase)) {
+        case "work_order":
+            return DRAFT_WORK_ORDER_OPERATIONAL_SKILLS;
+        case "story":
+            return DRAFT_WORK_ITEM_OPERATIONAL_SKILLS;
+        default:
+            return DRAFT_WORK_ITEM_OPERATIONAL_SKILLS;
+    }
+}
+function draftPhaseHooks(phase) {
+    switch (normalizeDraftPhase(phase)) {
+        case "work_order":
+            return DRAFT_WORK_ORDER_OPERATIONAL_HOOKS;
+        case "story":
+            return DRAFT_WORK_ITEM_OPERATIONAL_HOOKS;
+        default:
+            return DRAFT_WORK_ITEM_OPERATIONAL_HOOKS;
+    }
+}
+function normalizeDraftPhase(phase) {
+    return phase.trim().toLowerCase().replaceAll("-", "_");
+}
 export function buildSpecBody(laneCommand, workItem, phase = "implementation") {
     const prompt = laneCommand.body.replaceAll("{workItemId}", workItem.id);
     return `---

package/dist/worktree/worktree.service.d.ts

@@ -9,7 +9,8 @@ export declare class GitWorktreeService implements WorktreeService {
     private resolveRepoPath;
     private findExistingRepoPath;
     private resolveMatchingRepo;
-    private ensureBaseBranch;
+    private resolveBaseStartPoint;
+    private resetWorktreeToBase;
     private gitRefExists;
     private currentBranch;
     private ensureGitIdentity;

package/dist/worktree/worktree.service.js

@@ -14,7 +14,7 @@ export class GitWorktreeService {
         const baseBranch = normalizeBranchName(request.baseBranch, "develop");
         const repoPath = await this.resolveRepoPath(request.repo, allowedRoot, baseBranch);
         await this.ensureGitIdentity(repoPath);
-        await this.ensureBaseBranch(repoPath, baseBranch);
+        const baseStartPoint = await this.resolveBaseStartPoint(repoPath, baseBranch);
         const shortId = request.workItem.id.replace(/-/g, "").slice(0, 12);
         const kind = safeSegment(request.workItem.kind, "work-item");
         const fallbackWorktreeKey = `${kind}/${shortId}`;
@@ -30,7 +30,7 @@ export class GitWorktreeService {
         const exists = await directoryExists(worktreePath);
         let resolvedWorktreePath;
         if (!exists) {
-            await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseBranch]);
+            await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseStartPoint]);
             resolvedWorktreePath = await resolveExistingDirectoryPath(worktreePath);
         }
         else {
@@ -42,6 +42,9 @@ export class GitWorktreeService {
             if (currentBranch !== branchName) {
                 throw new Error(`Existing worktree ${resolvedWorktreePath} is on branch '${currentBranch}', expected '${branchName}'.`);
             }
+            if (shouldResetExistingWorktree(request)) {
+                await this.resetWorktreeToBase(resolvedWorktreePath, baseStartPoint);
+            }
         }
         await this.ensureGitIdentity(resolvedWorktreePath);
         await clearRunArtifactRoots(resolvedWorktreePath, request);
@@ -164,21 +167,27 @@ export class GitWorktreeService {
         const resolved = await resolveExistingDirectoryPath(candidate);
         return isSubPath(allowedRoot, resolved) ? resolved : null;
     }
-    async ensureBaseBranch(repoPath, baseBranch) {
-        if (await this.gitRefExists(repoPath, `refs/heads/${baseBranch}`)) {
-            return;
-        }
+    async resolveBaseStartPoint(repoPath, baseBranch) {
+        const localRef = `refs/heads/${baseBranch}`;
+        const remoteRef = `refs/remotes/origin/${baseBranch}`;
         const origin = await this.git.run(repoPath, ["remote", "get-url", "origin"]).catch(() => "");
-        if (origin.trim().length === 0) {
-            throw new Error(`Base branch '${baseBranch}' was not found in the local checkout.`);
+        if (origin.trim().length > 0) {
+            const fetched = await this.git.run(repoPath, ["fetch", "--prune", "origin"])
+                .then(() => true)
+                .catch(() => false);
+            if (fetched && await this.gitRefExists(repoPath, remoteRef)) {
+                return remoteRef;
+            }
         }
-        await this.git.run(repoPath, ["fetch", "origin", `${baseBranch}:refs/remotes/origin/${baseBranch}`]).catch(() => "");
-        if (await this.gitRefExists(repoPath, `refs/remotes/origin/${baseBranch}`)) {
-            await this.git.run(repoPath, ["branch", baseBranch, `refs/remotes/origin/${baseBranch}`]);
-            return;
+        if (await this.gitRefExists(repoPath, localRef)) {
+            return localRef;
         }
         throw new Error(`Base branch '${baseBranch}' was not found locally or on origin.`);
     }
+    async resetWorktreeToBase(worktreePath, baseStartPoint) {
+        await this.git.run(worktreePath, ["reset", "--hard", baseStartPoint]);
+        await this.git.run(worktreePath, ["clean", "-fd"]);
+    }
     async gitRefExists(repoPath, gitRef) {
         return this.git.run(repoPath, ["show-ref", "--verify", "--quiet", gitRef]).then(() => true).catch(() => false);
     }
@@ -269,6 +278,17 @@ function normalizeOwnerType(value) {
     }
     return null;
 }
+function shouldResetExistingWorktree(request) {
+    const lane = request.lane.trim().toLowerCase();
+    const phase = request.phase.trim().toLowerCase().replace(/-/g, "_");
+    if (lane === "develop" && (phase === "implementation" || phase === "self_review" || phase === "validation")) {
+        return false;
+    }
+    if (lane === "qa" || phase === "qa") {
+        return false;
+    }
+    return true;
+}
 function qaReworkPacketFileName(packetPath) {
     const normalized = packetPath.trim().replace(/\\/g, "/");
     const fileName = normalized.split("/").filter(Boolean).at(-1) ?? "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.3-dev.b6be5e7f9668",
+  "version": "0.1.3-dev.bd0c67bbf352",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",