@starci/hfs 4.0.3 → 4.0.5

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 4.0.5 - 2026-10-01
+
+- Changed: workflow worktree runtime copies, the services coverage scope for Sonar and codecov.yml, sonar-gate, canon-pins.
+
+## Unreleased (alpha.4, bumped in C0's batch)
+
+- Changed (contract change `sonar-services-coverage`): Sonar and Codecov judge the services' coverage. The managed `sonar-project.properties` adds `sonar.javascript.lcov.reportPaths=be/coverage/lcov.info` and `sonar.coverage.inclusions=be/src/**/*.service.ts`; a new managed `codecov.yml` (slot `app.quality-config`, now `{sonar-project.properties,codecov.yml}`) holds the same paths at 100 on the project and the patch and ignores `fe/**`; the managed CI workflow uploads the be lcov with `codecov/codecov-action@v5` and the `CODECOV_TOKEN` secret after the unit run. Both files are rendered from one scope, `coverageScope(presets)`: the installed jest preset's `COVERAGE_SOURCES` on the be side (`loadPresets` now returns `coverageSources`). An app re-renders with `hfs sync --write`.
+- Changed: the bundled runtime copies of `knowledge/sonar-gate.yaml` (coverage 100 overall and on new code, per file; every hotspot reviewed), `knowledge/hfs/slots.yaml` (the quality-config slot) and `modules/kernel/failure-codes.yaml` (the R11 law and HFS_SONAR_CONFIG text).
+
+## 4.0.4 - 2026-10-01
+
+- Changed: the bundled runtime copy of knowledge/hfs/canon-pins.yaml pins @starci/test-world 1.0.3. No rule or command changed.
+
 ## 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.

package/README.md

@@ -70,7 +70,7 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 | `FE_I18N_KEYS` | error | a literal key read through `next-intl` that a locale lacks, or a catalog key no source reads (R106; the architecture machine) |
 | `FE_NO_TESTS` | error | a front end holds a `*.spec.*`, `*.test.*` or `*-spec.*` file, an `e2e/`, `__tests__/`, `__mocks__/` or `test-support/` directory, a vitest, Playwright, jest or Cypress file, a test script, or a test dependency in a `package.json`; no exception (R97; `scripts/lib/hfs-rules/fe-no-tests.mjs`) |
 | `HFS_GITIGNORE_BLOCK_DRIFT` | error | the managed `.gitignore` block differs from its render (R04; `sync/managed.mjs`) |
-| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render: no `sonar.host.url`, the `sonar.exclusions` of the installed jest preset, no coverage import (R11; `sync/managed.mjs`) |
+| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render: no `sonar.host.url`, the `sonar.exclusions` of the installed jest preset, the be lcov import with the services as the only coverage scope (R11; `sync/managed.mjs`) |
 | `HFS_FORMAT` | error | a tracked file the repository's own prettier would change (R19; `sync/format.mjs`, not under `--fast`) |
 | `HFS_FORMAT_TOOL_MISSING` | refusal (exit 2) | prettier is not installed in the repository; the format check is never skipped |
 
@@ -114,12 +114,14 @@ The managed `sonar-project.properties` carries `sonar.externalIssuesReportPaths`
 reaches Sonar while the job stays failed. There is no `continue-on-error`. CI runs `npm run lint -- --sonar reports/lint.sonar.json` once at the app root, before the scan. The duplicate-block threshold (`ruleParams.<side>.duplicateBlock`) has no Sonar property for TypeScript (SonarJS detects
 clones with its own token rule), so the machine enforces it (R21) and its findings are imported like every other.
 
-The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (duplication, blocker and critical issues, hotspots; no coverage condition) and an `overall` part (0 open issues on the whole code,
-duplicated lines density, cognitive complexity through the S3776 rule). A SonarQube gate condition cannot filter by engine, so the condition counts every
+The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (coverage 100, duplication, blocker and critical issues, hotspots) and an `overall` part (coverage 100, 0 open issues on the whole code,
+every hotspot reviewed, duplicated lines density, cognitive complexity through the S3776 rule). A SonarQube gate condition cannot filter by engine, so the condition counts every
 open issue, imported or native; that is stricter than the three imports alone and is intended. `hfs check` reports `HFS_SONAR_CONFIG` (R11) when the
 properties file is not its render or the stack declaration names another gate. R20 and R21 have their Sonar enforcers as conditions of that file.
 
-Sonar does not depend on coverage: the managed properties file has no `sonar.*.lcov.reportPaths` and no `sonar.coverage.*`, the gate has no coverage condition, and the managed CI workflow uploads no coverage anywhere (no Codecov). The back end's unit coverage is the runner's: the managed `test` script is `jest --selectProjects unit --coverage`, which fails below the per-file 100 threshold on `src/**/*.service.ts`.
+Coverage is the services' alone, from one scope. The managed `test` script is `jest --selectProjects unit --coverage`: it fails below the per-file 100 threshold on `src/**/*.service.ts` and writes `be/coverage/lcov.info` (the jest preset's lcov reporter). The managed `sonar-project.properties` imports that report (`sonar.javascript.lcov.reportPaths=be/coverage/lcov.info`) with `sonar.coverage.inclusions=be/src/**/*.service.ts` and no other coverage key, so a handler, resolver, controller, module, config file or test is not a coverage target and `fe/` is outside coverage. The managed `codecov.yml` holds the same paths at 100 on the project and the patch and ignores `fe/**`; the managed CI workflow uploads the lcov with `codecov/codecov-action` after the unit run. `hfs sync` renders the scope into both files from the installed jest preset's `COVERAGE_SOURCES` (`coverageScope` in `sync/index.mjs`), so they can never drift. The runtime judges the coverage per file: `sonar-local.mjs scan` holds every service a slice touched at 100, and `sonar-local.mjs dashboard` fails a project unless every service is at 100.
+
+The upload needs the repository secret `CODECOV_TOKEN` (the owner adds it once per repository: Codecov, the repository's settings, then GitHub Settings > Secrets and variables > Actions > New repository secret `CODECOV_TOKEN`). Without it the step is skipped like the Sonar steps without `SONAR_TOKEN`.
 
 ## Maintaining the bundle
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "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/engine/machine-db.mjs

@@ -43,9 +43,9 @@ import { redactBytes, redactData, redactText } from '../scripts/lib/redact.mjs';
 const require = createRequire(import.meta.url);
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 export const MACHINE_SCHEMA = 'starci/machine@1';
-export const MACHINE_VERSION = 2;
+export const MACHINE_VERSION = 3;
 /** Forward migrations after 0001-init, in order; each bumps user_version to its `version` (migrateMachine). */
-export const MACHINE_MIGRATIONS = Object.freeze([{ version: 2, name: '0002-worktrees-no-workflow-kind' }]);
+export const MACHINE_MIGRATIONS = Object.freeze([{ version: 2, name: '0002-worktrees-no-workflow-kind' }, { version: 3, name: '0003-worktrees-workflow-orca' }]);
 export const MACHINE_BUSY_TIMEOUT_MS = 15000;
 /** Test seam: STARCI_MACHINE_BUSY_TIMEOUT_MS (a positive integer) replaces the writer's busy_timeout; unset in production. */
 export const busyTimeoutOf = (env = process.env) => { const n = Number(env?.STARCI_MACHINE_BUSY_TIMEOUT_MS); return Number.isInteger(n) && n > 0 ? n : MACHINE_BUSY_TIMEOUT_MS; };

package/runtime/engine/migrations/machine/0003-worktrees-workflow-orca.sql

@@ -0,0 +1,21 @@
+-- 0003-worktrees-workflow-orca (starci/machine@1, user_version 2 -> 3). Applied by engine/machine-db.mjs migrateMachine on
+-- the first writer open of an older machine.sqlite (after an integrity_check and a VACUUM INTO backup, with foreign_key_check
+-- + quick_check before COMMIT); a fresh machine.sqlite runs 0001 then the forward files.
+--
+-- One worktree per Kernel workflow replaces the per-op worktree (owner decision WFWT, final). Orca creates and owns it (the
+-- Kernel launch), so the registry keys it by Orca's worktree id (orca_id, unique among the rows that have one), records
+-- the workflow's last checkpoint (checkpoint_sha) and the moment its finish asked for its release (release_pending_at: the
+-- host-side GC removes it once the Kernel's and the ops' terminals are released; never from inside itself). The draw
+-- critic's placement is an Orca worktree too (kind critic). worktrees.kind no longer accepts 'op': a row of that kind
+-- describes the removed mechanism and is deleted (a directory it named, if any is left, is an unregistered worktree the
+-- worktree GC and the footprint scan report); then the table's CHECK is rewritten in place (writable_schema: the views over worktrees stay as they are).
+DELETE FROM worktrees WHERE kind='op';
+ALTER TABLE worktrees ADD COLUMN orca_id TEXT;
+ALTER TABLE worktrees ADD COLUMN checkpoint_sha TEXT;
+ALTER TABLE worktrees ADD COLUMN release_pending_at INTEGER;
+CREATE UNIQUE INDEX IF NOT EXISTS ux_worktrees_orca_id ON worktrees(orca_id) WHERE orca_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS ix_worktrees_workflow ON worktrees(workflow_id,kind,removed_at);
+PRAGMA writable_schema=ON;
+UPDATE sqlite_master
+   SET sql=replace(sql, 'CHECK(kind IN (''op'',''land-scratch'',', 'CHECK(kind IN (''workflow'',''critic'',''land-scratch'',')
+ WHERE type='table' AND name='worktrees';

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

@@ -16,6 +16,13 @@ purpose: >-
 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/heroicons':
+    version: 0.3.1
+    group: starci
+    install: registry
+    side: fe
+    source: packages/heroicons/package.json
+    why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
     version: 0.8.1
     group: starci
@@ -24,14 +31,14 @@ 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.3
+    version: 3.0.5
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     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.3
+    version: 8.0.5
     group: starci
     install: registry
     side: fe
@@ -57,21 +64,21 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.2.1
+    version: 2.2.2
     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.'
+    why: '2.2.2: the unit run writes the lcov Sonar and Codecov import (services only); 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.2
+    version: 1.0.3
     group: starci
     install: registry
     side: be
     source: packages/test-world/package.json
-    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).'
+    why: '1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 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.3
+    version: 4.0.5
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -246,7 +246,7 @@ slots:
     rules: [HFS_TOOL_CONFIG_LOCAL]
   - id: app.quality-config
     profiles: [app]
-    path: sonar-project.properties
+    path: "{sonar-project.properties,codecov.yml}"
     presence: required
     tracked: tracked
     tier: none
@@ -373,7 +373,7 @@ slots:
     tracked: external
     tier: none
     tests: none
-    goesTo: "D:/starci-lanes/<project>/<lane>/ (outside every repository) for a lane; a runtime op worktree (.starciwork/worktrees/<op>) is git-excluded, never tracked, and removed when its op settles"
+    goesTo: "D:/starci-lanes/<project>/<lane>/ (outside every repository) for a lane; a Kernel workflow's worktree is created and owned by Orca outside the app checkout, never tracked, and removed by the runtime's host-side controller once the workflow's finish marked it release-pending"
   - id: app.plaintext-env
     profiles: [app]
     path: "{.env,.env.*,.secrets/,**/*.pem,**/*.key}"
@@ -387,12 +387,12 @@ slots:
   # ----- 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/,.starcistacks/,.sops.yaml,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,codecov.yml,.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/, .starciwork, .starcistacks and .sops.yaml per app"
+    goesTo: "the app root: one package.json, lockfile, hfs.json, README, git and CI files, hooks, formatter, Sonar and Codecov 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

package/runtime/knowledge/sonar-gate.yaml

@@ -8,16 +8,24 @@ purpose: |
   conditions and selects it for the project, and (2) judges an op's slice - the lines it changed - against
   the same numbers. Code-writing ops cannot settle done while the slice is red
   (scripts/kernel/sonar-settle.mjs). Changing a number here changes every repository on the next scan.
-  The gate has two parts: `newCode` (the recent work: duplication, blocker/critical issues, hotspots) and
-  `overall` (the whole code: no imported HFS, ESLint or stylelint finding, no duplicated-lines excess, no cognitive-
-  complexity issue). The one Sonar mechanism of the HFS canon is packages/hfs/README.md section "Sonar".
+  The gate has two parts: `newCode` (the recent work: coverage, duplication, blocker/critical issues, hotspots) and
+  `overall` (the whole code: coverage, no imported HFS, ESLint or stylelint finding, no bug, code smell or
+  vulnerability, every hotspot reviewed, no duplicated-lines excess, no cognitive-complexity issue). The one Sonar
+  mechanism of the HFS canon is packages/hfs/README.md section "Sonar".
 gate:
   name: starci-new-code
   # A project with no new-code baseline judges the whole project as new code (nivo inc-f92febebbb64); a fixed
   # window keeps "new code" the recent work on main, so the server gate is passable on a healthy main.
   newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
 newCode:
-  # Sonar holds NO coverage condition: unit coverage is the runner's job (jest per-file 100 on `*.service.ts`), never an lcov import.
+  # Coverage of the services only. The be unit run writes coverage/lcov.info (@starci/jest-preset coverageReporters lcov) and the
+  # managed sonar-project.properties imports it (sonar.javascript.lcov.reportPaths=be/coverage/lcov.info) with
+  # sonar.coverage.inclusions=be/src/**/*.service.ts, the one scope rendered by hfs sync from the preset's COVERAGE_SOURCES (codecov.yml
+  # is rendered from the same constant). A handler, resolver, controller, module, config file or test is not a coverage target and
+  # fe/ is outside coverage entirely, so coverage on these conditions is the services' coverage alone.
+  coverage:
+    metric: new_coverage
+    minPercent: 100
   # SonarQube's ignoreSmallChanges: fewer changed lines than this are not held to duplication.
   ignoreBelowChangedLines: 20
   duplication:
@@ -49,6 +57,19 @@ overall:
     metric: violations
     max: 0
     engines: [starci-hfs, eslint, stylelint]
+    # The dashboard counts (`sonar-local dashboard`): each type of open issue, each held at `max`.
+    types: {bugs: BUG, code_smells: CODE_SMELL, vulnerabilities: VULNERABILITY}
+  # Every security hotspot of the whole code is reviewed (the dashboard's "hotspots reviewed").
+  hotspots:
+    metric: security_hotspots_reviewed
+    minReviewedPercent: 100
+  # The services' coverage (see newCode.coverage), overall and per file: with the inclusions in place each `*.service.ts` is its
+  # own measure, so one service below 100 fails the slice verdict (sonar-local evaluateSlice) and the dashboard verdict
+  # (sonar-local dashboard) although the project average may round to 100. A file outside the inclusions is never read.
+  coverage:
+    metric: coverage
+    minPercent: 100
+    perFile: true
   # HFS_DUPLICATE_CODE (R21): duplicated lines density of the whole project, the Sonar enforcer of the machine's clone check.
   # SonarJS runs its own token-based detection (sonar.cpd.* minimums are not read for TypeScript), so ruleParams.<profile>.duplicateBlock
   # is enforced by the machine and imported as starci-hfs issues, and this density is the Sonar-side backstop.
@@ -70,8 +91,10 @@ enforcedOps: [backend.implement, interface.implement, code.refactor]
 reasoning: |
   Chosen against the four projects the local server holds on 2026-09-29 (whole-project duplicated lines
   1.6 / 2.1 / 1.7 / 0.0 percent), so new code that meets them is at or below what main already carries.
-  no coverage condition: the unit project fails below its per-file 100 threshold on `*.service.ts`, so Sonar never
-  imports an lcov report and never judges coverage.
+  coverage 100 on services, overall and new code (owner 2026-10-01): the unit project already fails below its per-file
+  100 threshold on `*.service.ts`; Sonar imports the same run's lcov with the same scope, so the dashboard, the slice
+  verdict and the server gate show the number the runner enforces, file by file. Only services count: business logic
+  lives there, the thin layers are covered through them, and the front end has no unit tests.
   duplication 3: the Sonar way value; the worst project today is 2.1, so 3 rejects a real copy-paste block and
   passes ordinary work.
   blocker/critical 0: the two severities that are defects, not style. main carries old debt of both kinds

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

@@ -1482,11 +1482,11 @@ HFS_SLOT_UNDECLARED:
   kind: check-finding
 
 HFS_SONAR_CONFIG:
-  title: "Sonar config is generated, with no host URL and no coverage import"
+  title: "Sonar config is generated, with no host URL, importing the be lcov with the services as the only coverage scope"
   title_vi: "Cấu hình Sonar lệch"
-  meaning_vi: "Cấu hình Sonar lệch: `<detail>`. Sonar phải đọc đúng cấu hình sinh ra, không nhập báo cáo độ phủ."
+  meaning_vi: "Cấu hình Sonar lệch: `<detail>`. Sonar phải đọc đúng cấu hình sinh ra và nhập báo cáo độ phủ lcov của be, chỉ tính các service."
   causes_vi:
-    - "Vi phạm luật R11: `sonar-project.properties` do template sinh: không `sonar.host.url`, `sources`/`tests` không chồng, `sonar.exclusions` = đúng danh sách loại trừ của jest, không nhập lcov hay `sonar.coverage.*`, không nhắc kiểu spec đã bỏ, và nhận báo cáo ESLint cùng tệp nhập lỗi HFS (`sonar.eslint.reportPaths`, `sonar.externalIssuesReportPaths`) để mọi lỗi canon hiện trong Sonar."
+    - "Vi phạm luật R11: `sonar-project.properties` do template sinh: không `sonar.host.url`, `sources`/`tests` không chồng, `sonar.exclusions` = đúng danh sách loại trừ của jest, nhập lcov của be (`sonar.javascript.lcov.reportPaths=be/coverage/lcov.info`) với `sonar.coverage.inclusions=be/src/**/*.service.ts` và không khóa độ phủ nào khác, không nhắc kiểu spec đã bỏ, và nhận báo cáo ESLint cùng tệp nhập lỗi HFS (`sonar.eslint.reportPaths`, `sonar.externalIssuesReportPaths`) để mọi lỗi canon hiện trong Sonar."
     - "Khối `services.sonar.qualityGate` của khai báo stack phải gọi đúng cổng chất lượng duy nhất của `knowledge/sonar-gate.yaml`; repo không tự ghi ngưỡng."
   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."
   owner: op-retry

package/runtime/scripts/lib/safe-remove.mjs

@@ -212,6 +212,21 @@ export function mainCheckoutDamage(before, after) {
   return out;
 }
 
+/**
+ * The link step of every worktree removal (git's here, Orca's in scripts/lib/worktrees.mjs removeOrcaWorktree): every link
+ * under `target` found WITHOUT following one (linksUnder), each removed as a link (removeLink: `cmd /c rmdir <link>`, never
+ * /s), outermost first, then a re-scan that must find ZERO. {ok, links, errors: [{path, code, message}]}; ok false: a link
+ * is stuck and the caller removes nothing.
+ */
+export function removeLinksUnder(target) {
+  const out = { ok: false, links: 0, errors: [] };
+  if (!fs.existsSync(target)) { out.ok = true; return out; }
+  for (const link of linksUnder(target)) { if (removeLink(link)) out.links += 1; else out.errors.push({ path: link, code: 'LINK_STUCK', message: 'a link could not be removed' }); }
+  for (const l of linksUnder(target)) if (!out.errors.some((e) => e.path === l)) out.errors.push({ path: l, code: 'LINK_STUCK', message: 'a link is still there after removal' });
+  out.ok = out.errors.length === 0;
+  return out;
+}
+
 /**
  * Remove a git worktree (the one algorithm; the 490-file .claude incident and nivo-fe inc-c8fbf76aa499):
  *   1. enumerate every link in it WITHOUT following one (linksUnder);
@@ -236,13 +251,9 @@ export function safeRemoveWorktree(worktree, { repo, git = null, retries = 5 } =
   if (refused) { out.errors.push({ path: target, code: 'REFUSED', message: `refusing to remove ${refused}` }); return out; }
   const before = mainRoot ? mainCheckoutGuard(mainRoot, { git: run }) : null;
   if (fs.existsSync(target)) {
-    for (const link of linksUnder(target)) { if (removeLink(link)) out.links += 1; else out.errors.push({ path: link, code: 'LINK_STUCK', message: 'a link could not be removed' }); }
-    const left = linksUnder(target);
-    if (left.length) {
-      for (const l of left) if (!out.errors.some((e) => e.path === l)) out.errors.push({ path: l, code: 'LINK_STUCK', message: 'a link is still there after removal' });
-      out.reason = 'link-stuck';
-      return out;
-    }
+    const unlinked = removeLinksUnder(target);
+    out.links = unlinked.links;
+    if (!unlinked.ok) { out.errors.push(...unlinked.errors); out.reason = 'link-stuck'; return out; }
     out.removed.links = out.links;
     const registered = trees.some((t) => same(t, target));
     if (registered && repo) run(['worktree', 'remove', '--force', target], { cwd: repo });

package/sync/index.mjs

@@ -8,7 +8,8 @@
 // side (be, fe) for a side slot, whose files land under that side's folder. Two targets are not whole files of a managedBy slot
 // and are listed in this module: the marked block of the root .gitignore, and .starciwork/.gitignore, which lives inside the
 // .starciwork directory slot. Every file is rendered with the app's hfs.json (both sides and their apps) and, for the Sonar
-// exclusions, the jest preset the app installs for its be side. `--check` compares the sha256 of the rendered content with the
+// exclusions and the one coverage scope (sonar.coverage.inclusions and codecov.yml alike), the jest preset the app installs for
+// its be side. `--check` compares the sha256 of the rendered content with the
 // file on disk and fails on any drift; `--write` rewrites the drifted files. `.gitignore` is the one shared file: only the marked
 // block is managed and the app's own lines around it are left alone. The root package.json is managed by its `scripts` block
 // only (mode scripts, compared as parsed JSON): the rest of the file (dependencies, npm workspaces of fe/packages/*) is the app's.
@@ -98,7 +99,10 @@ export function render(text, vars, readTemplate = readBundled) {
   });
 }
 
-/** The Sonar exclusions from the jest preset the app installs for its be side: { sonarExclusions }. */
+/**
+ * What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions and the coverage sources
+ * (`COVERAGE_SOURCES`, the globs jest collects coverage from): { sonarExclusions, coverageSources }.
+ */
 export async function loadPresets(root) {
   const name = '@starci/jest-preset';
   const require = createRequire(path.join(root, 'package.json'));
@@ -109,7 +113,21 @@ export async function loadPresets(root) {
     throw new SyncError('HFS_SYNC_PRESET_MISSING', `${name} is not installed under ${root}; set it to the exact version in knowledge/hfs/canon-pins.yaml and reinstall`);
   }
   const preset = require(resolved);
-  return { sonarExclusions: preset.sonarExclusions() };
+  return { sonarExclusions: preset.sonarExclusions(), coverageSources: [...preset.COVERAGE_SOURCES] };
+}
+
+/** Where the be unit run writes the lcov report (jest `coverageDirectory` coverage under be/, reporter lcov), from the app root. */
+export const LCOV_REPORT = 'be/coverage/lcov.info';
+
+/**
+ * THE coverage scope of an app, from the app root: the preset's coverage sources on the be side (`be/src/**` + `/*.service.ts`).
+ * It is the one source of sonar.coverage.inclusions and of the codecov.yml status paths, so the two can never drift; fe/ is
+ * outside it (a front end has no tests).
+ */
+export function coverageScope(presets) {
+  const sources = presets?.coverageSources;
+  if (!Array.isArray(sources) || !sources.length) throw new SyncError('HFS_SYNC_PRESET_MISSING', '@starci/jest-preset gives no COVERAGE_SOURCES: the coverage scope cannot be rendered');
+  return sources.map(glob => `be/${glob}`);
 }
 
 /**
@@ -156,6 +174,9 @@ export function variables(app, scope, presets, sonarKey) {
     sonarKey: sonarKey ?? app.project,
     sonarExclusions: [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**'].filter(Boolean).join(','),
     sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
+    lcovReport: LCOV_REPORT,
+    coverageInclusions: scope === APP_SCOPE ? coverageScope(presets).join(',') : '',
+    codecovPaths: scope === APP_SCOPE ? coverageScope(presets).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
     tsconfigPaths: ['be/tsconfig.json', ...feTsconfigs].join(','),
     styleGlob: STYLE_GLOB,
   };

package/sync/managed.mjs

@@ -20,7 +20,7 @@
 //                                 `prettier`, `lint-staged`, `jest`). Forbidden tool-config files (.eslintrc*, .eslintignore, a second
 //                                 eslint.config.*) are refused by hfs-check through the slot manifest under the same code.
 //   HFS_SONAR_CONFIG (R11)        sonar-project.properties differs from its render (the render names no host URL, sources and tests that
-//                                 do not overlap, the `sonar.exclusions` of the jest preset (a back end), no coverage import, the ESLint report and the
+//                                 do not overlap, the `sonar.exclusions` of the jest preset (a back end), the be lcov with the services as the coverage scope, the ESLint report and the
 //                                 HFS import files Sonar reads), or the stack declaration names a quality gate other than the one
 //                                 gate of knowledge/sonar-gate.yaml (bundled in the runtime copy). One edit is one finding.
 //   HFS_TS_STRICT (R22)           the root tsconfig.json drift (either profile), named by flag (ts-strict.mjs) instead of by hash.

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -14,6 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -29,6 +30,14 @@ jobs:
         run: npm run typecheck
       - name: unit
         run: npm test -- --ci
+      - name: coverage upload
+        uses: codecov/codecov-action@v5
+        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
+        with:
+          token: ${{ env.CODECOV_TOKEN }}
+          files: {{lcovReport}}
+          disable_search: true
+          fail_ci_if_error: true
       - name: build be
         run: npm run build:be
       - name: build fe

package/templates/app/quality-config/codecov.yml

@@ -0,0 +1,22 @@
+{{header}}
+# The be unit run's lcov ({{lcovReport}}), uploaded by the managed CI workflow. Coverage is the services' alone: the status
+# paths are the one coverage scope hfs sync renders into sonar.coverage.inclusions too, held at 100 on the project and on
+# the patch. fe/ is outside coverage (a front end has no tests).
+codecov:
+  require_ci_to_pass: true
+coverage:
+  status:
+    project:
+      default:
+        target: 100%
+        threshold: 0%
+        paths:
+{{codecovPaths}}
+    patch:
+      default:
+        target: 100%
+        threshold: 0%
+        paths:
+{{codecovPaths}}
+ignore:
+  - "fe/**"

package/templates/app/quality-config/sonar-project.properties

@@ -7,4 +7,6 @@ sonar.exclusions={{sonarExclusions}}
 sonar.test.inclusions=**/*.spec.ts
 sonar.typescript.tsconfigPaths={{tsconfigPaths}}
 sonar.externalIssuesReportPaths=reports/lint.sonar.json
+sonar.javascript.lcov.reportPaths={{lcovReport}}
+sonar.coverage.inclusions={{coverageInclusions}}
 sonar.nodejs.maxspace=8192