peaks-loop 4.1.0 → 4.1.1

package/dist/services/prd/handoff-frontmatter.js

@@ -48,6 +48,20 @@ function blockSequence(key, values) {
         return [`${key}: []`];
     return [`${key}:`, ...values.map((value) => `  - ${yamlScalar(value)}`)];
 }
+/**
+ * The OPTIONAL form: no line at all when the field is absent or empty.
+ *
+ * `goals` and its siblings cannot use this — `isHandoffFrontmatter` requires an
+ * ARRAY there, so an omitted line would fail the shape check on read, and `[]` is
+ * the honest rendering of "declared, none". The authored fields have no such
+ * requirement: a capsule that names no files declares nothing, and a `files: []`
+ * line would read as a claim that the slice touches no file.
+ */
+function blockOptionalSequence(key, values) {
+    if (values === undefined || values.length === 0)
+        return [];
+    return [`${key}:`, ...values.map((value) => `  - ${yamlScalar(value)}`)];
+}
 /**
  * Render `gateEvidence` as a YAML map of quoted path scalars, or as NOTHING.
  *
@@ -103,6 +117,44 @@ function gateEvidenceBlock(evidence) {
     });
     return entries.length === 0 ? [] : ['gateEvidence:', ...entries];
 }
+/**
+ * Render a sequence of records (`decisions`, `risks`) as a YAML block list, or
+ * as NOTHING when the list is absent or empty — the same omission policy as
+ * `gateEvidence`, so a capsule that declares no risks gains no noise line.
+ *
+ * The field names are rendered in the order given, and every value is validated
+ * as a string HERE rather than dropped later. That is deliberate: the bug these
+ * fields fix was a serializer that rendered from the type and so discarded
+ * anything the type did not name, silently, on every rewrite. A record missing a
+ * required field therefore has to stop the write, not vanish from it.
+ */
+function blockRecords(key, items, requiredFields) {
+    if (items === undefined || items.length === 0)
+        return [];
+    const lines = [`${key}:`];
+    items.forEach((rawItem, index) => {
+        // The values are checked at RUNTIME, not trusted from the type, because a
+        // capsule reaches here from `readHandoff` as well as from a producer: the
+        // spread that makes an authored field survive a read also makes it survive
+        // unvalidated. A record missing a required field stops the write rather than
+        // vanishing from it — which is precisely how the old serializer made a
+        // declared risk look satisfied.
+        const record = rawItem !== null && typeof rawItem === 'object' ? { ...rawItem } : {};
+        const missing = requiredFields.filter((field) => typeof record[field] !== 'string' || record[field] === '');
+        if (missing.length > 0) {
+            throw new Error(`handoff: ${key}[${index}] is missing ${missing.join(', ')} — refusing to write a ` +
+                `record the next role cannot read (a risk without a mitigation is a red line, and ` +
+                'dropping the field is how it looked satisfied)');
+        }
+        requiredFields.forEach((field, fieldIndex) => {
+            const value = record[field];
+            lines.push(fieldIndex === 0
+                ? `  - ${field}: ${yamlScalar(value)}`
+                : `    ${field}: ${yamlScalar(value)}`);
+        });
+    });
+    return lines;
+}
 /**
  * Serialize `frontmatter` into the fenced block, terminated by the closing
  * `---` and a trailing newline. Callers append the body verbatim, which keeps
@@ -125,6 +177,15 @@ export function serializeHandoffFrontmatter(frontmatter) {
         ...blockSequence('acceptanceCriteria', frontmatter.acceptanceCriteria),
         ...blockSequence('preservedBehavior', frontmatter.preservedBehavior),
         `handoffPath: ${yamlScalar(frontmatter.handoffPath)}`,
+        // The authored fields: written by peaks-prd / peaks-rd, read by peaks-qa's
+        // mechanical cross-checks, and PRESERVED by every rewrite. They sit after
+        // `handoffPath` because `schemaVersion` and `sha256` must stay first-parsed,
+        // and before `gateEvidence` because that block is last by contract.
+        ...blockOptionalSequence('scope', frontmatter.scope),
+        ...blockOptionalSequence('files', frontmatter.files),
+        ...blockRecords('decisions', frontmatter.decisions, ['id', 'summary', 'rationale']),
+        ...blockRecords('risks', frontmatter.risks, ['id', 'description', 'mitigation']),
+        ...blockOptionalSequence('nextActions', frontmatter.nextActions),
         // LAST, after every anchored field: `schemaVersion` / `sha256` are
         // matched as `^`-anchored lines by the gate and both audit loaders, so
         // nothing new may be inserted before them. A nested map also renders

package/dist/services/prd/handoff-gate-evidence.js

@@ -8,16 +8,8 @@
 // `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:35-41`; the
 // key set is `GATE_EVIDENCE_KEYS` in `./handoff-types.js`.
 //
-// WHAT THIS FILE USED TO SAY, AND WHY THAT WAS FALSE: its header claimed the
-// field was a `string[]` of "gate names" and that `initHandoff` wrote it.
-// Neither held. `grep -rn gateEvidence src/` hit this file and nothing else —
-// there was no producer (`HandoffFrontmatter` had no such field,
-// `serializeHandoffFrontmatter` never emitted it, `initHandoff` rejected it)
-// and no consumer. The field was prose describing data that did not exist,
-// and the comment asserting a producer was the reason nobody noticed.
-//
 // WHAT IS ON DISK NOW, stated precisely because a header that overclaims is
-// the defect above. B1 added the producer FUNCTIONS; B2 wired their callers,
+// the defect below. B1 added the producer FUNCTIONS; B2 wired their callers,
 // which is what made the difference — until then every producer passed
 // nothing, so no capsule carried the field and saying otherwise would have
 // described a fact that held only inside tests (F1 of `rid-b1-qa`). At
@@ -28,7 +20,19 @@
 // artifact is readable — and carries no `gateEvidence` block at all when it
 // is not. Gate C (`checkPrerequisites` at `rd:qa-handoff`) fails a declared
 // path that is not on disk. Every clause above is asserted end-to-end in
-// `tests/unit/prd/gate-evidence-derivation.test.ts`.
+// `tests/unit/prd/gate-evidence-derivation.test.ts`. The derived map is also
+// printed by `peaks prd handoff init` (dry-run and applied), so the key set
+// does not have to be read out of this source file.
+//
+// WHAT THIS FILE USED TO SAY, AND WHY THAT WAS FALSE: its header claimed the
+// field was a `string[]` of "gate names" and that `initHandoff` wrote it.
+// Neither held. `grep -rn gateEvidence src/` hit this file and nothing else —
+// there was no producer (`HandoffFrontmatter` had no such field,
+// `serializeHandoffFrontmatter` never emitted it, `initHandoff` rejected it)
+// and no consumer. The field was prose describing data that did not exist,
+// and the comment asserting a producer was the reason nobody noticed. That
+// paragraph describes the PRE-B1 state; reading it as the current state is
+// the exact misreading that put it here.
 //
 // WHY IT IS STILL STAND-ALONE: keeping the typed-value logic here, rather
 // than in `handoff-service.ts`, keeps `HandoffFrontmatter` a pure data shape

package/dist/services/prd/handoff-service.d.ts

@@ -22,7 +22,7 @@
  * the body content as UTF-8 bytes. The body MUST be the literal
  * markdown source — no normalization, no trailing-newline padding.
  */
-import type { GateEvidence, Handoff, HandoffProbe } from './handoff-types.js';
+import type { GateEvidence, Handoff, HandoffDecision, HandoffProbe, HandoffRisk } from './handoff-types.js';
 export { handoffRelativePath, resolveHandoffPath } from './handoff-path-resolution.js';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
 export declare function sha256OfBody(body: string): string;
@@ -58,6 +58,16 @@ export declare function initHandoff(opts: {
      *  is refused here by a throw and there by a status; neither silently
      *  produces a map the other cannot. */
     gateEvidence?: GateEvidence;
+    /** The authored fields peaks-qa cross-checks (`decisions[] ↔ tests`,
+     *  `risks[] ↔ security tests`, `files[] ↔ git diff`). They are OPTIONAL and
+     *  pass through verbatim: unlike `gateEvidence`, nothing derives them — they
+     *  are a writer's judgement about the slice, so a producer that has not made
+     *  that judgement declares nothing rather than an empty claim. */
+    scope?: readonly string[];
+    files?: readonly string[];
+    decisions?: readonly HandoffDecision[];
+    risks?: readonly HandoffRisk[];
+    nextActions?: readonly string[];
 }): Handoff;
 /** Write a Handoff to disk. `projectRoot` is the absolute project
  *  root (so the `.peaks/_runtime/...` path is resolved absolutely).

package/dist/services/prd/handoff-service.js

@@ -63,7 +63,17 @@ export function initHandoff(opts) {
         // would also make `serializeHandoffFrontmatter`'s
         // `frontmatter.gateEvidence` key present-but-undefined for every caller
         // that declares nothing.
-        ...(opts.gateEvidence === undefined ? {} : { gateEvidence: opts.gateEvidence })
+        ...(opts.gateEvidence === undefined ? {} : { gateEvidence: opts.gateEvidence }),
+        // The authored fields, each spread only when present. The same
+        // `exactOptionalPropertyTypes` reason as `gateEvidence` above: an absent
+        // field is absent, not present-and-undefined, so a capsule that declares
+        // nothing writes nothing — and a copy is taken so a caller mutating its own
+        // array afterwards cannot change a handoff that has already been hashed.
+        ...(opts.scope === undefined ? {} : { scope: [...opts.scope] }),
+        ...(opts.files === undefined ? {} : { files: [...opts.files] }),
+        ...(opts.decisions === undefined ? {} : { decisions: [...opts.decisions] }),
+        ...(opts.risks === undefined ? {} : { risks: [...opts.risks] }),
+        ...(opts.nextActions === undefined ? {} : { nextActions: [...opts.nextActions] })
     };
     return { frontmatter, body: opts.body };
 }

package/dist/services/prd/handoff-types.d.ts

@@ -63,7 +63,39 @@ export type GateEvidence = Readonly<Partial<Record<GateEvidenceKey, string>>>;
  * immutability: once written, peaks-rd / peaks-qa / sub-agents MUST
  * NOT mutate the on-disk copy.
  */
-export interface HandoffFrontmatter {
+/** One entry of `decisions[]` — a choice an implementer could question. */
+export type HandoffDecision = {
+    readonly id: string;
+    readonly summary: string;
+    readonly rationale: string;
+};
+/** One entry of `risks[]`. `mitigation` is required by the field rule in
+ *  `skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:52`: a risk
+ *  without one is a red line, so the type has no optional form of it. */
+export type HandoffRisk = {
+    readonly id: string;
+    readonly description: string;
+    readonly mitigation: string;
+};
+/**
+ * The fields a WRITER authors and a READER cross-checks, absent when the capsule
+ * declares nothing. They were documented as required frontmatter long before the
+ * type carried them — `readHandoff` spread the parsed YAML, so an authored capsule
+ * kept them at runtime while the serializer, which renders from the TYPE, dropped
+ * them on every rewrite. That is the data loss `handoff-auto-regen` used to cause
+ * and these fields exist to end.
+ */
+export type HandoffAuthoredFields = {
+    /** Repo-relative paths this slice touches, sorted. */
+    readonly scope?: readonly string[];
+    /** Files the slice expects in its diff; peaks-qa checks this against git. */
+    readonly files?: readonly string[];
+    readonly decisions?: readonly HandoffDecision[];
+    readonly risks?: readonly HandoffRisk[];
+    /** Verb-first; what the next role does, in order. */
+    readonly nextActions?: readonly string[];
+};
+export interface HandoffFrontmatter extends HandoffAuthoredFields {
     readonly requestId: string;
     readonly sessionId: string;
     readonly schemaVersion: HandoffSchemaVersion;

package/dist/services/recommendations/installed-capability-detector.d.ts

@@ -9,9 +9,9 @@
  * the question from evidence that already exists on disk — no install
  * side effect, no network, no subprocess:
  *
- *   - `everything-claude-code.*` — satisfied when the ECC cache is
- *     populated (`~/.peaks/cache/ecc-installed.json` + at least one
- *     cached/materialized agent).
+ *   - `everything-claude-code.*` — satisfied when the ECC agents are readable,
+ *     i.e. `~/.peaks/agents/ecc/` holds at least one agent (landed by
+ *     `peaks ecc install` from the `ecc-universal` dependency).
  *   - a source that maps to an npm package — satisfied when that package
  *     (or its `.bin` shim) is present in the project's `node_modules`.
  *
@@ -23,8 +23,8 @@ export type InstalledCapabilityProbe = {
     readonly projectRoot: string;
     /** Override for tests; defaults to `<projectRoot>/node_modules`. */
     readonly nodeModulesDir?: string;
-    /** Override for tests; defaults to a live ECC cache probe. */
-    readonly eccCacheAvailable?: boolean;
+    /** Override for tests; defaults to a live probe of the materialized copy. */
+    readonly eccAgentsAvailable?: boolean;
 };
 /**
  * Return the capabilityIds whose acquisition is already satisfied.

package/dist/services/recommendations/installed-capability-detector.js

@@ -9,9 +9,9 @@
  * the question from evidence that already exists on disk — no install
  * side effect, no network, no subprocess:
  *
- *   - `everything-claude-code.*` — satisfied when the ECC cache is
- *     populated (`~/.peaks/cache/ecc-installed.json` + at least one
- *     cached/materialized agent).
+ *   - `everything-claude-code.*` — satisfied when the ECC agents are readable,
+ *     i.e. `~/.peaks/agents/ecc/` holds at least one agent (landed by
+ *     `peaks ecc install` from the `ecc-universal` dependency).
  *   - a source that maps to an npm package — satisfied when that package
  *     (or its `.bin` shim) is present in the project's `node_modules`.
  *
@@ -20,7 +20,7 @@
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { hasMaterializedEccAgents, listCachedAgents } from 'peaks-loop-mut';
+import { hasMaterializedEccAgents } from 'peaks-loop-mut';
 import { seedCapabilityItems } from './capability-seed-items.js';
 const ECC_SOURCE_ID = 'everything-claude-code';
 /**
@@ -42,12 +42,13 @@ function packagePresent(nodeModulesDir, packageName) {
         return false;
     }
 }
-function eccCacheAvailable() {
+function eccAgentsAvailable() {
     try {
-        // Cached agents imply the manifest + sha dir exist; the materialized
-        // plugin-free copy is checked independently so a hand-populated
-        // `~/.peaks/agents/ecc/` still counts as satisfied.
-        return listCachedAgents().length > 0 || hasMaterializedEccAgents();
+        // The materialized copy is what the LLM can dispatch, so it is the only
+        // evidence that counts. The cache probe this replaced
+        // (`listCachedAgents()`, reading `~/.peaks/cache/ecc-<sha>/`) described
+        // something downloaded but not necessarily usable.
+        return hasMaterializedEccAgents();
     }
     catch {
         return false;
@@ -59,7 +60,7 @@ function eccCacheAvailable() {
  */
 export function detectInstalledCapabilityIds(probe) {
     const nodeModulesDir = probe.nodeModulesDir ?? join(probe.projectRoot, 'node_modules');
-    const eccAvailable = probe.eccCacheAvailable ?? eccCacheAvailable();
+    const eccAvailable = probe.eccAgentsAvailable ?? eccAgentsAvailable();
     const installed = new Set();
     for (const item of seedCapabilityItems) {
         if (item.sourceId === ECC_SOURCE_ID) {

package/dist/services/scan/archetype-detection.d.ts

@@ -30,6 +30,43 @@ export declare function readPackageJsonDeps(projectRoot: string): Promise<{
     deps: Record<string, string>;
 }>;
 export declare function detectBackendFrameworks(deps: Record<string, string>): Promise<string[]>;
+/**
+ * Manifests that only a service writes. Language-diverse on purpose: every
+ * other probe in this file is Node-specific, and a repository whose backend is
+ * Go / Java / Kotlin / Python / Ruby / PHP / Rust has no Node manifest at all,
+ * so a Node-only evidence set reported it as `frontendOnly`.
+ */
+export declare const SERVICE_ONLY_MANIFEST_FILES: string[];
+/**
+ * Manifests a service MAY write and a library or CLI also writes. Counted as
+ * backend evidence only when the file itself names a web framework — the
+ * alternative is a boolean that fires on any Python or Rust directory, which
+ * trades one wrong answer for another.
+ */
+export declare const CONDITIONAL_SERVICE_MANIFESTS: ReadonlyArray<readonly [string, RegExp]>;
+/**
+ * How deep from the project root a service is allowed to sit before its
+ * manifest stops being counted. Two levels covers the layouts that were
+ * invisible (`apps/gateway/package.json`, `services/checkout/requirements.txt`,
+ * `web/` + `cmd/server`), and a deeper walk would read generated trees.
+ */
+export declare const SERVICE_MANIFEST_MAX_DEPTH = 2;
+/**
+ * Backend evidence that lives OUTSIDE the root manifest: a workspace package's
+ * own `package.json`, and any non-Node service manifest.
+ *
+ * Returns `dir: evidence` strings (`apps/gateway: express`, `go.mod`,
+ * `services/checkout: requirements.txt`) rather than a boolean, because the
+ * whole defect this probe closes was a verdict that could not say what it saw.
+ */
+export declare function detectNestedServiceEvidence(projectRoot: string, backendDepNames?: readonly string[]): Promise<string[]>;
+/**
+ * Next.js server actions: `'use server'` in a file under `app/`. Route handlers
+ * under `pages/api` / `app/api` were the only Next backend the detector knew
+ * about, so a Next app that mutates data through actions — the documented
+ * Next.js way — was reported as having no backend at all.
+ */
+export declare function detectNextServerActions(projectRoot: string): Promise<boolean>;
 export declare function detectNextApiRoutes(projectRoot: string, hasNext: boolean): Promise<boolean>;
 export declare function detectBackendDirs(projectRoot: string): Promise<string[]>;
 export declare function detectSwagger(projectRoot: string): Promise<string[]>;

package/dist/services/scan/archetype-detection.js

@@ -10,8 +10,8 @@
  * `decideIntegrationMode`) and the public `scanArchetype` entry; the
  * `frontendOnly` / `frontendOnlyReason` output contract is unchanged.
  */
-import { stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative as relativePath } from 'node:path';
 import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
 export const BACKEND_DEP_NAMES = [
     'express',
@@ -85,6 +85,179 @@ export async function readPackageJsonDeps(projectRoot) {
 export async function detectBackendFrameworks(deps) {
     return BACKEND_DEP_NAMES.filter((name) => name !== 'next' && Object.prototype.hasOwnProperty.call(deps, name));
 }
+/**
+ * Manifests that only a service writes. Language-diverse on purpose: every
+ * other probe in this file is Node-specific, and a repository whose backend is
+ * Go / Java / Kotlin / Python / Ruby / PHP / Rust has no Node manifest at all,
+ * so a Node-only evidence set reported it as `frontendOnly`.
+ */
+export const SERVICE_ONLY_MANIFEST_FILES = [
+    'go.mod',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'settings.gradle',
+    'settings.gradle.kts',
+    'manage.py',
+    'config.ru',
+    'artisan'
+];
+/**
+ * Manifests a service MAY write and a library or CLI also writes. Counted as
+ * backend evidence only when the file itself names a web framework — the
+ * alternative is a boolean that fires on any Python or Rust directory, which
+ * trades one wrong answer for another.
+ */
+export const CONDITIONAL_SERVICE_MANIFESTS = [
+    ['requirements.txt', /\b(fastapi|flask|django|uvicorn|gunicorn|aiohttp|tornado|starlette)\b/i],
+    ['pyproject.toml', /\b(fastapi|flask|django|uvicorn|gunicorn|aiohttp|tornado|starlette)\b/i],
+    ['Cargo.toml', /\b(actix-web|axum|rocket|warp|tonic|hyper|poem)\b/i],
+    ['Gemfile', /\b(rails|sinatra|hanami|puma|rack)\b/i],
+    ['composer.json', /\b(laravel|symfony|slim)\b/i]
+];
+/** Directories never worth descending into when looking for a service manifest. */
+const MANIFEST_WALK_SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'target',
+    'vendor',
+    '__pycache__',
+    '.git'
+]);
+/**
+ * How deep from the project root a service is allowed to sit before its
+ * manifest stops being counted. Two levels covers the layouts that were
+ * invisible (`apps/gateway/package.json`, `services/checkout/requirements.txt`,
+ * `web/` + `cmd/server`), and a deeper walk would read generated trees.
+ */
+export const SERVICE_MANIFEST_MAX_DEPTH = 2;
+/**
+ * How many leading bytes of a source file are read to find a directive. `'use
+ * server'` must be the first statement, so the head is the whole question, and
+ * reading a bounded head keeps this probe from pulling multi-megabyte files into
+ * memory.
+ */
+const DIRECTIVE_HEAD_BYTES = 400;
+async function readDirSafe(dir) {
+    try {
+        return await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        // An unreadable directory is not evidence of a backend, and not of its
+        // absence either; the root manifest already carries the project.
+        return [];
+    }
+}
+function relativeFromRoot(projectRoot, dir) {
+    return relativePath(projectRoot, dir).replace(/\\/g, '/');
+}
+function labeled(relative, file) {
+    return relative === '' ? file : `${relative}/${file}`;
+}
+function descendable(entries, dir, depth) {
+    if (depth >= SERVICE_MANIFEST_MAX_DEPTH)
+        return [];
+    return entries
+        .filter((entry) => entry.isDirectory() &&
+        !MANIFEST_WALK_SKIP_DIRS.has(entry.name) &&
+        !entry.name.startsWith('.'))
+        .map((entry) => ({ dir: join(dir, entry.name), depth: depth + 1 }));
+}
+/**
+ * Service manifests sitting in ONE directory: the unmistakable ones by name,
+ * and the shared ones only when the file names a web framework.
+ */
+async function manifestEvidenceInDir(dir, relative, names) {
+    const found = SERVICE_ONLY_MANIFEST_FILES.filter((manifest) => names.has(manifest)).map((manifest) => labeled(relative, manifest));
+    for (const [manifest, pattern] of CONDITIONAL_SERVICE_MANIFESTS) {
+        if (!names.has(manifest))
+            continue;
+        const text = await readText(join(dir, manifest)).catch(() => '');
+        const matched = pattern.exec(text);
+        if (matched !== null) {
+            found.push(`${labeled(relative, manifest)} (${matched[0].toLowerCase()})`);
+        }
+    }
+    return found;
+}
+/**
+ * A nested `package.json` declares its own dependencies, and a workspace root
+ * does not list them. Reading only the root is how an express service under
+ * `apps/` became `frontendOnly`.
+ */
+async function workspacePackageEvidence(dir, relative, names, backendDepNames) {
+    if (relative === '' || !names.has('package.json'))
+        return [];
+    const { deps } = await readPackageJsonDeps(dir);
+    return backendDepNames
+        .filter((dep) => dep !== 'next' && Object.prototype.hasOwnProperty.call(deps, dep))
+        .map((dep) => `${relative}: ${dep}`);
+}
+/**
+ * Backend evidence that lives OUTSIDE the root manifest: a workspace package's
+ * own `package.json`, and any non-Node service manifest.
+ *
+ * Returns `dir: evidence` strings (`apps/gateway: express`, `go.mod`,
+ * `services/checkout: requirements.txt`) rather than a boolean, because the
+ * whole defect this probe closes was a verdict that could not say what it saw.
+ */
+export async function detectNestedServiceEvidence(projectRoot, backendDepNames = BACKEND_DEP_NAMES) {
+    const evidence = [];
+    const queue = [{ dir: projectRoot, depth: 0 }];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        const entries = await readDirSafe(current.dir);
+        const names = new Set(entries.map((entry) => entry.name));
+        const relative = relativeFromRoot(projectRoot, current.dir);
+        evidence.push(...(await manifestEvidenceInDir(current.dir, relative, names)));
+        evidence.push(...(await workspacePackageEvidence(current.dir, relative, names, backendDepNames)));
+        queue.push(...descendable(entries, current.dir, current.depth));
+    }
+    return evidence.sort();
+}
+/** Does this directory tree contain a file opening with `'use server'`? */
+async function hasUseServerFile(rootDir) {
+    const queue = [{ dir: rootDir, depth: 0 }];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        const entries = await readDirSafe(current.dir);
+        for (const entry of entries) {
+            const full = join(current.dir, entry.name);
+            if (entry.isDirectory())
+                continue;
+            if (!/\.(ts|tsx|js|jsx)$/.test(entry.name))
+                continue;
+            const text = await readText(full).catch(() => '');
+            if (/['"]use server['"]/.test(text.slice(0, DIRECTIVE_HEAD_BYTES)))
+                return true;
+        }
+        queue.push(...descendable(entries, current.dir, current.depth));
+    }
+    return false;
+}
+/**
+ * Next.js server actions: `'use server'` in a file under `app/`. Route handlers
+ * under `pages/api` / `app/api` were the only Next backend the detector knew
+ * about, so a Next app that mutates data through actions — the documented
+ * Next.js way — was reported as having no backend at all.
+ */
+export async function detectNextServerActions(projectRoot) {
+    for (const root of ['app', 'src/app']) {
+        const rootDir = join(projectRoot, root);
+        if (await isDirectory(rootDir)) {
+            if (await hasUseServerFile(rootDir))
+                return true;
+        }
+    }
+    return false;
+}
 export async function detectNextApiRoutes(projectRoot, hasNext) {
     if (!hasNext) {
         return false;

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

@@ -1,7 +1,7 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory } from 'peaks-loop-shared/fs';
-import { detectBackendDirs, detectBackendFrameworks, detectMonorepoConfigs, detectNextApiRoutes, detectSwagger, GREENFIELD_MAX_SRC_FILES, GREENFIELD_MAX_LOCKFILE_DAYS, HIGH_CONFIDENCE_SIGNAL_COUNT, LEGACY_MIN_SRC_FILES, lockfileAgeDays, LOCKFILE_STALE_DAYS, readPackageJsonDeps } from './archetype-detection.js';
+import { detectBackendDirs, detectBackendFrameworks, detectMonorepoConfigs, detectNestedServiceEvidence, detectNextApiRoutes, detectNextServerActions, detectSwagger, GREENFIELD_MAX_SRC_FILES, GREENFIELD_MAX_LOCKFILE_DAYS, HIGH_CONFIDENCE_SIGNAL_COUNT, LEGACY_MIN_SRC_FILES, lockfileAgeDays, LOCKFILE_STALE_DAYS, readPackageJsonDeps } from './archetype-detection.js';
 async function countSrcFiles(projectRoot, max = 500) {
     const srcDir = join(projectRoot, 'src');
     if (!(await isDirectory(srcDir))) {
@@ -30,11 +30,26 @@ async function countSrcFiles(projectRoot, max = 500) {
     }
     return count;
 }
+/**
+ * THE backend predicate — one answer, three callers.
+ *
+ * `decideArchetype`, `decideFrontendOnly` and `decideIntegrationMode` each
+ * spelled the same triple out inline, so a signal added for one of them left
+ * the other two reading a different project. The report then contradicted
+ * itself, which is the failure `54ba0cc4` ("one answer for where frontendOnly
+ * lives") was meant to end but did not. Anything that asks "does this repo
+ * have a backend?" asks here.
+ */
+function hasBackendEvidence(detected) {
+    return (detected.hasBackendFramework ||
+        detected.hasNextApiRoutes ||
+        detected.hasNextServerActions ||
+        detected.backendDirsPresent.length > 0 ||
+        detected.nestedServiceEvidence.length > 0);
+}
 function decideArchetype(detected) {
     const signals = [];
-    const hasBackend = detected.hasBackendFramework ||
-        detected.hasNextApiRoutes ||
-        detected.backendDirsPresent.length > 0;
+    const hasBackend = hasBackendEvidence(detected);
     signals.push({
         name: 'backend-presence',
         matched: hasBackend,
@@ -44,8 +59,12 @@ function decideArchetype(detected) {
                     ? `framework: ${detected.backendFrameworks.join(', ')}`
                     : null,
                 detected.hasNextApiRoutes ? 'next-api-routes' : null,
+                detected.hasNextServerActions ? 'next-server-actions' : null,
                 detected.backendDirsPresent.length > 0
                     ? `dirs: ${detected.backendDirsPresent.join(', ')}`
+                    : null,
+                detected.nestedServiceEvidence.length > 0
+                    ? `nested: ${detected.nestedServiceEvidence.join(', ')}`
                     : null
             ]
                 .filter(Boolean)
@@ -131,33 +150,24 @@ function decideFrontendOnly(report) {
     if (report.archetype === 'legacy-frontend' || report.archetype === 'frontend-monorepo') {
         return { frontendOnly: true, reason: `archetype=${report.archetype}` };
     }
-    const noBackend = !report.detected.hasBackendFramework &&
-        !report.detected.hasNextApiRoutes &&
-        report.detected.backendDirsPresent.length === 0;
+    const noBackend = !hasBackendEvidence(report.detected);
     if (noBackend && !report.detected.hasSwaggerOrProto) {
         return { frontendOnly: true, reason: 'no-backend-no-swagger' };
     }
-    if (report.detected.hasBackendFramework ||
-        report.detected.hasNextApiRoutes ||
-        report.detected.backendDirsPresent.length > 0) {
-        return { frontendOnly: false, reason: 'backend-detected' };
+    if (noBackend) {
+        return { frontendOnly: false, reason: 'swagger-or-proto-present' };
     }
-    return { frontendOnly: false, reason: 'swagger-or-proto-present' };
+    return { frontendOnly: false, reason: 'backend-detected' };
 }
 /**
  * Three frontend integration scenarios, from the signals `detected`
- * already holds. Backend presence uses the SAME triple as
- * `decideArchetype`'s `hasBackend` (framework OR next API routes OR
- * backend dirs) rather than `hasBackendFramework` alone: `next` is
- * deliberately excluded from `backendFrameworks` (:77), so a Next
- * project with `pages/api` is `legacy-fullstack` there and must not be
- * `prd-only` here — one report cannot contradict itself.
+ * already holds. Backend presence is the SAME predicate `decideArchetype`
+ * uses (`hasBackendEvidence`), because one report cannot be
+ * `legacy-fullstack` and `prd-only` at once — a Next project with server
+ * actions, or an express service under `apps/`, is a backend for both.
  */
 function decideIntegrationMode(report) {
-    const hasBackend = report.detected.hasBackendFramework ||
-        report.detected.hasNextApiRoutes ||
-        report.detected.backendDirsPresent.length > 0;
-    if (hasBackend) {
+    if (hasBackendEvidence(report.detected)) {
         return { integrationMode: 'full-stack', reason: 'backend-detected' };
     }
     if (report.detected.hasSwaggerOrProto) {
@@ -172,6 +182,8 @@ export async function scanArchetype(options) {
     const hasNext = Object.prototype.hasOwnProperty.call(deps, 'next');
     const hasNextApiRoutes = await detectNextApiRoutes(projectRoot, hasNext);
     const backendDirsPresent = await detectBackendDirs(projectRoot);
+    const nestedServiceEvidence = await detectNestedServiceEvidence(projectRoot);
+    const hasNextServerActions = hasNext ? await detectNextServerActions(projectRoot) : false;
     const swaggerPaths = await detectSwagger(projectRoot);
     const monorepoConfigs = await detectMonorepoConfigs(projectRoot);
     const srcFileCount = await countSrcFiles(projectRoot);
@@ -180,6 +192,8 @@ export async function scanArchetype(options) {
         hasPackageJson,
         hasBackendFramework: backendFrameworks.length > 0,
         backendFrameworks,
+        nestedServiceEvidence,
+        hasNextServerActions,
         hasSwaggerOrProto: swaggerPaths.length > 0,
         swaggerPaths,
         hasMonorepoConfig: monorepoConfigs.length > 0,

package/dist/services/scan/scan-types.d.ts

@@ -22,6 +22,15 @@ export type ArchetypeReport = {
         hasPackageJson: boolean;
         hasBackendFramework: boolean;
         backendFrameworks: string[];
+        /** Backend evidence the ROOT manifest cannot see: a workspace package's own
+         *  `package.json` (`apps/gateway: express`) and any non-Node service
+         *  manifest (`go.mod`, `services/checkout/requirements.txt (fastapi)`).
+         *  Every probe that filled `detected` before this field read Node's
+         *  manifest only, so a Go or Java service reported as `frontendOnly`. */
+        nestedServiceEvidence: string[];
+        /** Next.js server actions (`'use server'` under `app/`). Route handlers
+         *  (`pages/api` / `app/api`) were the only Next backend recognised. */
+        hasNextServerActions: boolean;
         hasSwaggerOrProto: boolean;
         swaggerPaths: string[];
         hasMonorepoConfig: boolean;