@ornexus/neocortex 4.60.66 → 4.60.68

package/packages/client/dist/yolo/invoke-envelope-capability.js

@@ -1 +1,62 @@
-import{YOLO_INVOKE_ENVELOPE_CAPABILITY as u}from"../../../shared/dist/yolo/spec-envelope.js";const y=16*1024,b=/^[0-9]{1,6}\.[0-9]{1,6}\.[0-9]{1,6}(?:-[A-Za-z0-9.-]{1,40})?$/;function e(n,a,t){return Object.freeze({supported:n,capability:u,reason:a,...t&&b.test(t)?{serverVersion:t}:{},publicSafe:!0})}async function h(n,a=globalThis.fetch){if(!a)return e(!1,"fetch-unavailable");const t=new AbortController,l=setTimeout(()=>t.abort(),5e3);l.unref?.();try{const c=await a(`${n.replace(/\/+$/,"")}/api/v1/health`,{method:"GET",headers:{accept:"application/json"},signal:t.signal});if(!c.ok)return e(!1,"http-rejected");const f=await c.text();if(Buffer.byteLength(f,"utf8")>y)return e(!1,"response-too-large");let r;try{r=JSON.parse(f)}catch{return e(!1,"response-invalid")}if(!r||typeof r!="object"||Array.isArray(r))return e(!1,"response-invalid");const i=r,s=i.capabilities,o=typeof i.version=="string"?i.version:void 0;return!Array.isArray(s)||s.some(p=>typeof p!="string"||p.length>80)?e(!1,"response-invalid",o):s.includes(u)?e(!0,"supported",o):e(!1,"capability-missing",o)}catch{return e(!1,"request-failed")}finally{clearTimeout(l)}}export{h as probeYoloInvokeEnvelopeCapability};
+import { YOLO_INVOKE_ENVELOPE_CAPABILITY } from '../../../shared/dist/yolo/spec-envelope.js';
+const MAX_CAPABILITY_RESPONSE_BYTES = 16 * 1024;
+const PUBLIC_VERSION = /^[0-9]{1,6}\.[0-9]{1,6}\.[0-9]{1,6}(?:-[A-Za-z0-9.-]{1,40})?$/;
+function result(supported, reason, serverVersion) {
+    return Object.freeze({
+        supported,
+        capability: YOLO_INVOKE_ENVELOPE_CAPABILITY,
+        reason,
+        ...(serverVersion && PUBLIC_VERSION.test(serverVersion) ? { serverVersion } : {}),
+        publicSafe: true,
+    });
+}
+/**
+ * Non-mutating, fail-closed compatibility probe for targeted YOLO requests.
+ * Older strict servers must be rejected before local release-gate execution.
+ */
+export async function probeYoloInvokeEnvelopeCapability(serverUrl, fetcher = globalThis.fetch) {
+    if (!fetcher)
+        return result(false, 'fetch-unavailable');
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5_000);
+    timeout.unref?.();
+    try {
+        const response = await fetcher(`${serverUrl.replace(/\/+$/, '')}/api/v1/health`, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return result(false, 'http-rejected');
+        const raw = await response.text();
+        if (Buffer.byteLength(raw, 'utf8') > MAX_CAPABILITY_RESPONSE_BYTES) {
+            return result(false, 'response-too-large');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return result(false, 'response-invalid');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return result(false, 'response-invalid');
+        }
+        const record = parsed;
+        const capabilities = record.capabilities;
+        const serverVersion = typeof record.version === 'string' ? record.version : undefined;
+        if (!Array.isArray(capabilities)
+            || capabilities.some((value) => typeof value !== 'string' || value.length > 80)) {
+            return result(false, 'response-invalid', serverVersion);
+        }
+        return capabilities.includes(YOLO_INVOKE_ENVELOPE_CAPABILITY)
+            ? result(true, 'supported', serverVersion)
+            : result(false, 'capability-missing', serverVersion);
+    }
+    catch {
+        return result(false, 'request-failed');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/packages/client/dist/yolo/spec-envelope-collector.js

@@ -1,5 +1,185 @@
-import{execFileSync as L}from"node:child_process";import{existsSync as S,readFileSync as $,realpathSync as w,statSync as R}from"node:fs";import{join as f,sep as b}from"node:path";import{createYoloSpecEnvelopeV1 as E,YOLO_SPEC_ARTIFACT_LIMIT_BYTES as O,YOLO_SPEC_MAX_ARTIFACTS as g,YOLO_SPEC_TOTAL_LIMIT_BYTES as I}from"../../../shared/dist/yolo/spec-envelope.js";import{inspectFrontmatterContext as v}from"../../../shared/dist/frontmatter-context-contract.js";const C=["core/templates/specs/feature-spec-template.md","core/templates/specs/architecture-spec-template.md","core/templates/specs/contract-spec-template.md","core/templates/specs/story-spec-template.md","core/templates/specs/traceability-matrix-template.md"],P=/(?:^|[\s([`'";])((?:docs\/(?:stories|epics|specs|architecture|examples)\/|core\/templates\/specs\/)[A-Za-z0-9_./-]+\.(?:md|mdx|feature))(?:$|[\s)\]`'",;])/gm,W=/^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)+$/;function Z(e){const r=[...e.matchAll(/(?:^|\s)@?docs\/stories\/([A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)+)\.story\.md(?=\s|$)/g)].map(c=>c[1]),s=e.trim().split(/\s+/).slice(1).map(c=>c.replace(/^@/,"")).filter(c=>W.test(c)),o=[...new Set([...r,...s])];return o.length===1?o[0]:null}function A(e){return e.startsWith("core/templates/")?"template":e.startsWith("docs/epics/")?"epic":e.startsWith("docs/stories/")&&e.endsWith(".story.md")?"story":e.endsWith(".rtm.md")?"traceability":e.toLowerCase().includes("adr")?"adr":e.toLowerCase().includes("contract")?"contract":e.toLowerCase().includes("nfr")?"nfr":e.endsWith(".feature")?"bdd":e.toLowerCase().includes("traceability")?"traceability":e.startsWith("docs/examples/")?"example":"spec"}function z(e){return[...new Set([...e.matchAll(P)].map(r=>r[1]).filter(r=>!!r))].sort()}function a(e,r){const s=w(e);let o;try{o=w(f(s,r))}catch{throw new Error("yolo-spec-envelope-required")}if(!o.startsWith(`${s}${b}`))throw new Error("yolo-spec-envelope-path-out-of-scope");if(!R(o).isFile())throw new Error("yolo-spec-envelope-unsafe");if(R(o).size>O)throw new Error("yolo-spec-envelope-too-large");return $(o,"utf8")}function m(e,r){const o=v(e,{context:r==="story"?"story-target":"epic-target",explicitlySelected:!0});if(o.status==="malformed"||o.status==="oversized")throw new Error("yolo-spec-envelope-unsafe");if(o.status==="absent")return e;const c=e.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);if(!c)throw new Error("yolo-spec-envelope-unsafe");return`---
-${Object.entries(o.metadata).map(([n,l])=>`${n}: ${JSON.stringify(l)}`).join(`
-`)}
----
-${e.slice(c[0].length)}`}function _(e){try{return L("git",["-C",e,"rev-parse","HEAD"],{encoding:"utf8",timeout:2e3,stdio:["ignore","pipe","ignore"]}).trim()}catch{throw new Error("yolo-spec-envelope-stale")}}function H(e){const r=`docs/stories/${e.storyId}.story.md`,s=`docs/epics/epic-${e.epicId}.md`,o=e.headSha??_(e.projectRoot),c=m(a(e.projectRoot,r),"story"),u=m(a(e.projectRoot,s),"epic"),n=[{kind:"story",path:r,content:c},{kind:"epic",path:s,content:u}],l=new Set([`docs/stories/${e.storyId}.spec.md`,`docs/stories/${e.storyId}.tasks.md`,`docs/stories/${e.storyId}.rtm.md`]),h=[...new Set([...z(c),...[...l].filter(t=>S(f(e.projectRoot,t)))])].sort(),T=[...h.filter(t=>l.has(t)),...h.filter(t=>!l.has(t))];let p=n.reduce((t,i)=>t+Buffer.byteLength(i.content,"utf8"),0),y=0;for(const t of T){if(t===r||t===s||!S(f(e.projectRoot,t)))continue;if(t.startsWith("docs/stories/")&&t.endsWith(".story.md")||t.startsWith("docs/epics/"))throw new Error("yolo-spec-envelope-target-mismatch");const i=a(e.projectRoot,t),d=Buffer.byteLength(i,"utf8");if(n.length>=g||p+d>I){if(l.has(t))throw new Error("yolo-spec-envelope-too-large");y+=1;continue}n.push({kind:A(t),path:t,content:i}),p+=d}y&&e.onOmittedReferences?.(y);for(const t of C){if(t===r||t===s||h.includes(t)||!S(f(e.projectRoot,t)))continue;const i=a(e.projectRoot,t),d=Buffer.byteLength(i,"utf8");n.length>=g||p+d>I||(n.push({kind:A(t),path:t,content:i}),p+=d)}const j=E({storyId:e.storyId,epicId:e.epicId,targetPath:r,inputSha256:e.inputSha256,headSha:o,collectedAt:e.collectedAt??new Date().toISOString(),artifacts:n}),x=e.headSha??_(e.projectRoot);if(o!==x||m(a(e.projectRoot,r),"story")!==c||m(a(e.projectRoot,s),"epic")!==u||n.some(t=>t.kind!=="story"&&t.kind!=="epic"&&a(e.projectRoot,t.path)!==t.content))throw new Error("yolo-spec-envelope-stale");return j}function D(e,r=new Date().toISOString()){return E({storyId:e.storyId,epicId:e.epicId,targetPath:e.targetPath,inputSha256:e.inputSha256,headSha:e.sourceRevision.headSha,collectedAt:r,artifacts:e.artifacts.map(({kind:s,path:o,content:c})=>({kind:s,path:o,content:c}))})}export{H as collectYoloSpecEnvelope,Z as extractTargetedYoloStoryId,D as refreshPrecollectedYoloSpecEnvelope};
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { createYoloSpecEnvelopeV1, YOLO_SPEC_ARTIFACT_LIMIT_BYTES, YOLO_SPEC_MAX_ARTIFACTS, YOLO_SPEC_TOTAL_LIMIT_BYTES, } from '../../../shared/dist/yolo/spec-envelope.js';
+import { inspectFrontmatterContext } from '../../../shared/dist/frontmatter-context-contract.js';
+const TEMPLATE_PATHS = [
+    'core/templates/specs/feature-spec-template.md',
+    'core/templates/specs/architecture-spec-template.md',
+    'core/templates/specs/contract-spec-template.md',
+    'core/templates/specs/story-spec-template.md',
+    'core/templates/specs/traceability-matrix-template.md',
+];
+const REFERENCE_PATH = /(?:^|[\s([`'";])((?:docs\/(?:stories|epics|specs|architecture|examples)\/|core\/templates\/specs\/)[A-Za-z0-9_./-]+\.(?:md|mdx|feature))(?:$|[\s)\]`'",;])/gm;
+const STORY_ID = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)+$/;
+/** Resolve only an explicit story target. Inline YOLO text intentionally has no match. */
+export function extractTargetedYoloStoryId(args) {
+    const pathMatches = [...args.matchAll(/(?:^|\s)@?docs\/stories\/([A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)+)\.story\.md(?=\s|$)/g)]
+        .map((match) => match[1]);
+    const tokenMatches = args.trim().split(/\s+/).slice(1)
+        .map((token) => token.replace(/^@/, ''))
+        .filter((token) => STORY_ID.test(token));
+    const matches = [...new Set([...pathMatches, ...tokenMatches])];
+    return matches.length === 1 ? matches[0] : null;
+}
+function artifactKind(path) {
+    if (path.startsWith('core/templates/'))
+        return 'template';
+    if (path.startsWith('docs/epics/'))
+        return 'epic';
+    if (path.startsWith('docs/stories/') && path.endsWith('.story.md'))
+        return 'story';
+    if (path.endsWith('.rtm.md'))
+        return 'traceability';
+    if (path.toLowerCase().includes('adr'))
+        return 'adr';
+    if (path.toLowerCase().includes('contract'))
+        return 'contract';
+    if (path.toLowerCase().includes('nfr'))
+        return 'nfr';
+    if (path.endsWith('.feature'))
+        return 'bdd';
+    if (path.toLowerCase().includes('traceability'))
+        return 'traceability';
+    if (path.startsWith('docs/examples/'))
+        return 'example';
+    return 'spec';
+}
+function selectedReferencePaths(story) {
+    return [...new Set([...story.matchAll(REFERENCE_PATH)].map((match) => match[1]).filter((path) => Boolean(path)))].sort();
+}
+function safeSource(root, path) {
+    const rootReal = realpathSync(root);
+    let fileReal;
+    try {
+        fileReal = realpathSync(join(rootReal, path));
+    }
+    catch {
+        throw new Error('yolo-spec-envelope-required');
+    }
+    if (!fileReal.startsWith(`${rootReal}${sep}`))
+        throw new Error('yolo-spec-envelope-path-out-of-scope');
+    if (!statSync(fileReal).isFile())
+        throw new Error('yolo-spec-envelope-unsafe');
+    if (statSync(fileReal).size > YOLO_SPEC_ARTIFACT_LIMIT_BYTES)
+        throw new Error('yolo-spec-envelope-too-large');
+    return readFileSync(fileReal, 'utf8');
+}
+function publicMarkdown(source, kind) {
+    const context = kind === 'story' ? 'story-target' : 'epic-target';
+    const inspected = inspectFrontmatterContext(source, { context, explicitlySelected: true });
+    if (inspected.status === 'malformed' || inspected.status === 'oversized')
+        throw new Error('yolo-spec-envelope-unsafe');
+    if (inspected.status === 'absent')
+        return source;
+    const match = source.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+    if (!match)
+        throw new Error('yolo-spec-envelope-unsafe');
+    const fields = Object.entries(inspected.metadata).map(([key, value]) => `${key}: ${JSON.stringify(value)}`);
+    return `---\n${fields.join('\n')}\n---\n${source.slice(match[0].length)}`;
+}
+function readHeadSha(root) {
+    try {
+        return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], {
+            encoding: 'utf8', timeout: 2_000, stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        throw new Error('yolo-spec-envelope-stale');
+    }
+}
+export function collectYoloSpecEnvelope(options) {
+    const targetPath = `docs/stories/${options.storyId}.story.md`;
+    const epicPath = `docs/epics/epic-${options.epicId}.md`;
+    const initialHead = options.headSha ?? readHeadSha(options.projectRoot);
+    const story = publicMarkdown(safeSource(options.projectRoot, targetPath), 'story');
+    const epic = publicMarkdown(safeSource(options.projectRoot, epicPath), 'epic');
+    const artifacts = [
+        { kind: 'story', path: targetPath, content: story },
+        { kind: 'epic', path: epicPath, content: epic },
+    ];
+    const coreStoryReferences = new Set([
+        `docs/stories/${options.storyId}.spec.md`,
+        `docs/stories/${options.storyId}.tasks.md`,
+        `docs/stories/${options.storyId}.rtm.md`,
+    ]);
+    // Older stories may not link to their own SDD files. Bind physically present
+    // siblings to the same HEAD/content checks as explicitly referenced files.
+    const selectedReferences = [...new Set([
+            ...selectedReferencePaths(story),
+            ...[...coreStoryReferences].filter((path) => existsSync(join(options.projectRoot, path))),
+        ])].sort();
+    const prioritizedReferences = [
+        ...selectedReferences.filter((path) => coreStoryReferences.has(path)),
+        ...selectedReferences.filter((path) => !coreStoryReferences.has(path)),
+    ];
+    let selectedBytes = artifacts.reduce((sum, artifact) => sum + Buffer.byteLength(artifact.content, 'utf8'), 0);
+    let omittedReferences = 0;
+    for (const path of prioritizedReferences) {
+        if (path === targetPath || path === epicPath || !existsSync(join(options.projectRoot, path)))
+            continue;
+        // A foreign story/epic is a target conflict, never optional context. The
+        // byte budget must not turn a prior target-mismatch denial into admission.
+        if ((path.startsWith('docs/stories/') && path.endsWith('.story.md'))
+            || path.startsWith('docs/epics/'))
+            throw new Error('yolo-spec-envelope-target-mismatch');
+        const content = safeSource(options.projectRoot, path);
+        const bytes = Buffer.byteLength(content, 'utf8');
+        if (artifacts.length >= YOLO_SPEC_MAX_ARTIFACTS || selectedBytes + bytes > YOLO_SPEC_TOTAL_LIMIT_BYTES) {
+            if (coreStoryReferences.has(path))
+                throw new Error('yolo-spec-envelope-too-large');
+            omittedReferences += 1;
+            continue;
+        }
+        artifacts.push({ kind: artifactKind(path), path, content });
+        selectedBytes += bytes;
+    }
+    // Templates and non-core references are supporting context. Preserve the
+    // story's own SDD artifacts and signal omissions without exposing paths.
+    if (omittedReferences)
+        options.onOmittedReferences?.(omittedReferences);
+    for (const path of TEMPLATE_PATHS) {
+        if (path === targetPath || path === epicPath || selectedReferences.includes(path)
+            || !existsSync(join(options.projectRoot, path)))
+            continue;
+        const content = safeSource(options.projectRoot, path);
+        const bytes = Buffer.byteLength(content, 'utf8');
+        if (artifacts.length >= YOLO_SPEC_MAX_ARTIFACTS || selectedBytes + bytes > YOLO_SPEC_TOTAL_LIMIT_BYTES)
+            continue;
+        artifacts.push({ kind: artifactKind(path), path, content });
+        selectedBytes += bytes;
+    }
+    const envelope = createYoloSpecEnvelopeV1({
+        storyId: options.storyId,
+        epicId: options.epicId,
+        targetPath,
+        inputSha256: options.inputSha256,
+        headSha: initialHead,
+        collectedAt: options.collectedAt ?? new Date().toISOString(),
+        artifacts,
+    });
+    const finalHead = options.headSha ?? readHeadSha(options.projectRoot);
+    if (initialHead !== finalHead
+        || publicMarkdown(safeSource(options.projectRoot, targetPath), 'story') !== story
+        || publicMarkdown(safeSource(options.projectRoot, epicPath), 'epic') !== epic
+        || artifacts.some((artifact) => artifact.kind !== 'story' && artifact.kind !== 'epic'
+            && safeSource(options.projectRoot, artifact.path) !== artifact.content)) {
+        throw new Error('yolo-spec-envelope-stale');
+    }
+    return envelope;
+}
+/**
+ * Reissue a precollected physical snapshot with a fresh bounded transport time.
+ * The caller still performs the final disk/HEAD collection and digest comparison.
+ */
+export function refreshPrecollectedYoloSpecEnvelope(envelope, collectedAt = new Date().toISOString()) {
+    return createYoloSpecEnvelopeV1({
+        storyId: envelope.storyId,
+        epicId: envelope.epicId,
+        targetPath: envelope.targetPath,
+        inputSha256: envelope.inputSha256,
+        headSha: envelope.sourceRevision.headSha,
+        collectedAt,
+        artifacts: envelope.artifacts.map(({ kind, path, content }) => ({ kind, path, content })),
+    });
+}

package/packages/client/dist/yoloop/discovery-hook.js

@@ -1,2 +1,300 @@
-import{existsSync as f,readFileSync as h,renameSync as m,statSync as y,writeFileSync as j}from"node:fs";import{basename as p,dirname as b,resolve as l,isAbsolute as O}from"node:path";import{discoverEpicsFromDir as w,mergeDiscoveredIntoState as g,buildDefaultDiscoveryFs as k}from"./shared-discover-epics.js";import{extractYoloopTargetPath as z,isYoloopInvocation as S}from"./target-normalization.js";function v(e,o){return O(e)?e:l(o,e)}function $(e,o,t){if(o.epics.length===0)return;const s=l(e,".neocortex","state.json");if(f(s))try{const i=h(s,"utf8"),r=JSON.parse(i),n=g(r,o);if(n.added.length===0&&n.storiesAdded===0)return;r.last_updated=new Date().toISOString();const a=`${s}.tmp.${process.pid}.${Date.now()}`;j(a,`${JSON.stringify(r,null,2)}
-`,"utf8"),m(a,s)}catch(i){const r=i instanceof Error?i.message:String(i);t?.warn?.(`[neocortex] discovery hook: failed to persist .neocortex/state.json: ${r}. Proceeding with request snapshot only.`)}}function A(e,o){const t=p(o),s=e.epics.filter(r=>r.path===o||r.filename===t),i=new Set(s.map(r=>r.id));return{epics:Object.freeze(s),warnings:Object.freeze([...e.warnings,...s.length===0?[`single-file discovery found no matching epic descriptor for ${t}`]:[]]),skipped:Object.freeze([...e.skipped,...e.epics.filter(r=>!i.has(r.id)).map(r=>`${r.filename}: skipped (not requested file)`)])}}async function D(e){if(!e.featureFlag)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"flag off"};if(!S(e.args))return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"not a yoloop trigger"};const o=z(e.args,e.projectRoot);if(!o)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"no path arg"};let t;try{t=v(o,e.projectRoot)}catch(r){const n=r instanceof Error?r.message:String(r);return e.logger?.warn?.(`[neocortex] discovery hook: path resolution failed: ${n}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"path resolution failed"}}let s=!1,i=!1;try{if(f(t)){const r=y(t);s=r.isDirectory(),i=r.isFile()}}catch{s=!1,i=!1}if(!s&&!i)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"path not found"};try{const r=await k(),n=s?t:b(t),a=w(n,r),c=i?A(a,t):a,d=g(e.stateSnapshot,c);$(e.projectRoot,c,e.logger),(d.added.length>0||d.storiesAdded>0)&&e.logger?.info?.(`[neocortex] discovered ${d.added.length} epic(s), ${d.storiesAdded} story-ies from ${s?t:p(t)}`);for(const u of c.warnings)e.logger?.warn?.(`[neocortex] discovery: ${u}`);return{applied:!0,added:d.added,skipped:d.skipped,storiesAdded:d.storiesAdded}}catch(r){const n=r instanceof Error?r.message:String(r);return e.logger?.warn?.(`[neocortex] discovery hook failed: ${n}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:`error: ${n}`}}}async function I(e){if(!e.featureFlag)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"flag off"};try{return await D(e)}catch(o){const t=o instanceof Error?o.message:String(o);return e.logger?.warn?.(`[neocortex] discovery hook (outer) failed: ${t}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:`outer error: ${t}`}}}export{I as maybeRunDiscoveryHook,D as runDiscoveryHook};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * Epic P120.04 -- Client-side discovery hook (extends P101.07 pattern).
+ *
+ * Pre-request hook that, when `YOLOOP_AUTO_DISCOVERY=on` and trigger is
+ * `*yoloop` resolving to a directory, calls `discoverEpicsFromDir()` (P120.01)
+ * + `mergeDiscoveredIntoState()` (P120.02) on the client BEFORE sending the
+ * invoke request. Server (P120.05) sees the enriched state in
+ * `body.stateSnapshot.epics`, relaxing `EPIC_NOT_FOUND` for filesystem epics.
+ *
+ * Hook follows P101.07 pattern (lazy dynamic import for tree-shaking via
+ * the wrapper in `invoke-hooks.ts`, fail-soft try/catch, mutate stateSnapshot
+ * in place).
+ *
+ * Activation conditions (ALL must hold):
+ *   1. `featureFlag === true` -- operator opt-in via `YOLOOP_AUTO_DISCOVERY=on`
+ *   2. Args resolve to a yoloop trigger (regex per P101.07)
+ *   3. Args target via `@<path>` resolves to a directory
+ *
+ * Fail-open contract: ANY error in discovery / merge / fs-resolution is
+ * caught + logged (warn) + returns `{ applied: false, reason }`. The
+ * caller (invoke.ts wrapper) ALSO catches outermost. Hook NEVER blocks
+ * the invoke request. Worst case: state is unenriched + server falls back
+ * to existing canonical resolver (pre-P120 behavior).
+ *
+ * Pattern references:
+ *  - P101.07 (yoloop pre-request hook) -- exact pattern reused
+ *  - P120.01 (discoverEpicsFromDir) -- consumed via local SSoT-Shadow inline
+ *  - P120.02 (mergeDiscoveredIntoState) -- consumed via local SSoT-Shadow inline
+ *  - P120.03 (feature flag) -- gating variable
+ *  - P107.02 (architecture-policy hook) -- secondary reference for
+ *    fail-soft + dynamic import + state mutation
+ *
+ * Pre-request hook order (client-side, before invoke POST):
+ *   1. P121.05: maybeAutoResolveYoloopArgs (invoke-hooks.ts)  -- rewrite empty args
+ *   2. P101.07: yoloop client state collection                -- read ~/.neocortex/yoloop-state.json
+ *   3. P120.04: maybeRunDiscoveryHook (this hook)             -- scan args dir for epics
+ *   4. P107.02: architecture-policy reader                    -- attach state.architecture_policy
+ *   5. POST /invoke
+ *
+ * P121.05 runs FIRST so that subsequent hooks (P101.07, this hook) see the
+ * rewritten args. The discovery hook itself sees `*yoloop @docs/epics/`
+ * after P121.05 fires and proceeds normally.
+ */
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, resolve, isAbsolute } from 'node:path';
+// P120.04: import from local SSoT-Shadow inline mirror (P117.01 pattern).
+// See `./shared-discover-epics.ts` for sync rules and drift test enforcement
+// in `client/__tests__/discover-shared-sync.test.ts`.
+import { discoverEpicsFromDir, mergeDiscoveredIntoState, buildDefaultDiscoveryFs, } from './shared-discover-epics.js';
+import { extractYoloopTargetPath, isYoloopInvocation, } from './target-normalization.js';
+// =====================================================================
+// Internal helpers
+// =====================================================================
+/**
+ * Resolve a `@<path>` token to an absolute path, given a project root.
+ * Pure function: zero I/O.
+ */
+function resolveAtPath(token, projectRoot) {
+    if (isAbsolute(token))
+        return token;
+    return resolve(projectRoot, token);
+}
+/**
+ * Keep on-disk `.neocortex/state.json` aligned with the enriched snapshot.
+ *
+ * The server receives `stateSnapshot`, so snapshot mutation is sufficient for
+ * the current invoke. Persisting discovered epics removes the next-iteration
+ * EPIC_NOT_FOUND failure and matches the operator expectation that filesystem
+ * epics are registered once discovered. This writer reads state.json fresh so
+ * transient request-only fields (for example `stateSnapshot.yoloop`) are not
+ * accidentally stored in the project state.
+ */
+function persistDiscoveredStateJson(projectRoot, discovered, logger) {
+    if (discovered.epics.length === 0)
+        return;
+    const statePath = resolve(projectRoot, '.neocortex', 'state.json');
+    if (!existsSync(statePath))
+        return;
+    try {
+        const raw = readFileSync(statePath, 'utf8');
+        const diskState = JSON.parse(raw);
+        const merge = mergeDiscoveredIntoState(diskState, discovered);
+        if (merge.added.length === 0 && merge.storiesAdded === 0)
+            return;
+        diskState.last_updated = new Date().toISOString();
+        const tmpPath = `${statePath}.tmp.${process.pid}.${Date.now()}`;
+        writeFileSync(tmpPath, `${JSON.stringify(diskState, null, 2)}\n`, 'utf8');
+        renameSync(tmpPath, statePath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger?.warn?.(`[neocortex] discovery hook: failed to persist .neocortex/state.json: ${msg}. Proceeding with request snapshot only.`);
+    }
+}
+function filterDiscoveryToFile(result, absPath) {
+    const targetBase = basename(absPath);
+    const epics = result.epics.filter((epic) => {
+        return epic.path === absPath || epic.filename === targetBase;
+    });
+    const epicIds = new Set(epics.map((epic) => epic.id));
+    return {
+        epics: Object.freeze(epics),
+        warnings: Object.freeze([
+            ...result.warnings,
+            ...(epics.length === 0
+                ? [`single-file discovery found no matching epic descriptor for ${targetBase}`]
+                : []),
+        ]),
+        skipped: Object.freeze([
+            ...result.skipped,
+            ...result.epics
+                .filter((epic) => !epicIds.has(epic.id))
+                .map((epic) => `${epic.filename}: skipped (not requested file)`),
+        ]),
+    };
+}
+// =====================================================================
+// Public API
+// =====================================================================
+/**
+ * Run discovery + merge if hook conditions are met.
+ *
+ * Async because `buildDefaultDiscoveryFs()` lazy-imports `node:fs` /
+ * `node:path` (tree-shake friendly per P120.01 design). Returns
+ * synchronously-resolvable promise in the no-op cases (flag off, non-yoloop
+ * trigger, file not dir, missing dir) -- discovery work only happens on
+ * the happy path.
+ *
+ * **Never throws**. ANY error is caught, logged via `logger.warn`, and
+ * returned as `{ applied: false, reason }`. Caller continues normal
+ * invoke flow without enrichment.
+ *
+ * @param ctx hook context (args + projectRoot + stateSnapshot + flag + logger)
+ * @returns DiscoveryHookResult with telemetry counters
+ */
+export async function runDiscoveryHook(ctx) {
+    // -------------------------------------------------------------------
+    // Activation conditions (ordered cheap-to-expensive)
+    // -------------------------------------------------------------------
+    // 1. Feature flag check (zero I/O, fastest)
+    if (!ctx.featureFlag) {
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: 'flag off',
+        };
+    }
+    // 2. Yoloop trigger detection (regex over args)
+    if (!isYoloopInvocation(ctx.args)) {
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: 'not a yoloop trigger',
+        };
+    }
+    // 3. Extract target path arg
+    const pathToken = extractYoloopTargetPath(ctx.args, ctx.projectRoot);
+    if (!pathToken) {
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: 'no path arg',
+        };
+    }
+    // 4. Resolve to absolute path
+    let absPath;
+    try {
+        absPath = resolveAtPath(pathToken, ctx.projectRoot);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger?.warn?.(`[neocortex] discovery hook: path resolution failed: ${msg}. Proceeding without enrichment.`);
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: 'path resolution failed',
+        };
+    }
+    // 5. Verify path exists and determine scan mode.
+    let isDir = false;
+    let isFile = false;
+    try {
+        if (existsSync(absPath)) {
+            const stat = statSync(absPath);
+            isDir = stat.isDirectory();
+            isFile = stat.isFile();
+        }
+    }
+    catch {
+        // statSync error -> treat as missing (fail-open)
+        isDir = false;
+        isFile = false;
+    }
+    if (!isDir && !isFile) {
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: 'path not found',
+        };
+    }
+    // -------------------------------------------------------------------
+    // Activation: run discovery + merge
+    // -------------------------------------------------------------------
+    try {
+        const fs = await buildDefaultDiscoveryFs();
+        const scanDir = isDir ? absPath : dirname(absPath);
+        const rawResult = discoverEpicsFromDir(scanDir, fs);
+        const result = isFile ? filterDiscoveryToFile(rawResult, absPath) : rawResult;
+        // Even if zero epics discovered, we still count this as "applied" for
+        // observability (caller knows hook ran). State stays untouched.
+        const merge = mergeDiscoveredIntoState(ctx.stateSnapshot, result);
+        persistDiscoveredStateJson(ctx.projectRoot, result, ctx.logger);
+        // Telemetry: emit info if anything was added
+        if (merge.added.length > 0 || merge.storiesAdded > 0) {
+            ctx.logger?.info?.(`[neocortex] discovered ${merge.added.length} epic(s), ${merge.storiesAdded} story-ies from ${isDir ? absPath : basename(absPath)}`);
+        }
+        // Surface non-fatal warnings (e.g., orphan stories, ID collisions)
+        for (const w of result.warnings) {
+            ctx.logger?.warn?.(`[neocortex] discovery: ${w}`);
+        }
+        return {
+            applied: true,
+            added: merge.added,
+            skipped: merge.skipped,
+            storiesAdded: merge.storiesAdded,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger?.warn?.(`[neocortex] discovery hook failed: ${msg}. Proceeding without enrichment.`);
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: `error: ${msg}`,
+        };
+    }
+}
+/**
+ * Async wrapper with lazy-load semantics + outermost defensive try/catch.
+ *
+ * Designed to be invoked from `invoke-hooks.ts`. Performs the same
+ * `featureFlag` short-circuit as `runDiscoveryHook` to keep the async
+ * import truly tree-shakeable when the flag is off. Wraps the inner call
+ * in an additional try/catch as defense-in-depth (the hook itself is
+ * already fail-open, but module-load errors are caught here).
+ */
+export async function maybeRunDiscoveryHook(ctx) {
+    // Defense-in-depth: short-circuit BEFORE doing any work if flag is off.
+    // Note: in practice, callers (invoke-hooks.ts) also check the flag
+    // before importing this module to maximize tree-shaking. This is a
+    // belt-and-suspenders guard.
+    if (!ctx.featureFlag) {
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: 'flag off',
+        };
+    }
+    try {
+        return await runDiscoveryHook(ctx);
+    }
+    catch (err) {
+        // runDiscoveryHook is itself fail-open; this is defense-in-depth.
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger?.warn?.(`[neocortex] discovery hook (outer) failed: ${msg}. Proceeding without enrichment.`);
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: `outer error: ${msg}`,
+        };
+    }
+}

package/packages/client/dist/yoloop/index.js

@@ -1 +1,8 @@
-import{YoloopClientStateStore as r,createDefaultCounters as t,createDefaultState as a}from"./yoloop-client-state-store.js";import{isYoloopTrigger as s,readYoloopForRequest as l,persistYoloopFromResponse as i,maybeRunDiscoveryHook as u}from"./invoke-hooks.js";export{r as YoloopClientStateStore,t as createDefaultCounters,a as createDefaultState,s as isYoloopTrigger,u as maybeRunDiscoveryHook,i as persistYoloopFromResponse,l as readYoloopForRequest};
+/**
+ * Epic P101.06 -- Client-side yoloop state persistence.
+ *
+ * Re-exports the YoloopClientStateStore class and wire-format types for
+ * consumption by invoke.ts (P101.07 pre/post-request hooks).
+ */
+export { YoloopClientStateStore, createDefaultCounters, createDefaultState, } from './yoloop-client-state-store.js';
+export { isYoloopTrigger, readYoloopForRequest, persistYoloopFromResponse, maybeRunDiscoveryHook, } from './invoke-hooks.js';