@starci/hfs 4.5.1 → 4.7.0

package/runtime/knowledge/hfs/ci-standard.yaml

@@ -0,0 +1,103 @@
+schema: starci/ci-standard@1
+id: ci-standard
+title: The one StarCi CI standard
+
+# OWNER RULING ci-standard (2026-10-18, modules/kernel/owner-rulings.yaml): ".claude defines ONE standard CI ruleset, its own CI and the examples follow it, and apps
+# inherit it." This file is the one place that standard is written. Each item names what it requires, the workflows it covers and what enforces it:
+#   app-ci         the managed .github/workflows/ci.yml of an app (rendered by `starci app sync` from packages/hfs/templates/app/ci-workflows*; the examples are the
+#                  reference, and their rendered CI runs green on GitHub through the candidate flow as part of every release proof: the runtime's examples.yml)
+#   runtime        the runtime repository's own workflows (.github/workflows/*.yml), checked by the same rules, not rendered
+# Enforcers: rule R301 CI_STANDARD (scripts/hfs/rules/ci-standard.mjs over app-ci in the app check and the example apps, scripts/hfs/runtime-rules/runtime-ci-standard.mjs
+# over the runtime's own workflows) checks every item marked `check: ci-standard`; the other items are owned by the rule or render named in `by`.
+# Apps get the standard only through `starci app sync`: the managed CI files are sync targets, and `starci app sync --check` / the app check refuse drift.
+
+# The jobs of the managed app CI (job ids, in this order), per edition; `sonar` exists when the Sonar service is enabled.
+jobs:
+  full: {required: [fast, lint, test, coverage, build], optional: [sonar]}
+  lite: {required: [fast, lint, test, coverage, build], optional: [db-types, sonar]}
+
+# The per-job settings the managed CI renders when .starcistacks/application-stacks.yaml ci.jobs leaves them out (ci.jobs.<job>.timeoutMinutes,
+# ci.jobs.test.shards). Sized from a real run (NIVO v0.2.3 on the 2-vCPU GitHub runner, 2026-10-18): the be lint with the Sonar import took 11.5 minutes and the
+# fe lint more than 8 in one 20-minute job, and ~900 unit suites ran at ~4 s each (670 of 904 in 45 minutes). One lint job per side, and 6 shards of ~150 suites
+# (~10 minutes each plus the install) leave each job well inside its timeout.
+defaults:
+  shards: 6
+  timeoutMinutes: {fast: 20, lint: 30, test: 25, coverage: 20, build: 30, sonar: 20, db-types: 30}
+
+# The steps that need a raised Node heap on the GitHub runner, matched on their `run` text, and the least heap they must declare in NODE_OPTIONS.
+heap:
+  minMiB: 6144
+  steps: ['npm run lint', 'app lint', 'app check --coverage-from']
+
+items:
+  - id: candidate-trigger
+    title: the release CI runs on the release candidate ref
+    requires: "ci.yml runs on push of branches ['release/candidate-*'] and tags ['v*'] (and workflow_dispatch); the release flows wait for the run of the release sha there"
+    covers: [app-ci, runtime]
+    by: [R221 CI_TRIGGERS_RELEASE_ONLY, R251 HFS_APP_WORKFLOW_TRIGGER]
+  - id: job-shape
+    title: the job shape fast / lint / test / coverage / build / sonar
+    requires: "the managed CI holds exactly the jobs of `jobs` for its edition; the unit run is a step of `test`; the merge, the coverage proof and the Codecov upload are steps of `coverage`, which alone holds the OIDC id-token"
+    covers: [app-ci]
+    check: ci-standard
+  - id: full-history-base-ref
+    title: full history and the lint base STARCI_BASE_REF
+    requires: "every actions/checkout of the managed CI fetches the full history (fetch-depth: 0), and the lint job writes STARCI_BASE_REF to GITHUB_ENV before it lints"
+    covers: [app-ci]
+    check: ci-standard
+  - id: heap-per-step
+    title: a raised heap on every heavy step
+    requires: "every step whose run matches heap.steps declares NODE_OPTIONS with --max-old-space-size of at least heap.minMiB, on the step itself"
+    covers: [app-ci, runtime]
+    check: ci-standard
+  - id: sonar-lint-per-side
+    title: the Sonar lint runs per side
+    requires: "a lint with a Sonar import (--sonar) names its side (--side be|fe); the reports are merged into reports/lint.sonar.json afterwards; no combined lint with Sonar"
+    covers: [app-ci, runtime]
+    check: ci-standard
+  - id: test-sharding
+    title: the unit run in shards, merged once
+    requires: "the test job is a matrix over shard (ci.jobs.test.shards, default defaults.shards); each shard runs npm test with --shard=<i>/<N> and without the per-file threshold, uploads its lcov, and the coverage job merges them (starci app coverage merge) before the coverage proof proves 100 per file"
+    covers: [app-ci]
+    check: ci-standard
+  - id: lint-parallel
+    title: lint each side in its own job
+    requires: "the lint job is a matrix over side [be, fe]; each side lints (with its own Sonar report when a token is set) in parallel, and the sonar job merges the reports"
+    covers: [app-ci]
+    check: ci-standard
+  - id: cache-saved-always
+    title: caches keyed by the lockfile and saved always
+    requires: "no actions/cache key holds the commit sha (a cache saved only on a green run never warms); the jest and build caches restore by lockfile hash (restore-keys) and save with actions/cache/save under if: always()"
+    covers: [app-ci]
+    check: ci-standard
+  - id: fe-build-env
+    title: each fe app builds with its own env
+    requires: "the build job builds every fe app with that app's own public build values (static NEXT_PUBLIC_* from the declaration), never a shared env"
+    covers: [app-ci]
+    by: [render packages/hfs/sync/ci-commands.mjs, R300 FE_PUBLIC_BUILD_ARG_MISSING]
+  - id: optional-providers
+    title: optional providers probe, then skip with a notice
+    requires: "an optional Codecov or Sonar step (continue-on-error) is preceded in its job by its availability probe (id codecov-availability / sonar-availability); a strict provider fails the job"
+    covers: [app-ci]
+    check: ci-standard
+  - id: timeouts
+    title: a timeout on every job, configurable per job
+    requires: "every job declares timeout-minutes; the managed CI renders ci.jobs.<job>.timeoutMinutes of the manifest, else defaults.timeoutMinutes"
+    covers: [app-ci, runtime]
+    check: ci-standard
+  - id: sha-pinned-actions
+    title: every action pinned to a commit sha
+    requires: "every remote `uses:` is pinned to a 40-hex commit sha (a docker:// action to a sha256 digest); a local ./ action is allowed"
+    covers: [app-ci, runtime]
+    check: ci-standard
+    by: [R251 HFS_DEPLOY_WORKFLOW (app workflows)]
+  - id: prettier-stable
+    title: the rendered CI is prettier's output
+    requires: "every rendered managed workflow is byte-identical to prettier's output with the canon config"
+    covers: [app-ci]
+    by: [self-check rendered-prettier, render packages/hfs/sync]
+  - id: context-validity
+    title: expressions use only the contexts available at their key
+    requires: "GitHub Actions expressions read only contexts available at their workflow key"
+    covers: [app-ci, runtime]
+    by: [R299 HFS_WORKFLOW_CONTEXT]

package/runtime/knowledge/hfs/rules.yaml

@@ -3558,7 +3558,7 @@ rules:
       - {kind: hfs, id: lite-secret-custody, at: scripts/hfs/rules/supabase-secrets.mjs}
   - id: R221
     code: "CI_TRIGGERS_RELEASE_ONLY"
-    law: "The only workflow triggers are a push of release tags, a person dispatching it and, in the runtime's own workflows (`.github/workflows/` at the root), a push to `main`: every tracked workflow declares an `on` that holds only `push` filtered to `tags: ['v*']` (and, in the runtime's own workflows, `branches: [main]`; no paths or ignore filter beside them) and `workflow_dispatch`. The examples and the hfs app templates (so every scaffolded app inherits it) take the tag and the dispatch only: an app's CI runs once per release, on its tag. A push to any other branch, a pull_request, a schedule, a workflow_call or any other event refuses the workflow."
+    law: "The only workflow triggers are a push of release tags, a push of release candidate branches `release/candidate-*`, a person dispatching it and, in the runtime's own workflows (`.github/workflows/` at the root), a push to `main`: every tracked workflow declares an `on` that holds only `push` filtered to `tags: ['v*']` and/or `branches` naming only `release/candidate-*` (and, in the runtime's own workflows, `main`; no paths or ignore filter beside them) and `workflow_dispatch`. Every `ci.yml`, and the runtime's `examples.yml`, must name `release/candidate-*`: `starci release cut` and `starci app release push` push the exact release sha there and move main and the tag only when that run is green (owner ruling candidate-ci, 2026-10-18). A push to any other branch, a pull_request, a schedule, a workflow_call or any other event refuses the workflow."
     scope: runtime
     editions: [lite, full]
     docs: [docs/git-governance.md#r221]
@@ -4026,7 +4026,7 @@ rules:
       - {path: packages/hfs/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml, edition: lite}
       - {path: packages/hfs/templates/app/ci-workflows/github/workflows/ci.yml, edition: full}
     witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): the mutation witness was a deleted runtime spec or fixture", date: "2026-10-17"}
-    law: "In lite and full apps, deployment jobs declare a protected environment, explicit permissions and concurrency, materialize sealed secrets through SOPS_AGE_KEY or starci app secret materialize, and reference only the age key and transport SSH key/known_hosts secrets. They never embed a dotenv blob or write a dotenv file. Every remote workflow action uses a 40-hex commit SHA (local actions are allowed and container actions require a full sha256 digest); supply-chain reports each unpinned uses reference at its source line, including disabled jobs and steps; installed tools are checksum or digest verified, or supplied by a pinned action. App workflows start only on release tags [v*] or workflow_dispatch, never on a branch push."
+    law: "In lite and full apps, deployment jobs declare a protected environment, explicit permissions and concurrency, materialize sealed secrets through SOPS_AGE_KEY or starci app secret materialize, and reference only the age key and transport SSH key/known_hosts secrets. They never embed a dotenv blob or write a dotenv file. Every remote workflow action uses a 40-hex commit SHA (local actions are allowed and container actions require a full sha256 digest); supply-chain reports each unpinned uses reference at its source line, including disabled jobs and steps; installed tools are checksum or digest verified, or supplied by a pinned action. App workflows start only on release tags [v*], the release candidate branches release/candidate-* (required in ci.yml: starci app release push waits for that run, owner ruling candidate-ci 2026-10-18) or workflow_dispatch, never on another branch push."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["HFS_DEPLOY_WORKFLOW", "HFS_WORKFLOW_PIN", "HFS_CI_TOOL_INSTALL", "HFS_APP_WORKFLOW_TRIGGER"]
@@ -4967,3 +4967,20 @@ rules:
       - {path: packages/hfs/templates/app/skeleton/.starcistacks, edition: full}
     specNa: "owner:no-runtime-specs (2026-10-17): the runtime has no specs of its own; this code is enforced by runtime code and its spec proof was a deleted runtime spec"
     witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): external smoke fixtures", date: "2026-10-17"}
+  - id: R301
+    code: "CI_STANDARD"
+    law: "The managed app CI, the example apps (the reference) and the runtime repository's own workflows follow the ONE CI standard of knowledge/hfs/ci-standard.yaml (owner ruling ci-standard, 2026-10-18): the job shape fast/test/build(/sonar) with the unit run and the Codecov upload in test alone, full history with STARCI_BASE_REF written before the lint, NODE_OPTIONS --max-old-space-size=6144 on every heavy step, the Sonar lint per side, optional providers probed before they skip, a timeout on every job and every action pinned to a commit sha; the other items (candidate trigger R221, per-fe-app build env, prettier-stable renders, R299 contexts) are owned by the rules the standard names. Apps get the standard only through starci app sync."
+    kinds: [check]
+    gates: [settle, land, ci]
+    failureCodes: ["CI_STANDARD"]
+    enforcers:
+      - {kind: hfs, id: ci-standard, at: scripts/hfs/rules/ci-standard.mjs}
+      - {kind: runtime, id: ci-standard-runtime, at: scripts/hfs/runtime-rules/runtime-ci-standard.mjs}
+    editions: [lite, full]
+    docs:
+      - {path: docs/application-stacks.md#r301, editions: [lite, full]}
+    exemplifiedBy:
+      - {path: packages/hfs/templates/app/ci-workflows-lite/github/workflows/ci.yml, edition: lite}
+      - {path: packages/hfs/templates/app/ci-workflows/github/workflows/ci.yml, edition: full}
+    specNa: "owner:no-runtime-specs (2026-10-17): the runtime has no specs of its own; the scaffold e2e (e2e/hfs-scaffold-app.spec.mjs: a fresh scaffold has no finding) and the example apps prove it"
+    witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): the runtime has no spec fixtures", date: "2026-10-18"}

package/runtime/knowledge/sonar-gate.yaml

@@ -41,8 +41,8 @@ newCode:
     minReviewedPercent: 100
     unreviewedMax: 0
 # The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `starci app lint`
-# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry), which writes ONE file, reports/lint.sonar.json
-# (`starci app lint --sonar reports/lint.sonar.json`), named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
+# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry). CI runs it per side with --side and --sonar,
+# then merges rules by id and joins issues into ONE file, reports/lint.sonar.json, named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
 # the whole project at zero. The file carries three engines:
 #   starci-hfs   the repository findings of `starci app check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
 #   eslint       ESLint's json over the repository (the BE and FE canon plugins alike, per-file and project-graph rules)

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

@@ -1701,6 +1701,16 @@ CI_SECRET_SEALED:
   owner: op-retry
   kind: check-finding
 
+CI_STANDARD:
+  title: "A workflow breaks the StarCi CI standard"
+  title_vi: "Workflow vi phạm chuẩn CI của StarCi"
+  meaning_vi: "Workflow CI (của app, của ví dụ hoặc của runtime) không đáp ứng một mục của knowledge/hfs/ci-standard.yaml; mục bị vi phạm được nêu trong ngoặc vuông."
+  causes_vi:
+    - "Vi phạm R301: job shape, lịch sử đầy đủ và STARCI_BASE_REF, heap cho bước nặng, lint Sonar theo từng phía, probe nhà cung cấp tùy chọn, timeout hoặc ghim action theo sha."
+  nextStep_vi: "App: chạy starci app sync --write để render lại CI chuẩn (không sửa tay); runtime: sửa workflow theo mục được nêu."
+  owner: op-retry
+  kind: check-finding
+
 CI_TRIGGERS_RELEASE_ONLY:
   title: "Workflow trigger other than a release tag, a person or the runtime's main"
   title_vi: "Workflow có trigger không phải tag phát hành, người chạy tay hay main của runtime"

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -152,6 +152,13 @@ $defs:
       optional:
         description: Skip an unreachable quality provider with a notice; SonarQube defaults true, SonarCloud and Codecov false.
         type: boolean
+      badgeToken:
+        description: >-
+          codecov and sonar only: a read-only, public-safe badge token (Codecov graphing token, Sonar project badge token)
+          that the README badge of a private repository needs. It is public configuration rendered into README.md, never a
+          secret; a CI token or any write credential never goes here.
+        type: string
+        pattern: '^[A-Za-z0-9_-]{6,128}$'
       ecosystems: {type: array, items: {enum: [npm, docker, github-actions]}}
       schedule:
         type: object
@@ -275,8 +282,30 @@ $defs:
           repository: {type: string, pattern: '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$'}
           defaultBranch: {type: string, minLength: 1, default: main}
           workflow: {type: string, pattern: '^[A-Za-z0-9_.-]+\.ya?ml$', default: ci.yml}
+          visibility:
+            description: The GitHub repository visibility; private READMEs need services.<id>.badgeToken for live badges. Omitted means unknown.
+            enum: [public, private]
       secrets: {type: array, items: {$ref: '#/$defs/ciSecret'}}
       vars: {type: array, items: {$ref: '#/$defs/ciVariable'}}
+      jobs:
+        description: >-
+          Per-job settings of the managed CI (the CI standard, knowledge/hfs/ci-standard.yaml defaults): timeoutMinutes per job and the number of unit-run shards.
+          Omitted settings take the standard's defaults; starci app sync renders them.
+        type: object
+        additionalProperties: false
+        properties:
+          fast: {$ref: '#/$defs/ciJob'}
+          lint: {$ref: '#/$defs/ciJob'}
+          test:
+            type: object
+            additionalProperties: false
+            properties:
+              timeoutMinutes: {type: integer, minimum: 5, maximum: 360}
+              shards: {type: integer, minimum: 1, maximum: 20}
+          coverage: {$ref: '#/$defs/ciJob'}
+          build: {$ref: '#/$defs/ciJob'}
+          sonar: {$ref: '#/$defs/ciJob'}
+          db-types: {$ref: '#/$defs/ciJob'}
       dependabot:
         type: object
         additionalProperties: false
@@ -290,6 +319,11 @@ $defs:
               properties:
                 name: {$ref: '#/$defs/ciName'}
                 purpose: {type: string}
+  ciJob:
+    type: object
+    additionalProperties: false
+    properties:
+      timeoutMinutes: {type: integer, minimum: 5, maximum: 360}
   ciSecret:
     anyOf:
       - type: object
@@ -310,6 +344,9 @@ $defs:
           purpose: {type: string}
           optional: {type: boolean}
   ciVariable:
+    description: >-
+      A public CI variable either carries its literal value, or declares ownerValue true (no value) when only the owner
+      may supply it; var sync skips an owner-supplied value and ci verify checks that it exists by name.
     anyOf:
       - type: object
         additionalProperties: false
@@ -330,6 +367,25 @@ $defs:
           value: {type: string}
           purpose: {type: string}
           optional: {type: boolean}
+      - type: object
+        additionalProperties: false
+        required: [name, scope, ownerValue]
+        properties:
+          name: {$ref: '#/$defs/ciName'}
+          scope: {const: repository}
+          ownerValue: {const: true}
+          purpose: {type: string}
+          optional: {type: boolean}
+      - type: object
+        additionalProperties: false
+        required: [name, scope, ownerValue, environment]
+        properties:
+          name: {$ref: '#/$defs/ciName'}
+          scope: {const: environment}
+          environment: {type: string, pattern: '^[a-z][a-z0-9-]*$'}
+          ownerValue: {const: true}
+          purpose: {type: string}
+          optional: {type: boolean}
   serviceStack:
     description: >-
       Which stack defines a local service - either a project-owned .starcistacks stack

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "d230745d3aa5cfe65f75cb5fb2872924b935f1b4610c0b72db2f729572386404",
+  "hash": "441c47efec9ac314fb4ffd8b203fd6469aac65710ca9cd12aace0c032c2c537f",
   "global": [
     {
       "name": "json",
@@ -177,7 +177,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "ci": {
-          "summary": "set declared GitHub CI secrets and variables and verify their custody",
+          "summary": "set declared GitHub CI secrets and variables, verify their custody, or run the managed CI locally",
           "owner": "@starci/hfs",
           "positional": [
             {
@@ -185,7 +185,8 @@ export const CATALOG = {
               "enum": [
                 "secret",
                 "var",
-                "verify"
+                "verify",
+                "local"
               ],
               "required": true,
               "variadic": false
@@ -224,22 +225,37 @@ export const CATALOG = {
             {
               "name": "value",
               "type": "string",
-              "summary": "public variable value that must agree with the manifest"
+              "summary": "public variable value that must agree with the manifest; var set ownerValue requires stdin instead"
             },
             {
               "name": "execute",
               "type": "boolean",
-              "summary": "apply the variable sync plan"
+              "summary": "apply the variable sync plan; var sync skips ownerValue variables"
             },
             {
               "name": "json",
               "type": "boolean",
-              "summary": "print verification findings as JSON"
+              "summary": "print verification findings (or the local plan and results) as JSON"
+            },
+            {
+              "name": "jobs",
+              "type": "string",
+              "summary": "local: the jobs to run, comma separated (default fast,lint,test,coverage,build; sonar and db-types only when named)"
+            },
+            {
+              "name": "parallel",
+              "type": "string",
+              "summary": "local: job instances run at once (default half the CPUs, at most 4)"
+            },
+            {
+              "name": "dry-run",
+              "type": "boolean",
+              "summary": "local: print which steps would run and which only GitHub can run"
             }
           ],
           "exit": {
-            "0": "action completed or verification clean",
-            "1": "verification findings",
+            "0": "action completed, verification clean or every local job green",
+            "1": "verification findings or a local job red",
             "2": "refusal or bad usage"
           },
           "json": "flag",
@@ -250,13 +266,66 @@ export const CATALOG = {
             "starci app ci var set SONAR_HOST_URL",
             "starci app ci var sync",
             "starci app ci var sync --execute",
-            "starci app ci verify --json"
+            "starci app ci verify --json",
+            "starci app ci local --dry-run",
+            "starci app ci local --jobs lint,test --parallel 4"
+          ],
+          "editions": [
+            "full",
+            "lite"
+          ],
+          "impl": null,
+          "conventions": [
+            "local reads .github/workflows/ci.yml and runs every job instance (matrix values substituted) on this machine, in parallel, a job after its needs",
+            "it skips what only GitHub runs (uses: actions, npm ci, the lint baseline, a step whose if: needs a Sonar token, a tag ref or step outputs) and lists it",
+            "the unit shards write be/coverage/shards/shard-<i>, which the coverage job merges; each instance logs to a temp directory"
+          ],
+          "runtimeSide": "host"
+        },
+        "coverage": {
+          "summary": "merge the lcov reports of the sharded unit run into one report",
+          "owner": "@starci/hfs",
+          "positional": [
+            {
+              "name": "action",
+              "enum": [
+                "merge"
+              ],
+              "required": true,
+              "variadic": false
+            }
+          ],
+          "flags": [
+            {
+              "name": "out",
+              "type": "string",
+              "summary": "the merged lcov to write (the managed CI writes be/coverage/lcov.info)"
+            },
+            {
+              "name": "cwd",
+              "type": "string",
+              "summary": "the app root (default the current directory)"
+            }
+          ],
+          "exit": {
+            "0": "merged",
+            "2": "bad usage or no report found"
+          },
+          "json": "none",
+          "examples": [
+            "starci app coverage merge --out be/coverage/lcov.info be/coverage/shards"
           ],
           "editions": [
             "full",
             "lite"
           ],
           "impl": null,
+          "conventions": [
+            "the CI standard shards the unit run (npm test -- --shard=i/N); each shard writes an lcov over the whole coverage scope",
+            "merge sums every line, function and branch hit by identity across the reports and writes one record per source file",
+            "a path is an lcov file or a directory searched for every lcov.info below it; no report found refuses (exit 2), never an empty report",
+            "the coverage proof (starci app check --coverage-from), the Codecov upload and the Sonar import read the merged report"
+          ],
           "runtimeSide": "host"
         },
         "db": {
@@ -618,8 +687,8 @@ export const CATALOG = {
           ],
           "exit": {
             "0": "gate green or push done or nothing to do",
-            "1": "a gate is red or the push was refused by the hook",
-            "2": "refusal or bad usage including RELEASE_CI_RED and RELEASE_SONAR_UNAVAILABLE"
+            "1": "a gate is red, the candidate CI of the sha is not green, or the push was refused by the hook",
+            "2": "refusal or bad usage including RELEASE_SONAR_UNAVAILABLE"
           },
           "json": "flag",
           "examples": [
@@ -641,10 +710,11 @@ export const CATALOG = {
             "declared release.gates gets audit appended if missing",
             "--sonar appends @sonar/scan@4.3.0 against services.sonar.host (host.public for a host mapping), plus organization for sonarcloud;",
             "disabled or unavailable Sonar or an unset token refuses RELEASE_SONAR_UNAVAILABLE",
-            "gate checks the newest completed ci.yml run on the default branch, including reachable push/tag runs;",
-            "failure, cancelled or timed_out refuses RELEASE_CI_RED with its URL and SHA;",
-            "unreadable GitHub or no run warns RELEASE_CI_UNKNOWN and continues",
-            "only the owner's starci release ci-override --sha <sha> --reason <text> record can override red CI; there is no --no-ci-check flag",
+            "OWNER RULING candidate-ci (2026-10-18): the gate no longer reads the default-branch CI; the verdict is the candidate run of the sha",
+            "push --execute sends HEAD to refs/heads/release/candidate-<version> first and waits for its ci.yml run (it triggers on release/candidate-*)",
+            "green moves the branch and the tag in one atomic push; red refuses RELEASE_CANDIDATE_CI_RED naming the failing jobs",
+            "no run, or no end in time, refuses RELEASE_CANDIDATE_CI_TIMEOUT; unreadable GitHub refuses RELEASE_CI_UNKNOWN; nothing reaches the branch",
+            "only the owner's starci release ci-override --sha <sha> --reason <text> record lets a red candidate through; there is no --no-ci-check flag",
             "gate refuses a dirty tree, HEAD other than --source, a moved HEAD and a tree dirtied by the gates; record and tag only when all gates are green",
             "a gate with summary jest is red on failed tests and on a coverage threshold miss even when the process exits 0",
             "push needs the annotated tag and L4 record of HEAD, runs git push --dry-run --atomic first and never uses --no-verify"
@@ -7317,12 +7387,12 @@ export const CATALOG = {
             {
               "name": "dev",
               "type": "boolean",
-              "summary": "save the packages as development dependencies"
+              "summary": "save the CLI and explicit packages as development dependencies"
             },
             {
               "name": "canon",
               "type": "boolean",
-              "summary": "install the target CLI and all of its exact StarCi canon pins"
+              "summary": "install the target CLI and move its declared exact StarCi canon pins"
             }
           ],
           "exit": {
@@ -7353,10 +7423,12 @@ export const CATALOG = {
             "bare package names resolve only from knowledge/hfs/canon-pins.yaml and never through a registry lookup",
             "explicit versions use exact x.y.z form and must agree with the canon pin when one exists, except the target CLI version on a canon upgrade",
             "naming @starci/cli or passing --canon installs the exact target CLI first,",
-            "then reads its installed HFS runtime canon-pins.yaml and installs every pinned @starci package in the same host lock",
+            "then reads its installed HFS runtime canon-pins.yaml and, in the same host lock,",
+            "moves each other pinned @starci package only where a root or workspace package.json declares it, in its own section",
             "--canon without a CLI positional uses the running runtime's exact CLI pin as the target",
             "target pins never fall back to the running runtime when the target pin file is missing or inconsistent",
-            "each target StarCi pin is reported as moved or refused with a reason; a failed canon phase exits nonzero even when the first CLI install succeeded",
+            "each target StarCi pin is reported as moved (with its workspace), skipped when no package.json declares it, or refused with a reason",
+            "a failed canon phase exits nonzero even when the first CLI install succeeded",
             "installs always use --save-exact and report the package.json and package-lock.json diff stat"
           ],
           "runtimeSide": "host"
@@ -7721,6 +7793,11 @@ export const CATALOG = {
               "name": "keep",
               "type": "boolean",
               "summary": "keep and print the temporary application path"
+            },
+            {
+              "name": "source",
+              "type": "boolean",
+              "summary": "scaffold with this checkout and install the @starci scope from its packed tarballs (the pre-publish form release scaffold-e2e runs)"
             }
           ],
           "exit": {
@@ -7731,7 +7808,8 @@ export const CATALOG = {
           "json": "none",
           "examples": [
             "starci release app-installs",
-            "starci release app-installs --keep"
+            "starci release app-installs --keep",
+            "starci release app-installs --source"
           ],
           "editions": [
             "full"
@@ -7776,7 +7854,7 @@ export const CATALOG = {
           "runtimeSide": "tree"
         },
         "ci-override": {
-          "summary": "the owner accepts red CI for one SHA and records who and why",
+          "summary": "the owner accepts a red candidate CI for one SHA (emergency path) and records who and why",
           "owner": "runtime",
           "flags": [
             {
@@ -7811,14 +7889,17 @@ export const CATALOG = {
             "script": "scripts/supervisor/release-ci-override-cli.mjs"
           },
           "conventions": [
-            "OWNER RULING 2026-10-17 (chat to main, relayed): alpha.20 \"cut refuses when the latest CI on main is red, with a documented owner override verb\";",
-            "the override is owner-only, records who and why in the owner rulings, and agents cannot run it.",
+            "OWNER RULING candidate-ci (2026-10-18): a release reaches main only when the candidate CI of its own sha is green;",
+            "this verb is the one documented EMERGENCY path for a red candidate.",
+            "The override is owner-only, records who and why, and agents cannot run it (OWNER RULING alpha20-ci-override-owner-only).",
             "Every bound role is refused by the command guard and by this script. The owner must use a terminal and type the first 12 SHA characters exactly.",
             "Writes <git-common-dir>/starci-release/<sha>.ci-override.json, schema starci/ci-override@1,",
             "with sha, reason, by (git user.name and OS user), at, and runUrl (empty if GitHub is unavailable).",
-            "For the runtime, appends ci-override-<sha12> under rulings before the top-level supersedes key in modules/kernel/owner-rulings.yaml.",
-            "Commit that entry into the tree being cut. App repositories receive only the record.",
-            "An override applies only to its exact SHA. It does not permit a cut when CI is unknown. Existing ruling IDs with another reason refuse."
+            "release cut and app release push read that record for the exact candidate sha only; the release record logs its use.",
+            "For the runtime it also appends ci-override-<sha12> under rulings in modules/kernel/owner-rulings.yaml as the audit trail.",
+            "App repositories receive only the record.",
+            "An override applies only to its exact SHA. It never permits a release whose CI is unknown or timed out.",
+            "Existing ruling IDs with another reason refuse."
           ],
           "runtimeSide": "tree"
         },
@@ -7940,8 +8021,8 @@ export const CATALOG = {
             }
           ],
           "exit": {
-            "0": "the release was cut and main plus its tag were pushed atomically, or --plan found nothing missing",
-            "1": "refused (RELEASE_CI_RED, RELEASE_CI_UNKNOWN, dirty tree, no or wrong tag, release notes incomplete, version not moved past the remote main, suite red, main moved, secret scan) and nothing was pushed",
+            "0": "the candidate CI of the release sha was green, then main plus its tag were pushed atomically, or --plan found nothing missing",
+            "1": "refused (RELEASE_CANDIDATE_CI_RED, RELEASE_CANDIDATE_CI_TIMEOUT, RELEASE_CI_UNKNOWN, dirty tree, no or wrong tag, release notes incomplete, version not moved past the remote main, suite red, main moved, secret scan) and nothing was pushed",
             "2": "bad usage"
           },
           "json": "flag",
@@ -7958,14 +8039,18 @@ export const CATALOG = {
             "script": "scripts/supervisor/release-cut-cli.mjs"
           },
           "conventions": [
-            "OWNER RULING 2026-10-17 (chat to main, relayed): alpha.20 \"cut refuses when the latest CI on main is red, with a documented owner override verb\";",
-            "the override is owner-only, records who and why in the owner rulings, and agents cannot run it.",
-            "Before the suite, including --plan, read the newest completed CI workflow run on main.",
-            "Only success continues; every other conclusion refuses RELEASE_CI_RED and names the run URL and headSha.",
-            "Unreadable GitHub or no completed run refuses RELEASE_CI_UNKNOWN: a cut must not proceed blind, including under suite ci.",
-            "The owner may run starci release ci-override --sha <headSha> --reason <text>.",
-            "A red run requires both starci-release/<headSha>.ci-override.json in the git common dir and ci-override-<sha12>",
-            "in modules/kernel/owner-rulings.yaml of the tree being cut. Commit the ruling before cutting."
+            "OWNER RULING candidate-ci (2026-10-18): never again have main receive a release whose CI is red, with the owner confirming afterwards.",
+            "Before the suite, including --plan, the workflows the candidate CI waits for (release-cut.yaml candidate.workflows) must be readable,",
+            "else RELEASE_CI_UNKNOWN. The latest run on main is no longer read: a red main needs no owner override before the next release.",
+            "After the suite and the secret scan the exact HEAD is pushed to refs/heads/release/candidate-<version>;",
+            "a re-cut of the same version force-moves only that ref, never main.",
+            "The cut waits for every required workflow run of that sha (pollSeconds, graceMinutes, waitMinutes in release-cut.yaml).",
+            "Red refuses RELEASE_CANDIDATE_CI_RED with the run URLs and the failing jobs and steps; nothing reaches main.",
+            "No run within the grace, or no end within the wait, refuses RELEASE_CANDIDATE_CI_TIMEOUT.",
+            "A red candidate keeps its ref for diagnosis; after a cut the candidate ref is left on the remote, naming the released sha.",
+            "Only on green is the annotated tag created and main plus the tag pushed atomically; the release record logs the candidate verdict.",
+            "Emergency path, owner-only: starci release ci-override --sha <HEAD> --reason <text> lets a red candidate through.",
+            "The release record logs its use."
           ],
           "runtimeSide": "tree"
         },

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -4,6 +4,14 @@ import { parseYaml } from '../../engine/yaml.mjs';
 
 const nameOf = (item) => typeof item === 'string' ? item : item?.name;
 
+/** A public CI variable declares either a manifest value or an owner-supplied value, never both. */
+function variableProblems(item, at, invalid) {
+  const hasValue = item != null && Object.hasOwn(item, 'value');
+  const hasOwnerValue = item != null && Object.hasOwn(item, 'ownerValue');
+  if (hasValue && hasOwnerValue) invalid(at, 'a variable has either a value or ownerValue');
+  else if (!hasValue && item?.ownerValue !== true) invalid(at, 'a variable needs a value or ownerValue: true');
+}
+
 /** Each CI name belongs to one class and scope; declarations contain names and public configuration only. */
 export function readCiDeclaration(doc) {
   const problems = [], seen = new Set();
@@ -17,8 +25,9 @@ export function readCiDeclaration(doc) {
     if (!['repository', 'environment'].includes(scope)) invalid(`${where}.scope`, 'scope must be repository or environment');
     if (scope === 'environment' && (typeof item?.environment !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.environment))) invalid(`${where}.environment`, 'environment scope requires an environment name');
     if ((dependabot || scope !== 'environment') && item && Object.hasOwn(item, 'environment')) invalid(`${where}.environment`, 'only environment scope may name an environment');
+    if (variable) variableProblems(item, where, invalid);
     return { name, scope, environment: item?.environment ?? null, purpose: item?.purpose ?? null,
-      optional: item?.optional === true, ...(variable ? { value: item?.value } : {}) };
+      optional: item?.optional === true, ...(variable ? { value: item?.value, ownerValue: item?.ownerValue === true } : {}) };
   });
   const ci = doc?.ci;
   const secrets = normalize(ci?.secrets, 'ci.secrets');