@ornexus/neocortex 4.59.1

package/packages/client/dist/yoloop/discovery-hook.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @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.
+ */
+/**
+ * Logger contract -- structural, accepts any object with optional `warn` /
+ * `info` methods. Allows console, pino-style, or test stubs.
+ */
+export interface DiscoveryHookLogger {
+    warn?(message: string): void;
+    info?(message: string): void;
+}
+/**
+ * Input context for the hook. `stateSnapshot` is mutated in place when
+ * discovery applies (P101.07 pattern).
+ */
+export interface DiscoveryHookContext {
+    /** Raw trigger args (e.g., `"*yoloop @docs/epics/"`). */
+    readonly args: string;
+    /** Absolute path to the consumer project root. */
+    readonly projectRoot: string;
+    /** State snapshot collected by `collectStateSnapshot` -- mutated in place. */
+    readonly stateSnapshot: {
+        epics?: Record<string, unknown>;
+        stories?: Record<string, unknown>;
+    } & Record<string, unknown>;
+    /** YOLOOP_AUTO_DISCOVERY flag value (operator opt-in). */
+    readonly featureFlag: boolean;
+    /** Optional logger (defaults to no-op). */
+    readonly logger?: DiscoveryHookLogger;
+}
+/**
+ * Output of the hook. `applied: true` means discovery + merge ran
+ * successfully and `stateSnapshot` was mutated.
+ */
+export interface DiscoveryHookResult {
+    /** True if discovery + merge applied; false if hook was a no-op. */
+    readonly applied: boolean;
+    /** IDs of epics newly added to `state.epics` (empty if !applied). */
+    readonly added: ReadonlyArray<string>;
+    /** Epics skipped by merge (e.g., create-epic preserved). */
+    readonly skipped: ReadonlyArray<{
+        id: string;
+        reason: string;
+    }>;
+    /** Number of stories added to `state.stories`. */
+    readonly storiesAdded: number;
+    /** Reason hook was a no-op (only present if !applied). */
+    readonly reason?: string;
+}
+/**
+ * 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 declare function runDiscoveryHook(ctx: DiscoveryHookContext): Promise<DiscoveryHookResult>;
+/**
+ * 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 declare function maybeRunDiscoveryHook(ctx: DiscoveryHookContext): Promise<DiscoveryHookResult>;

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

@@ -0,0 +1,2 @@
+import{existsSync as f,readFileSync as m,renameSync as y,statSync as O,writeFileSync as b}from"node:fs";import{basename as p,dirname as j,resolve as l,isAbsolute as w}from"node:path";import{discoverEpicsFromDir as z,mergeDiscoveredIntoState as g,buildDefaultDiscoveryFs as S}from"./shared-discover-epics.js";const u=/^\s*\*?(yoloop|auto-yolo|epic-runner|story-runner|loop-yolo|auto-epic)\b/i;function k(e){const o=e.match(/@(\S+)/);if(o)return o[1];const t=e.replace(u,"").trim();return t?t.split(/\s+/).find(i=>i.length>0&&!i.startsWith("-"))??null:null}function A(e,o){return w(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=m(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 d=`${s}.tmp.${process.pid}.${Date.now()}`;b(d,`${JSON.stringify(r,null,2)}
+`,"utf8"),y(d,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 v(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(typeof e.args!="string"||!u.test(e.args))return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"not a yoloop trigger"};const o=k(e.args);if(!o)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"no path arg"};let t;try{t=A(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=O(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 S(),n=s?t:j(t),d=z(n,r),c=i?v(d,t):d,a=g(e.stateSnapshot,c);$(e.projectRoot,c,e.logger),(a.added.length>0||a.storiesAdded>0)&&e.logger?.info?.(`[neocortex] discovered ${a.added.length} epic(s), ${a.storiesAdded} story-ies from ${s?t:p(t)}`);for(const h of c.warnings)e.logger?.warn?.(`[neocortex] discovery: ${h}`);return{applied:!0,added:a.added,skipped:a.skipped,storiesAdded:a.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 R(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{R as maybeRunDiscoveryHook,D as runDiscoveryHook};

package/packages/client/dist/yoloop/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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, type ClientYoloopLogger, } from './yoloop-client-state-store.js';
+export { isYoloopTrigger, readYoloopForRequest, persistYoloopFromResponse, maybeRunDiscoveryHook, } from './invoke-hooks.js';
+export type { DiscoveryHookContext, DiscoveryHookResult, DiscoveryHookLogger, } from './discovery-hook.js';
+export type { YoloopPersistedCounters, YoloopPersistedLock, YoloopPersistedSession, YoloopPersistedState, YoloopSessionMode, YoloopStateOperation, YoloopStateUpdate, } from './shared-yoloop-types.js';

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

@@ -0,0 +1 @@
+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};

package/packages/client/dist/yoloop/invoke-hooks.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Epic P101.07 -- invoke.ts hooks for yoloop state persistence.
+ *
+ * Two hooks:
+ *   - `readYoloopForRequest(args, projectRoot)` — pre-request; returns
+ *     `YoloopPersistedState | undefined` to embed in stateSnapshot.yoloop.
+ *     Returns undefined (no-op) for non-yoloop invocations to avoid I/O.
+ *   - `persistYoloopFromResponse(metadata, projectRoot)` — post-response;
+ *     if the server returned `yoloopStateUpdate`, apply operations locally.
+ *     Fail-soft: warns to stderr on error but never throws.
+ *
+ * Trigger detection is regex-based over the first token of `args`, aligned
+ * with the P96.01 TRIGGER_ALIASES set for yoloop. Cheap enough to run on
+ * every invoke.
+ */
+import type { YoloopPersistedState } from './shared-yoloop-types.js';
+import type { DiscoveryHookContext, DiscoveryHookResult } from './discovery-hook.js';
+import type { GraphRetrievalHookContext, GraphRetrievalHookResult } from '../graph-retrieval/pre-command-hook.js';
+/**
+ * Detect whether an args string is a yoloop invocation (including aliases).
+ * Matches: `*yoloop`, `yoloop`, `*auto-yolo`, `*epic-runner`, `*story-runner`,
+ * `*loop-yolo`, `*auto-epic` (case-insensitive, with optional leading whitespace
+ * and optional `*` prefix).
+ */
+export declare function isYoloopTrigger(args: string): boolean;
+/**
+ * Input context for `maybeAutoResolveYoloopArgs`.
+ *
+ * `args` is mutated in place. Caller (invoke.ts) reads the rewritten value
+ * after the hook returns. `projectRoot` and `logger` are read-only.
+ */
+export interface AutoResolveYoloopContext {
+    /** Raw args. Mutated in place when auto-resolve fires. */
+    args: string;
+    /** Absolute path to the consumer project root. */
+    readonly projectRoot: string;
+    /** Optional structural logger (info/warn). Defaults to no-op. */
+    readonly logger?: {
+        info?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+}
+/**
+ * P121.05 -- Zero-config `*yoloop`. When the user types `*yoloop` (or any
+ * alias) with no args, auto-resolve to `<projectRoot>/docs/epics/` if that
+ * directory exists.
+ *
+ * Behavior:
+ *   - Yoloop trigger detection: same regex as P101.07 / P120.04.
+ *   - Args-empty detection: trigger token + optional whitespace; remainder
+ *     `=== ''` after `.trim()`.
+ *   - Directory existence: synchronous `fs.statSync(...).isDirectory()`,
+ *     wrapped in try/catch.
+ *   - Rewrite: appends ` @docs/epics/` to the matched trigger token,
+ *     preserving the original token (canonical or alias) and any leading
+ *     `*` prefix.
+ *   - Fail-soft: any error -> `ctx.logger.warn` + return unchanged args.
+ *
+ * Mutates `ctx.args` in place when auto-resolve fires. Caller (invoke.ts)
+ * propagates the new value via the InvokeOptions immutable update pattern.
+ *
+ * AC1, AC2, AC3, AC4, AC5, AC6, AC7, AC8, AC13.
+ */
+export declare function maybeAutoResolveYoloopArgs(ctx: AutoResolveYoloopContext): void;
+/**
+ * Pre-request hook: read client-side yoloop state for the given project.
+ * Returns undefined for non-yoloop invocations (no I/O). Returns undefined
+ * on read error (fail-soft -- server treats as fresh start).
+ */
+export declare function readYoloopForRequest(args: string, projectRoot: string, nowIso?: string): Promise<YoloopPersistedState | undefined>;
+/**
+ * Post-response hook: apply server-provided operations to local state.
+ * Safe to call for any response — no-op if no yoloopStateUpdate present.
+ * Fail-soft: warns to stderr on error, never throws (the agent already
+ * received instructions; next invoke self-heals via stateSnapshot.yoloop).
+ */
+export declare function persistYoloopFromResponse(metadata: Record<string, unknown> | undefined, projectRoot: string, nowIso?: string): Promise<void>;
+/**
+ * Epic P125.03 -- Post-response hook: persist server-migrated state back
+ * to `.neocortex/state.json` via atomic temp+rename.
+ *
+ * Triggered when `metadata.stateMutated === true` AND
+ * `metadata.migratedState` is a plain object. The server detected legacy
+ * `planning.*` schema in the incoming `stateSnapshot`, ran the
+ * `migrateStateJson` (P103.03) pure-fn in memory, and shipped the canonical
+ * v1 payload back via metadata. This hook writes that payload verbatim to
+ * the client filesystem.
+ *
+ * P101 ADR preserved: the server NEVER touches client filesystem -- the
+ * mutation is computed server-side and persisted client-side. The hook is
+ * the closing half of the contract.
+ *
+ * Atomicity: writes to `.neocortex/state.json.tmp.<random>` first, then
+ * renames into place (POSIX atomic). Guarantees no partial-write corruption
+ * on crash mid-write. Mirrors `YoloopClientStateStore.writeState()`
+ * pattern.
+ *
+ * Fail-soft: any error -> warn to stderr + return. Never throws (caller
+ * already received instructions; next invoke self-heals -- server re-runs
+ * migrate idempotently and re-emits the same payload).
+ */
+export declare function persistMigratedStateFromResponse(metadata: Record<string, unknown> | undefined, projectRoot: string): Promise<void>;
+/**
+ * P120.04: lazy-loaded discovery hook wrapper.
+ *
+ * Short-circuits BEFORE the dynamic import when `featureFlag` is off, so
+ * clients with `YOLOOP_AUTO_DISCOVERY` unset (default) never load the
+ * discovery-hook module. ESM tree-shakers can prune the entire module +
+ * its `shared-discover-epics.ts` mirror in production builds.
+ *
+ * Defensive try/catch around the dynamic import handles the
+ * (vanishingly unlikely) case where the hook module is missing or the
+ * dynamic import itself throws -- never blocks the invoke flow.
+ *
+ * Caller (invoke.ts) is expected to ALSO wrap this in a try/catch as
+ * belt-and-suspenders.
+ */
+export declare function maybeRunDiscoveryHook(ctx: DiscoveryHookContext): Promise<DiscoveryHookResult>;
+/**
+ * P158.06: lazy-loaded graph retrieval wrapper.
+ *
+ * Short-circuits before dynamic import when the feature flag is off. Runtime
+ * errors are public-warning/fail-soft and never block invoke.
+ */
+export declare function maybeRunGraphRetrievalHook(ctx: GraphRetrievalHookContext): Promise<GraphRetrievalHookResult>;

package/packages/client/dist/yoloop/invoke-hooks.js

@@ -0,0 +1,5 @@
+import{YoloopClientStateStore as u}from"./yoloop-client-state-store.js";function g(e){return/^\s*\*?(yoloop|auto-yolo|epic-runner|story-runner|loop-yolo|auto-epic)\b/i.test(e)}const y=/^\s*\*?(yoloop|auto-yolo|epic-runner|story-runner|loop-yolo|auto-epic)\b/i;function h(e){if(typeof e.args!="string"||e.args.length===0)return;const r=e.args.match(y);if(!r)return;const t=r[0];if(e.args.slice(t.length).trim()!=="")return;let a=!1;try{const n=require("node:fs"),i=require("node:path").join(e.projectRoot,"docs","epics");a=n.statSync(i).isDirectory()}catch(n){const s=n instanceof Error?n.message:String(n);e.logger?.warn?.(`[Neocortex] Zero-config *yoloop hook (P121.05): could not stat docs/epics/: ${s}. Proceeding with raw args.`);return}a&&(e.args=`${t} @docs/epics/`,e.logger?.info?.("[Neocortex] Zero-config *yoloop (P121.05): auto-resolved empty args to @docs/epics/"))}async function w(e,r,t){if(g(e))try{return await new u(r).readAll(t)}catch(o){process.stderr.write(`[yoloop] Failed to read local state: ${o.message}. Continuing without state.
+`);return}}async function k(e,r,t){if(!e)return;const o=e.yoloopStateUpdate;if(!(!o||!Array.isArray(o.operations)||o.operations.length===0))try{await new u(r).applyUpdate(o,t)}catch(a){const n=a.message??String(a);process.stderr.write(`[yoloop] Failed to persist state: ${n}. Your next *yoloop may repeat or skip an operation. Run *yoloop again to retry.
+`)}}async function j(e,r){if(!e||e.stateMutated!==!0)return;const t=e.migratedState;if(!(!t||typeof t!="object"||Array.isArray(t)))try{const o=await import("node:fs/promises"),a=await import("node:path"),n=await import("node:crypto"),s=a.join(r,".neocortex"),i=a.join(s,"state.json"),c=a.join(s,`state.json.backup-${new Date().toISOString().replace(/[:.]/g,"-")}`),p=a.join(s,`state.json.tmp.${n.randomBytes(6).toString("hex")}`);await o.mkdir(s,{recursive:!0});try{await o.copyFile(i,c)}catch(l){if(l?.code!=="ENOENT")throw l}const d=JSON.stringify(t,null,2);await o.writeFile(p,d,"utf8"),await o.rename(p,i),process.stderr.write(`[Neocortex P125.03] state.json auto-migrated to canonical v1 schema by server. Legacy planning.* fields converted to epics{} + stories{}; backup=${a.basename(c)}.
+`)}catch(o){const a=o.message??String(o);process.stderr.write(`[Neocortex P125.03] Failed to persist auto-migrated state: ${a}. Your next invoke will retry (server runs migrate idempotently). If the warning persists, run \`neocortex invoke "*migrate-state --apply"\` manually.
+`)}}async function S(e){if(!e.featureFlag)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"flag off"};try{return await(await import("./discovery-hook.js")).runDiscoveryHook(e)}catch(r){const t=r instanceof Error?r.message:String(r);return e.logger?.warn?.(`[neocortex] discovery hook (lazy load) failed: ${t}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:`lazy load error: ${t}`}}}async function b(e){if(!e.featureFlag)return{applied:!1,reason:"flag_off"};try{return await(await import("../graph-retrieval/pre-command-hook.js")).runGraphRetrievalHook(e)}catch(r){const t=r instanceof Error?r.message:String(r);return e.logger?.warn?.(`[neocortex] graph retrieval hook (lazy load) failed: ${t}. Proceeding without enrichment.`),{applied:!1,reason:"hook_error",warning:t}}}export{g as isYoloopTrigger,h as maybeAutoResolveYoloopArgs,S as maybeRunDiscoveryHook,b as maybeRunGraphRetrievalHook,j as persistMigratedStateFromResponse,k as persistYoloopFromResponse,w as readYoloopForRequest};

package/packages/client/dist/yoloop/shared-discover-epics.d.ts

@@ -0,0 +1,289 @@
+/**
+ * @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.
+ */
+/**
+ * P120.04: Inlined byte-identical mirror from
+ *          `@neocortex/shared/yoloop/discover-epics`.
+ *
+ * Same regression class as P117.01 (checkpoint inline) + P117.07 (yoloop types
+ * inline) + P119.02 (policy types inline). Mirrors P92.01 server SSoT-Shadow
+ * precedent.
+ *
+ * Live regression: client tarball is published standalone via `@ornexus/neocortex`
+ * and does NOT include `@neocortex/shared` as a runtime dependency (workspace
+ * package, excluded from tarball per `.npmignore` + `tsconfig.build.json`). Any
+ * non-erased import of `@neocortex/shared` in `packages/client/dist/yoloop/**`
+ * causes runtime `ERR_MODULE_NOT_FOUND` on globally installed `@ornexus/neocortex`.
+ * For P120.04 this would silently disable the discovery hook, defeating the
+ * P120 epic premise (filesystem epics deserve to run).
+ *
+ * Sync responsibility: `discover-shared-sync.test.ts` (client-side drift test,
+ * AC equivalent of P117.01/P117.07/P119.02 drift tests).
+ *
+ * Defense-in-depth: `validate-pre-publish.js` ships `validateClientNoSharedImport()`
+ * (P117.01 expanded by P118.01 to whole-tree) — match = exit 1 (publish blocked).
+ *
+ * DO NOT EDIT WITHOUT also editing `packages/shared/src/yoloop/discover-epics.ts`.
+ *
+ * Pattern references:
+ *  - P92.01 (SSoT-Shadow canonical) — server inline mirror precedent
+ *  - P117.01 (checkpoint inline) — first client-side application
+ *  - P117.07 (yoloop types inline) — second application
+ *  - P119.02 (policy types inline) — third application
+ *  - P120.01 (discoverEpicsFromDir SSoT) — source of this mirror
+ *  - P120.02 (mergeDiscoveredIntoState SSoT) — source of this mirror
+ */
+/**
+ * Source of the canonical epic ID resolution.
+ *
+ *   - `'frontmatter'`: `id:` field in YAML frontmatter (highest priority)
+ *   - `'filename-canonical'`: matched `EPIC_FILE_PATTERNS[0]` or `[1]` (numeric)
+ *   - `'filename-slug'`: matched `EPIC_FILE_PATTERNS[2]` (alpha-slug fallback)
+ */
+export type EpicIdSource = 'frontmatter' | 'filename-canonical' | 'filename-slug';
+/**
+ * Descriptor for a discovered epic file.
+ * Wire-format public (consumed by P120.02 merge fn + admin observability).
+ */
+export interface EpicDescriptor {
+    /** Canonical ID (e.g., "P119", "01", "customer-portal"). */
+    readonly id: string;
+    /** Basename only (e.g., "epic-P119.md"). */
+    readonly filename: string;
+    /** Path relative to the scan dir. */
+    readonly path: string;
+    /** Optional title from frontmatter. */
+    readonly title?: string;
+    /** Optional status from frontmatter. */
+    readonly status?: string;
+    /** Optional epic dependencies from frontmatter. */
+    readonly depends_on?: readonly string[];
+    /** Provenance marker -- always 'discovered' from this fn. */
+    readonly source: 'discovered';
+    /** ISO 8601 timestamp at discovery time. */
+    readonly discovered_at: string;
+    /** Stories linked to this epic via filename pattern OR frontmatter epic_id. */
+    readonly stories: ReadonlyArray<StoryDescriptor>;
+    /** Internal: how was the canonical ID resolved (debugging + tests). */
+    readonly _idSource: EpicIdSource;
+}
+/**
+ * Descriptor for a discovered story file.
+ * Stories are attached to their owning epic via `EpicDescriptor.stories[]`.
+ */
+export interface StoryDescriptor {
+    /** Canonical (e.g., "P119.01", "01.02"). */
+    readonly id: string;
+    readonly epic_id: string;
+    readonly filename: string;
+    readonly path: string;
+    readonly title?: string;
+    readonly status?: string;
+    readonly depends_on?: readonly string[];
+    readonly files_to_modify?: readonly string[];
+}
+/**
+ * Output shape for `discoverEpicsFromDir`.
+ * `warnings` and `skipped` are non-fatal observability data.
+ */
+export interface DiscoveryResult {
+    readonly epics: ReadonlyArray<EpicDescriptor>;
+    readonly warnings: ReadonlyArray<string>;
+    readonly skipped: ReadonlyArray<string>;
+}
+/**
+ * Filesystem abstraction injected into the discovery fn.
+ * Caller wraps `node:fs` (server / client hook) or supplies an in-memory
+ * mock (tests). Adapter is fail-open: methods MUST swallow IO errors.
+ */
+export interface DiscoveryFsAdapter {
+    /** Returns `true` if path is an existing directory. `false` on any error. */
+    isDirectory(path: string): boolean;
+    /** Returns directory entries (filenames). `[]` on error. */
+    readdir(path: string): ReadonlyArray<string>;
+    /** Returns file content as utf-8 string. `''` on error. */
+    readFile(path: string): string;
+    /** Joins path segments per platform separator. */
+    join(...parts: string[]): string;
+}
+/**
+ * Canonical naming contract for files generated by `*create-epic`.
+ *
+ * Discovery keeps accepting older forms for compatibility, but new generated
+ * files must use only the canonical values below.
+ */
+export declare const GENERATED_NAMING_CONTRACT: Readonly<{
+    readonly epicId: "P{number}";
+    readonly epicFilename: "docs/epics/epic-P{number}.md";
+    readonly storyId: "P{number}.NN";
+    readonly storyFilename: "docs/stories/P{number}.NN.story.md";
+    readonly acceptedOnly: Readonly<{
+        epicFilenames: readonly string[];
+        storyFilenames: readonly string[];
+    }>;
+}>;
+/**
+ * Three accepted epic filename conventions.
+ * Anchored regex (`^...$`) so partial matches are rejected.
+ *
+ *   - `[0]` generated canonical: `epic-P119.md`
+ *         accepted legacy:       `epic-92.5.md`, `epic-277.md`
+ *   - `[1]` accepted legacy:     `EPIC-01-foundation.md`, `EPIC-12_setup.md`
+ *   - `[2]` accepted legacy:     `epic-customer-portal.md`, `epic-feature-x.md`
+ *
+ * Group 1 is the canonical ID (or slug) extracted from the filename.
+ */
+export declare const EPIC_FILE_PATTERNS: readonly [RegExp, RegExp, RegExp];
+/**
+ * Three accepted story filename conventions.
+ *
+ *   - `[0]` generated canonical: `P119.01.story.md`
+ *         accepted legacy:       `01.02.story.md`
+ *   - `[1]` accepted legacy:     `story-P104.04.md`
+ *   - `[2]` accepted legacy:     `EPIC-01.STORY-02.md`
+ *
+ * Group 1 = story ID for `[0]` and `[1]`. For `[2]`, group 1 = epic id,
+ * group 2 = story local id (composite).
+ *
+ * Pattern[0] accepts both `P119.01.story.md` (P-prefix) and `01.02.story.md`
+ * (numeric only) -- the `P?` prefix is optional.
+ */
+export declare const STORY_FILE_PATTERNS: readonly [RegExp, RegExp, RegExp];
+/**
+ * Default filesystem adapter wrapping `node:fs` synchronous APIs.
+ * Lazy-loaded via dynamic require so this module is safe to import in
+ * non-Node environments (browser bundles tree-shake unused calls).
+ *
+ * @example
+ * ```ts
+ * const fs = await buildDefaultDiscoveryFs();
+ * const result = discoverEpicsFromDir(dir, fs);
+ * ```
+ */
+export declare function buildDefaultDiscoveryFs(): Promise<DiscoveryFsAdapter>;
+/**
+ * Resolve canonical epic ID from filename + frontmatter.
+ *
+ * Priority (highest to lowest):
+ *   1. Frontmatter `id:` field (operator-authoritative)
+ *   2. `EPIC_FILE_PATTERNS[0]` canonical (numeric or P-prefix)
+ *   3. `EPIC_FILE_PATTERNS[1]` uppercase numeric
+ *   4. `EPIC_FILE_PATTERNS[2]` alpha-slug fallback
+ *
+ * Returns `null` if no pattern matches AND no frontmatter id.
+ *
+ * @param filename basename only (e.g., `epic-P119.md`)
+ * @param frontmatter parsed frontmatter (may have `id?: string`)
+ */
+export declare function getEpicIdFromDescriptor(filename: string, frontmatter: {
+    id?: string;
+}): {
+    id: string;
+    source: EpicIdSource;
+} | null;
+/**
+ * Scan `dir` for epic markdown files and return discovered descriptors.
+ *
+ * Behavior:
+ *   - Non-recursive scan of `dir/*.md`
+ *   - Sibling stories directory at `<dir>/../stories/*.story.md` (if exists)
+ *   - Files with prefix `_` or `.` are skipped (drafts, hidden)
+ *   - Subdirectories listed in `IGNORED_SUBDIRS` are not recursed
+ *   - Frontmatter parser extracts `id`, `title`, `status`, `epic_id`
+ *   - ID derivation: frontmatter > canonical regex > slug fallback
+ *   - Slug collision: 2nd file with same canonical ID gets `-2`, `-3` suffix + warning
+ *   - Story-to-epic linking: prefer frontmatter `epic_id` field, fallback filename pattern
+ *   - Default fs adapter wraps `node:fs` synchronous methods (lazy-loaded)
+ *
+ * @param dir absolute or relative path to the epics directory
+ * @param fs optional fs adapter; defaults to `node:fs` wrapper (lazy)
+ * @returns DiscoveryResult with epics, warnings, skipped arrays
+ */
+export declare function discoverEpicsFromDir(dir: string, fs: DiscoveryFsAdapter): DiscoveryResult;
+/**
+ * Options for `mergeDiscoveredIntoState`.
+ *
+ * Wire-format public (consumed by P120.04 client hook + tests).
+ */
+export interface MergeOptions {
+    /**
+     * Force discovered entries to overwrite `source: 'create-epic'` records.
+     * Default: `false` (defense in depth -- canonical registrations are
+     * preserved by default to prevent silent overwrite by misconfigured
+     * discovery hooks).
+     */
+    readonly forceOverwrite?: boolean;
+    /**
+     * Override `new Date().toISOString()` for deterministic test output.
+     * When provided, all `discovered_at` and `merged_at` fields use this value.
+     */
+    readonly nowIso?: string;
+}
+/**
+ * Result of `mergeDiscoveredIntoState`.
+ * Caller-readable counters for telemetry / observability.
+ */
+export interface MergeResult {
+    /** Reference to the (possibly mutated) state object for chaining. */
+    readonly state: {
+        epics: Record<string, unknown>;
+        stories: Record<string, unknown>;
+    };
+    /** IDs of epics newly added to `state.epics`. */
+    readonly added: ReadonlyArray<string>;
+    /**
+     * IDs of epics skipped by the non-overwrite guard, plus reason.
+     * `reason` values: `'create-epic source preserved (defense)'`,
+     * `'orphan story (no parent epic in discovered set)'`.
+     */
+    readonly skipped: ReadonlyArray<{
+        id: string;
+        reason: string;
+    }>;
+    /** Number of stories added to `state.stories`. */
+    readonly storiesAdded: number;
+}
+/**
+ * Merge `DiscoveryResult` (from `discoverEpicsFromDir`) into a `state` object,
+ * preserving canonical `*create-epic`-registered entries unless `forceOverwrite`.
+ *
+ * **Critical defense**: the non-overwrite guard prevents discovered entries
+ * from clobbering valuable canonical registrations. Even with `forceOverwrite:
+ * true`, the function preserves the existing `source` field for audit trail.
+ *
+ * **Idempotency**: re-running merge with the same `discovered` + same `state`
+ * produces identical output (no duplicate stories, timestamps from first run
+ * preserved). Critical for `/loop` iteration which may re-invoke discovery
+ * between stories.
+ *
+ * **Mutation semantics**: state is mutated in place for performance (state.json
+ * can have hundreds of entries). Caller (P120.04 client hook) is responsible
+ * for deep cloning before merge if needed for diffing/audit.
+ *
+ * @param state target state object (`null`/`undefined` ok -- treated as empty)
+ * @param discovered discovery result (epics + warnings + skipped)
+ * @param options optional behavior modifiers
+ * @returns `MergeResult` with mutated state + telemetry counters
+ *
+ * @example
+ * ```ts
+ * const result = mergeDiscoveredIntoState(state, discovered);
+ * if (result.skipped.length > 0) {
+ *   console.warn('skipped:', result.skipped);
+ * }
+ * console.info(`merged ${result.added.length} epics, ${result.storiesAdded} stories`);
+ * ```
+ */
+export declare function mergeDiscoveredIntoState(state: {
+    epics?: Record<string, unknown>;
+    stories?: Record<string, unknown>;
+} | null | undefined, discovered: DiscoveryResult, options?: MergeOptions): MergeResult;

package/packages/client/dist/yoloop/shared-discover-epics.js

@@ -0,0 +1 @@
+const B=Object.freeze({epicId:"P{number}",epicFilename:"docs/epics/epic-P{number}.md",storyId:"P{number}.NN",storyFilename:"docs/stories/P{number}.NN.story.md",acceptedOnly:Object.freeze({epicFilenames:Object.freeze(["docs/epics/epic-{number}.md","docs/epics/EPIC-{number}-{slug}.md","docs/epics/EPIC-{number}_{slug}.md","docs/epics/epic-{slug}.md"]),storyFilenames:Object.freeze(["docs/stories/{number}.NN.story.md","docs/stories/story-P{number}.NN.md","docs/stories/story-{number}.NN.md","docs/stories/EPIC-{number}.STORY-{number}.md"])})}),$=Object.freeze([/^epic-(P?\d+(?:\.\d+)?)\.md$/i,/^EPIC-(\d+)(?:[-_].*)?\.md$/,/^epic-([a-z0-9][a-z0-9_-]*)\.md$/i]),z=Object.freeze([/^(P?\d+\.\d+(?:\.\d+)?)\.story\.md$/i,/^story-(P?\d+\.\d+)\.md$/i,/^EPIC-(\d+)\.STORY-(\d+)\.md$/]),v=Object.freeze(["_archive","_drafts","archive","drafts"]),D=/^---\s*\n([\s\S]*?)\n---/;function O(t,e){const n=new RegExp(`^${e}:\\s*(.+?)\\s*$`,"mi"),s=t.match(n);if(!s)return;let o=s[1].trim();return(o.startsWith('"')&&o.endsWith('"')||o.startsWith("'")&&o.endsWith("'"))&&(o=o.slice(1,-1)),o||void 0}function I(t){if(typeof t!="string"||t.length===0)return{};const e=t.match(D);if(!e)return{};const n=e[1];return{id:O(n,"id"),title:O(n,"title"),status:O(n,"status"),epic_id:O(n,"epic_id"),depends_on:R(n),files_to_modify:S(n,"files_to_modify")}}function E(t){let e=t.trim();if((e.startsWith('"')&&e.endsWith('"')||e.startsWith("'")&&e.endsWith("'"))&&(e=e.slice(1,-1).trim()),!!e&&!/^(null|undefined|true|false)$/i.test(e))return e}function R(t){return S(t,"depends_on")}function S(t,e){const n=e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),o=t.match(new RegExp(`^${n}:[ \\t]*(.+?)[ \\t]*$`,"mi"))?.[1]?.trim();if(o!==void 0){const p=(o.startsWith("[")&&o.endsWith("]")?o.slice(1,-1).split(","):[o]).map(E).filter(f=>typeof f=="string"&&f.length>0);return p.length>0?Object.freeze(p):void 0}const m=t.split(/\r?\n/),h=[];let l=!1;for(const _ of m){if(!l){new RegExp(`^${n}:\\s*$`,"i").test(_.trim())&&(l=!0);continue}if(/^[A-Za-z0-9_-]+:\s*/.test(_))break;const p=_.match(/^\s*-\s*(.+?)\s*$/);if(!p)continue;const f=E(p[1]);f&&h.push(f)}return h.length>0?Object.freeze(h):void 0}function F(t){return t.startsWith("_")||t.startsWith(".")}function N(t){return v.includes(t)}async function U(){const t=await import("node:fs"),e=await import("node:path");return{isDirectory(n){try{return t.statSync(n).isDirectory()}catch{return!1}},readdir(n){try{return t.readdirSync(n)}catch{return[]}},readFile(n){try{return t.readFileSync(n,"utf8")}catch{return""}},join(...n){try{return e.join(...n)}catch{return n.join("/")}}}}function x(t,e){let n=!1,s=null,o=null;for(let m=0;m<$.length;m++){const h=$[m],l=t.match(h);if(l){n=!0,s=l[1],o=m===2?"filename-slug":"filename-canonical";break}}return n?e.id&&e.id.length>0?{id:e.id,source:"frontmatter"}:{id:s,source:o}:null}function T(t){for(const e of $){const n=t.match(e);if(n)return n[1]}return null}function j(t){const e=t.trim();return/^\d+(?:\.\d+)*$/i.test(e)?`P${e}`.toUpperCase():e.toUpperCase()}function W(t){const e=j(t);return/^P\d+(?:\.\d+)?$/i.test(e)?`epic-${e}.md`:`epic-${t}.md`}function C(t){const e=j(t);return/^P\d+\.\d+(?:\.\d+)?$/i.test(e)?`${e}.story.md`:`${t}.story.md`}function w(t,e){return!t||!e?!1:j(t)!==j(e)}function M(t,e,n){return`frontmatter/filename mismatch: epic '${t}' has frontmatter id '${e}' but filename implies '${n}'. Repair by using generated canonical '${W(e)}' or changing frontmatter id to '${n}'.`}function k(t,e,n){return`frontmatter/filename mismatch: story '${t}' has frontmatter id '${e}' but filename implies '${n}'. Repair by using generated canonical '${C(e)}' or changing frontmatter id to '${n}'.`}function A(t){let e=t.match(z[0]);if(e){const n=e[1],s=n.indexOf(".");return{id:n,epic_id_hint:s>0?n.slice(0,s):null}}if(e=t.match(z[1]),e){const n=e[1],s=n.indexOf(".");return{id:n,epic_id_hint:s>0?n.slice(0,s):null}}if(e=t.match(z[2]),e){const n=e[1],s=e[2];return{id:`${n}.${s}`,epic_id_hint:n}}return null}function L(t,e){return e.join(t,"..","stories")}function Y(t,e){const n=[],s=[],o=[],m=new Date().toISOString();if(typeof t!="string"||t.length===0)return Object.freeze({epics:Object.freeze([]),warnings:Object.freeze([]),skipped:Object.freeze([])});if(!e.isDirectory(t))return Object.freeze({epics:Object.freeze([]),warnings:Object.freeze([]),skipped:Object.freeze([])});const h=[...e.readdir(t)].sort(),l=[];for(const i of h){const r=e.join(t,i);if(F(i)){s.push(`${i}: ignored (draft or hidden prefix)`);continue}if(e.isDirectory(r)){if(N(i)){s.push(`${i}: ignored subdirectory`);continue}s.push(`${i}: subdirectory not recursed`);continue}if(!i.endsWith(".md"))continue;if(!$.some(g=>g.test(i))){s.push(`${i}: did not match any EPIC_FILE_PATTERNS`);continue}const d=e.readFile(r),y=I(d),u=T(i);y.id&&w(y.id,u)&&n.push(M(i,y.id,u)),l.push({filename:i,fullPath:r,frontmatter:y})}const _=new Map,p=[];for(const i of l){const r=x(i.filename,i.frontmatter);if(r===null){s.push(`${i.filename}: id resolution returned null`);continue}let c=r.id;const d=c,y=_.get(d)??0;y>0&&(c=`${d}-${y+1}`,n.push(`epic ID collision: '${d}' resolved to '${c}' for ${i.filename}`)),_.set(d,y+1),p.push({candidate:i,finalId:c,idSource:r.source})}const f=new Map,b=L(t,e);if(e.isDirectory(b)){const i=[...e.readdir(b)].sort();for(const r of i){if(F(r)||!r.endsWith(".md"))continue;const c=e.join(b,r);if(e.isDirectory(c))continue;const d=A(r);if(!d)continue;const y=e.readFile(c),u=I(y);u.id&&w(u.id,d.id)&&n.push(k(r,u.id,d.id));const g=u.epic_id??d.epic_id_hint;if(!g){n.push(`story '${r}' has no epic_id (frontmatter or filename pattern)`);continue}const P=Object.freeze({id:d.id,epic_id:g,filename:r,path:c,...u.title?{title:u.title}:{},...u.status?{status:u.status}:{},...u.depends_on?{depends_on:u.depends_on}:{},...u.files_to_modify?{files_to_modify:u.files_to_modify}:{}});f.has(g)||f.set(g,[]),f.get(g).push(P)}}for(const i of p){const r=f.get(i.finalId)??[],c=Object.freeze({id:i.finalId,filename:i.candidate.filename,path:i.candidate.fullPath,...i.candidate.frontmatter.title?{title:i.candidate.frontmatter.title}:{},...i.candidate.frontmatter.status?{status:i.candidate.frontmatter.status}:{},...i.candidate.frontmatter.depends_on?{depends_on:i.candidate.frontmatter.depends_on}:{},source:"discovered",discovered_at:m,stories:Object.freeze([...r]),e:i.idSource});o.push(c)}const a=new Set(o.map(i=>i.id));for(const[i,r]of f.entries())if(!a.has(i))for(const c of r)n.push(`orphan story '${c.filename}' references unknown epic '${i}'`);return Object.freeze({epics:Object.freeze(o),warnings:Object.freeze(n),skipped:Object.freeze(s)})}function G(t){if(typeof t!="string")return!1;const e=t.trim().toLowerCase().replace(/_/g,"-");return e==="done"||e==="completed"||e==="merged"}function Z(t,e,n){const s=t??{};(!s.epics||typeof s.epics!="object")&&(s.epics={}),(!s.stories||typeof s.stories!="object")&&(s.stories={});const o=s.epics,m=s.stories,h=[],l=[];let _=0;const p=n?.forceOverwrite===!0,f=n?.nowIso??new Date().toISOString(),b=new Set;for(const a of e.epics)b.add(a.id);for(const a of e.epics){const i=o[a.id];if(i&&i.source==="create-epic"&&!p){l.push({id:a.id,reason:"create-epic source preserved (defense)"});continue}if(i&&i.source==="discovered"&&!p){const c=i;c.depends_on=a.depends_on??[];continue}const r={id:a.id,title:a.title??"",status:a.status??"planning",source:"discovered",discovered_at:f,merged_at:f,stories:a.stories.map(c=>c.id),depends_on:a.depends_on??[]};o[a.id]=r,h.push(a.id)}for(const a of e.epics)for(const i of a.stories){const r=m[i.id];if(r&&r.source==="create-epic"&&!p){l.push({id:i.id,reason:"create-epic source preserved (defense, story)"});continue}if(r&&G(r.status)&&!p){const d=r;d.depends_on=i.depends_on??[],d.files_to_modify=i.files_to_modify??[];continue}if(r&&r.source==="discovered"&&!p){const d=r;d.depends_on=i.depends_on??[],d.files_to_modify=i.files_to_modify??[];continue}const c={id:i.id,epic_id:i.epic_id,title:i.title??"",status:i.status??"backlog",source:"discovered",discovered_at:f,depends_on:i.depends_on??[],files_to_modify:i.files_to_modify??[]};m[i.id]=c,_++}return{state:s,added:Object.freeze([...h]),skipped:Object.freeze([...l]),storiesAdded:_}}export{$ as EPIC_FILE_PATTERNS,B as GENERATED_NAMING_CONTRACT,z as STORY_FILE_PATTERNS,U as buildDefaultDiscoveryFs,Y as discoverEpicsFromDir,x as getEpicIdFromDescriptor,Z as mergeDiscoveredIntoState};