@starci/hfs 4.0.0 → 4.0.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.0.2 - 2026-10-01
+
+- Changed (owner correction): `.starcistacks/` and `.sops.yaml` live at the app root, beside `be/`, `fe/` and `.starciwork`. The slots `be.starcistacks` and `be.sops` are replaced by `app.starcistacks` and `app.sops` (profile app, required); `repo.side-root-forbidden` now lists `.starcistacks/` and `.sops.yaml`, so a side holding either is `HFS_FORBIDDEN_PRESENT`, and the architecture machine reports a `.starcistacks` in either side as `HFS_STACKS_IN_SIDE` (it replaces `HFS_STACKS_IN_FE`). R10 `HFS_STACKS_SHAPE` judges the app root's tree.
+- Changed: the managed `.gitignore` block carries the `.starcistacks` custody rules of `modules/schemas/stacks-layout.yaml` (`custody.gitignoreRules`, in order), rooted at the app root; an app keeps no hand-written custody block.
+- Changed: `hfs scaffold app` writes `.starcistacks/application-stacks.yaml` and `.sops.yaml` at the app root (they were under `be/`); `hfs work-hygiene` guards the app root's `.starcistacks/`; the Sonar key and gate are read from `.starcistacks/application-stacks.yaml` at the app root.
+- Changed: R47 `test-world-files` and R84 `connection-map` read the stack of the app root from the side they judge.
+
+## 4.0.1 - 2026-10-01
+
+- Fixed: `hfs scaffold app` no longer writes a hand-made lockfile. The 4.0.0 stub held only the root entry, so `npm ci` in a new app failed with EUSAGE ("package.json and package-lock.json are not in sync"). Once the files are written, the scaffold runs `npm install --package-lock-only --ignore-scripts --no-audit --no-fund` in the new app root (registry or npm cache; no node_modules, no scripts), so the lockfile resolves every dependency of the root and its workspaces and `npm ci` accepts it. If npm cannot resolve it, the scaffold exits 2 with `HFS_SCAFFOLD_LOCK_FAILED`, names the step and removes the app it began: no stub lock and no app without a lock is left. There is no switch to skip the step.
+- Fixed (false positive): R14 `HFS_DEP_VERSION_SKEW` does not report a bundled copy in the lockfile (`inBundle`, a package's bundleDependencies, e.g. the tslib inside `@tailwindcss/oxide-wasm32-wasi`): it ships inside its parent's tarball and nothing in the app can move it. A fresh scaffold's real lock has one.
+
 ## 4.0.0 - 2026-10-01
 
 - Added: the scaffolded root `package.json` (and its lockfile root entry) pins `@starci/test-world` from `knowledge/hfs/canon-pins.yaml` (1.0.0), the package whose `starci-test-stack` bin the managed `test:stack` script runs.

package/bin/hfs.mjs

@@ -215,7 +215,7 @@ export async function main(argv, { stdout = (s) => process.stdout.write(s), stde
       const [kind, name, ...extra] = opts.positional;
       if (kind !== 'app' || !name || extra.length || opts.repo !== undefined) throw new Error('hfs scaffold takes `app <name> [--into <dir>]`');
       const { root: created, files } = scaffoldApp({ name, into: path.resolve(opts.into ?? process.cwd()), presets: presets ?? await scaffoldPresets() });
-      stdout(`hfs scaffold app: created ${created} (${files.length} files); next: npm install, then npm run lint\n`);
+      stdout(`hfs scaffold app: created ${created} (${files.length} files); next: npm ci, then npm run lint\n`);
       return 0;
     }
     if (opts.positional.length !== 1) throw new Error('hfs explain takes exactly one path');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "The HFS command line of a StarCi app (one repository: the root, be/ and fe/): hfs lint, check, scaffold app, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
   "type": "module",
   "license": "UNLICENSED",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -24,19 +24,19 @@ pins:
     source: packages/grammar/package.json
     why: nivo-fe pins 0.4.11 and 0.5.0 in one workspace, starci-next-fe 0.5.1, miamia-fe 0.5.0; the runtime source is 0.8.0 (the brand layer sets `--font-sans` and `--font-mono`; the grammar reads them; 0.7.2 added the Input tel kind and IconButton disclosure props).
   '@starci/eslint-canon-be':
-    version: 3.0.0
+    version: 3.0.2
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
-    why: '3.0.0: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side; the project graph is built per side. 2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws.'
+    why: '3.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 3.0.1: its bundled canon-pins copy pins hfs 4.0.1. 3.0.0: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side; the project graph is built per side. 2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws.'
   '@starci/eslint-canon-fe':
-    version: 8.0.0
+    version: 8.0.2
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
-    why: '8.0.0: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side; the project graph is built per side. 7.0.0: the front end has no tests (FE_NO_TESTS R97 in hfs); no-vietnamese-in-source (R91).'
+    why: '8.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 8.0.1: its bundled canon-pins copy pins hfs 4.0.1. 8.0.0: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side; the project graph is built per side. 7.0.0: the front end has no tests (FE_NO_TESTS R97 in hfs); no-vietnamese-in-source (R91).'
   '@starci/stylelint-canon':
     version: 2.0.1
     group: starci
@@ -64,19 +64,19 @@ pins:
     source: packages/jest-preset/package.json
     why: '2.2.0: the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; 2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/test-world':
-    version: 1.0.0
+    version: 1.0.2
     group: starci
     install: registry
     side: be
     source: packages/test-world/package.json
-    why: 'the shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs, the outage lock and the starci-test-stack bin behind the managed test:stack script; a devDependency of every back end.'
+    why: '1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. The shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs, the outage lock and the starci-test-stack bin behind the managed test:stack script; a devDependency of every back end. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
   '@starci/hfs':
-    version: 4.0.0
+    version: 4.0.2
     group: starci
     install: registry
     side: both
     source: packages/hfs/package.json
-    why: '4.0.0: the app monorepo standard: one app repository with the root package.json, lockfile and hfs.json of kind app, and the be/ and fe/ sides; `hfs scaffold app <name>` makes it, `hfs lint` at the root lints be/** with the BE canon and fe/** with the FE canon; the standalone be/fe repository kinds and `hfs init` are deleted.'
+    why: '4.0.2: .starcistacks and .sops.yaml live at the app root (slots app.starcistacks, app.sops; a side holding either is refused, HFS_STACKS_IN_SIDE), the managed .gitignore block carries the custody rules, the scaffold writes them at the root. 4.0.1: `hfs scaffold app` resolves the real lockfile with npm (`npm install --package-lock-only`) instead of writing a root-only stub that `npm ci` refuses. 4.0.0: the app monorepo standard: one app repository with the root package.json, lockfile and hfs.json of kind app, and the be/ and fe/ sides; `hfs scaffold app <name>` makes it, `hfs lint` at the root lints be/** with the BE canon and fe/** with the FE canon; the standalone be/fe repository kinds and `hfs init` are deleted.'
   # --- tooling
   typescript:
     version: 5.9.3

package/runtime/knowledge/hfs/slots.yaml

@@ -321,6 +321,27 @@ slots:
              "features/<feature>/uat/<name>/{seed,cleanup}.sql", "_resources/{identities,environments,fixtures}/<slug>/resource.yaml"]
     forbids: [evidence/, logs/, reports/, captures/, runs/, "kernel-*/", "*.sqlite*", _derived/, "work/node records"]
     rules: [HFS_AGENT_DATA_TRACKED, HFS_WORK_NODE_RETIRED, HFS_IDENTITY_CUSTODY]
+  - id: app.starcistacks
+    profiles: [app]
+    # The stack declarations and the sealed custody of the app, at the app root beside be/, fe/ and .starciwork (never under a side).
+    path: ".starcistacks/"
+    presence: required
+    tracked: tracked
+    tier: none
+    tests: none
+    requires: [application-stacks.yaml]
+    allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,k8s,terraform}/**", "<env>/infra/metadata.json",
+             "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/seeds/**"]
+    forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
+    rules: [HFS_STACKS_SHAPE, HFS_STACKS_IN_SIDE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
+  - id: app.sops
+    profiles: [app]
+    # The sops custody rule of .starcistacks/<env>/secrets/*.enc, at the app root beside the tree it seals.
+    path: .sops.yaml
+    presence: required
+    tracked: tracked
+    tier: none
+    tests: none
   - id: app.build-output
     profiles: [app]
     path: "{**/node_modules/,coverage/,reports/,test-results/,**/*.tsbuildinfo}"
@@ -360,18 +381,18 @@ slots:
     tracked: external
     tier: none
     tests: none
-    goesTo: "be/.starcistacks/<env>/secrets/<slug>.enc; decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
+    goesTo: ".starcistacks/<env>/secrets/<slug>.enc (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
     rules: [HFS_PLAINTEXT_SECRET]
 
   # ----- side root (both sides): what the old standalone repository root held, less the app-root files ----------
   - id: repo.side-root-forbidden
     profiles: [be, fe]
-    path: "{package.json,package-lock.json,hfs.json,README.md,.gitignore,.gitattributes,.husky/,.github/,.starciwork/,sonar-project.properties,.prettierrc,.prettierignore,scripts/}"
+    path: "{package.json,package-lock.json,hfs.json,README.md,.gitignore,.gitattributes,.husky/,.github/,.starciwork/,.starcistacks/,.sops.yaml,sonar-project.properties,.prettierrc,.prettierignore,scripts/}"
     presence: forbidden
     tracked: external
     tier: none
     tests: none
-    goesTo: "the app root: one package.json, lockfile, hfs.json, README, git and CI files, hooks, formatter, Sonar configuration, scripts/ and .starciwork per app"
+    goesTo: "the app root: one package.json, lockfile, hfs.json, README, git and CI files, hooks, formatter, Sonar configuration, scripts/, .starciwork, .starcistacks and .sops.yaml per app"
   - id: be.tool-config
     profiles: [be]
     # Managed files (hfs sync renders them, hfs check compares them): the whole tool configuration of a back end. Each is
@@ -529,7 +550,7 @@ slots:
     tracked: external
     tier: none
     tests: none
-    goesTo: "be/.starcistacks/<env>/secrets/<slug>.enc; decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
+    goesTo: ".starcistacks/<env>/secrets/<slug>.enc (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
     rules: [HFS_PLAINTEXT_SECRET]
   - id: be.root-e2e
     profiles: [be]
@@ -825,7 +846,7 @@ slots:
       infrastructure (containers) and runs apps/migrate's exported bootstrap once; use-test-world.ts exports
       useTestWorld({ apps: { <name>: { module, listen? } } } | { modules: [...] }) -> world.apps.<name>.api,
       world.db.<connection> (the shared EntityManager), world.infra.<service> (latency/cut/restore on a REAL service of the repository's
-      own stack, `.starcistacks/<env>`, each behind toxiproxy), world.fake.<provider> (a network-edge fake of an external SaaS started by the world, with
+      own stack, the app root's `.starcistacks/<env>`, each behind toxiproxy), world.fake.<provider> (a network-edge fake of an external SaaS started by the world, with
       failNext/replayWebhook/delay), world.waitFor; fakes/<provider>/ holds the fake servers and payload fixtures, kit/ the inlined test helpers, and the world root may hold role-suffixed helpers (<name>.client.ts, <name>.contracts.ts, ...). Nothing is
       overridden in the DI container. It is the only test location that may import typeorm's DataSource or testcontainers,
       call migrate/runMigrations/synchronize, or write process.env.
@@ -905,27 +926,6 @@ slots:
     tests: none
     goesTo: "src/tests/world/ (the only test infrastructure location; e2e/<area>/ holds only *.e2e-spec.ts)"
 
-  # ----- BE: work and stacks -----------------------------------------------------------------------------
-  - id: be.starcistacks
-    profiles: [be]
-    path: ".starcistacks/"
-    presence: required
-    tracked: tracked
-    tier: none
-    tests: none
-    requires: [application-stacks.yaml]
-    allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,k8s,terraform}/**", "<env>/infra/metadata.json",
-             "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/seeds/**"]
-    forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
-    rules: [HFS_STACKS_SHAPE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
-  - id: be.sops
-    profiles: [be]
-    path: .sops.yaml
-    presence: required
-    tracked: tracked
-    tier: none
-    tests: none
-
   # ----- FE: apps ----------------------------------------------------------------------------------------
   - id: fe.app.next
     profiles: [fe]

package/runtime/modules/kernel/failure-codes.yaml

@@ -1503,21 +1503,21 @@ HFS_SRC_LAYOUT_INVALID:
   owner: op-retry
   kind: check-finding
 
-HFS_STACKS_IN_FE:
-  title: "Stack declarations in the front end (fe/)"
-  title_vi: "Khai báo stack nằm trong repo giao diện"
-  meaning_vi: "Repo giao diện đang chứa thư mục .starcistacks, trong khi khai báo stack chỉ được đặt ở repo backend."
+HFS_STACKS_IN_SIDE:
+  title: "Stack declarations under a side (be/ or fe/) instead of the app root"
+  title_vi: "Khai báo stack nằm trong một phía (be/ hoặc fe/) thay vì ở gốc app"
+  meaning_vi: "Một phía của app (be/ hoặc fe/) đang chứa thư mục .starcistacks, trong khi .starcistacks chỉ được đặt ở gốc app, cạnh be/, fe/ và .starciwork."
   causes_vi:
-    - "Sao chép nhầm thư mục stack từ backend sang"
-    - "Worker tạo stack ở sai repo"
-  nextStep_vi: "Bộ kiểm kiến trúc từ chối; op phải xóa thư mục khỏi repo giao diện và đặt khai báo ở backend."
+    - "Còn giữ bố cục cũ be/.starcistacks từ trước khi chuyển về gốc app"
+    - "Worker tạo stack trong một phía thay vì ở gốc app"
+  nextStep_vi: "Bộ kiểm kiến trúc từ chối; op phải dời thư mục bằng git mv về .starcistacks ở gốc app và sửa mọi đường dẫn trỏ tới nó."
   owner: op-retry
   kind: check-finding
 
 HFS_STACKS_SHAPE:
   title: "`.starcistacks` has the standard shape and the host Sonar owner"
   title_vi: "Hình dạng .starcistacks sai"
-  meaning_vi: "`.starcistacks` có `<path>` ngoài hình dạng chuẩn (danh sách allows của slot be.starcistacks, gồm cả infra/metadata.json) (hoặc còn trỏ `.stacks`)."
+  meaning_vi: "`.starcistacks` có `<path>` ngoài hình dạng chuẩn (danh sách allows của slot app.starcistacks, gồm cả infra/metadata.json) (hoặc còn trỏ `.stacks`)."
   causes_vi:
     - "Vi phạm luật R10: `.starcistacks/<env>/` chỉ có `README.md`, `environment.json`, `infra/{compose,k8s,terraform}`, `runtime/{config,env}`, `secrets/`, `seeds/`; khối sonar là `owner: host` trỏ `.claude/ext/sonar`; không còn gốc `.stacks`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."

package/runtime/scripts/checks/architecture/connection-map.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { machineKit, pascal, upperSnake } from './machine-ast.mjs';
+import { locateDeclaration } from '../../lib/hfs-slots.mjs';
 
 /**
  * R84 `connection-map` (BE_CONNECTION_DUPLICATE), folding RED01 and RED02. One physical database is one connection, one
@@ -179,11 +180,13 @@ export function checkConnectionMap(input) {
   // 4. Stacks: two connections that resolve to one host, port and database are one database.
   let stacksChecked = 0;
   let stacksSkipped = 0;
-  const stacksRoot = path.join(config.root, '.starcistacks');
+  // .starcistacks sits at the app root: the side folder the machine judges reads its app's tree (locateDeclaration).
+  const stacksRoot = path.join(locateDeclaration(config.root).appRoot, '.starcistacks');
   let envs = [];
   try { envs = fs.readdirSync(stacksRoot, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name).sort(); } catch { envs = []; }
   for (const env of envs) {
-    const rel = `.starcistacks/${env}/runtime/env`;
+    // Relative to the side folder the machine judges (`../.starcistacks/...` for a side): the app-relative path once the side is prefixed.
+    const rel = path.relative(config.root, path.join(stacksRoot, env, 'runtime', 'env')).split(path.sep).join('/');
     const values = readEnvFiles(path.join(stacksRoot, env, 'runtime', 'env'));
     if (!values || values.size === 0) { stacksSkipped += 1; continue; }
     const seen = new Map();

package/runtime/scripts/checks/architecture/hfs.mjs

@@ -36,7 +36,7 @@ export const HFS_RULE_IDS = [
   'HFS_ROOT_MARKDOWN_FORBIDDEN',
   'HFS_ROOT_SRC_FORBIDDEN_FE',
   'HFS_SRC_LAYOUT_INVALID',
-  'HFS_STACKS_IN_FE',
+  'HFS_STACKS_IN_SIDE',
   'HFS_TEST_KIND_RETIRED',
   'HFS_WORK_IN_FE',
 ];
@@ -423,9 +423,9 @@ export function checkHfs(config) {
   const allowed = slotRootEntries(resolver, profile);
   for (const entry of [...tree.top].sort()) {
     if (NON_NPM_ENTRIES.has(entry) || /\.md$/iu.test(entry)) continue;
+    if (entry === '.starcistacks') { finding('HFS_STACKS_IN_SIDE', entry, `The ${profile} side must not hold .starcistacks; stack declarations and sealed custody live in the app root .starcistacks.`); continue; }
     if (frontend && !backend) {
       if (entry === '.starciwork') { finding('HFS_WORK_IN_FE', entry, 'The fe side must not hold a .starciwork tree; Work records live in the app root .starciwork.'); continue; }
-      if (entry === '.starcistacks') { finding('HFS_STACKS_IN_FE', entry, 'The fe side must not hold .starcistacks; stack declarations live in be/.starcistacks.'); continue; }
       if (entry === 'src') { finding('HFS_ROOT_SRC_FORBIDDEN_FE', entry, 'The fe side keeps source only under apps/<app>/src; the fe/src/ tree must move.'); continue; }
     }
     if (frontend && !backend && (isFeTestPath(entry) || isFeTestPath(`${entry}/x`))) continue;   // a test entry of a front end is FE_NO_TESTS's, the one finding of that path

package/runtime/scripts/checks/architecture/test-world-files.mjs

@@ -1,5 +1,6 @@
 import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { locateDeclaration } from '../../lib/hfs-slots.mjs';
 import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService, readStack } from '../../lib/stack-services.mjs';
 
 /**
@@ -159,7 +160,8 @@ export function checkTestWorldFiles(input) {
   const services = [];
   for (const environment of environments) {
     let stack = null;
-    try { stack = readStack({ root: config.root, environment }); } catch { stack = null; }
+    // The stack is the app root's .starcistacks: the side folder the machine judges reads its app's (locateDeclaration).
+    try { stack = readStack({ root: locateDeclaration(config.root).appRoot, environment }); } catch { stack = null; }
     for (const service of stack?.services ?? []) if (service.role !== 'service' && !services.some(known => known.name === service.name)) services.push({ ...service, environment });
   }
   const stackHint = `${STACKS_DIRECTORY}/${environments.join(', ')}`;

package/runtime/scripts/lib/hfs-check.mjs

@@ -219,7 +219,7 @@ const onSide = (side, p) => (p ? path.posix.normalize(`${side}/${p}`) : p);
 
 /**
  * The findings of one scope: the app root (profile app; its own files, and the rules of the files only the root holds: the one
- * package.json and lockfile, CI, hooks, .starciwork) or one side (profile be or fe; the side folder is `repoRoot` and every path is
+ * package.json and lockfile, CI, hooks, .starciwork, .starcistacks) or one side (profile be or fe; the side folder is `repoRoot` and every path is
  * relative to it, exactly as the standalone repository root was). `files` are the scope's tracked paths; `all` (root only) every
  * tracked path of the app, for the rules that read across it (dependency skew, proof commands).
  */
@@ -269,11 +269,12 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
       ...testTopologyFindings({ repoRoot, files }),
       ...proofCommandFindings({ repoRoot, files: all, resolver, sides: Object.keys(repo.sides ?? {}) }),
       ...appFrontendFindings({ repoRoot, files: all, repo }),
+      ...stacksFindings({ repoRoot, files, resolver }),
       // The tree check of the app root the machine runs per side for a side folder: README, root entries, automatic gates, hooks path.
       ...checkAppRoot({ root: repoRoot, resolver, tree: trackedTreeView(all) }).violations.map((item) => ({ code: item.ruleId, level: 'error', path: item.path, line: item.line, column: item.column, source: 'machine', message: `${item.path}: ${item.message}` })),
     );
   } else if (repo.profile === 'be') {
-    findings.push(...contractFindings({ files, repo, resolver }), ...stacksFindings({ repoRoot, files, resolver }), ...testTopologyFindings({ repoRoot, files }));
+    findings.push(...contractFindings({ files, repo, resolver }), ...testTopologyFindings({ repoRoot, files }));
   } else {
     findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter(inScope) }));
   }

package/runtime/scripts/lib/hfs-rules/deps.mjs

@@ -4,7 +4,9 @@
 //   - a dependency the root `overrides` pins to a version (a string that is not a `$name` reference) is declared at that version everywhere
 //     it is declared: an override the manifests disagree with is a second version in disguise;
 //   - the lockfile (package-lock.json, read, never installed) holds no nested copy of a dependency the workspace declares:
-//     `node_modules/<a>/node_modules/<name>` or `apps/<app>/node_modules/<name>` next to the hoisted `node_modules/<name>`.
+//     `node_modules/<a>/node_modules/<name>` or `apps/<app>/node_modules/<name>` next to the hoisted `node_modules/<name>`. A
+//     bundled copy (`inBundle`: it ships inside its parent's tarball, its bundleDependencies) is not one: no range, override or
+//     dedupe of the workspace can move it, so it is the parent's, not a second copy the workspace keeps.
 import { found, readJson } from './read.mjs';
 
 export const DEP_VERSION_SKEW = 'HFS_DEP_VERSION_SKEW';
@@ -54,7 +56,7 @@ export function depFindings({ repoRoot, files }) {
     }
     for (const [key, entry] of Object.entries(lock.packages)) {
       const nested = NESTED.exec(key);
-      if (!nested || entry.link || HOISTED.test(key) || !declared.has(nested[1])) continue;
+      if (!nested || entry.link || entry.inBundle || HOISTED.test(key) || !declared.has(nested[1])) continue;
       const name = nested[1];
       findings.push(found(DEP_VERSION_SKEW, 'package-lock.json', `${key} is a nested copy of ${name}${entry.version ? ` ${entry.version}` : ''}${hoisted.has(name) ? ` next to the hoisted ${hoisted.get(name)}` : ''}; the workspace keeps one copy (align the ranges or add a root override)`, { dependency: name, lockPath: key, version: entry.version }));
     }

package/runtime/scripts/lib/hfs-rules/stacks.mjs

@@ -1,5 +1,5 @@
 // stacks.mjs - HFS_STACKS_SHAPE (R10): `.starcistacks` has the standard shape and the host Sonar owner.
-//   - every tracked path under `.starcistacks/` is one the be.starcistacks slot allows (its `allows` list is the shape:
+//   - every tracked path under the app root's `.starcistacks/` is one the app.starcistacks slot allows (its `allows` list is the shape:
 //     application-stacks.yaml and <env>/{README.md, environment.json, infra/{compose,k8s,terraform}, runtime/{config,env},
 //     secrets/<slug>.enc, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
 //     `deployment.json` and `k8s/` are not in the list, so they fall out of it;
@@ -11,7 +11,7 @@ import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../stack-
 import { found } from './read.mjs';
 
 export const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
-export const STACKS_SLOT = 'be.starcistacks';
+export const STACKS_SLOT = 'app.starcistacks';
 export const HOST_SONAR_ROOT = '.claude/ext/sonar';
 const SEALED = /\.enc$/;
 const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc$/;
@@ -22,7 +22,7 @@ const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(e
 
 const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
 
-/** The shape findings of the `.starcistacks` tree of a back-end repository. */
+/** The shape findings of the `.starcistacks` tree at the app root (`repoRoot` is the app root, `files` its own tracked paths). */
 export function stacksFindings({ repoRoot, files, resolver }) {
   const slot = resolver.slot(STACKS_SLOT);
   if (!slot) return [];

package/scaffold/app.mjs

@@ -1,8 +1,9 @@
 // hfs scaffold app <name> - the first tree of a new app, the one shape every StarCi product has:
 //
 //   <name>/            hfs.json (kind app), package.json (every dependency of both sides at its canon pin, the managed scripts),
-//                      package-lock.json, README.md, the managed root files (CI, husky, .gitignore block, Sonar, prettier) and
-//                      .starciwork; scripts/codegen.mjs, the app's own step of `npm run codegen`
+//                      package-lock.json, README.md, the managed root files (CI, husky, .gitignore block, Sonar, prettier),
+//                      .starciwork, .starcistacks/application-stacks.yaml and .sops.yaml (the stack tree lives at the app root, never
+//                      under be/); scripts/codegen.mjs, the app's own step of `npm run codegen`
 //   <name>/be/         the back-end side: the managed tool configuration and the templates/be/skeleton tree (the api app's
 //                      entrypoint, platform config/logging/errors/clock/cqrs, the liveness capability and the health feature)
 //   <name>/fe/         the front-end side: the managed tool configuration and the templates/fe/skeleton tree (the next-intl
@@ -11,10 +12,13 @@
 //
 // The skeleton files are written once from templates/<app|be|fe>/skeleton ({{project}}, {{app}} and {{appPascal}} filled, a
 // `__app__` folder named after the side's app); the managed files are the render of `hfs sync` (sync/index.mjs), so a fresh app
-// is in sync by construction. Nothing is installed: `npm install` completes the lockfile, which is written as the root entry only.
-// An existing directory is refused, never merged into.
+// is in sync by construction. The lockfile is never written by hand: once the files are written, npm resolves the real one
+// (`npm install --package-lock-only`, no node_modules, no scripts), so `npm ci` installs the new app as it is. When npm cannot
+// resolve it the scaffold fails (HFS_SCAFFOLD_LOCK_FAILED), names the step and removes the app it began, so no app without a lock
+// and no stub lock is ever left. An existing directory is refused, never merged into.
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { TEMPLATES_DIR, renderTargets, writeTargets } from '../sync/index.mjs';
@@ -148,11 +152,30 @@ function skeletonOf(scope, app, vars) {
   return files;
 }
 
+/** The npm step that resolves the lockfile of a new app, exactly as the error names it. */
+export const LOCK_STEP = 'npm install --package-lock-only --ignore-scripts --no-audit --no-fund';
+
+/**
+ * Resolves the real package-lock.json of the app at `root` with npm (the registry and the npm cache; no node_modules and no
+ * lifecycle script). `{ ok: true }` or `{ ok: false, detail }`.
+ */
+export function npmLock(root) {
+  // Through the shell (npm is npm.cmd on Windows, which runs only there); the command is the fixed literal LOCK_STEP.
+  const run = spawnSync(LOCK_STEP, { cwd: root, encoding: 'utf8', shell: true, windowsHide: true, timeout: 600_000 });
+  if (run.status === 0 && fs.existsSync(path.join(root, 'package-lock.json'))) return { ok: true };
+  const said = `${run.stderr ?? ''}\n${run.stdout ?? ''}`.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  // npm's own error lines (`npm error code ETARGET`, `npm error notarget No matching version found for x@1.2.3.`), without the log pointer.
+  const errors = said.filter(line => /^npm (?:error|ERR!)/i.test(line) && !/complete log/i.test(line)).map(line => line.replace(/^npm (?:error|ERR!)\s*/i, ''));
+  const reason = run.error ? String(run.error.message) : errors.slice(0, 2).join('; ') || said[0] || 'no output';
+  return { ok: false, detail: `exit ${run.status ?? 'none'}: ${reason}` };
+}
+
 /**
- * `hfs scaffold app <name>`: writes the new app under `into` and returns `{ root, files }` (app-relative paths, sorted). `presets`
- * is what sync loads from the installed @starci/jest-preset (the Sonar exclusions); the CLI passes the one it resolves.
+ * `hfs scaffold app <name>`: writes the new app under `into`, resolves its lockfile with npm (`lock`, npmLock), and returns
+ * `{ root, files }` (app-relative paths, sorted). `presets` is what sync loads from the installed @starci/jest-preset (the Sonar
+ * exclusions); the CLI passes the one it resolves. A failed lock step removes the app and throws HFS_SCAFFOLD_LOCK_FAILED.
  */
-export function scaffoldApp({ name, into, presets, manifest = loadSlotManifest() }) {
+export function scaffoldApp({ name, into, presets, manifest = loadSlotManifest(), lock = npmLock }) {
   if (!NAME.test(String(name))) throw new ScaffoldError('HFS_SCAFFOLD_NAME_INVALID', `the app name ${name} must be kebab-case (a project name: ${NAME})`);
   const root = path.join(into, name);
   if (fs.existsSync(root)) throw new ScaffoldError('HFS_SCAFFOLD_EXISTS', `${root} already exists; hfs scaffold app never writes into an existing directory`);
@@ -163,7 +186,6 @@ export function scaffoldApp({ name, into, presets, manifest = loadSlotManifest()
   const files = [
     { path: 'hfs.json', content: jsonText(declaration) },
     { path: 'package.json', content: jsonText(pkg) },
-    { path: 'package-lock.json', content: jsonText({ name, version: pkg.version, lockfileVersion: 3, requires: true, packages: { '': { name, version: pkg.version, dependencies: pkg.dependencies, devDependencies: pkg.devDependencies } } }) },
     { path: 'be/nest-cli.json', content: jsonText(nestCli(app)) },
     ...app.sides.fe.apps.map(entry => ({ path: `fe/apps/${entry.name}/tsconfig.json`, content: jsonText(nextAppTsconfig()) })),
     ...['app', 'be', 'fe'].flatMap(scope => skeletonOf(scope, app, { sonarGate: parseYaml(fs.readFileSync(SONAR_GATE_FILE, 'utf8')).gate.name })),
@@ -175,5 +197,10 @@ export function scaffoldApp({ name, into, presets, manifest = loadSlotManifest()
   }
   const targets = renderTargets(declaration, presets, { manifest });
   writeTargets(root, targets);
-  return { root, files: [...new Set([...files.map(file => file.path), ...targets.map(target => target.path)])].sort() };
+  const locked = lock(root);
+  if (!locked.ok) {
+    fs.rmSync(root, { recursive: true, force: true });
+    throw new ScaffoldError('HFS_SCAFFOLD_LOCK_FAILED', `\`${LOCK_STEP}\` could not resolve the lockfile of ${root} (${locked.detail}); the app was removed. Check the network and the npm registry, then run hfs scaffold app ${name} again`);
+  }
+  return { root, files: [...new Set([...files.map(file => file.path), ...targets.map(target => target.path), 'package-lock.json'])].sort() };
 }

package/sync/hygiene.mjs

@@ -1,6 +1,6 @@
 // hfs work-hygiene: the guard for the two trees an app tracks besides source. A file under the app root's .starciwork must be
-// product content (the .starciwork/.gitignore allowlist admits it, so agent output is refused), and a file under the be side's
-// be/.starcistacks must not be a plaintext secret (only *.enc is sealed). It is also the secrets guard of the commit: every staged file, in
+// product content (the .starciwork/.gitignore allowlist admits it, so agent output is refused), and a file under the app root's
+// .starcistacks must not be a plaintext secret (only *.enc is sealed). It is also the secrets guard of the commit: every staged file, in
 // any tree, is read from the index and judged with the one secret judgement of `hfs check` (scripts/lib/hfs-rules/secrets.mjs: a secret by
 // being, an .enc that is no sops envelope, a line that matches a secret pattern), so no plaintext secret reaches the history whatever
 // .gitignore says (`git add -f`, a path tracked before a rule tightened). There is no override. The pre-commit hook judges the staged
@@ -18,9 +18,9 @@ import { pathToFileURL } from 'node:url';
 import { secretFileFindings } from '../runtime/scripts/lib/hfs-rules/secrets.mjs';
 
 const PLAINTEXT_NAME = /(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|identity|age))$/;
-/** The app root's work tree and the be side's stack tree, app-relative (hfs work-hygiene runs at the app root). */
+/** The app root's work tree and stack tree, app-relative (hfs work-hygiene runs at the app root). */
 const WORK = '.starciwork/';
-const STACKS = 'be/.starcistacks/';
+const STACKS = '.starcistacks/';
 const GUARDED = file => file.startsWith(WORK) || file.startsWith(STACKS);
 
 /** The subset of `files` git ignores (as if untracked), asked in one call: a Set of paths. */
@@ -44,7 +44,7 @@ export function hygieneFindings(files, ignored) {
     }
     if (file.startsWith(STACKS) && !file.endsWith('.enc') && !file.endsWith('.env.example')) {
       if (file.includes('/secrets/')) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
-      else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to be/.starcistacks/<env>/secrets/<slug>.enc' });
+      else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to .starcistacks/<env>/secrets/<slug>.enc' });
     }
   }
   return findings;

package/sync/sonar-key.mjs

@@ -1,14 +1,12 @@
-// The Sonar project key of an app: read from its stack declaration (be/.starcistacks/application-stacks.yaml,
+// The Sonar project key of an app: read from its stack declaration (.starcistacks/application-stacks.yaml at the app root,
 // services.sonar.projects[]) when one names the app, so there is one source of the key. Only when no declaration names the app
 // does sync derive the key from the project name.
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
 
-/** The side folder that holds an app's stack declaration. */
-export const STACKS_SIDE = 'be';
-/** The stack declaration, app-relative. */
-export const DECLARATION = path.join(STACKS_SIDE, '.starcistacks', 'application-stacks.yaml');
+/** The stack declaration, app-relative: .starcistacks sits at the app root, beside be/, fe/ and .starciwork. */
+export const DECLARATION = path.join('.starcistacks', 'application-stacks.yaml');
 
 /** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
 export function repositoryName(root) {

package/templates/app/gitignore

@@ -4,3 +4,29 @@ schema.gql
 # fe: Next build output and its generated type file
 .next/
 next-env.d.ts
+# .starcistacks custody at the app root: modules/schemas/stacks-layout.yaml custody.gitignoreRules, in order. Only the
+# declaration, runbooks, key lists, seeds, the rendered environment, the infra definitions and sealed *.enc are tracked.
+.starcistacks/**
+!.starcistacks/**/
+!.starcistacks/**/KEYS.md
+!.starcistacks/**/.gitkeep
+!.starcistacks/application-stacks.yaml
+!.starcistacks/*/README.md
+!.starcistacks/*/environment.json
+!.starcistacks/*/seeds/**
+!.starcistacks/*/infra/metadata.json
+!.starcistacks/*/infra/compose/**
+!.starcistacks/*/infra/k8s/**
+!.starcistacks/*/infra/terraform/**
+.starcistacks/*/infra/**/.env
+.starcistacks/*/infra/**/.env.*
+.starcistacks/*/infra/**/*.env
+.starcistacks/*/infra/**/*.key
+.starcistacks/*/infra/**/*.pem
+.starcistacks/*/infra/**/*.tfvars
+.starcistacks/*/infra/terraform/.terraform/
+.starcistacks/*/infra/terraform/*.tfstate
+.starcistacks/*/infra/terraform/*.tfstate.*
+.starcistacks/*/infra/terraform/files/
+.starcistacks/*/infra/terraform/*.tar.gz
+!.starcistacks/**/*.enc

package/templates/{be → app}/skeleton/.starcistacks/application-stacks.yaml

@@ -1,3 +1,4 @@
+# The stack declaration of the app, at the app root beside be/, fe/ and .starciwork (never under a side).
 schema: starci/application-stacks@1
 services:
   sonar: