peaks-loop 4.0.9 → 4.0.11

package/dist/services/audit/enforcers/active-skill-resolver.js

@@ -24,11 +24,11 @@
  *      `legacyPresence === true` is passed by the caller
  *   4. null (caller did not set a skill; enforcers can decide to skip)
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getSessionIdCanonical } from '../../session/session-manager.js';
 import { getSessionDir } from '../../session/getSessionDir.js';
-import { readPresenceLease } from '../../skills/presence-lease-service.js';
+import { readPresenceLease, listPresenceLeases } from '../../skills/presence-lease-service.js';
 import { getCurrentSessionId } from '../../skills/skill-presence-service.js';
 const ACTIVE_SKILL_PREFIX = 'active-skill-';
 /**
@@ -43,71 +43,82 @@ const ACTIVE_SKILL_PREFIX = 'active-skill-';
 export function resolveActiveSkillForCaller(projectRoot, opts) {
     const envOverride = process.env.PEAKS_ACTIVE_SKILL;
     if (typeof envOverride === 'string' && envOverride.length > 0) {
-        return { skill: envOverride, callerId: null, sessionId: null, source: 'env' };
+        return { skill: envOverride, callerId: null, sessionId: null, mode: null, source: 'env' };
     }
     let sessionId = null;
     try {
         sessionId = getSessionIdCanonical(projectRoot);
     }
     catch {
-        return { skill: null, callerId: null, sessionId: null, source: 'none' };
+        return { skill: null, callerId: null, sessionId: null, mode: null, source: 'none' };
     }
     if (sessionId === null) {
-        return { skill: null, callerId: null, sessionId: null, source: 'none' };
+        return { skill: null, callerId: null, sessionId: null, mode: null, source: 'none' };
     }
     // 4.0.8 preferred: read the canonical lease projection. The lease
-    // service exposes `readPresenceLease({ projectRoot, sessionId,
-    // callerId, workflowId, graphRef })`; we need *some* callerId to
-    // point at a single lease. Hook enforcers don't have a callerId
-    // (they're per-IDE, per-window), so we walk the canonical
-    // presence-index to find any active lease. When the index is empty
-    // (e.g. ad-hoc / pre-migration projects) we fall through to the
-    // legacy walk below.
+    // service writes leases to `<sessionDir>/leases/presence-<caller>-<workflow>.json`
+    // (RD §4). We enumerate that directory via `listPresenceLeases`,
+    // which is the lease-service's own helper and knows the canonical
+    // layout. The first in-flight (status === 'preparing' | 'running')
+    // lease wins; this preserves the prior behaviour of returning a
+    // single skill per resolution. When the lease dir is empty (e.g.
+    // ad-hoc / pre-migration projects) we fall through to the legacy
+    // walk below.
     const sessionDir = getSessionDir(projectRoot, sessionId);
     if (!existsSync(sessionDir)) {
-        return { skill: null, callerId: null, sessionId, source: 'none' };
+        return { skill: null, callerId: null, sessionId, mode: null, source: 'none' };
     }
-    let entries = [];
+    let canonicalLeases = [];
     try {
-        entries = readdirSync(sessionDir);
+        canonicalLeases = listPresenceLeases(projectRoot, sessionId);
     }
     catch {
-        entries = [];
+        canonicalLeases = [];
     }
-    const indexEntries = entries.filter((e) => !e.startsWith(ACTIVE_SKILL_PREFIX) && e.endsWith('.json') && !e.includes('.tmp-'));
-    for (const entry of indexEntries) {
-        // The canonical presence-index lives at `<sessionDir>/presence-index/<callerId>.json`.
-        // We synthesise the read from any presence-* lease file we find;
-        // the readPresenceLease call surfaces a typed `PresenceProjection`
-        // and we map `lease.skill` → resolution.
-        if (!entry.startsWith('presence-'))
+    for (const lease of canonicalLeases) {
+        if (lease.status !== 'preparing' && lease.status !== 'running')
             continue;
-        const callerId = entry.slice('presence-'.length, -'.json'.length);
-        // Derive workflowId from the same file name (canonical
-        // leaseFilePath encodes `presence-<caller>-<workflow>.json`).
-        const lastDash = callerId.lastIndexOf('-');
-        if (lastDash < 0)
+        if (typeof lease.skill !== 'string' || lease.skill.length === 0)
+            continue;
+        // When a callerId is supplied, restrict the walk to that
+        // caller's lease. Slice 2026-08-04-rid-005 surfaces this for the
+        // statusline read so two concurrent sessions bound to the same
+        // project session do not see each other's skill.
+        if (typeof opts?.callerId === 'string' && opts.callerId.length > 0 && lease.callerId !== opts.callerId)
             continue;
-        const workflowId = callerId.slice(lastDash + 1);
-        const pureCaller = callerId.slice(0, lastDash);
         try {
             const projection = readPresenceLease({
                 projectRoot,
                 sessionId,
-                callerId: pureCaller,
-                workflowId,
-                graphRef: `graphs/${workflowId}.json`,
+                callerId: lease.callerId,
+                workflowId: lease.workflowId,
+                graphRef: lease.graphRef,
             });
             if (projection.lease !== null && typeof projection.lease.skill === 'string' && projection.lease.skill.length > 0) {
-                return { skill: projection.lease.skill, callerId: pureCaller, sessionId, source: 'canonical' };
+                return {
+                    skill: projection.lease.skill,
+                    callerId: lease.callerId,
+                    sessionId,
+                    mode: typeof projection.mode === 'string' && projection.mode.length > 0 ? projection.mode : null,
+                    source: 'canonical',
+                };
             }
         }
-        catch { /* fall through to legacy walk */ }
+        catch { /* fall through to next lease */ }
     }
     // Legacy fall-back (one minor release). Gated on `legacyPresence:
-    // true` so production hooks prefer the canonical projection.
+    // true` so production hooks prefer the canonical projection. Reads
+    // the session dir root for the per-caller `active-skill-*.json`
+    // marker files written by the 4.0.7 `setSkillPresenceForCaller`.
     if (opts?.legacyPresence === true) {
-        for (const entry of entries) {
+        let legacyEntries = [];
+        try {
+            legacyEntries = readdirSync(sessionDir);
+        }
+        catch {
+            legacyEntries = [];
+        }
+        for (const entry of legacyEntries) {
             if (!entry.startsWith(ACTIVE_SKILL_PREFIX) || !entry.endsWith('.json'))
                 continue;
             const callerId = entry.slice(ACTIVE_SKILL_PREFIX.length, -'.json'.length);
@@ -116,7 +127,10 @@ export function resolveActiveSkillForCaller(projectRoot, opts) {
                 const raw = readFileSync(filePath, 'utf8');
                 const parsed = JSON.parse(raw);
                 if (typeof parsed.skill === 'string' && parsed.skill.length > 0) {
-                    return { skill: parsed.skill, callerId, sessionId, source: 'file' };
+                    const legacyMode = typeof parsed.mode === 'string' && parsed.mode.length > 0
+                        ? parsed.mode
+                        : null;
+                    return { skill: parsed.skill, callerId, sessionId, mode: legacyMode, source: 'file' };
                 }
             }
             catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
@@ -129,5 +143,5 @@ export function resolveActiveSkillForCaller(projectRoot, opts) {
     // walk can still resolve a session id if the canonical resolver
     // returns null (e.g. ad-hoc projects without a `.peaks/_runtime/session.json`).
     void getCurrentSessionId;
-    return { skill: null, callerId: null, sessionId, source: 'none' };
+    return { skill: null, callerId: null, sessionId, mode: null, source: 'none' };
 }

package/dist/services/container/container-lease.js

@@ -29,6 +29,7 @@
  */
 import { randomBytes } from 'node:crypto';
 import { posix as path } from 'node:path';
+import { normalizePath } from '../../shared/path-utils.js';
 export const DEFAULT_TTL_BY_ROLE = Object.freeze({
     rd: 30 * 60 * 1_000,
     qa: 15 * 60 * 1_000,
@@ -126,7 +127,7 @@ export function deserializeContainerLease(raw) {
 function joinPath(...segments) {
     if (segments.length === 0)
         return '';
-    const normalized = segments.map((s) => s.replace(/\\/g, '/'));
+    const normalized = segments.map((s) => normalizePath(s));
     let acc = normalized[0];
     for (let i = 1; i < normalized.length; i++) {
         acc = path.join(acc, normalized[i]);

package/dist/services/impact/impact-scan-service.js

@@ -13,6 +13,7 @@
  * command; `peaks impact must-check` returns the must-check list
  * subset. Persistence is per-invocation (no state file).
  */
+import { normalizePath } from '../../shared/path-utils.js';
 /**
  * Default business flow map (covers the most common B-end
  * archetypes; users can override via --flows in the CLI).
@@ -34,7 +35,7 @@ export const DEFAULT_BUSINESS_FLOWS = new Map([
  * (the file itself, the parent dir, the project-wide pattern).
  */
 function pathToGlobs(path) {
-    const normalized = path.replace(/\\/g, '/');
+    const normalized = normalizePath(path);
     const parts = normalized.split('/');
     // Drop the filename → get the parent pattern: "src/foo/" → "src/**"
     const parent = parts.length > 1 ? parts.slice(0, -1).join('/') + '/**' : '**';
@@ -42,7 +43,7 @@ function pathToGlobs(path) {
 }
 /** Simple glob matcher supporting `**` and `*`. */
 export function matchGlob(pattern, path) {
-    const normalizedPath = path.replace(/\\/g, '/');
+    const normalizedPath = normalizePath(path);
     // Build regex by splitting on glob tokens, escaping the rest.
     // Order: ** (doublestar) → .* ; * → [^/]* ; other → escape
     let regexStr = '';
@@ -108,7 +109,7 @@ export function runImpactScan(opts) {
     // Predict other files that may be affected (siblings of changed files).
     const impactedFiles = [];
     for (const f of changed) {
-        const parts = f.replace(/\\/g, '/').split('/');
+        const parts = normalizePath(f).split('/');
         if (parts.length <= 1)
             continue;
         const parent = parts.slice(0, -1).join('/');

package/dist/services/migrate-skill-name/migrate.js

@@ -19,6 +19,7 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { normalizePath } from '../../shared/path-utils.js';
 /**
  * Skip-paths are matched against the path relative to `projectRoot`,
  * forward-slashed (Windows-friendly). Each entry is a SUBSTRING —
@@ -41,7 +42,7 @@ function escapeRe(input) {
 }
 /** True iff `absPath` falls under any skip-path (substring match). */
 export function shouldSkip(projectRoot, absPath) {
-    const rel = relative(projectRoot, absPath).replace(/\\/g, '/');
+    const rel = normalizePath(relative(projectRoot, absPath));
     return SKIP_DIRS.some((skip) => rel.includes(skip));
 }
 /**

package/dist/services/openspec/artifact-boundary.js

@@ -22,6 +22,7 @@
  */
 import { posix, relative, resolve, isAbsolute as nodeIsAbsolute } from 'node:path';
 import { isPathInsideArtifactRoot as _isPathInsideArtifactRoot } from '../../shared/path-safety.js';
+import { normalizePath } from '../../shared/path-utils.js';
 export function ok(value) {
     return { ok: true, value };
 }
@@ -111,7 +112,7 @@ export function planArtifactPath(input) {
     // Always normalize separators to forward-slashes for the JSON-safe output,
     // then run posix.normalize so empty segments (foo//bar) and `..` segments
     // collapse to canonical form.
-    const forwardSlashed = candidateRaw.replace(/\\/g, '/');
+    const forwardSlashed = normalizePath(candidateRaw);
     const normalized = posix.normalize(forwardSlashed);
     // Resolve against workspaceRoot. If the candidate is already absolute,
     // posix.normalize preserves the leading `/`; `resolve` keeps it absolute
@@ -129,7 +130,7 @@ export function planArtifactPath(input) {
         });
     }
     const relativePath = relative(workspaceRoot, absolutePath);
-    const jsonSafeRelativePath = relativePath.replace(/\\/g, '/');
+    const jsonSafeRelativePath = normalizePath(relativePath);
     return ok({ absolutePath, relativePath, jsonSafeRelativePath });
 }
 const WORKSPACE_UNAVAILABLE_NEXT_ACTIONS = [

package/dist/services/openspec/coverage-evidence-reader.js

@@ -24,6 +24,7 @@ import { posix, relative, resolve } from 'node:path';
 import { readFile, stat } from 'node:fs/promises';
 import { isDirectory } from 'peaks-loop-shared/fs';
 import { ok, err } from './artifact-boundary.js';
+import { normalizePath } from '../../shared/path-utils.js';
 // ---------------------------------------------------------------------------
 // Discovery
 // ---------------------------------------------------------------------------
@@ -63,7 +64,7 @@ export async function resolveCoverageSummaryPath(input) {
     return err({ code: 'missing', triedPaths });
 }
 function toPosix(p) {
-    return p.replace(/\\/g, '/').replace(/\/$/, '');
+    return normalizePath(p).replace(/\/$/, '');
 }
 async function isReadable(p) {
     try {
@@ -112,7 +113,7 @@ export async function readC8Summary(path) {
         if (lines === null || statements === null || functions === null || branches === null) {
             continue;
         }
-        const normalizedKey = posix.normalize(key.replace(/\\/g, '/'));
+        const normalizedKey = posix.normalize(normalizePath(key));
         files.set(normalizedKey, {
             path: normalizePathSep(normalizedKey),
             relativePath: normalizedKey,
@@ -141,7 +142,7 @@ function asMetric(input) {
     return { pct, covered, total };
 }
 function normalizePathSep(p) {
-    return p.replace(/\\/g, '/');
+    return normalizePath(p);
 }
 // ---------------------------------------------------------------------------
 // Capability Mapping block parser (proposal.md)
@@ -215,7 +216,7 @@ function parseCapabilityRow(line) {
         return null;
     const row = {
         capability,
-        source: source.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, ''),
+        source: normalizePath(source).replace(/^\.\//, '').replace(/\/$/, ''),
     };
     if (testAnchor !== undefined && testAnchor !== '') {
         row.testAnchor = testAnchor;
@@ -236,7 +237,7 @@ function parseCapabilityRow(line) {
 export async function resolveCapabilityFiles(input) {
     const abs = resolve(input.projectRoot, input.row.source);
     if (!(await isDirectory(abs))) {
-        const rel = relative(input.projectRoot, abs).replace(/\\/g, '/');
+        const rel = normalizePath(relative(input.projectRoot, abs));
         return [rel];
     }
     return await walkTsFiles(abs, input.projectRoot);
@@ -261,7 +262,7 @@ async function walkTsFiles(absRoot, projectRoot) {
                 stack.push(full);
             }
             else if (entry.isFile() && entry.name.endsWith('.ts')) {
-                const rel = relative(projectRoot, full).replace(/\\/g, '/');
+                const rel = normalizePath(relative(projectRoot, full));
                 out.push(rel);
             }
         }
@@ -339,7 +340,7 @@ export async function validateCapabilityCoverage(input) {
 export async function findStaleChangeFiles(input) {
     const { stat: statFn } = await import('node:fs/promises');
     const summaryMtime = (await statFn(input.summary.path)).mtimeMs;
-    const changeRoot = `${input.openspecRoot.replace(/\\/g, '/').replace(/\/$/, '')}/changes/${input.changeId}`;
+    const changeRoot = `${normalizePath(input.openspecRoot).replace(/\/$/, '')}/changes/${input.changeId}`;
     const candidates = [
         `${changeRoot}/proposal.md`,
         `${changeRoot}/tasks.md`,
@@ -375,7 +376,7 @@ export async function findStaleChangeFiles(input) {
         try {
             const m = (await statFn(candidate)).mtimeMs;
             if (m > summaryMtime) {
-                stale.push(relative(input.projectRoot, candidate).replace(/\\/g, '/'));
+                stale.push(normalizePath(relative(input.projectRoot, candidate)));
             }
         }
         catch {

package/dist/services/prd/handoff-auto-regen.js

@@ -16,6 +16,7 @@ import { dirname, join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
 import { sha256OfBody } from './handoff-service.js';
+import { normalizePath } from '../../shared/path-utils.js';
 /**
  * Auto-regen the prd/handoff.md under `.peaks/_runtime/<sid>/prd/`.
  * Returns the outcome; never throws.
@@ -58,7 +59,7 @@ export async function autoRegenPrdHandoff(opts) {
         'goals: []',
         'acceptanceCriteria: []',
         'preservedBehavior: []',
-        `handoffPath: ${handoffPath.replace(opts.projectRoot, '').replace(/\\/g, '/').replace(/^\//, '')}`,
+        `handoffPath: ${normalizePath(handoffPath.replace(opts.projectRoot, '')).replace(/^\//, '')}`,
         '---',
         ''
     ].join('\n');

package/dist/services/qa/bdd-test-style-verifier.d.ts

@@ -0,0 +1,88 @@
+/**
+ * src/services/qa/bdd-test-style-verifier.ts
+ *
+ * rid-2026-08-05-bdd-test-style Slice B — peaks-qa verification-time
+ * BDD test-style verifier. This is the read-only, post-edit companion
+ * to the `scripts/migrate-to-bdd.mjs` AST migrator shipped in Slice A.
+ *
+ * Purpose:
+ *   When peaks-qa runs its verification gate, it picks up the git diff
+ *   for the slice and asks this module whether the new / modified test
+ *   files comply with the BDD given-when-then style. The verdict is
+ *   surfaced as either `ok` (and the slice can advance) or one of two
+ *   structured failure reasons (`missing-given-when-then` or
+ *   `description-no-should-when`) that the caller turns into a
+ *   `qa-handoff` rejection back to peaks-rd.
+ *
+ * Why a real AST and not a regex:
+ *   The Slice A migrator established the convention: test files have
+ *   multi-line `it(...)` calls, nested arrow bodies, and string
+ *   literals that often contain words like "when" inside the assertion
+ *   message (not in the description). A regex pass on the raw source
+ *   would false-positive on string internals. The TypeScript Compiler
+ *   API (already a dev dep via vitest) lets us:
+ *     1. Inspect the first `StringLiteral` argument of an `it` /
+ *        `test` / `describe` call without scanning comments or
+ *        string content inside the body.
+ *     2. Walk only the leading-comment ranges that sit before the
+ *        first statement of the callback block, so a `// when:`
+ *        inside an `expect(actual).toEqual('when X happens')` is
+ *        correctly ignored.
+ *
+ * No new dependencies. The verifier is intentionally synchronous and
+ * pure (input source + path list -> verdict) so peaks-qa can call it
+ * from a deterministic verification step without subprocess overhead.
+ *
+ * Anti-fake-green (CLI silent-catch rule):
+ *   This module throws on parse failure. It does NOT swallow parse
+ *   errors and return `{ ok: true }` — that would silently green-light
+ *   malformed test files. A parse error is a structural problem; the
+ *   caller must surface it.
+ */
+/** Structured failure reasons the verifier can return. */
+export type BddStyleFailureReason = 'missing-given-when-then' | 'description-no-should-when';
+/** Successful verdict — includes the count of inspected `it`/`test` calls. */
+export interface BddStyleOk {
+    readonly ok: true;
+    readonly scanned: number;
+}
+/** Structured failure verdict — the file/line makes the rejection actionable. */
+export interface BddStyleFail {
+    readonly ok: false;
+    readonly reason: BddStyleFailureReason;
+    readonly file: string;
+    readonly line: number;
+    /** For `description-no-should-when`: the original description. */
+    readonly description?: string;
+    /** For `missing-given-when-then`: a stable string the caller can compare. */
+    readonly expected?: string;
+}
+export type BddStyleVerdict = BddStyleOk | BddStyleFail;
+/** Public input surface — keep small so the contract is hard to misuse. */
+export interface VerifyBddStyleInput {
+    readonly projectRoot: string;
+    readonly testFiles: readonly string[];
+}
+/**
+ * Verify that every `it(...)` / `test(...)` call in the given test
+ * files follows the BDD given-when-then contract.
+ *
+ * Contract:
+ *   1. The first `StringLiteral` argument of every `it` / `test` call
+ *      MUST match `/(\bwhen\b|\bshould\b)/` (word-boundary anchored,
+ *      case-insensitive). A regex on the raw description is correct
+ *      here because the description itself is a literal — there is
+ *      no nested template literal to misread.
+ *   2. The callback body (the second argument when it is an arrow /
+ *      function expression with a block) MUST have a `// given:`,
+ *      `// when:`, `// then:` triple at the top, in that order,
+ *      within the first 3 leading-comment ranges before the first
+ *      statement. The `// arrange:` / `// act:` / `// assert:` AAA
+ *      legacy is NOT accepted — the contract is given-when-then
+ *      only.
+ *
+ * Returns the FIRST failure encountered (file order, then
+ * top-to-bottom line order). A structured `BddStyleFail` is what the
+ * caller maps to `qa-handoff` rejection.
+ */
+export declare function verifyBddStyle(input: VerifyBddStyleInput): BddStyleVerdict;