@ornexus/neocortex 4.60.55 → 4.60.57

package/packages/client/dist/resolvers/remote-resolver.js

@@ -1 +1 @@
-import{ResolverMode as y,NoOpCache as d}from"../types/index.js";import{InMemoryAssetCache as m}from"../cache/in-memory-asset-cache.js";const C=3e4,f=3,w=1e3,p=1e4;class o extends Error{statusCode;endpoint;constructor(t,e,s){super(t),this.statusCode=e,this.endpoint=s,this.name="RemoteResolverError"}}class ${mode=y.REMOTE;serverUrl;licenseKey;timeout;retryCount;cache;assetCache;licenseClient;constructor(t){this.serverUrl=t.serverUrl.replace(/\/+$/,""),this.licenseKey=t.licenseKey,this.timeout=t.timeout??C,this.retryCount=t.retryCount??f,this.cache=t.cacheProvider??new d,this.licenseClient=t.licenseClient??null,this.assetCache=new m}async resolveStep(t,e){const s=`step:${t}`;return this.fetchWithInMemoryCache(s,{method:"GET",path:`/api/v1/steps/${encodeURIComponent(t)}`})}async resolveSkill(t,e){const s=`skill:${t}`;return this.fetchWithInMemoryCache(s,{method:"GET",path:`/api/v1/skills/${encodeURIComponent(t)}`})}async resolveStandard(t){const e=`standard:${t}`;return this.fetchWithInMemoryCache(e,{method:"GET",path:`/api/v1/standards/${encodeURIComponent(t)}`})}async resolveRegistry(){return this.fetchWithCacheFallback("registry",{method:"GET",path:"/api/v1/registry"})}async assemblePrompt(t,e){return this.fetchWithRetry({method:"POST",path:"/api/v1/prompts/assemble",body:{stepId:t,context:e}})}async isAvailable(){try{const t=new AbortController,e=setTimeout(()=>t.abort(),5e3),s=await fetch(`${this.serverUrl}/api/v1/health`,{method:"GET",headers:await this.buildHeaders(),signal:t.signal});return clearTimeout(e),s.ok}catch{return!1}}async dispose(){await this.cache.clear(),await this.assetCache.clear()}async buildHeaders(){const t={"Content-Type":"application/json","X-Client-Version":"0.1.0"};if(this.licenseClient){const e=await this.licenseClient.getToken();e&&(t.Authorization=`Bearer ${e}`)}return t}async fetchWithRetry(t){let e,s=!1;for(let n=0;n<=this.retryCount;n++)try{const a=new AbortController,c=setTimeout(()=>a.abort(),this.timeout),i=`${this.serverUrl}${t.path}`,h={method:t.method,headers:await this.buildHeaders(),signal:a.signal};t.body&&(h.body=JSON.stringify(t.body));const r=await fetch(i,h);if(clearTimeout(c),!r.ok){const l=await r.text().catch(()=>"Unknown error");if(r.status===401&&!s&&this.licenseClient){if(s=!0,await this.licenseClient.forceRefresh()){n--;continue}throw new o(`API error: ${r.status} ${r.statusText} - ${l}`,r.status,t.path)}throw r.status>=400&&r.status<500&&r.status!==429?new o(`API error: ${r.status} ${r.statusText} - ${l}`,r.status,t.path):new o(`Server error: ${r.status} ${r.statusText}`,r.status,t.path)}return await r.json()}catch(a){if(e=a instanceof Error?a:new Error(String(a)),a instanceof o&&a.statusCode&&a.statusCode>=400&&a.statusCode<500&&a.statusCode!==429)throw a;if(n<this.retryCount){const c=Math.min(w*Math.pow(2,n),p),i=Math.random()*c*.25;await this.sleep(c+i)}}throw e??new o("All retry attempts failed",void 0,t.path)}async fetchWithCacheFallback(t,e){try{const s=await this.fetchWithRetry(e);return this.cache.set(t,JSON.stringify(s)).catch(()=>{}),s}catch(s){const n=await this.cache.get(t);if(n!==null)try{return JSON.parse(n)}catch{}throw s}}async fetchWithInMemoryCache(t,e){try{const s=await this.fetchWithRetry(e);return this.assetCache.set(t,JSON.stringify(s)).catch(()=>{}),s}catch(s){const n=await this.assetCache.get(t);if(n!==null)try{return JSON.parse(n)}catch{}throw s}}sleep(t){return new Promise(e=>setTimeout(e,t))}}export{$ as RemoteResolver,o as RemoteResolverError};
+import{ResolverMode as y,NoOpCache as d}from"../types/index.js";import{InMemoryAssetCache as m}from"../cache/in-memory-asset-cache.js";import{CLIENT_VERSION as C}from"../version.js";const f=3e4,w=3,p=1e3,T=1e4;class n extends Error{statusCode;endpoint;constructor(t,e,r){super(t),this.statusCode=e,this.endpoint=r,this.name="RemoteResolverError"}}class b{mode=y.REMOTE;serverUrl;licenseKey;timeout;retryCount;cache;assetCache;licenseClient;constructor(t){this.serverUrl=t.serverUrl.replace(/\/+$/,""),this.licenseKey=t.licenseKey,this.timeout=t.timeout??f,this.retryCount=t.retryCount??w,this.cache=t.cacheProvider??new d,this.licenseClient=t.licenseClient??null,this.assetCache=new m}async resolveStep(t,e){const r=`step:${t}`;return this.fetchWithInMemoryCache(r,{method:"GET",path:`/api/v1/steps/${encodeURIComponent(t)}`})}async resolveSkill(t,e){const r=`skill:${t}`;return this.fetchWithInMemoryCache(r,{method:"GET",path:`/api/v1/skills/${encodeURIComponent(t)}`})}async resolveStandard(t){const e=`standard:${t}`;return this.fetchWithInMemoryCache(e,{method:"GET",path:`/api/v1/standards/${encodeURIComponent(t)}`})}async resolveRegistry(){return this.fetchWithCacheFallback("registry",{method:"GET",path:"/api/v1/registry"})}async assemblePrompt(t,e){return this.fetchWithRetry({method:"POST",path:"/api/v1/prompts/assemble",body:{stepId:t,context:e}})}async isAvailable(){try{const t=new AbortController,e=setTimeout(()=>t.abort(),5e3),r=await fetch(`${this.serverUrl}/api/v1/health`,{method:"GET",headers:await this.buildHeaders(),signal:t.signal});return clearTimeout(e),r.ok}catch{return!1}}async dispose(){await this.cache.clear(),await this.assetCache.clear()}async buildHeaders(){const t={"Content-Type":"application/json","X-Client-Version":C};if(this.licenseClient){const e=await this.licenseClient.getToken();e&&(t.Authorization=`Bearer ${e}`)}return t}async fetchWithRetry(t){let e,r=!1;for(let o=0;o<=this.retryCount;o++)try{const a=new AbortController,c=setTimeout(()=>a.abort(),this.timeout),i=`${this.serverUrl}${t.path}`,h={method:t.method,headers:await this.buildHeaders(),signal:a.signal};t.body&&(h.body=JSON.stringify(t.body));const s=await fetch(i,h);if(clearTimeout(c),!s.ok){const l=await s.text().catch(()=>"Unknown error");if(s.status===401&&!r&&this.licenseClient){if(r=!0,await this.licenseClient.forceRefresh()){o--;continue}throw new n(`API error: ${s.status} ${s.statusText} - ${l}`,s.status,t.path)}throw s.status>=400&&s.status<500&&s.status!==429?new n(`API error: ${s.status} ${s.statusText} - ${l}`,s.status,t.path):new n(`Server error: ${s.status} ${s.statusText}`,s.status,t.path)}return await s.json()}catch(a){if(e=a instanceof Error?a:new Error(String(a)),a instanceof n&&a.statusCode&&a.statusCode>=400&&a.statusCode<500&&a.statusCode!==429)throw a;if(o<this.retryCount){const c=Math.min(p*Math.pow(2,o),T),i=Math.random()*c*.25;await this.sleep(c+i)}}throw e??new n("All retry attempts failed",void 0,t.path)}async fetchWithCacheFallback(t,e){try{const r=await this.fetchWithRetry(e);return this.cache.set(t,JSON.stringify(r)).catch(()=>{}),r}catch(r){const o=await this.cache.get(t);if(o!==null)try{return JSON.parse(o)}catch{}throw r}}async fetchWithInMemoryCache(t,e){try{const r=await this.fetchWithRetry(e);return this.assetCache.set(t,JSON.stringify(r)).catch(()=>{}),r}catch(r){const o=await this.assetCache.get(t);if(o!==null)try{return JSON.parse(o)}catch{}throw r}}sleep(t){return new Promise(e=>setTimeout(e,t))}}export{b as RemoteResolver,n as RemoteResolverError};

package/packages/client/dist/yolo/change-evidence-collector.d.ts

@@ -0,0 +1,6 @@
+import { type YoloChangeEvidenceV1 } from '../../../shared/dist/yolo/change-evidence.js';
+export declare function collectYoloChangeEvidence(options: {
+    readonly projectRoot: string;
+    readonly defaultBranch: string;
+    readonly expectedHeadSha: string;
+}): YoloChangeEvidenceV1;

package/packages/client/dist/yolo/change-evidence-collector.js

@@ -0,0 +1 @@
+import{execFileSync as h}from"node:child_process";import{realpathSync as c}from"node:fs";import{createYoloChangeEvidenceV1 as d}from"../../../shared/dist/yolo/change-evidence.js";function r(e,o){try{return h("git",["-C",e,...o],{encoding:"utf8",timeout:3e3,maxBuffer:1024*1024,stdio:["ignore","pipe","ignore"]})}catch{throw new Error("yolo-change-evidence-unavailable")}}function g(e){if(!/^[A-Za-z0-9][A-Za-z0-9_./-]{0,119}$/.test(e.defaultBranch)||e.defaultBranch.includes(".."))throw new Error("yolo-change-evidence-unavailable");const o=r(e.projectRoot,["rev-parse","--show-toplevel"]).trim();if(c(o)!==c(e.projectRoot))throw new Error("yolo-change-evidence-unavailable");const a=r(e.projectRoot,["rev-parse","HEAD"]).trim();if(a!==e.expectedHeadSha)throw new Error("yolo-change-evidence-stale");let t;try{t=r(e.projectRoot,["merge-base","HEAD",e.defaultBranch]).trim()}catch{t=r(e.projectRoot,["merge-base","HEAD",`refs/remotes/origin/${e.defaultBranch}`]).trim()}const n=r(e.projectRoot,["diff","--name-only","-z",t,"--"]).split("\0").filter(Boolean),l=r(e.projectRoot,["ls-files","--others","--exclude-standard","-z"]).split("\0").filter(Boolean),i=d({baseSha:t,headSha:a,changedPaths:[...n,...l]});if(r(e.projectRoot,["rev-parse","HEAD"]).trim()!==a)throw new Error("yolo-change-evidence-stale");return i}export{g as collectYoloChangeEvidence};

package/packages/client/dist/yolo/spec-envelope-collector.d.ts

@@ -0,0 +1,11 @@
+import { type YoloSpecEnvelopeV1 } from '../../../shared/dist/yolo/spec-envelope.js';
+export interface CollectYoloSpecEnvelopeOptions {
+    readonly projectRoot: string;
+    readonly storyId: string;
+    readonly epicId: string;
+    readonly inputSha256: string;
+    /** Test seam; production callers omit it and read Git HEAD physically. */
+    readonly headSha?: string;
+    readonly collectedAt?: string;
+}
+export declare function collectYoloSpecEnvelope(options: CollectYoloSpecEnvelopeOptions): YoloSpecEnvelopeV1;

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

@@ -0,0 +1,5 @@
+import{execFileSync as h}from"node:child_process";import{existsSync as w,readFileSync as S,realpathSync as d,statSync as m}from"node:fs";import{join as f,sep as E}from"node:path";import{createYoloSpecEnvelopeV1 as R,YOLO_SPEC_ARTIFACT_LIMIT_BYTES as v}from"../../../shared/dist/yolo/spec-envelope.js";import{inspectFrontmatterContext as g}from"../../../shared/dist/frontmatter-context-contract.js";const j=["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"],x=/(?:^|[\s([`'";])((?:docs\/(?:stories|epics|specs|architecture|examples)\/|core\/templates\/specs\/)[A-Za-z0-9_./-]+\.(?:md|mdx|feature))(?:$|[\s)\]`'",;])/gm;function A(e){return e.startsWith("core/templates/")?"template":e.startsWith("docs/epics/")?"epic":e.startsWith("docs/stories/")&&e.endsWith(".story.md")?"story":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 I(e){return[...new Set([...e.matchAll(x)].map(t=>t[1]).filter(t=>!!t))].sort()}function n(e,t){const c=d(e);let r;try{r=d(f(c,t))}catch{throw new Error("yolo-spec-envelope-required")}if(!r.startsWith(`${c}${E}`))throw new Error("yolo-spec-envelope-path-out-of-scope");if(!m(r).isFile())throw new Error("yolo-spec-envelope-unsafe");if(m(r).size>v)throw new Error("yolo-spec-envelope-too-large");return S(r,"utf8")}function a(e,t){const r=g(e,{context:t==="story"?"story-target":"epic-target",explicitlySelected:!0});if(r.status==="malformed"||r.status==="oversized")throw new Error("yolo-spec-envelope-unsafe");if(r.status==="absent")return e;const s=e.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);if(!s)throw new Error("yolo-spec-envelope-unsafe");return`---
+${Object.entries(r.metadata).map(([i,p])=>`${i}: ${JSON.stringify(p)}`).join(`
+`)}
+---
+${e.slice(s[0].length)}`}function u(e){try{return h("git",["-C",e,"rev-parse","HEAD"],{encoding:"utf8",timeout:2e3,stdio:["ignore","pipe","ignore"]}).trim()}catch{throw new Error("yolo-spec-envelope-stale")}}function L(e){const t=`docs/stories/${e.storyId}.story.md`,c=`docs/epics/epic-${e.epicId}.md`,r=e.headSha??u(e.projectRoot),s=a(n(e.projectRoot,t),"story"),l=a(n(e.projectRoot,c),"epic"),i=[{kind:"story",path:t,content:s},{kind:"epic",path:c,content:l}];for(const o of new Set([...I(s),...j]))o===t||o===c||!w(f(e.projectRoot,o))||i.push({kind:A(o),path:o,content:n(e.projectRoot,o)});const p=R({storyId:e.storyId,epicId:e.epicId,targetPath:t,inputSha256:e.inputSha256,headSha:r,collectedAt:e.collectedAt??new Date().toISOString(),artifacts:i}),y=e.headSha??u(e.projectRoot);if(r!==y||a(n(e.projectRoot,t),"story")!==s||a(n(e.projectRoot,c),"epic")!==l||i.some(o=>o.kind!=="story"&&o.kind!=="epic"&&n(e.projectRoot,o.path)!==o.content))throw new Error("yolo-spec-envelope-stale");return p}export{L as collectYoloSpecEnvelope};

package/packages/shared/dist/frontmatter-context-contract.js

@@ -0,0 +1,326 @@
+import { Buffer } from 'node:buffer';
+export const FRONTMATTER_CONTEXTS = [
+    'wrapper',
+    'delegated-prompt',
+    'epic-target',
+    'story-target',
+    'memory-wrapper',
+];
+export const FRONTMATTER_STATUSES = [
+    'absent',
+    'valid',
+    'malformed',
+    'oversized',
+];
+export const FRONTMATTER_REASON_CODES = [
+    'frontmatter-absent',
+    'frontmatter-valid',
+    'frontmatter-malformed',
+    'frontmatter-oversized',
+    'frontmatter-preserved',
+    'frontmatter-projection-withheld',
+    'frontmatter-explicit-selection-required',
+    'frontmatter-metadata-projected',
+    'frontmatter-unknown-fields-omitted',
+    'frontmatter-unsupported-value',
+];
+export const FRONTMATTER_LIMITS = Object.freeze({
+    maxBytes: 8 * 1024,
+    maxLines: 128,
+    maxFields: 32,
+    maxListItems: 32,
+    maxValueChars: 512,
+});
+const EPIC_TARGET_FIELDS = Object.freeze([
+    'id',
+    'title',
+    'status',
+    'source',
+    'depends_on',
+    'related_epics',
+    'total_stories',
+    'completed_stories',
+]);
+const STORY_TARGET_FIELDS = Object.freeze([
+    'id',
+    'epic_id',
+    'title',
+    'status',
+    'priority',
+    'depends_on',
+    'files_to_modify',
+]);
+const LIST_FIELDS = new Set([
+    'depends_on',
+    'related_epics',
+    'files_to_modify',
+]);
+const NUMBER_FIELDS = new Set([
+    'total_stories',
+    'completed_stories',
+]);
+export const FRONTMATTER_CONTEXT_POLICY = Object.freeze({
+    wrapper: Object.freeze({
+        preserveSource: true,
+        metadataProjection: 'withheld',
+        bodyProjection: 'explicit-command-only',
+        allowedFields: Object.freeze([]),
+    }),
+    'delegated-prompt': Object.freeze({
+        preserveSource: true,
+        metadataProjection: 'withheld',
+        bodyProjection: 'server-authorized-command-only',
+        allowedFields: Object.freeze([]),
+    }),
+    'epic-target': Object.freeze({
+        preserveSource: true,
+        metadataProjection: 'explicit-target-only',
+        bodyProjection: 'none',
+        allowedFields: EPIC_TARGET_FIELDS,
+    }),
+    'story-target': Object.freeze({
+        preserveSource: true,
+        metadataProjection: 'explicit-target-only',
+        bodyProjection: 'none',
+        allowedFields: STORY_TARGET_FIELDS,
+    }),
+    'memory-wrapper': Object.freeze({
+        preserveSource: true,
+        metadataProjection: 'withheld',
+        bodyProjection: 'none',
+        allowedFields: Object.freeze([]),
+    }),
+});
+function byteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+function scanFrontmatter(source) {
+    if (typeof source !== 'string')
+        return { status: 'malformed' };
+    if (!source.startsWith('---'))
+        return { status: 'absent' };
+    const opening = source.match(/^---(?:\r\n|\n)/);
+    if (!opening)
+        return { status: 'malformed' };
+    const contentStart = opening[0].length;
+    let cursor = contentStart;
+    let lineCount = 1;
+    while (cursor <= source.length) {
+        const newlineIndex = source.indexOf('\n', cursor);
+        const lineEnd = newlineIndex === -1 ? source.length : newlineIndex;
+        const rawLine = source.slice(cursor, lineEnd);
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        lineCount += 1;
+        const inspectedEnd = newlineIndex === -1 ? lineEnd : newlineIndex + 1;
+        if (lineCount > FRONTMATTER_LIMITS.maxLines ||
+            byteLength(source.slice(0, inspectedEnd)) > FRONTMATTER_LIMITS.maxBytes) {
+            return { status: 'oversized' };
+        }
+        if (line === '---') {
+            return {
+                status: 'valid',
+                block: source.slice(contentStart, cursor),
+            };
+        }
+        if (newlineIndex === -1)
+            break;
+        cursor = newlineIndex + 1;
+    }
+    return { status: 'malformed' };
+}
+function unquote(value) {
+    if (value.length > FRONTMATTER_LIMITS.maxValueChars)
+        return null;
+    const first = value[0];
+    const last = value[value.length - 1];
+    const startsQuoted = first === '"' || first === "'";
+    const endsQuoted = last === '"' || last === "'";
+    if (startsQuoted !== endsQuoted || (startsQuoted && first !== last))
+        return null;
+    if (startsQuoted && value.length >= 2) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function parseListItem(value) {
+    const parsed = unquote(value.trim());
+    if (parsed === null || parsed.length === 0)
+        return null;
+    return parsed;
+}
+function parseInlineValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (trimmed.startsWith('[') || trimmed.endsWith(']')) {
+        if (!trimmed.startsWith('[') || !trimmed.endsWith(']'))
+            return null;
+        const body = trimmed.slice(1, -1).trim();
+        if (!body)
+            return Object.freeze([]);
+        const rawItems = body.split(',');
+        if (rawItems.length > FRONTMATTER_LIMITS.maxListItems)
+            return null;
+        const items = rawItems.map(parseListItem);
+        if (items.some((item) => item === null))
+            return null;
+        return Object.freeze(items);
+    }
+    const unquoted = unquote(trimmed);
+    if (unquoted === null)
+        return null;
+    const quoted = (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"));
+    if (quoted)
+        return unquoted;
+    if (unquoted === 'true')
+        return true;
+    if (unquoted === 'false')
+        return false;
+    if (/^-?(?:0|[1-9]\d*)$/.test(unquoted)) {
+        const numberValue = Number(unquoted);
+        if (!Number.isFinite(numberValue) || !Number.isSafeInteger(numberValue))
+            return null;
+        return numberValue;
+    }
+    return unquoted;
+}
+function parseFrontmatterBlock(block) {
+    const fields = {};
+    let fieldCount = 0;
+    let pendingListKey = null;
+    let pendingList = [];
+    const commitPendingList = () => {
+        if (!pendingListKey)
+            return true;
+        if (pendingList.length > FRONTMATTER_LIMITS.maxListItems)
+            return false;
+        fields[pendingListKey] = Object.freeze([...pendingList]);
+        pendingListKey = null;
+        pendingList = [];
+        return true;
+    };
+    for (const rawLine of block.split(/\r?\n/)) {
+        if (!rawLine.trim() || rawLine.trimStart().startsWith('#'))
+            continue;
+        const listMatch = rawLine.match(/^\s+-\s+(.+?)\s*$/);
+        if (listMatch) {
+            if (!pendingListKey)
+                return { status: 'malformed', unsupportedValue: true };
+            if (listMatch[1].trim().length > FRONTMATTER_LIMITS.maxValueChars) {
+                return { status: 'oversized' };
+            }
+            const item = parseListItem(listMatch[1]);
+            if (item === null)
+                return { status: 'malformed', unsupportedValue: true };
+            pendingList.push(item);
+            if (pendingList.length > FRONTMATTER_LIMITS.maxListItems)
+                return { status: 'oversized' };
+            continue;
+        }
+        if (!commitPendingList())
+            return { status: 'oversized' };
+        const fieldMatch = rawLine.match(/^([A-Za-z_][A-Za-z0-9_-]{0,63}):(?:\s*(.*))?$/);
+        if (!fieldMatch)
+            return { status: 'malformed', unsupportedValue: true };
+        const key = fieldMatch[1];
+        if (Object.prototype.hasOwnProperty.call(fields, key)) {
+            return { status: 'malformed', unsupportedValue: true };
+        }
+        fieldCount += 1;
+        if (fieldCount > FRONTMATTER_LIMITS.maxFields)
+            return { status: 'oversized' };
+        const rawValue = fieldMatch[2] ?? '';
+        if (!rawValue.trim()) {
+            pendingListKey = key;
+            continue;
+        }
+        const value = parseInlineValue(rawValue);
+        if (value === null) {
+            return rawValue.length > FRONTMATTER_LIMITS.maxValueChars
+                ? { status: 'oversized' }
+                : { status: 'malformed', unsupportedValue: true };
+        }
+        fields[key] = value;
+    }
+    if (!commitPendingList())
+        return { status: 'oversized' };
+    return { status: 'valid', fields: Object.freeze(fields) };
+}
+function result(context, status, reasonCodes, metadata = Object.freeze({})) {
+    return Object.freeze({
+        context,
+        status,
+        reasonCodes: Object.freeze([...new Set(reasonCodes)]),
+        metadata: Object.freeze({ ...metadata }),
+    });
+}
+function isValidAllowedFieldValue(key, value) {
+    if (LIST_FIELDS.has(key)) {
+        return Array.isArray(value) && value.every((item) => typeof item === 'string');
+    }
+    if (NUMBER_FIELDS.has(key)) {
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+    }
+    return typeof value === 'string';
+}
+/**
+ * Classify bounded frontmatter without returning source text, body content, or
+ * rejected values. The caller supplies the context; file content never grants
+ * execution authority or selects its own interpretation mode.
+ */
+export function inspectFrontmatterContext(source, options) {
+    const structural = scanFrontmatter(source);
+    if (structural.status === 'absent') {
+        return result(options.context, 'absent', ['frontmatter-absent']);
+    }
+    if (structural.status === 'malformed') {
+        return result(options.context, 'malformed', ['frontmatter-malformed']);
+    }
+    if (structural.status === 'oversized') {
+        return result(options.context, 'oversized', ['frontmatter-oversized']);
+    }
+    const parsed = parseFrontmatterBlock(structural.block);
+    if (parsed.status === 'malformed') {
+        return result(options.context, 'malformed', [
+            'frontmatter-malformed',
+            ...(parsed.unsupportedValue ? ['frontmatter-unsupported-value'] : []),
+        ]);
+    }
+    if (parsed.status === 'oversized') {
+        return result(options.context, 'oversized', ['frontmatter-oversized']);
+    }
+    const policy = FRONTMATTER_CONTEXT_POLICY[options.context];
+    const baseReasons = [
+        'frontmatter-valid',
+        'frontmatter-preserved',
+    ];
+    if (policy.metadataProjection === 'withheld') {
+        baseReasons.push('frontmatter-projection-withheld');
+        return result(options.context, 'valid', baseReasons);
+    }
+    if (options.explicitlySelected !== true) {
+        baseReasons.push('frontmatter-explicit-selection-required', 'frontmatter-projection-withheld');
+        return result(options.context, 'valid', baseReasons);
+    }
+    const allowedFields = new Set(policy.allowedFields);
+    const metadata = {};
+    let omittedUnknownField = false;
+    for (const [key, value] of Object.entries(parsed.fields)) {
+        if (!allowedFields.has(key)) {
+            omittedUnknownField = true;
+            continue;
+        }
+        if (!isValidAllowedFieldValue(key, value)) {
+            return result(options.context, 'malformed', [
+                'frontmatter-malformed',
+                'frontmatter-unsupported-value',
+            ]);
+        }
+        metadata[key] = value;
+    }
+    baseReasons.push('frontmatter-metadata-projected');
+    if (omittedUnknownField)
+        baseReasons.push('frontmatter-unknown-fields-omitted');
+    return result(options.context, 'valid', baseReasons, metadata);
+}

package/packages/shared/dist/yolo/change-evidence.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+const SHA = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;
+const PATH = /^[A-Za-z0-9_.-][A-Za-z0-9_./ -]{0,239}$/;
+const UNSAFE = /(^|\/)(?:\.env(?:\.|$)|secrets?|credentials?|private-prompts?|customer-data)(?:\/|$)|(?:token|password|license[_-]?key|secret)[=:]/i;
+function digest(paths) {
+    return createHash('sha256').update(JSON.stringify(paths)).digest('hex');
+}
+function fail() { throw new Error('yolo-change-evidence-unsafe'); }
+function validPath(path) {
+    return typeof path === 'string' && PATH.test(path) && !path.includes('\\')
+        && !path.split('/').includes('..') && posix.normalize(path) === path && !UNSAFE.test(path);
+}
+export function createYoloChangeEvidenceV1(input) {
+    if (!SHA.test(input.baseSha) || !SHA.test(input.headSha) || !Array.isArray(input.changedPaths))
+        fail();
+    const paths = [...new Set(input.changedPaths)].sort();
+    if (paths.length > 256 || paths.some((path) => !validPath(path)))
+        fail();
+    return {
+        schemaVersion: 1,
+        source: 'git-diff-base-and-worktree',
+        baseSha: input.baseSha,
+        headSha: input.headSha,
+        changedPaths: paths,
+        pathsSha256: digest(paths),
+    };
+}
+export function assertYoloChangeEvidenceV1(value, expectedHeadSha) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail();
+    const record = value;
+    const keys = Object.keys(record).sort();
+    const expected = ['schemaVersion', 'source', 'baseSha', 'headSha', 'changedPaths', 'pathsSha256'].sort();
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])
+        || record.schemaVersion !== 1 || record.source !== 'git-diff-base-and-worktree'
+        || typeof record.baseSha !== 'string' || !SHA.test(record.baseSha)
+        || record.headSha !== expectedHeadSha || typeof record.headSha !== 'string' || !SHA.test(record.headSha)
+        || !Array.isArray(record.changedPaths) || record.changedPaths.length > 256
+        || record.changedPaths.some((path) => !validPath(path))
+        || JSON.stringify([...new Set(record.changedPaths)].sort()) !== JSON.stringify(record.changedPaths)
+        || record.pathsSha256 !== digest(record.changedPaths))
+        fail();
+}

package/packages/shared/dist/yolo/spec-envelope.js

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { inspectFrontmatterContext } from '../frontmatter-context-contract.js';
+export const YOLO_SPEC_ARTIFACT_LIMIT_BYTES = 64 * 1024;
+export const YOLO_SPEC_TOTAL_LIMIT_BYTES = 128 * 1024;
+export const YOLO_SPEC_MAX_ARTIFACTS = 12;
+export const YOLO_SPEC_MAX_AGE_MS = 120_000;
+export const YOLO_SPEC_FUTURE_SKEW_MS = 30_000;
+const HASH = /^[a-f0-9]{64}$/;
+const HEAD = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const STORY_ID = /^[A-Za-z0-9]+(?:\.[A-Za-z0-9]+)+$/;
+const EPIC_ID = /^[A-Za-z0-9]+$/;
+const KINDS = ['story', 'epic', 'spec', 'contract', 'adr', 'nfr', 'example', 'bdd', 'traceability', 'template'];
+const ALLOWED_PATH = /^(?:docs\/(?:stories|epics|specs|architecture|examples)\/|core\/templates\/specs\/)[A-Za-z0-9_./-]+$/;
+const PROHIBITED_CONTENT = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:bearer|token|password|secret|api[_-]?key)\s*[:=]\s*\S+|\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b|\b(?:sk-|ghp_|github_pat_|npm_)[A-Za-z0-9_-]{12,}\b|(?:^|[\s"'(])\/(?:home|media|root|etc|var|Users)\/)/im;
+function deny(code) {
+    throw new Error(code);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function validPath(value) {
+    return typeof value === 'string'
+        && value.length > 0 && value.length <= 240
+        && ALLOWED_PATH.test(value)
+        && !value.includes('\\') && !value.split('/').includes('..')
+        && posix.normalize(value) === value;
+}
+function normalizeContent(content) {
+    if (content.includes('\0') || /\r(?!\n)/.test(content))
+        deny('yolo-spec-envelope-unsafe');
+    const normalized = content.replaceAll('\r\n', '\n');
+    if (PROHIBITED_CONTENT.test(normalized))
+        deny('yolo-spec-envelope-unsafe');
+    return normalized;
+}
+function artifactManifestSha256(artifacts) {
+    return sha256(JSON.stringify(artifacts.map(({ kind, path, byteLength, sha256: digest }) => [kind, path, byteLength, digest])));
+}
+function unsignedEnvelopeSha256(value) {
+    return sha256(JSON.stringify(value));
+}
+function checkArtifact(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ['kind', 'path', 'content', 'byteLength', 'sha256'])
+        || !KINDS.includes(String(value.kind)) || !validPath(value.path))
+        deny('yolo-spec-envelope-path-out-of-scope');
+    if (typeof value.content !== 'string' || !Number.isSafeInteger(value.byteLength) || !HASH.test(String(value.sha256))) {
+        deny('yolo-spec-envelope-unsafe');
+    }
+    const content = normalizeContent(value.content);
+    const bytes = Buffer.byteLength(content, 'utf8');
+    if (bytes > YOLO_SPEC_ARTIFACT_LIMIT_BYTES)
+        deny('yolo-spec-envelope-too-large');
+    if (content !== value.content || bytes !== value.byteLength || sha256(content) !== value.sha256) {
+        deny('yolo-spec-envelope-digest-mismatch');
+    }
+}
+export function createYoloSpecEnvelopeV1(input) {
+    if (!Array.isArray(input.artifacts) || input.artifacts.length > YOLO_SPEC_MAX_ARTIFACTS)
+        deny('yolo-spec-envelope-too-large');
+    const artifacts = input.artifacts.map((artifact) => {
+        if (!isRecord(artifact) || !KINDS.includes(String(artifact.kind)) || !validPath(artifact.path)
+            || typeof artifact.content !== 'string')
+            deny('yolo-spec-envelope-path-out-of-scope');
+        const content = normalizeContent(artifact.content);
+        return {
+            kind: artifact.kind,
+            path: artifact.path,
+            content,
+            byteLength: Buffer.byteLength(content, 'utf8'),
+            sha256: sha256(content),
+        };
+    }).sort((left, right) => left.kind.localeCompare(right.kind) || left.path.localeCompare(right.path));
+    const unsigned = {
+        schemaVersion: 1,
+        storyId: input.storyId,
+        epicId: input.epicId,
+        targetPath: input.targetPath,
+        inputSha256: input.inputSha256,
+        sourceRevision: { headSha: input.headSha, manifestSha256: artifactManifestSha256(artifacts) },
+        collectedAt: input.collectedAt,
+        artifacts,
+    };
+    const envelope = { ...unsigned, envelopeSha256: unsignedEnvelopeSha256(unsigned) };
+    assertYoloSpecEnvelopeV1(envelope, {
+        storyId: input.storyId, epicId: input.epicId, targetPath: input.targetPath,
+        inputSha256: input.inputSha256, nowMs: Date.parse(input.collectedAt),
+    });
+    return envelope;
+}
+export function assertYoloSpecEnvelopeV1(value, context) {
+    if (!isRecord(value) || !hasExactKeys(value, ['schemaVersion', 'storyId', 'epicId', 'targetPath', 'inputSha256', 'sourceRevision', 'collectedAt', 'artifacts', 'envelopeSha256'])
+        || value.schemaVersion !== 1 || typeof value.storyId !== 'string' || !STORY_ID.test(value.storyId)
+        || typeof value.epicId !== 'string' || !EPIC_ID.test(value.epicId)
+        || !validPath(value.targetPath) || !HASH.test(String(value.inputSha256))
+        || !HASH.test(String(value.envelopeSha256)))
+        deny('yolo-spec-envelope-unsafe');
+    if (value.storyId !== context.storyId || value.epicId !== context.epicId
+        || value.targetPath !== context.targetPath || value.inputSha256 !== context.inputSha256
+        || value.targetPath !== `docs/stories/${value.storyId}.story.md`)
+        deny('yolo-spec-envelope-target-mismatch');
+    const source = value.sourceRevision;
+    if (!isRecord(source) || !hasExactKeys(source, ['headSha', 'manifestSha256'])
+        || !HEAD.test(String(source.headSha)) || !HASH.test(String(source.manifestSha256)))
+        deny('yolo-spec-envelope-unsafe');
+    if (typeof value.collectedAt !== 'string' || !/^\d{4}-\d{2}-\d{2}T.*Z$/.test(value.collectedAt))
+        deny('yolo-spec-envelope-stale');
+    const collectedMs = Date.parse(value.collectedAt);
+    const nowMs = context.nowMs ?? Date.now();
+    if (!Number.isFinite(collectedMs) || !Number.isFinite(nowMs)
+        || nowMs - collectedMs > YOLO_SPEC_MAX_AGE_MS || collectedMs - nowMs > YOLO_SPEC_FUTURE_SKEW_MS)
+        deny('yolo-spec-envelope-stale');
+    if (!Array.isArray(value.artifacts) || value.artifacts.length < 1 || value.artifacts.length > YOLO_SPEC_MAX_ARTIFACTS)
+        deny('yolo-spec-envelope-too-large');
+    const artifacts = value.artifacts;
+    for (const artifact of artifacts)
+        checkArtifact(artifact);
+    const typedArtifacts = artifacts;
+    if (typedArtifacts.reduce((sum, artifact) => sum + artifact.byteLength, 0) > YOLO_SPEC_TOTAL_LIMIT_BYTES)
+        deny('yolo-spec-envelope-too-large');
+    const keys = typedArtifacts.map((artifact) => `${artifact.kind}:${artifact.path}`);
+    if (new Set(keys).size !== keys.length || keys.some((key, index) => index > 0 && key < keys[index - 1]))
+        deny('yolo-spec-envelope-unsafe');
+    if (typedArtifacts.filter((artifact) => artifact.kind === 'story' && artifact.path === value.targetPath).length !== 1
+        || typedArtifacts.filter((artifact) => artifact.kind === 'epic' && artifact.path === `docs/epics/epic-${value.epicId}.md`).length !== 1
+        || typedArtifacts.some((artifact) => artifact.kind === 'story' && artifact.path !== value.targetPath)
+        || typedArtifacts.some((artifact) => artifact.kind === 'epic' && artifact.path !== `docs/epics/epic-${value.epicId}.md`)) {
+        deny('yolo-spec-envelope-target-mismatch');
+    }
+    const story = typedArtifacts.find((artifact) => artifact.kind === 'story');
+    const epic = typedArtifacts.find((artifact) => artifact.kind === 'epic');
+    const storyContext = inspectFrontmatterContext(story.content, { context: 'story-target', explicitlySelected: true });
+    const epicContext = inspectFrontmatterContext(epic.content, { context: 'epic-target', explicitlySelected: true });
+    if (storyContext.status !== 'valid' || storyContext.metadata.id !== value.storyId
+        || storyContext.metadata.epic_id !== value.epicId
+        || epicContext.status !== 'valid' || epicContext.metadata.id !== value.epicId) {
+        deny('yolo-spec-envelope-target-mismatch');
+    }
+    if (artifactManifestSha256(typedArtifacts) !== source.manifestSha256)
+        deny('yolo-spec-envelope-digest-mismatch');
+    const unsigned = {
+        schemaVersion: value.schemaVersion,
+        storyId: value.storyId,
+        epicId: value.epicId,
+        targetPath: value.targetPath,
+        inputSha256: value.inputSha256,
+        sourceRevision: value.sourceRevision,
+        collectedAt: value.collectedAt,
+        artifacts: value.artifacts,
+    };
+    if (unsignedEnvelopeSha256(unsigned) !== value.envelopeSha256)
+        deny('yolo-spec-envelope-digest-mismatch');
+}

package/targets-stubs/antigravity/gemini.md

@@ -1,4 +1,4 @@
-# 🧠 Neocortex v4.60.55 | OrNexus Team
+# 🧠 Neocortex v4.60.57 | 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.55 | OrNexus Team"
+description: "🧠 Neocortex v4.60.57 | 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.55'
+    version: '4.60.57'
     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.55 | OrNexus Team"
+description: "🧠 Neocortex Root Agent v4.60.57 | 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.55                           │
+│      ###  ########      v4.60.57                           │
 │ #########      #####                                       │
 │ ##    ##############    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.55'
+    version: '4.60.57'
     architecture: 'thin-client'
     module: stand-alone
     hasSidecar: false