@starci/hfs 4.0.1 → 4.0.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.0.3 - 2026-10-01
+
+- Changed: the bundled canon-pins copy pins @starci/stylelint-canon 2.0.2, @starci/eslint-canon-be 3.0.3 and @starci/eslint-canon-fe 8.0.3, so `hfs scaffold app` writes those pins.
+- Added: `npm test` (bin/hfs.test.mjs, not published): the CLI loads with no installed dependency, the clean-install proof of the package (scripts/checks/package-clean-test.mjs).
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "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",
@@ -32,6 +32,7 @@
   },
   "scripts": {
     "sync": "node scripts/sync-runtime.mjs",
-    "sync:check": "node scripts/sync-runtime.mjs --check"
+    "sync:check": "node scripts/sync-runtime.mjs --check",
+    "test": "node --test \"bin/*.test.mjs\""
   }
 }

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

@@ -17,35 +17,35 @@ pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
   '@starci/grammar':
-    version: 0.8.0
+    version: 0.8.1
     group: starci
     install: registry
     side: fe
     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.1
+    version: 3.0.3
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
-    why: '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.'
+    why: '3.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 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.1
+    version: 8.0.3
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
-    why: '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).'
+    why: '8.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 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
+    version: 2.0.2
     group: starci
     install: registry
     side: fe
     source: packages/stylelint/package.json
-    why: '2.0.1 accepts `--font-sans` and `--font-mono` in the brand layer (the vocabulary follows the grammar 0.8.0). 2.0.0 adds status-contrast (HeroUI soft pairs measured per theme), fixes brand-layer-shape on the shared :root,.light,.dark block and the info soft pair, and derives appTokens with loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
+    why: '2.0.2: no-class-selector refuses a compound class selector (`div.card`), which the 2.0.1 pattern let through. 2.0.1 accepts `--font-sans` and `--font-mono` in the brand layer (the vocabulary follows the grammar 0.8.0). 2.0.0 adds status-contrast (HeroUI soft pairs measured per theme), fixes brand-layer-shape on the shared :root,.light,.dark block and the info soft pair, and derives appTokens with loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
   '@starci/tsconfig':
-    version: 2.0.0
+    version: 2.0.1
     group: starci
     install: registry
     side: both
@@ -57,26 +57,26 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.2.0
+    version: 2.2.1
     group: starci
     install: registry
     side: be
     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.1
+    version: 4.0.3
     group: starci
     install: registry
     side: both
     source: packages/hfs/package.json
-    why: '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.'
+    why: '4.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2, eslint-canon-be 3.0.3 and eslint-canon-fe 8.0.3 (what `hfs scaffold app` writes); the package gains its own clean-install test. 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/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

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: