@ornexus/neocortex 4.60.27 → 4.60.29

package/packages/shared/dist/yoloop/branch-unit.js

@@ -0,0 +1,343 @@
+/**
+ * Public, deterministic branch-unit contract for epic-owned YOLO/YOLOOP runs.
+ * Pure data/functions only: callers own Git and filesystem effects.
+ */
+export const BRANCH_UNIT_MODES = Object.freeze(['epic', 'story']);
+const LEGACY_INTEGRATION_STEPS = new Set([
+    'step-c-09-sync-main',
+    'step-c-10-create-pr',
+    'step-c-11-review-pr',
+    'step-c-12-merge-pr',
+]);
+/** Resolve once from persisted state. Existing Git progress always wins. */
+export function resolveBranchUnit(epic, stories) {
+    const legacyProgress = stories.some(hasLegacyStoryGitProgress);
+    if (epic.branch_mode === 'story') {
+        return resolution('story', 'recorded', true, epic, ['branch-mode-recorded-story']);
+    }
+    if (epic.branch_mode === 'epic') {
+        const conflictingEvidence = classifyRecordedEpicStoryGitEvidence(epic, stories);
+        if (conflictingEvidence === 'strong') {
+            return resolution('story', 'legacy-progress', true, epic, [
+                'branch-mode-conflict-legacy-progress-preserved',
+                'branch-mode-recorded-epic-not-applied',
+            ]);
+        }
+        if (conflictingEvidence === 'ambiguous') {
+            return resolution('story', 'legacy-progress', true, epic, [
+                'branch-mode-conflict-legacy-progress-preserved',
+                'branch-mode-conflict-ambiguous-story-git-evidence',
+                'branch-mode-recorded-epic-not-applied',
+            ]);
+        }
+        return resolution('epic', 'recorded', hasEpicGitProgress(epic, stories), epic, ['branch-mode-recorded-epic']);
+    }
+    if (legacyProgress || stories.some(hasAnyStoryProgress)) {
+        return resolution('story', 'legacy-progress', true, epic, ['legacy-story-git-progress-detected']);
+    }
+    if (nonEmpty(epic.execution_branch)) {
+        return resolution('epic', 'epic-boundary', hasEpicGitProgress(epic, stories), epic, ['epic-execution-branch-declared']);
+    }
+    return resolution('epic', 'new-epic-default', false, {
+        ...epic,
+        execution_branch: `epic/${epic.id}`,
+        // Setup records the real current branch before switching. Pure planning
+        // must not invent a default origin.
+        origin_branch: epic.origin_branch,
+    }, ['missing-branch-mode-new-epic-default']);
+}
+/** Retry-safe checkpoint persistence decision; same key may never change range. */
+export function reconcileStoryCheckpoint(current, requested) {
+    if (!current)
+        return { kind: 'accepted', checkpoint: requested };
+    if (current.idempotencyKey !== requested.idempotencyKey)
+        return { kind: 'accepted', checkpoint: requested };
+    if (current.storyId === requested.storyId &&
+        current.epicId === requested.epicId &&
+        current.branch === requested.branch &&
+        current.baseSha === requested.baseSha &&
+        current.headSha === requested.headSha &&
+        sameStrings(current.commits, requested.commits) &&
+        current.dispatchId === requested.dispatchId &&
+        current.bundleId === requested.bundleId &&
+        current.bundleDigest === requested.bundleDigest &&
+        current.graphRevision === requested.graphRevision &&
+        current.claimRevision === requested.claimRevision &&
+        sameEvidenceReceipt(current.qaReceipt, requested.qaReceipt) &&
+        sameEvidenceReceipt(current.reviewReceipt, requested.reviewReceipt))
+        return { kind: 'reused', checkpoint: current };
+    return { kind: 'blocked', reasonCode: 'checkpoint-idempotency-conflict' };
+}
+/** Plan a rollback that reverts only the selected story and protects later ranges. */
+export function buildStoryRollbackPlan(target, later) {
+    const protectedLaterCommits = [...new Set(later.flatMap((item) => item.commits))];
+    if (target.commits.some((sha) => protectedLaterCommits.includes(sha))) {
+        return { blocked: true, reasonCode: 'overlapping-story-checkpoints' };
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        storyId: target.storyId,
+        epicId: target.epicId,
+        strategy: 'additive-revert',
+        targetCommitsNewestFirst: Object.freeze([...target.commits].reverse()),
+        protectedLaterCommits: Object.freeze(protectedLaterCommits),
+        historyRewrite: false,
+    });
+}
+export function acquireEpicBranchLease(current, requested, nowIso) {
+    if (!current || current.expiresAt <= nowIso)
+        return { kind: 'acquired', lease: requested };
+    if (current.ownerStoryId === requested.ownerStoryId &&
+        current.sessionId === requested.sessionId &&
+        current.idempotencyKey === requested.idempotencyKey)
+        return { kind: 'reused', lease: current };
+    return {
+        kind: 'blocked',
+        reasonCode: 'epic-worktree-writer-active',
+        canonicalReasonCode: 'epic-checkout-writer-active',
+        holderStoryId: current.ownerStoryId,
+    };
+}
+export function validateStoryCheckpoint(checkpoint, resolution) {
+    const errors = [];
+    if (resolution.mode !== 'epic')
+        errors.push('checkpoint-requires-epic-branch-mode');
+    if (checkpoint.schemaVersion !== 1)
+        errors.push('checkpoint-schema-version-invalid');
+    if (checkpoint.epicId !== resolution.epicId)
+        errors.push('checkpoint-epic-mismatch');
+    if (!nonEmpty(checkpoint.storyId) || !checkpoint.storyId.startsWith(`${checkpoint.epicId}.`))
+        errors.push('checkpoint-story-mismatch');
+    if (!isSha(checkpoint.baseSha) || !isSha(checkpoint.headSha))
+        errors.push('checkpoint-invalid-sha');
+    if (checkpoint.baseSha === checkpoint.headSha)
+        errors.push('checkpoint-empty-range');
+    if (!Array.isArray(checkpoint.commits) || checkpoint.commits.length === 0 || checkpoint.commits.some((sha) => !isSha(sha))) {
+        errors.push('checkpoint-invalid-commits');
+    }
+    else {
+        if (!checkpoint.commits.includes(checkpoint.headSha))
+            errors.push('checkpoint-head-not-in-commits');
+        if (new Set(checkpoint.commits).size !== checkpoint.commits.length)
+            errors.push('checkpoint-duplicate-commits');
+    }
+    if (!nonEmpty(checkpoint.branch))
+        errors.push('checkpoint-branch-missing');
+    if (resolution.executionBranch && checkpoint.branch !== resolution.executionBranch)
+        errors.push('checkpoint-branch-mismatch');
+    if (!nonEmpty(checkpoint.idempotencyKey))
+        errors.push('checkpoint-idempotency-key-missing');
+    if (checkpoint.dispatchId !== undefined && !isHash(checkpoint.dispatchId))
+        errors.push('checkpoint-dispatch-invalid');
+    if (checkpoint.bundleId !== undefined && !isHash(checkpoint.bundleId))
+        errors.push('checkpoint-bundle-id-invalid');
+    if (checkpoint.bundleDigest !== undefined && !isHash(checkpoint.bundleDigest))
+        errors.push('checkpoint-bundle-digest-invalid');
+    if (checkpoint.graphRevision !== undefined && !isHash(checkpoint.graphRevision))
+        errors.push('checkpoint-graph-revision-invalid');
+    if (checkpoint.claimRevision === undefined)
+        errors.push('checkpoint-claim-revision-required');
+    else if (!isHash(checkpoint.claimRevision))
+        errors.push('checkpoint-claim-revision-invalid');
+    if (!Array.isArray(checkpoint.receiptRefs) || checkpoint.receiptRefs.length === 0 || checkpoint.receiptRefs.some((ref) => !nonEmpty(ref))) {
+        errors.push('checkpoint-receipts-missing');
+    }
+    if (checkpoint.qaVerdict !== 'passed' && checkpoint.qaVerdict !== 'blocked')
+        errors.push('checkpoint-qa-verdict-invalid');
+    if (!['approved', 'changes-requested', 'pending'].includes(checkpoint.reviewVerdict))
+        errors.push('checkpoint-review-verdict-invalid');
+    if (!nonEmpty(checkpoint.recordedAt) || !Number.isFinite(Date.parse(checkpoint.recordedAt)))
+        errors.push('checkpoint-recorded-at-invalid');
+    if (checkpoint.reviewVerdict === 'approved' && checkpoint.qaVerdict !== 'passed')
+        errors.push('checkpoint-review-without-qa');
+    errors.push(...validateCheckpointEvidence(checkpoint));
+    return Object.freeze([...new Set(errors)]);
+}
+function validateCheckpointEvidence(checkpoint) {
+    const errors = [];
+    const qa = checkpoint.qaReceipt;
+    const review = checkpoint.reviewReceipt;
+    if (!qa)
+        errors.push('checkpoint-qa-evidence-required');
+    else {
+        if (qa.schemaVersion !== 1 || qa.kind !== 'story_qa_evidence' || qa.producer !== 'local-yolo-tdd'
+            || (qa.evidenceVersion !== undefined && qa.evidenceVersion !== 'git-immutable-v1'
+                && qa.evidenceVersion !== 'p205-execution-v2')
+            || qa.verdict !== checkpoint.qaVerdict || !evidenceBindingMatches(checkpoint, qa)
+            || !isHash(qa.sourceEvidenceDigest) || !nonEmpty(qa.receiptRef)
+            || qa.receiptRef !== `story-qa:${qa.sourceEvidenceDigest}`
+            || !Number.isFinite(Date.parse(qa.checkedAt))) {
+            errors.push('checkpoint-qa-evidence-invalid');
+        }
+        else if (qa.evidenceVersion === 'p205-execution-v2' && (qa.contract !== 'P205-CI-02'
+            || qa.command !== 'node scripts/test-root.mjs --gate complete'
+            || typeof qa.manifestDigest !== 'string' || !isHash(qa.manifestDigest)
+            || !Array.isArray(qa.gateIds) || qa.gateIds.length === 0 || qa.gateIds.some((gateId) => !nonEmpty(gateId))
+            || typeof qa.resultDigest !== 'string' || !isHash(qa.resultDigest))) {
+            errors.push('checkpoint-qa-execution-evidence-invalid');
+        }
+    }
+    if (checkpoint.reviewVerdict !== 'pending') {
+        if (!review)
+            errors.push('checkpoint-review-evidence-required');
+        else if (review.schemaVersion !== 1 || review.kind !== 'story_review_evidence'
+            || review.producer !== 'root-commit-range-review' || review.verdict !== checkpoint.reviewVerdict
+            || !evidenceBindingMatches(checkpoint, review) || !isHash(review.sourceEvidenceDigest)
+            || !nonEmpty(review.receiptRef) || review.receiptRef !== `story-review:${review.sourceEvidenceDigest}`
+            || !Number.isFinite(Date.parse(review.reviewedAt))) {
+            errors.push('checkpoint-review-evidence-invalid');
+        }
+    }
+    else if (review) {
+        errors.push('checkpoint-review-evidence-unexpected');
+    }
+    if (qa && review) {
+        if (qa.receiptRef === review.receiptRef || review.qaReceiptRef !== qa.receiptRef) {
+            errors.push('checkpoint-evidence-not-independent');
+        }
+        if (!checkpoint.receiptRefs.includes(qa.receiptRef) || !checkpoint.receiptRefs.includes(review.receiptRef)) {
+            errors.push('checkpoint-evidence-refs-unbound');
+        }
+        if (Date.parse(review.reviewedAt) < Date.parse(qa.checkedAt))
+            errors.push('checkpoint-review-before-qa');
+    }
+    return errors;
+}
+function evidenceBindingMatches(checkpoint, evidence) {
+    return evidence.storyId === checkpoint.storyId
+        && evidence.epicId === checkpoint.epicId
+        && evidence.baseSha === checkpoint.baseSha
+        && evidence.headSha === checkpoint.headSha
+        && Boolean(checkpoint.bundleDigest) && evidence.bundleDigest === checkpoint.bundleDigest
+        && Boolean(checkpoint.graphRevision) && evidence.graphRevision === checkpoint.graphRevision;
+}
+function sameEvidenceReceipt(left, right) {
+    return JSON.stringify(left ?? null) === JSON.stringify(right ?? null);
+}
+export function toStoryReviewRequest(checkpoint) {
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: 'commit-range-review',
+        storyId: checkpoint.storyId,
+        epicId: checkpoint.epicId,
+        baseSha: checkpoint.baseSha,
+        headSha: checkpoint.headSha,
+        receiptRefs: checkpoint.receiptRefs,
+        gitPullRequest: false,
+    });
+}
+export function validateStoryRollback(receipt) {
+    const errors = [];
+    if (!isSha(receipt.originalBaseSha) || !isSha(receipt.originalHeadSha))
+        errors.push('rollback-invalid-original-range');
+    if (receipt.revertCommits.length === 0 || receipt.revertCommits.some((sha) => !isSha(sha)))
+        errors.push('rollback-revert-commits-required');
+    if (receipt.preservesLaterCommits !== true)
+        errors.push('rollback-must-preserve-later-commits');
+    if (receipt.historyRewrite !== false)
+        errors.push('rollback-history-rewrite-forbidden');
+    return Object.freeze([...new Set(errors)]);
+}
+export function assessEpicIntegrationReadiness(resolution, expectedStoryIds, checkpoints) {
+    const reasons = [];
+    if (resolution.mode !== 'epic')
+        reasons.push('epic-integration-not-applicable-to-story-mode');
+    if (!nonEmpty(resolution.executionBranch) || !nonEmpty(resolution.originBranch))
+        reasons.push('epic-branch-boundary-incomplete');
+    const byStory = new Map();
+    for (const checkpoint of checkpoints) {
+        if (!expectedStoryIds.includes(checkpoint.storyId))
+            reasons.push(`unexpected-story-checkpoint:${checkpoint.storyId}`);
+        if (byStory.has(checkpoint.storyId))
+            reasons.push(`duplicate-story-checkpoint:${checkpoint.storyId}`);
+        else
+            byStory.set(checkpoint.storyId, checkpoint);
+    }
+    for (const storyId of expectedStoryIds) {
+        const checkpoint = byStory.get(storyId);
+        if (!checkpoint)
+            reasons.push(`missing-story-checkpoint:${storyId}`);
+        else {
+            const validationErrors = validateStoryCheckpoint(checkpoint, resolution);
+            if (validationErrors.length > 0)
+                reasons.push(`invalid-story-checkpoint:${storyId}:${validationErrors.join(',')}`);
+            else if (checkpoint.qaVerdict !== 'passed' || checkpoint.reviewVerdict !== 'approved')
+                reasons.push(`unaccepted-story-checkpoint:${storyId}`);
+        }
+    }
+    return Object.freeze({
+        ready: reasons.length === 0,
+        gitPullRequestOwner: 'epic',
+        reasonCodes: Object.freeze(reasons),
+        checkpointStoryIds: Object.freeze(checkpoints.map((item) => item.storyId)),
+    });
+}
+function hasLegacyStoryGitProgress(story) {
+    return nonEmpty(story.branch_name) ||
+        (typeof story.pr_number === 'number' && story.pr_number > 0) ||
+        (story.steps_completed ?? []).some((step) => LEGACY_INTEGRATION_STEPS.has(step) && !(step === 'step-c-11-review-pr' && story.checkpoint));
+}
+/**
+ * An explicit epic boundary may coexist with steps written by older runners.
+ * Those step labels are not physical proof of a story-owned branch or PR. Only
+ * a distinct branch/ref, a positive story PR, C12, or a checkpoint bound to a
+ * different branch can override the immutable epic boundary. Malformed PR
+ * metadata at a PR-producing step remains fail-closed and publicly diagnosable.
+ */
+function classifyRecordedEpicStoryGitEvidence(epic, stories) {
+    let result = 'none';
+    const executionBranch = nonEmpty(epic.execution_branch) ? epic.execution_branch.trim() : null;
+    for (const story of stories) {
+        const storyBranch = nonEmpty(story.branch_name) ? story.branch_name.trim() : null;
+        const checkpointBranch = nonEmpty(story.checkpoint?.branch) ? story.checkpoint.branch.trim() : null;
+        const steps = new Set(story.steps_completed ?? []);
+        if ((storyBranch && storyBranch !== executionBranch) ||
+            (checkpointBranch && checkpointBranch !== executionBranch) ||
+            (typeof story.pr_number === 'number' && story.pr_number > 0) ||
+            steps.has('step-c-12-merge-pr')) {
+            return 'strong';
+        }
+        const hasPrProducingStep = steps.has('step-c-10-create-pr');
+        const hasMalformedPrMarker = story.pr_number !== null && story.pr_number !== undefined &&
+            !(typeof story.pr_number === 'number' && story.pr_number > 0);
+        if (hasPrProducingStep && hasMalformedPrMarker)
+            result = 'ambiguous';
+    }
+    return result;
+}
+function hasAnyStoryProgress(story) {
+    return nonEmpty(story.branch_name) ||
+        (typeof story.pr_number === 'number' && story.pr_number > 0) ||
+        (story.steps_completed ?? []).length > 0 ||
+        Boolean(story.checkpoint);
+}
+function hasEpicGitProgress(epic, stories) {
+    return nonEmpty(epic.execution_branch) ||
+        Boolean(epic.branch_lease) ||
+        (typeof epic.pr_number === 'number' && epic.pr_number > 0) ||
+        stories.some((story) => Boolean(story.checkpoint));
+}
+function resolution(mode, source, immutable, epic, reasonCodes) {
+    return Object.freeze({
+        schemaVersion: 1,
+        epicId: epic.id,
+        mode,
+        source,
+        immutable,
+        ...(nonEmpty(epic.execution_branch) ? { executionBranch: epic.execution_branch } : {}),
+        ...(nonEmpty(epic.origin_branch) ? { originBranch: epic.origin_branch } : {}),
+        reasonCodes: Object.freeze([...reasonCodes]),
+    });
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isSha(value) {
+    return /^[0-9a-f]{7,64}$/i.test(value);
+}
+function isHash(value) {
+    return /^[0-9a-f]{64}$/i.test(value);
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

package/targets-stubs/antigravity/gemini.md

@@ -1,4 +1,4 @@
-# 🧠 Neocortex v4.60.27 | OrNexus Team
+# 🧠 Neocortex v4.60.29 | OrNexus Team
 
 This project uses Neocortex, a Development Orchestrator.
 

package/targets-stubs/antigravity/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: neocortex
-description: "🧠 Neocortex v4.60.27 | OrNexus Team"
+description: "🧠 Neocortex v4.60.29 | OrNexus Team"
 ---
 
 <!--

package/targets-stubs/claude-code/neocortex-root.agent.yaml

@@ -4,7 +4,7 @@ agent:
     name: 'Neocortex Root Agent'
     title: 'Development Orchestrator (Root)'
     icon: '>'
-    version: '4.60.27'
+    version: '4.60.29'
     architecture: 'thin-client'
     module: stand-alone
     hasSidecar: false

package/targets-stubs/claude-code/neocortex-root.md

@@ -1,6 +1,6 @@
 ---
 name: neocortex-root
-description: "🧠 Neocortex Root Agent v4.60.27 | OrNexus Team"
+description: "🧠 Neocortex Root Agent v4.60.29 | OrNexus Team"
 model: opus
 color: blue
 tools:
@@ -108,7 +108,7 @@ SEMPRE que este agente for invocado, imprima o banner abaixo como PRIMEIRO outpu
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.60.27                           │
+│      ###  ########      v4.60.29                           │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │

package/targets-stubs/claude-code/neocortex.agent.yaml

@@ -4,7 +4,7 @@ agent:
     name: 'Neocortex'
     title: 'Development Orchestrator'
     icon: '>'
-    version: '4.60.27'
+    version: '4.60.29'
     architecture: 'thin-client'
     module: stand-alone
     hasSidecar: false

package/targets-stubs/claude-code/neocortex.md

@@ -1,6 +1,6 @@
 ---
 name: neocortex
-description: "🧠 Neocortex v4.60.27 | OrNexus Team"
+description: "🧠 Neocortex v4.60.29 | OrNexus Team"
 model: opus
 color: blue
 permissionMode: bypassPermissions
@@ -104,7 +104,7 @@ SEMPRE que este agente for invocado, imprima o banner abaixo como PRIMEIRO outpu
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.60.27                           │
+│      ###  ########      v4.60.29                           │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │

package/targets-stubs/codex/AGENTS.md

@@ -28,7 +28,7 @@ Codex built-in commands or actions.
 
 <!-- END: Plugin Conflict Prevention -->
 
-# Neocortex v4.60.27 | OrNexus Team
+# Neocortex v4.60.29 | OrNexus Team
 
 You are a Development Orchestrator. All orchestration logic is delivered by the remote Neocortex server.
 

package/targets-stubs/cursor/agent.md

@@ -1,6 +1,6 @@
 ---
 name: neocortex
-description: "🧠 Neocortex v4.60.27 | OrNexus Team"
+description: "🧠 Neocortex v4.60.29 | OrNexus Team"
 model: inherit
 readonly: false
 is_background: false
@@ -64,7 +64,7 @@ SEMPRE que este agente for invocado, imprima o banner abaixo como PRIMEIRO outpu
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.60.27                           │
+│      ###  ########      v4.60.29                           │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │

package/targets-stubs/gemini-cli/agent.md

@@ -1,6 +1,6 @@
 ---
 name: neocortex-root
-description: "🧠 Neocortex v4.60.27 | OrNexus Team"
+description: "🧠 Neocortex v4.60.29 | OrNexus Team"
 kind: local
 tools:
   # File operations (Gemini CLI built-ins)
@@ -62,7 +62,7 @@ SEMPRE que este agente for invocado, imprima o banner abaixo como PRIMEIRO outpu
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.60.27                           │
+│      ###  ########      v4.60.29                           │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │

package/targets-stubs/opencode/neocortex-root.md

@@ -58,7 +58,7 @@ explicit server opt-in rather than a local assumption.
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.60.27                           │
+│      ###  ########      v4.60.29                           │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │

package/targets-stubs/vscode/neocortex.agent.md

@@ -1,6 +1,6 @@
 ---
 name: "neocortex"
-description: "Neocortex v4.60.27 | OrNexus Team"
+description: "Neocortex v4.60.29 | OrNexus Team"
 tools:
   # Read / Edit (built-in tool sets)
   - read
@@ -68,7 +68,7 @@ SEMPRE que este agente for invocado, imprima o banner abaixo como PRIMEIRO outpu
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.60.27                           │
+│      ###  ########      v4.60.29                           │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │