starci-harness 1.1.0-alpha.21 → 1.1.0-alpha.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/contexts/code/be/persistence.md +2 -1
  2. package/contexts/decisions/rulings.yaml +57 -1
  3. package/contexts/grammars/contract-sections.md +4 -1
  4. package/contexts/grammars/contract.md +31 -1
  5. package/contexts/grammars/contract.yaml +47 -0
  6. package/contexts/harness/cli-canonical.md +1 -1
  7. package/contexts/hfs/harness.yaml +1 -1
  8. package/contexts/hfs/rules.yaml +33 -2
  9. package/contexts/hfs/slots.yaml +22 -4
  10. package/contexts/project/README.md +2 -0
  11. package/contexts/project/anatomy-full-be.md +1 -0
  12. package/contexts/project/anatomy-full-fe.md +1 -0
  13. package/contexts/project/anatomy-lite-be.md +2 -2
  14. package/contexts/project/anatomy-lite-fe.md +2 -2
  15. package/contexts/project/anatomy.md +3 -2
  16. package/contexts/project/check-cache.md +279 -0
  17. package/contexts/project/cicd.md +354 -0
  18. package/contexts/project/index.md +19 -9
  19. package/contexts/project/lint.md +2 -1
  20. package/contexts/stack/pins.yaml +8 -8
  21. package/contexts/ui/components/README.md +3 -0
  22. package/contexts/ui/components/backdrop.md +41 -0
  23. package/contexts/ui/components/card.md +2 -2
  24. package/contexts/ui/components/freestyle.md +41 -0
  25. package/contexts/ui/components/mascot.md +2 -2
  26. package/contexts/ui/components/page-header.md +3 -1
  27. package/contexts/ui/components/pane-grid.md +54 -0
  28. package/contexts/vendor/wrappers.yaml +1 -1
  29. package/dist/contexts-search.json +1 -1
  30. package/dist/core/app/stack.js +25 -4
  31. package/dist/core/app/stack.js.map +1 -1
  32. package/dist/core/check/ci-evidence.js +144 -0
  33. package/dist/core/check/ci-evidence.js.map +1 -0
  34. package/dist/core/check/ci.js +8 -0
  35. package/dist/core/check/ci.js.map +1 -1
  36. package/dist/core/release/affected.js +59 -16
  37. package/dist/core/release/affected.js.map +1 -1
  38. package/package.json +5 -2
  39. package/policy/quality.yaml +2 -0
@@ -63,7 +63,8 @@ the registry's imports and importers by `tier-direction` (R26), `owner-export-by
63
63
  which admit exactly the registry's `<c>Entities` imports and its `importedBy` importers; `owner-cycle` (R27)
64
64
  counts the registry as a unit of its own, so it never closes a cycle among capabilities through `platform/database`.
65
65
  Inherited columns count as the entity's own: `starci app db drift` reads them from TypeORM's metadata and `sql-owner` (R86)
66
- reads an inherited primary key; extending a base where the table has its columns is held by review.
66
+ reads an inherited primary key; `entity-extends-base` (R342) refuses an entity that declares a database-set `created_at` or
67
+ `updated_at` (and the generated uuid `id` beside both) itself, and names the base to extend.
67
68
 
68
69
  ## BE-PERSISTENCE-4 Lite reads and writes through entities; full SQL is a `sql`-tagged constant
69
70
 
@@ -305,6 +305,42 @@ rulings:
305
305
  words: "EmptyNotice có slot artwork"
306
306
  ruling: "EmptyNotice has an artwork slot: generated character art drawn as the Mascot at md and tied to its asset slot, and a first-run empty state uses EmptyNotice with that artwork."
307
307
  owner: "@starci/grammar src/core/composite/EmptyNotice; contexts/ui/components/empty-state.md empty-state.choose.cause"
308
+ - id: accent-corner
309
+ date: '2026-10-30'
310
+ status: live
311
+ words: "Thêm vào grammar"
312
+ ruling: "A one-corner rounding is a grammar prop, never app paint: SurfaceCard and MediaFrame take `accentCorner` (start-start, start-end, end-start or end-end), which draws that one logical corner at the Common accent radius `--grammar-accent-corner` while the other corners keep the family's surface radius. An app's `rounded-br` and its kin give way to it."
313
+ owner: "@starci/grammar src/core/branch/SurfaceCard, src/core/primitive/MediaFrame, src/common/styles.css; contexts/grammars/contract.md Corners are roles; contexts/grammars/contract.yaml DNA-COMMON-ACCENT-CORNER"
314
+ - id: backdrop
315
+ date: '2026-10-30'
316
+ status: live
317
+ words: "à đổi thành component background đi chứ nó cũng không phải là surfacecard, chốt vậy đi; Backdrop + giữ accentCorner"
318
+ ruling: "The brand half of a split screen (a sign-in) is a Backdrop, not a SurfaceCard: the brand's light tint full-bleed in its host, no card anatomy, the brand copy over it and a hero Mascot as its artwork, with one corner through `accentCorner`. SurfaceCard and MediaFrame keep `accentCorner` too."
319
+ owner: "@starci/grammar src/core/composite/Backdrop, src/common/styles.css; contexts/grammars/contract.md Backdrop; contexts/ui/components/backdrop.md"
320
+ - id: workspace-shell-fills-viewport
321
+ date: '2026-10-30'
322
+ status: live
323
+ words: "sao mà background dc nửa màn thôi thế???"
324
+ ruling: "A WorkspaceShell is at least one viewport tall, so the canvas under a short page runs to the bottom of the screen."
325
+ owner: "@starci/grammar src/common/styles.css .starci-core-workspace-shell"
326
+ - id: grammar-names-are-generic
327
+ date: '2026-10-31'
328
+ status: live
329
+ words: "tên gì chung chung tính chất grammar là cấp ui ux chung chung k bias tính năng hiểu k, ghi vào knowlege đi"
330
+ ruling: "The grammar is a generic UI/UX layer: a component, prop or token name says what it does as a layout or UI role (PaneGrid, SurfaceCard, Rail), never a product feature (chat, customer, order, invoice), so any product can reach for it. The multi-pane frame is PaneGrid; the old chat-named and PaneLayout spellings are removed, not aliased (removedVocabulary)."
331
+ owner: "@starci/grammar src/core/composition/PaneGrid; contexts/grammars/contract.md What a grammar provides; contexts/ui/components/page-header.md Owner split"
332
+ - id: pane-grid
333
+ date: '2026-10-31'
334
+ status: live
335
+ words: "phải xây kiểu grid hiểu không, kiểu bỏ A BC ngang hàng D ở dưới... và cách nhau bởi divider; chuẩn build grid và ghép các element nghiệp vụ của chat, mỗi grid có option surface hoặc k"
336
+ ruling: "The multi-pane frame is one generic PaneGrid, not a layout with fixed chat-shaped slots: named areas (A B C side by side, D below) laid out flush with a divider between neighbours, columns and rows by track role, the arrangement chosen per breakpoint, and each Pane either a borderless surface or a plain div. It only divides the space; what goes in a cell is the app's business. PaneLayout is removed, not aliased (removedVocabulary). A short inset separator inside a pane's content is the app's own element, not a grammar option."
337
+ owner: "@starci/grammar src/core/composition/PaneGrid, src/common/styles.css; contexts/grammars/contract.md PaneGrid; contexts/ui/components/pane-grid.md"
338
+ - id: grammar-freestyle-region
339
+ date: '2026-10-31'
340
+ status: live
341
+ words: "cái trang này free style đi trò div và làm bth thôi, thêm 1 component Freestyle hoặc tên gì đó tương đương đi trò, ý là cho custom nhưng vẫm bám grammar trừ bất đắc dĩ ntn"
342
+ ruling: "The grammar has one sanctioned escape hatch, Freestyle: a region that fills its host where the app writes its own plain divs and app CSS (layout, paint, radius, arbitrary values, absolutely positioned art) because no Grammar component fits. It names its reason, adds no paint of its own, and is a last resort: the rest of the page still follows the grammar, and a Grammar component used inside it is judged as before."
343
+ owner: "@starci/grammar src/core/composite/Freestyle; @starci/eslint-grammar-core src/freestyle.ts (R341) and exemptFreestyle; @starci/eslint-canon-fe src/lib/freestyle.ts; contexts/ui/components/freestyle.md"
308
344
  - id: STATE-8/loading-keeps-anatomy
309
345
  date: '2026-10-11'
310
346
  status: live
@@ -626,12 +662,32 @@ rulings:
626
662
  - id: entity-base
627
663
  date: '2026-10-30'
628
664
  status: live
629
- ruling: "Entities do not repeat the columns every table shares (owner 2026-10-30: \"trò đọc source starci academy backend gốc có extend AbstractEntity thì cũng update hfs lun nhé tránh lặp code trên các entity\"). platform/database carries the entity bases in abstract.entity.ts: AbstractEntity maps created_at and updated_at (timestamptz, set by the database: insert and update false), UuidAbstractEntity extends it with the generated uuid id. A table whose migration has those columns, with those names and types and set by the database, maps them by extending the base, imported from @modules/platform/database; a table without them extends nothing. The bases carry no GraphQL, validator or transformer decorator and map no table themselves; they are written by the first table that extends them, never by the starter."
665
+ ruling: "Entities do not repeat the columns every table shares (owner 2026-10-30: \"trò đọc source starci academy backend gốc có extend AbstractEntity thì cũng update hfs lun nhé tránh lặp code trên các entity\"). platform/database carries the entity bases in abstract.entity.ts: AbstractEntity maps created_at and updated_at (timestamptz, set by the database: insert and update false), UuidAbstractEntity extends it with the generated uuid id. A table whose migration has those columns, with those names and types and set by the database, maps them by extending the base, imported from @modules/platform/database; a table without them extends nothing. The bases carry no GraphQL, validator or transformer decorator and map no table themselves; they are written by the first table that extends them, never by the starter. Owner 2026-10-31 approved a lint so entities never repeat these columns again: R342 BE_ENTITY_EXTENDS_BASE (eslint-be entity-extends-base) refuses an entity that declares a database-set created_at or updated_at, or the generated uuid id beside both, itself."
630
666
  owner: "contexts/code/be/persistence.md BE-PERSISTENCE-3; @starci/hfs templates/be/skeleton platform/database abstract.entity.ts, templates/be/table/entity.ts.tpl"
667
+ - id: app-check-cache
668
+ date: '2026-10-31'
669
+ status: live
670
+ ruling: "Every app commits the results of `starci app check`, `starci app lint` and its unit coverage run in `.starcistacks/cache/` (check/, lint/, test-coverage/, sonar-baseline/, codecov-baseline/), one subfolder per family a selector of `app check` runs (`--hfs`, `--format`, `--db`, `--secrets`, `--wiring`, `--types`, `--lint`, `--test`, `--sonar`), keyed by content hashed with CRLF normalised to LF, never by time, deterministic and split per area; the CLI writes it and `app sync` never overwrites it. On a host and in CI a run judges only what differs from the cache; it is full when the cache is missing, on `--full`, when the one fingerprint check, lint and coverage share differs, and for a release. Every run hashes every file again, so a file whose hash differs is judged for real; CI trusts the cache only as it stands at the trusted base and fails a change whose committed record disagrees with what it inherited or computed. Sonar and Codecov baselines hold reference data only; the servers keep judging. The design is contexts/project/check-cache.md. Owner decisions, 2026-10-31: `app lint` stays its own verb and shares the cache with `app check`; HFS_CHECK_CACHE_FORGED is a hard blocker at any count, HFS_CHECK_CACHE_STALE and HFS_CHECK_CACHE_MISSING only warn; the release is always a full run; branch protection requiring the check is a later follow-up."
671
+ owner: "contexts/project/check-cache.md; @starci/hfs src/main.mts, lint/run.mts, coverage/, templates/; contexts/hfs/slots.yaml and rules.yaml once built"
672
+ words: "app check cache lại vào file dc không? sau chỉ check diff; giao làm luôn đi; nếu không có json thì check full hoặc trò require --force như github đi; suy nghĩ thiết kế phần này 1 agent opus nhé; chốt starcistacks lưu hết nhé và check diff và triển cho ci và local lun; thiết kế chuẩn để check ra bệnh và ghi vào cache"
673
+ - id: app-cicd-auto-deploy
674
+ date: '2026-10-31'
675
+ status: live
676
+ ruling: "Every app's managed `.github/` is one delivery pipeline keyed on the commit sha: the release tag run checks in full (or reuses a green candidate run of the same sha), builds each declared image once with SBOM and provenance and pushes it by `sha-<sha>` and `v<version>` to the declared registry (GitHub Actions cache per image; `linux/amd64` unless an environment declares another node), and when the one `verdict` job is green deploys every environment with `deploy.auto: true` in order through `starci app stack deploy --ci-run <run>`, which verifies the run's required jobs itself. Every green release tag deploys without waiting for the owner; `STARCI_DEPLOY_PAUSED` is the brake, and because agents push main, agents deploy. The deploy takes a lock on the manager shared with the urgent deploy, backs up and runs expand migrations inside the database's container before the services update and contract migrations only after accept in the same deploy, verifies, and on failure redeploys the previous accepted release from its stored bytes on top of Swarm's per-service update_config rollback; every attempt leaves a journal on the manager and the live service digests are compared with the accepted release. The CI SSH key is a sealed member of the environment (`vps-ci`), not a GitHub secret. Pull requests run checks only, with no secret, and Sonar runs on every full run. For an auto environment the owner's yes to deploy is that setting. The design is contexts/project/cicd.md."
677
+ owner: "contexts/project/cicd.md; @starci/hfs templates/app/ci-workflows*, sync/, stack/, release/; cli/src/core/check/ci.ts; contexts/hfs/rules.yaml R221, R251, R271 once built"
678
+ words: "cắm 1 opus nghiên cứu pattern ci cd chuẩn cho .github của từng dự án nhé — push cái build image mới push lên registry và tất cả pass, sau đó deploy lun, fail thì rollback trong môi trường dockerswarm. (approval, 2026-10-31:) Deploy lun có gì phải chờ"
631
679
 
632
680
  # Spellings knowledge no longer uses. A check refuses them in knowledge and instructions; `replacedBy` is what to
633
681
  # write instead. `pending` marks a name that still exists in published code until the follow-up lands.
634
682
  removedVocabulary:
683
+ - spelling: ChatWorkspace
684
+ as: grammar composition
685
+ replacedBy: PaneGrid
686
+ ruling: "grammar-names-are-generic"
687
+ - spelling: PaneLayout
688
+ as: grammar composition
689
+ replacedBy: PaneGrid
690
+ ruling: "pane-grid"
635
691
  - spelling: starci
636
692
  as: grammar family id
637
693
  replacedBy: core
@@ -8,7 +8,7 @@ the whole file and reads a section when it needs it: `starci contexts anchor <an
8
8
  `starci contexts search "<question>" --scope grammars` ranks them.
9
9
 
10
10
  - The grammar contract · `contexts/grammars/contract.md#the-grammar-contract` · 1 KB — Every grammar implements one contract, so a new grammar can be added without touching the others and two apps on the same grammar come out the same.
11
- - What a grammar provides · `contexts/grammars/contract.md#what-a-grammar-provides` · 2 KB
11
+ - What a grammar provides · `contexts/grammars/contract.md#what-a-grammar-provides` · 3 KB
12
12
  - The shared scale · `contexts/grammars/contract.md#the-shared-scale` · 2 KB — A row of controls reads as one object, so its controls share one height.
13
13
  - Intent x placement -> variant · `contexts/grammars/contract.md#intent-x-placement---variant` · 1 KB — The app states what a command does; the composition states where it sits; Common's map turns the pair into a HeroUI variant.
14
14
  - Roles · `contexts/grammars/contract.md#roles` · 1 KB — Each heading is one role of contract.yaml `roles`.
@@ -28,6 +28,9 @@ the whole file and reads a section when it needs it: `starci contexts anchor <an
28
28
  - EmptyState · `contexts/grammars/contract.md#emptystate` · 1 KB — An empty state is a region with nothing to show, or whose read failed: one message in the region's place inside the unchanged surface, and one action only when a real next step ...
29
29
  - Avatar · `contexts/grammars/contract.md#avatar` · 1 KB — An avatar is an identity mark on the ramp (`sm`, `md`, `lg`, and `control` in a bar), so it matches the controls beside it.
30
30
  - Mascot · `contexts/grammars/contract.md#mascot` · 1 KB — A mascot is generated character art on its own size scale, so one character comes out at one size on every screen: square boxes `sm`, `md` and `lg` (Common tokens ...
31
+ - Backdrop · `contexts/grammars/contract.md#backdrop` · 1 KB — A backdrop is the brand's own ground in a split screen: the family's light tint (`accentSoft`), full-bleed in its host, with the brand copy at the top and the artwork (a hero ...
32
+ - PaneGrid · `contexts/grammars/contract.md#panegrid` · 1 KB — A pane grid divides a bounded height into named areas (`["a b c", "d d d"]`): A, B and C side by side with D below.
33
+ - Freestyle · `contexts/grammars/contract.md#freestyle` · 1 KB — Freestyle is the one sanctioned escape hatch: a div that fills its host, where the app writes its own plain elements and CSS because no Grammar component fits (a sign-in brand ...
31
34
  - PageHeader · `contexts/grammars/contract.md#pageheader` · 1 KB — The page header is the top of one page: the trail, the page heading (the document's one h1) with the subject's mark, status chips and summary, the page's commands, and the page ...
32
35
  - Page · `contexts/grammars/contract.md#page` · 1 KB — A page is one route's frame: the page header band (PageHeader's slots, given as data) across the region, then the body in the page measure and gutter.
33
36
  - Diagram · `contexts/grammars/contract.md#diagram` · 1 KB — A diagram draws a structure the reader follows: `MermaidDiagram` renders an article's Mermaid source in the grammar's tokens, `FlowGraph` draws nodes and edges the app holds ...
@@ -11,6 +11,9 @@ WHEN to use it; a grammar file ([core](core.md), [offset-pop](offset-pop.md)) sa
11
11
  imports Common first and writes only inside its own layer and scope. A grammar is a scope because that is the
12
12
  only way two grammars can share every renderer: paint changes, the DOM never does. Overlay and toast mechanics
13
13
  are Common's ([common](common.md#one-root)); a grammar inherits them and never re-portals.
14
+ - **Names that describe the UI role.** A component, prop or token name says what it does as a layout or UI role
15
+ (`PaneGrid`, `SurfaceCard`, `Rail`), never a product feature (chat, customer, order, invoice), so any product
16
+ can reach for it. The grammar is a generic UI/UX layer (ruling `grammar-names-are-generic`).
14
17
  - **The token roles, bound or declared.** The HeroUI semantic variables are the interface between Common's
15
18
  anatomy and a grammar's material. A grammar binds each one or declares that it keeps HeroUI's default; an
16
19
  unbound role silently takes the host theme, which is how a grammar ends up with two accents.
@@ -54,7 +57,10 @@ the box is the ramp, the hit area meets its floor without redrawing the box (`DN
54
57
  three times `radius`, so whether a Button is a pill follows from the grammar's radius, never from a per-button
55
58
  choice. The grammar publishes the corner roles an app may name (`tiny`, `compact`, `control`, `surface`, `hero`,
56
59
  `pill`) as `--grammar-radius-*`, each set from its base radius; an app never writes a literal corner, which would
57
- freeze one grammar's value into every grammar.
60
+ freeze one grammar's value into every grammar. One corner may stand out: a SurfaceCard or MediaFrame names it in
61
+ `accentCorner` (a logical corner, `start-start` to `end-end`), drawn at the Common accent radius
62
+ `--grammar-accent-corner` while the others keep the family's radius (ruling accent-corner); an app never rounds one
63
+ corner itself.
58
64
 
59
65
  ## Intent x placement -> variant
60
66
 
@@ -226,6 +232,30 @@ it. It is decorative unless its `alt` names it. It carries the asset-slot props
226
232
  render is tied to the request that generated it; generated art reaches the page only through `Mascot` or a
227
233
  `MediaFrame` (lint R338, R339). The scale is Common's: a grammar changes nothing about it.
228
234
 
235
+ ### Backdrop
236
+
237
+ A backdrop is the brand's own ground in a split screen: the family's light tint (`accentSoft`), full-bleed in its host,
238
+ with the brand copy at the top and the artwork (a hero `Mascot`) filling the height left. It is a ground, not a card:
239
+ no border, no shadow, no card inset, and square corners except the one `accentCorner` names (ruling backdrop). A brand
240
+ moment among other content stays a soft `SurfaceCard`.
241
+
242
+ ### PaneGrid
243
+
244
+ A pane grid divides a bounded height into named areas (`["a b c", "d d d"]`): A, B and C side by side with D below. Panes
245
+ sit flush with no gap and one divider between neighbours (vertical between columns, horizontal between rows, n-1 lines,
246
+ none on an outer edge), all in the same border colour and weight as every other divider. Columns and rows are track roles (`auto`,
247
+ `fill`, `fill-2`, `fill-3`, `compact`, `standard`, `wide`), and `areas`, `columns` and `rows` may be given per breakpoint
248
+ (`base`, `medium` from 48rem, `wide` from 70rem), chosen by container query on the grid's own width. Each `Pane` is a
249
+ borderless surface (`surface`) or a plain div, may be its own scroll owner, and may collapse into a drawer where its
250
+ area is not arranged. It only divides the space: the pane's content is the app's (ruling pane-grid).
251
+
252
+ ### Freestyle
253
+
254
+ Freestyle is the one sanctioned escape hatch: a div that fills its host, where the app writes its own plain elements and
255
+ CSS because no Grammar component fits (a sign-in brand art, say). It adds no paint, inset or radius, names its `reason`
256
+ (stamped as `data-grammar-freestyle-reason`), and is a last resort: the rest of the page stays on the grammar, and a
257
+ Grammar component inside it keeps its contract (ruling grammar-freestyle-region).
258
+
229
259
  ### PageHeader
230
260
 
231
261
  The page header is the top of one page: the trail, the page heading (the document's one h1) with the subject's mark,
@@ -125,6 +125,7 @@ roles:
125
125
  states: [neutral, pending, PresentationState]
126
126
  grammarMayChange: [surface paint, edge (border/shadow by depth), radius via surfaceRadius, label placement inside or outside the material, the ink ground and its inks]
127
127
  dna: [DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE, DNA-COMMON-CARD-LABEL-ABOVE, DNA-COMMON-CARD-LABEL-HEADING, DNA-COMMON-LISTCARD-LABEL-OUTSIDE, DNA-COMMON-LISTCARD-LABEL-UNPAINTED, DNA-COMMON-ONE-HIGHLIGHT, DNA-COMMON-DIVIDER-FULL-BLEED, DNA-COMMON-SOFT-GROUND, DNA-COMMON-TREATMENT-TEXT-CONTRAST, DNA-CORE-EDGE-TOP, DNA-CORE-EDGE-NESTED, DNA-CORE-CARD-LABEL-OUTSIDE, DNA-OFFSET-POP-STICKER, DNA-OFFSET-POP-POCKET, DNA-OFFSET-POP-CARD-LABEL-OUTSIDE]
128
+ lint: [starci-grammar/no-raised-surface-in-surface]
128
129
 
129
130
  - id: button
130
131
  ui: ui/components/button.md
@@ -328,8 +329,44 @@ roles:
328
329
  states: ["loading (transparent, no plate)", loaded, "error (the Image's fallback)"]
329
330
  grammarMayChange: ["nothing: fit contain, the transparent ground with no plate, and the scale are Common's"]
330
331
  dna: []
332
+
333
+ - id: backdrop
334
+ ui: ui/components/backdrop.md
335
+ renderers: [Backdrop]
336
+ vendorParity: [] # no HeroUI part: a Common region
337
+ slots: ["children: the brand copy (logo, heading, tagline)", "artwork: decorative, usually a hero Mascot"]
338
+ variants:
339
+ accentCorner: { values: [start-start, start-end, end-start, end-end], chosenBy: app, meaning: "that one logical corner at --grammar-accent-corner; the others square" }
340
+ sizes: { fills: "its host's block size" }
341
+ states: []
342
+ grammarMayChange: ["nothing: the tint is the family's accentSoft, the inset and the accent radius are Common's"]
343
+ dna: [DNA-COMMON-BACKDROP-GROUND, DNA-COMMON-ACCENT-CORNER]
331
344
  lint: [starci-grammar/generated-art-in-mascot-or-media-frame, starci-grammar/mascot-asset-slot-required]
332
345
 
346
+ - id: pane-grid
347
+ ui: ui/components/pane-grid.md
348
+ renderers: [PaneGrid, Pane]
349
+ vendorParity: [Drawer]
350
+ slots: ["Pane children: the app's own elements, placed by area", "collapseLabel, openLabel, closeLabel: the drawer a collapsing pane becomes"]
351
+ variants: { surface: [true, false], scroll: [true, false], collapse: [drawer], track: [auto, fill, fill-2, fill-3, compact, standard, wide], breakpoint: [base, medium, wide] }
352
+ sizes: { fills: "its host's block and inline size" }
353
+ states: [drawer-open]
354
+ grammarMayChange: ["nothing: the grid, the dividers, the surface ground and the drawer are Common's"]
355
+ dna: []
356
+ lint: []
357
+
358
+ - id: freestyle
359
+ ui: ui/components/freestyle.md
360
+ renderers: [Freestyle]
361
+ vendorParity: [] # no HeroUI part: a Common region
362
+ slots: ["children: the app's own elements and CSS", "reason: required, why no Grammar component fits"]
363
+ variants: {}
364
+ sizes: { fills: "its host's block and inline size" }
365
+ states: []
366
+ grammarMayChange: ["nothing: it adds no paint, inset or radius"]
367
+ dna: []
368
+ lint: [starci-grammar/freestyle-has-reason]
369
+
333
370
  - id: shell
334
371
  ui: ui/composition.md
335
372
  renderers: [WorkspaceShell, TopBar, NavigationFeatureNav, Sidebar, PageContainer, PrimaryRailLayout]
@@ -643,6 +680,16 @@ mustKeep:
643
680
  - { select: '[data-grammar-surface-treatment] [data-component="Stepper"] [data-grammar-step-marker]' }
644
681
  - { select: '[data-grammar-surface-treatment] :is([data-component="Text"], [data-grammar-section-header] :is(h2, h3, p))' }
645
682
  owner: surfacecard-soft-treatment; COLOR-5; story Navigation & Data / Stepper on every treatment, Surfaces / Soft surface card
683
+ - id: DNA-COMMON-ACCENT-CORNER
684
+ role: card
685
+ law: The corner a SurfaceCard or MediaFrame names in accentCorner is drawn at the Common accent radius.
686
+ measure: { kind: style, select: '[data-grammar-accent-corner="end-end"]', metric: border-end-end-radius, op: "=", value: { token: --grammar-accent-corner } }
687
+ owner: accent-corner
688
+ - id: DNA-COMMON-BACKDROP-GROUND
689
+ role: backdrop
690
+ law: A Backdrop's ground is the family's accent-soft tint, with no border and no shadow.
691
+ measure: { kind: style, select: '[data-component="Backdrop"]', metric: background-color, op: "=", value: { token: --accent-soft } }
692
+ owner: backdrop
646
693
  # --- lists
647
694
  - id: DNA-COMMON-LIST-SEAMS
648
695
  role: list
@@ -73,7 +73,7 @@ longer drift.
73
73
  | add | `add <noun> <name>` with nouns api, webhook, realtime, saga, job, reactor, queue, projection, cli, table, app, block, composite, branch, leaf, page, layout, overlay, **service, spec, image** | FOLD `app new service|spec|image` into `app add` (both generate into an existing app and never overwrite); options a noun does not take are refused, not ignored |
74
74
  | upgrade | `upgrade [--execute]` | dry by default (today `--plan` is the dry flag and the default applies); FIX unreachable `--edition` refusal |
75
75
  | sync | `sync [--execute]` | `--check` = the default dry run (exit 1 on drift), `--write` -> `--execute`; FOLD `app sonar` (one block of one managed file) into it |
76
- | check | `check [--fast [--base]] [--staged] [--wiring] [--coverage-from] [--json]` | FOLD `app hygiene` into `app check --staged` (the pre-commit guard); gate per hfs 4.11.22: pass under 20 error findings with no hard blocker |
76
+ | check | `check [--full] [--hfs] [--format] [--db] [--secrets] [--wiring] [--types] [--lint] [--test] [--sonar] [--staged] [--coverage-from] [--json]` | FOLD `app hygiene` into `app check --staged` (the pre-commit guard); gate per hfs 4.11.22: pass under 20 error findings with no hard blocker |
77
77
  | lint | `lint [--changed ...|--workspace] [--side] [--fix] [--json] [--out <sonar file>]` | `--format json` -> `--json`; `--sonar <file>` -> `--out` |
78
78
  | slot | `slot <path> [--json]` | RENAME `app explain` (it names the slot that owns a path) |
79
79
  | emit | `emit` | drop the parsed-and-ignored `--json` |
@@ -338,7 +338,7 @@ slots:
338
338
  rule: owner ruling, every package is TypeScript source built to JavaScript (contexts/decisions/legacy-retirement.md section 3)
339
339
  - id: packages.hfs-source
340
340
  path:
341
- - "packages/hfs/{ci,codemod,coverage,db,emit,lint,release,report,scaffold,scripts,stack,sync,upgrade}/**/*.{mts,cts}"
341
+ - "packages/hfs/{cache,ci,codemod,coverage,db,emit,lint,release,report,scaffold,scripts,stack,sync,upgrade}/**/*.{mts,cts}"
342
342
  - packages/hfs/src/main.mts
343
343
  - packages/hfs/vendor-types.d.mts
344
344
  presence: optional
@@ -1680,7 +1680,7 @@ rules:
1680
1680
  - {kind: hfs, id: db-queue-cron}
1681
1681
  - id: R259
1682
1682
  code: DB_EXTENSION_ALLOWED
1683
- law: Database extensions follow the allowlist, migrations write no vault secret or role password, and destructive DDL lives only in contract migrations whose targets are unreferenced.
1683
+ law: Database extensions follow the allowlist, migrations write no vault secret or role password, and destructive DDL lives only in contract migrations whose targets are unreferenced, also by the previous release's sources.
1684
1684
  editions: [lite]
1685
1685
  failureCodes:
1686
1686
  - DB_EXTENSION_ALLOWED
@@ -1800,7 +1800,7 @@ rules:
1800
1800
  - {kind: hfs, id: doc-fresh}
1801
1801
  - id: R271
1802
1802
  code: HFS_RELEASE_TAG_MISMATCH
1803
- law: A release tag is a v-prefixed semantic version equal to the package version, images publish under it, and database deployment refuses a non-tag ref.
1803
+ law: A release tag is a v-prefixed semantic version equal to the package version, images are pushed under the immutable sha-<sha> tag with the release name as a guarded retag of that digest, and database deployment refuses a non-tag ref.
1804
1804
  failureCodes:
1805
1805
  - HFS_RELEASE_TAG_MISMATCH
1806
1806
  - HFS_DB_DEPLOY_UNGUARDED
@@ -2301,6 +2301,37 @@ rules:
2301
2301
  - FE_MASCOT_ASSET_SLOT_MISSING
2302
2302
  enforcers:
2303
2303
  - {kind: eslint-grammar-core, id: mascot-asset-slot-required}
2304
+ - id: R340
2305
+ code: FE_RAISED_SURFACE_IN_SURFACE
2306
+ law: A Grammar surface that accepts a depth prop (SurfaceListCard) does not pass depth="top" when a SurfaceCard, SurfaceListCard or SurfaceAccordionCard of the same file encloses it; a nested surface is subordinate (outlined, BOUNDARY-5), never raised again (BOUNDARY-6, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE), and the Grammar resolves the depth from the surface context. A depth computed at run time is not judged.
2307
+ failureCodes:
2308
+ - FE_RAISED_SURFACE_IN_SURFACE
2309
+ enforcers:
2310
+ - {kind: eslint-grammar-core, id: no-raised-surface-in-surface}
2311
+ - id: R341
2312
+ code: FE_FREESTYLE_REASON_MISSING
2313
+ law: A Grammar Freestyle region, the one sanctioned place where an app writes its own plain elements and CSS because no Grammar component fits, names its reason, a non-empty string literal saying why. The rules that judge hand-written elements, classes, styles and generated art leave the raw elements of a Freestyle subtree alone; a Grammar component inside it is judged as before. An element with a spread attribute is not judged.
2314
+ failureCodes:
2315
+ - FE_FREESTYLE_REASON_MISSING
2316
+ enforcers:
2317
+ - {kind: eslint-grammar-core, id: freestyle-has-reason}
2318
+ - id: R342
2319
+ code: BE_ENTITY_EXTENDS_BASE
2320
+ law: "An @Entity class does not repeat the columns every table shares: a database-set created_at or updated_at (CreateDateColumn, UpdateDateColumn, or a Column on those names with insert false, update false or a default) and, beside both, the generated uuid id are inherited from AbstractEntity or UuidAbstractEntity of @modules/platform/database (BE-PERSISTENCE-3, ruling entity-base). A table whose timestamps the application sets, or that lacks one, extends nothing; the base file platform/database/abstract.entity.ts is exempt."
2321
+ failureCodes:
2322
+ - BE_ENTITY_EXTENDS_BASE
2323
+ enforcers:
2324
+ - {kind: eslint-be, id: entity-extends-base}
2325
+
2326
+ - id: R343
2327
+ code: HFS_CHECK_CACHE_FORGED
2328
+ law: An app's committed check cache (.starcistacks/cache/) is trusted in CI only as it stands at the trusted base; a record whose key matches the tree and whose findings differ from the inherited or computed result is HFS_CHECK_CACHE_FORGED (a hard blocker at any count), a touched key without a current record is HFS_CHECK_CACHE_STALE and a missing cache is HFS_CHECK_CACHE_MISSING (both report-only warnings).
2329
+ failureCodes:
2330
+ - HFS_CHECK_CACHE_FORGED
2331
+ - HFS_CHECK_CACHE_STALE
2332
+ - HFS_CHECK_CACHE_MISSING
2333
+ enforcers:
2334
+ - {kind: hfs, id: check-cache}
2304
2335
 
2305
2336
  # Owner section. The gaps `starci contexts anatomy` (its dry run) takes as pending instead of red: a slot rule code no rule carries
2306
2337
  # (slot-rule-unknown), a rule with no enforcer (rule-no-enforcer) or only planned ones (rule-enforcer-planned). Each entry is
@@ -4,7 +4,7 @@
4
4
  # factories, the architecture machine and templates read this file; none hardcodes a path. Field meanings and the
5
5
  # ruleParams keys are explained in hfs/README.md; the reason for a slot's shape is its pattern topic.
6
6
  schema: starci/hfs-slots@3
7
- version: 3.14.0
7
+ version: 3.15.0
8
8
  presenceValues:
9
9
  - required
10
10
  - optional
@@ -1006,14 +1006,17 @@ slots:
1006
1006
  - id: app.ci-db
1007
1007
  profiles:
1008
1008
  - app
1009
- editionWhy: lite manages its database deploy workflow (starci app db migrate); full owns an optional
1010
- provider-specific workflow.
1009
+ editionWhy: a lite app migrates in the migrate phase of its stack deploy, so its database deploy workflow is
1010
+ retired (starci app sync --execute removes it); full owns an optional provider-specific workflow.
1011
1011
  path: .github/workflows/db-deploy.yml
1012
1012
  presence: optional
1013
+ litePresence: forbidden
1013
1014
  tracked: tracked
1014
1015
  tier: none
1015
1016
  tests: none
1016
- liteManagedBy: ci-workflows-lite
1017
+ goesTo: "the stack deploy: starci app stack deploy takes a verified backup, applies the expand migrations
1018
+ before the services update and the contract migrations after the accept (a full app keeps its own optional
1019
+ workflow)"
1017
1020
  rules:
1018
1021
  - HFS_MANAGED_FILE_DRIFT
1019
1022
  - id: app.ci-stack-deploy
@@ -1419,6 +1422,21 @@ slots:
1419
1422
  tests: none
1420
1423
  rules:
1421
1424
  - HFS_MANAGED_FILE_DRIFT
1425
+ - id: app.starcistacks.cache
1426
+ profiles:
1427
+ - app
1428
+ path: .starcistacks/cache/
1429
+ presence: optional
1430
+ tracked: tracked
1431
+ tier: none
1432
+ tests: none
1433
+ allows:
1434
+ - fingerprint.jsonl
1435
+ - check/**
1436
+ - lint/**
1437
+ - test-coverage/**
1438
+ - sonar-baseline/**
1439
+ - codecov-baseline/**
1422
1440
  - id: app.db.bootstrap
1423
1441
  profiles:
1424
1442
  - app
@@ -76,6 +76,8 @@ Work record .starciwork record: what must be true (fr, br, sds, contrac
76
76
  | [anatomy.md](anatomy.md) | the tree of an app root and its sides, and what each part is for; its generated slices `anatomy-<edition>-<side>.md` (the app root and one side of one edition) are what a task of that side reads |
77
77
  | [index.md](index.md) | generated: every file of `contexts/` with its size, first sentence, sections and ids, which a Kernel reads instead of the whole tree |
78
78
  | [lint.md](lint.md) | each canon package and gate: where it applies and what kind of fact it enforces; the facts no machine checks yet |
79
+ | [check-cache.md](check-cache.md) | the committed result cache in `.starcistacks/cache/` (proposed): when a run is full or incremental on a host and in CI, the fingerprint, trust, which step reuses what |
80
+ | [cicd.md](cicd.md) | the delivery pipeline every app's `.github/` gets (proposed): triggers, checks, one attested image build, the automatic Swarm deploy with migrations, verification and rollback, records, gates |
79
81
  | [stacks.md](stacks.md) | how an app runs: the `.starcistacks/` shape against project values, the dev and vps environments, ingress, sealed custody, the operations with their safety rules, local-run rules |
80
82
  | [work.md](work.md) | the `.starciwork` record families, their state, who writes what, UAT flows and evidence |
81
83
  | [lite.md](lite.md) | only what the lite edition does differently (backing services, patterns, infrastructure, deploy targets, CI, Work), each linked to its owner |
@@ -42,6 +42,7 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
42
42
  - `{be,fe}/` — **app.sides** required
43
43
  - `.starciwork/` — **app.starciwork** required · HFS_AGENT_DATA_TRACKED (no rule), HFS_IDENTITY_CUSTODY (no rule)
44
44
  - `.starcistacks/` — **app.starcistacks** required · R10, R01, R06, HFS_IDENTITY_CUSTODY (no rule)
45
+ - `cache/` — **app.starcistacks.cache** optional
45
46
  - `.sops.yaml` — **app.sops** required
46
47
 
47
48
  Git-ignored: `app.build-output`.
@@ -42,6 +42,7 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
42
42
  - `{be,fe}/` — **app.sides** required
43
43
  - `.starciwork/` — **app.starciwork** required · HFS_AGENT_DATA_TRACKED (no rule), HFS_IDENTITY_CUSTODY (no rule)
44
44
  - `.starcistacks/` — **app.starcistacks** required · R10, R01, R06, HFS_IDENTITY_CUSTODY (no rule)
45
+ - `cache/` — **app.starcistacks.cache** optional
45
46
  - `.sops.yaml` — **app.sops** required
46
47
 
47
48
  Git-ignored: `app.build-output`.
@@ -24,7 +24,6 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
24
24
  - `workflows/`
25
25
  - `ci.yml` — **app.ci** required · R13, R05, HFS_CI_E2E_AUTOMATIC (no rule)
26
26
  - `images.yml` — **app.ci-images** required · R05
27
- - `db-deploy.yml` — **app.ci-db** optional · R05
28
27
  - `stack-deploy.yml` — **app.ci-stack-deploy** optional · R05
29
28
  - `stack-key-restore.yml` — **app.ci-stack-key-restore** optional · R05
30
29
  - `<app>-deploy.yml` — **app.ci-deploy** optional · R06
@@ -41,6 +40,7 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
41
40
  - `.starciwork/` — **app.starciwork** optional · HFS_AGENT_DATA_TRACKED (no rule), HFS_IDENTITY_CUSTODY (no rule)
42
41
  - `.starcistacks/` — **app.starcistacks** required · R10, R01, R06, HFS_IDENTITY_CUSTODY (no rule)
43
42
  - `images/db/Dockerfile` — **app.db.image** required · R05
43
+ - `cache/` — **app.starcistacks.cache** optional
44
44
  - `.sops.yaml` — **app.sops** required
45
45
  - `db/` — **app.db** required
46
46
  - `migrations/`
@@ -50,7 +50,7 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
50
50
  - `bootstrap.sql` — **app.db.bootstrap** required · R05
51
51
 
52
52
  Git-ignored: `app.build-output`.
53
- Refused (forbidden or external): `app.tool-config-local`, `app.ci-e2e`, `app.browser`, `app.browser-config`, `app.tool-cache`, `app.agent-output`, `app.worktrees`, `app.plaintext-env`.
53
+ Refused (forbidden or external): `app.tool-config-local`, `app.ci-e2e`, `app.ci-db`, `app.browser`, `app.browser-config`, `app.tool-cache`, `app.agent-output`, `app.worktrees`, `app.plaintext-env`.
54
54
 
55
55
  ### lite · be/
56
56
 
@@ -24,7 +24,6 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
24
24
  - `workflows/`
25
25
  - `ci.yml` — **app.ci** required · R13, R05, HFS_CI_E2E_AUTOMATIC (no rule)
26
26
  - `images.yml` — **app.ci-images** required · R05
27
- - `db-deploy.yml` — **app.ci-db** optional · R05
28
27
  - `stack-deploy.yml` — **app.ci-stack-deploy** optional · R05
29
28
  - `stack-key-restore.yml` — **app.ci-stack-key-restore** optional · R05
30
29
  - `<app>-deploy.yml` — **app.ci-deploy** optional · R06
@@ -41,6 +40,7 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
41
40
  - `.starciwork/` — **app.starciwork** optional · HFS_AGENT_DATA_TRACKED (no rule), HFS_IDENTITY_CUSTODY (no rule)
42
41
  - `.starcistacks/` — **app.starcistacks** required · R10, R01, R06, HFS_IDENTITY_CUSTODY (no rule)
43
42
  - `images/db/Dockerfile` — **app.db.image** required · R05
43
+ - `cache/` — **app.starcistacks.cache** optional
44
44
  - `.sops.yaml` — **app.sops** required
45
45
  - `db/` — **app.db** required
46
46
  - `migrations/`
@@ -50,7 +50,7 @@ lint rule or gate enforces a rule is in anatomy.md's tree and the rule's page (`
50
50
  - `bootstrap.sql` — **app.db.bootstrap** required · R05
51
51
 
52
52
  Git-ignored: `app.build-output`.
53
- Refused (forbidden or external): `app.tool-config-local`, `app.ci-e2e`, `app.browser`, `app.browser-config`, `app.tool-cache`, `app.agent-output`, `app.worktrees`, `app.plaintext-env`.
53
+ Refused (forbidden or external): `app.tool-config-local`, `app.ci-e2e`, `app.ci-db`, `app.browser`, `app.browser-config`, `app.tool-cache`, `app.agent-output`, `app.worktrees`, `app.plaintext-env`.
54
54
 
55
55
  ### lite · fe/
56
56
 
@@ -63,7 +63,6 @@ Change a slot, a rule or a pattern's front matter, then regenerate in the same c
63
63
  - `workflows/`
64
64
  - `ci.yml` — **app.ci** required · R13 (machine `hooks-path-not-redirected`; hfs `ci-missing-canon`), R05 (hfs `managed-file-drift`), HFS_CI_E2E_AUTOMATIC (no rule)
65
65
  - `images.yml` — **app.ci-images** required · R05 (hfs `managed-file-drift`)
66
- - `db-deploy.yml` — **app.ci-db** optional · R05 (hfs `managed-file-drift`)
67
66
  - `stack-deploy.yml` — **app.ci-stack-deploy** optional · R05 (hfs `managed-file-drift`)
68
67
  - `stack-key-restore.yml` — **app.ci-stack-key-restore** optional · R05 (hfs `managed-file-drift`)
69
68
  - `<app>-deploy.yml` — **app.ci-deploy** optional · R06 (hfs `plaintext-secret` `plaintext-secret-staged`)
@@ -80,6 +79,7 @@ Change a slot, a rule or a pattern's front matter, then regenerate in the same c
80
79
  - `.starciwork/` — **app.starciwork** optional · HFS_AGENT_DATA_TRACKED (no rule), HFS_IDENTITY_CUSTODY (no rule)
81
80
  - `.starcistacks/` — **app.starcistacks** required · R10 (hfs `stacks-shape` `stacks-runtime` `stacks-evidence-runtime` `starcistacks-runtime` `starcistacks-runtime-gate`), R01 (hfs `slot-undeclared`; eslint-be `slot-undeclared`; eslint-fe `slot-undeclared`; machine `repository-tree-layout`), R06 (hfs `plaintext-secret` `plaintext-secret-staged`), HFS_IDENTITY_CUSTODY (no rule)
82
81
  - `images/db/Dockerfile` — **app.db.image** required · R05 (hfs `managed-file-drift`)
82
+ - `cache/` — **app.starcistacks.cache** optional
83
83
  - `.sops.yaml` — **app.sops** required
84
84
  - `db/` — **app.db** required
85
85
  - `migrations/`
@@ -89,7 +89,7 @@ Change a slot, a rule or a pattern's front matter, then regenerate in the same c
89
89
  - `bootstrap.sql` — **app.db.bootstrap** required · R05 (hfs `managed-file-drift`)
90
90
 
91
91
  Git-ignored: `app.build-output`.
92
- Refused (forbidden or external): `app.tool-config-local`, `app.ci-e2e`, `app.browser`, `app.browser-config`, `app.tool-cache`, `app.agent-output`, `app.worktrees`, `app.plaintext-env`.
92
+ Refused (forbidden or external): `app.tool-config-local`, `app.ci-e2e`, `app.ci-db`, `app.browser`, `app.browser-config`, `app.tool-cache`, `app.agent-output`, `app.worktrees`, `app.plaintext-env`.
93
93
 
94
94
  ### lite · be/
95
95
 
@@ -261,6 +261,7 @@ Refused (forbidden or external): `repo.side-root-forbidden`, `fe.tool-config-loc
261
261
  - `{be,fe}/` — **app.sides** required
262
262
  - `.starciwork/` — **app.starciwork** required · HFS_AGENT_DATA_TRACKED (no rule), HFS_IDENTITY_CUSTODY (no rule)
263
263
  - `.starcistacks/` — **app.starcistacks** required · R10 (hfs `stacks-shape` `stacks-runtime` `stacks-evidence-runtime` `starcistacks-runtime` `starcistacks-runtime-gate`), R01 (hfs `slot-undeclared`; eslint-be `slot-undeclared`; eslint-fe `slot-undeclared`; machine `repository-tree-layout`), R06 (hfs `plaintext-secret` `plaintext-secret-staged`), HFS_IDENTITY_CUSTODY (no rule)
264
+ - `cache/` — **app.starcistacks.cache** optional
264
265
  - `.sops.yaml` — **app.sops** required
265
266
 
266
267
  Git-ignored: `app.build-output`.