coentrify 0.0.1 → 0.1.0

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 (261) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +5 -4
  3. package/bin/coentrify.js +79 -12
  4. package/package.json +3 -2
  5. package/src/changelog/0.0.1.md +259 -0
  6. package/src/changelog/0.0.2.md +219 -0
  7. package/src/changelog/0.0.3.md +81 -0
  8. package/src/changelog/0.0.4.md +198 -0
  9. package/src/changelog/0.0.5.md +160 -0
  10. package/src/changelog/0.0.6.md +282 -0
  11. package/src/changelog/0.0.7.md +113 -0
  12. package/src/changelog/0.0.8.md +212 -0
  13. package/src/changelog/0.1.0.md +9 -0
  14. package/src/changelog/overview.md +13 -0
  15. package/src/coentrify-json.md +72 -0
  16. package/src/commands.md +48 -0
  17. package/src/glossary.md +132 -0
  18. package/src/how-it-works.md +51 -0
  19. package/src/onboarding.md +140 -0
  20. package/src/origin.md +19 -0
  21. package/src/philosophy.md +99 -0
  22. package/src/proof.md +596 -0
  23. package/src/readme.md +76 -0
  24. package/src/recommendations.md +100 -0
  25. package/src/standards/ai/match-known-commands-deterministically-classify-the-rest.md +22 -0
  26. package/src/standards/ai/overview.md +6 -0
  27. package/src/standards/ai/prompt-small-models-differently.md +21 -0
  28. package/src/standards/angular/canmatch-wildcard-for-route-access.md +22 -0
  29. package/src/standards/angular/interface-not-abstract-class-for-mock-swap.md +37 -0
  30. package/src/standards/angular/no-any-in-templates.md +25 -0
  31. package/src/standards/angular/no-inline-templates.md +14 -0
  32. package/src/standards/angular/one-component-per-folder-flat.md +12 -0
  33. package/src/standards/angular/one-projected-node-per-control-flow-block.md +19 -0
  34. package/src/standards/angular/overview.md +16 -0
  35. package/src/standards/angular/prefer-content-projection-over-props-angular.md +17 -0
  36. package/src/standards/angular/projected-content-is-never-styled-by-the-host.md +23 -0
  37. package/src/standards/angular/static-attribute-not-literal-binding.md +23 -0
  38. package/src/standards/angular/track-timed-items-by-an-id.md +17 -0
  39. package/src/standards/angular/ui-copy-in-template.md +26 -0
  40. package/src/standards/angular/use-modern-angular-template-apis.md +20 -0
  41. package/src/standards/architecture/adopt-configure-override.md +25 -0
  42. package/src/standards/architecture/app-shield.md +57 -0
  43. package/src/standards/architecture/converge-only-once-proven.md +22 -0
  44. package/src/standards/architecture/folder-concerns.md +28 -0
  45. package/src/standards/architecture/overview.md +11 -0
  46. package/src/standards/architecture/per-application-split-over-shared-branching.md +25 -0
  47. package/src/standards/architecture/separation-before-layer-standards.md +17 -0
  48. package/src/standards/architecture/unique-where-it-counts.md +19 -0
  49. package/src/standards/behavior/a-go-before-work-elsewhere.md +17 -0
  50. package/src/standards/behavior/a-maybe-is-a-trigger-to-investigate.md +20 -0
  51. package/src/standards/behavior/a-name-describes-its-unit.md +19 -0
  52. package/src/standards/behavior/a-quiet-tree-while-a-suite-runs.md +19 -0
  53. package/src/standards/behavior/always-make-no-mistakes.md +45 -0
  54. package/src/standards/behavior/always-verify-before-reporting-done.md +18 -0
  55. package/src/standards/behavior/always-work-from-a-plan.md +29 -0
  56. package/src/standards/behavior/anchor-edits-after-formatting.md +17 -0
  57. package/src/standards/behavior/backward-trace-missing-prerequisites.md +20 -0
  58. package/src/standards/behavior/code-review-compounds-into-patterns-and-sweeps.md +21 -0
  59. package/src/standards/behavior/communication-boundary.md +18 -0
  60. package/src/standards/behavior/dev-tiers.md +25 -0
  61. package/src/standards/behavior/docs-hold-only-what-the-director-decided.md +23 -0
  62. package/src/standards/behavior/dont-filter-data-without-a-spec.md +20 -0
  63. package/src/standards/behavior/dont-introduce-tech-debt.md +25 -0
  64. package/src/standards/behavior/feature-workflow.md +31 -0
  65. package/src/standards/behavior/file-a-change-with-coentrify.md +24 -0
  66. package/src/standards/behavior/flag-every-addition-of-your-own.md +22 -0
  67. package/src/standards/behavior/free-text-replies-no-buttons.md +20 -0
  68. package/src/standards/behavior/general-working-rules.md +37 -0
  69. package/src/standards/behavior/non-destructive-documenting-and-test-automation.md +20 -0
  70. package/src/standards/behavior/normal-dashes.md +15 -0
  71. package/src/standards/behavior/note-issues.md +26 -0
  72. package/src/standards/behavior/overview.md +46 -0
  73. package/src/standards/behavior/own-ports-own-processes.md +37 -0
  74. package/src/standards/behavior/project-lifecycle.md +21 -0
  75. package/src/standards/behavior/propagate-renames-and-convention-changes-everywhere.md +16 -0
  76. package/src/standards/behavior/prose-style.md +24 -0
  77. package/src/standards/behavior/prototype-mode-is-speed-first.md +20 -0
  78. package/src/standards/behavior/regular-layered-gap-analysis.md +20 -0
  79. package/src/standards/behavior/reload-the-standards-after-compacting.md +16 -0
  80. package/src/standards/behavior/review-changes-before-reporting-done.md +17 -0
  81. package/src/standards/behavior/review-every-capture-before-reporting.md +21 -0
  82. package/src/standards/behavior/standards-maintenance.md +65 -0
  83. package/src/standards/behavior/standards-over-skills.md +17 -0
  84. package/src/standards/behavior/sweeps-enumerate-into-tech-debt-first.md +20 -0
  85. package/src/standards/behavior/sync-the-docs-after-every-change.md +20 -0
  86. package/src/standards/behavior/the-quality-of-the-question.md +17 -0
  87. package/src/standards/behavior/things-of-one-kind-are-consistent.md +20 -0
  88. package/src/standards/behavior/understand-the-need.md +69 -0
  89. package/src/standards/behavior/use-us-english-everywhere.md +17 -0
  90. package/src/standards/behavior/verify-apis-against-docs-and-the-installed-artifact.md +17 -0
  91. package/src/standards/behavior/verify-control-before-rename.md +11 -0
  92. package/src/standards/code/code-principles.md +32 -0
  93. package/src/standards/code/escape-hatch-comments.md +20 -0
  94. package/src/standards/code/name-by-concept-not-copy.md +20 -0
  95. package/src/standards/code/no-abbreviated-names.md +20 -0
  96. package/src/standards/code/no-describe-what-comments.md +26 -0
  97. package/src/standards/code/overview.md +10 -0
  98. package/src/standards/code/pre-empt-recurring-code-review-nits.md +31 -0
  99. package/src/standards/commits/commits.md +44 -0
  100. package/src/standards/commits/gate-commits-on-exit-codes.md +22 -0
  101. package/src/standards/commits/main-stays-green-work-stays-clean.md +23 -0
  102. package/src/standards/commits/overview.md +8 -0
  103. package/src/standards/commits/verify-staging-before-committing.md +29 -0
  104. package/src/standards/docs/application-template.md +89 -0
  105. package/src/standards/docs/docs-are-hierarchical-explicit-and-short.md +48 -0
  106. package/src/standards/docs/docs-describe-behavior-not-wiring.md +24 -0
  107. package/src/standards/docs/docs-folder-structure.md +38 -0
  108. package/src/standards/docs/docs-state-knowledge.md +23 -0
  109. package/src/standards/docs/documentation-philosophy.md +62 -0
  110. package/src/standards/docs/feature-spec-template.md +89 -0
  111. package/src/standards/docs/feature-template.md +62 -0
  112. package/src/standards/docs/file-names.md +20 -0
  113. package/src/standards/docs/glossary.md +18 -0
  114. package/src/standards/docs/library-feedback.md +20 -0
  115. package/src/standards/docs/no-faux-headers-in-lists.md +18 -0
  116. package/src/standards/docs/overview.md +20 -0
  117. package/src/standards/docs/ui-vocabulary.md +31 -0
  118. package/src/standards/docs/workspace-levels.md +24 -0
  119. package/src/standards/docs/workspace-suite.md +24 -0
  120. package/src/standards/docs/workspace-template.md +41 -0
  121. package/src/standards/e2e/e2e-assert-before-interacting.md +21 -0
  122. package/src/standards/e2e/e2e-mock-contract.md +20 -0
  123. package/src/standards/e2e/e2e-runs-on-the-development-build.md +18 -0
  124. package/src/standards/e2e/e2e-test-conventions.md +61 -0
  125. package/src/standards/e2e/e2e-tests-must-demonstrate-behavior.md +28 -0
  126. package/src/standards/e2e/one-check-for-many-canvas-clicks.md +17 -0
  127. package/src/standards/e2e/overview.md +14 -0
  128. package/src/standards/e2e/per-feature-overview-test.md +30 -0
  129. package/src/standards/e2e/real-input-for-frame-races.md +25 -0
  130. package/src/standards/e2e/substring-locator-collisions.md +23 -0
  131. package/src/standards/e2e/use-the-e2e-pipeline-for-browser-probing.md +18 -0
  132. package/src/standards/electron/electron-packaging-and-suite.md +22 -0
  133. package/src/standards/electron/electron-shell-shape.md +21 -0
  134. package/src/standards/electron/overview.md +6 -0
  135. package/src/standards/gamedev/2d-visual-design.md +22 -0
  136. package/src/standards/gamedev/budget-exceptions.json +6 -0
  137. package/src/standards/gamedev/captures-and-reels.md +39 -0
  138. package/src/standards/gamedev/devbox.md +21 -0
  139. package/src/standards/gamedev/game-design-laws-experience.md +68 -0
  140. package/src/standards/gamedev/game-design-laws-guidance.md +43 -0
  141. package/src/standards/gamedev/game-design-laws-own-style.md +33 -0
  142. package/src/standards/gamedev/game-design-laws-progress.md +54 -0
  143. package/src/standards/gamedev/game-design-laws-quality.md +30 -0
  144. package/src/standards/gamedev/game-design-laws-story.md +45 -0
  145. package/src/standards/gamedev/game-design-laws-ui.md +52 -0
  146. package/src/standards/gamedev/game-design-laws-world.md +38 -0
  147. package/src/standards/gamedev/game-design-laws.md +112 -0
  148. package/src/standards/gamedev/game-phases-concept.md +29 -0
  149. package/src/standards/gamedev/game-phases-design.md +39 -0
  150. package/src/standards/gamedev/game-phases-development.md +30 -0
  151. package/src/standards/gamedev/game-phases-live.md +19 -0
  152. package/src/standards/gamedev/game-phases.md +52 -0
  153. package/src/standards/gamedev/game-work-workflow.md +47 -0
  154. package/src/standards/gamedev/gamedev-working-cadence.md +52 -0
  155. package/src/standards/gamedev/incremental-pacing.md +22 -0
  156. package/src/standards/gamedev/launch-strategy.md +50 -0
  157. package/src/standards/gamedev/measure-sound-never-guess.md +24 -0
  158. package/src/standards/gamedev/overview.md +29 -0
  159. package/src/standards/gamedev/own-icons.md +19 -0
  160. package/src/standards/gamedev/silent-runs.md +26 -0
  161. package/src/standards/gamedev/sprite-sheet-frames.md +23 -0
  162. package/src/standards/overview.md +43 -0
  163. package/src/standards/records/activity-log.md +33 -0
  164. package/src/standards/records/changelog-per-version.md +43 -0
  165. package/src/standards/records/healing-log.md +23 -0
  166. package/src/standards/records/overview.md +10 -0
  167. package/src/standards/records/playtest-files.md +38 -0
  168. package/src/standards/records/request-log.md +30 -0
  169. package/src/standards/records/user-test-files.md +21 -0
  170. package/src/standards/reporting/change-report.md +43 -0
  171. package/src/standards/reporting/overview.md +6 -0
  172. package/src/standards/reporting/reels-and-video-proof.md +32 -0
  173. package/src/standards/scripts/no-npx-in-scripts.md +20 -0
  174. package/src/standards/scripts/npm-script-naming.md +43 -0
  175. package/src/standards/scripts/overview.md +7 -0
  176. package/src/standards/scripts/thin-wrappers-in-ci-and-hooks.md +25 -0
  177. package/src/standards/security/keep-personal-data-out-of-requests.md +16 -0
  178. package/src/standards/security/keep-secrets-away-from-agents.md +21 -0
  179. package/src/standards/security/never-access-the-keychain.md +16 -0
  180. package/src/standards/security/overview.md +7 -0
  181. package/src/standards/simple-workflow/bugs-template.md +38 -0
  182. package/src/standards/simple-workflow/overview.md +12 -0
  183. package/src/standards/simple-workflow/plan-template.md +50 -0
  184. package/src/standards/simple-workflow/plans-vs-persistent-files.md +31 -0
  185. package/src/standards/simple-workflow/remove-completed-items-from-docs.md +19 -0
  186. package/src/standards/simple-workflow/roadmap-template.md +41 -0
  187. package/src/standards/simple-workflow/technical-debt-template.md +44 -0
  188. package/src/standards/simple-workflow/the-simple-workflow.md +48 -0
  189. package/src/standards/simple-workflow/todo-template.md +31 -0
  190. package/src/standards/tests/a-bugs-test-reproduces-with-real-input.md +18 -0
  191. package/src/standards/tests/bracket-state-changes-with-contrast-assertions.md +37 -0
  192. package/src/standards/tests/gestures-in-tests.md +35 -0
  193. package/src/standards/tests/implementation-agnostic-assertions.md +20 -0
  194. package/src/standards/tests/implementation-agnostic-locators.md +18 -0
  195. package/src/standards/tests/overview.md +13 -0
  196. package/src/standards/tests/realistic-test-data-variance.md +24 -0
  197. package/src/standards/tests/seed-surfaces-every-state-on-page-1.md +17 -0
  198. package/src/standards/tests/test-design.md +47 -0
  199. package/src/standards/tests/test-the-system-behind-a-mock.md +21 -0
  200. package/src/standards/tickets-workflow/agent-roles.md +54 -0
  201. package/src/standards/tickets-workflow/budget-exceptions.json +6 -0
  202. package/src/standards/tickets-workflow/building-a-ticket.md +47 -0
  203. package/src/standards/tickets-workflow/overview.md +15 -0
  204. package/src/standards/tickets-workflow/stabilize-before-adding.md +18 -0
  205. package/src/standards/tickets-workflow/the-builder.md +28 -0
  206. package/src/standards/tickets-workflow/the-conductor.md +44 -0
  207. package/src/standards/tickets-workflow/the-done-part.md +23 -0
  208. package/src/standards/tickets-workflow/ticket-template.md +96 -0
  209. package/src/standards/tickets-workflow/work-item-names.md +30 -0
  210. package/src/standards/tickets-workflow/work-tracking.md +177 -0
  211. package/src/standards/tickets-workflow/work-workflow.md +123 -0
  212. package/src/standards/tickets-workflow/writing-a-ticket.md +50 -0
  213. package/src/standards/tooling/browser-captures-go-to-disk.md +20 -0
  214. package/src/standards/tooling/check-where-a-pane-click-landed.md +19 -0
  215. package/src/standards/tooling/defer-tooling-until-the-cost-shows-up.md +19 -0
  216. package/src/standards/tooling/develop-against-mocks.md +19 -0
  217. package/src/standards/tooling/hygiene-tests-run-on-their-own-runner.md +18 -0
  218. package/src/standards/tooling/lightweight-test-reporting-only.md +16 -0
  219. package/src/standards/tooling/node-versions.md +24 -0
  220. package/src/standards/tooling/overview.md +17 -0
  221. package/src/standards/tooling/parallel-agents.md +45 -0
  222. package/src/standards/tooling/playwright-parallel-runs.md +30 -0
  223. package/src/standards/tooling/playwright-video-recording.md +32 -0
  224. package/src/standards/tooling/read-before-you-truncate.md +19 -0
  225. package/src/standards/tooling/start-playwright-on-a-clean-port.md +22 -0
  226. package/src/standards/tooling/vitepress-wiki.md +38 -0
  227. package/src/standards/typescript/always-add-explicit-types.md +32 -0
  228. package/src/standards/typescript/barrel-imports.md +21 -0
  229. package/src/standards/typescript/no-magic-values.md +52 -0
  230. package/src/standards/typescript/one-artifact-per-file.md +19 -0
  231. package/src/standards/typescript/overview.md +8 -0
  232. package/src/standards/ui/communicate-state.md +21 -0
  233. package/src/standards/ui/never-obscure-information-the-user-needs.md +26 -0
  234. package/src/standards/ui/overview.md +16 -0
  235. package/src/standards/ui/pixel-perfect-design-check.md +22 -0
  236. package/src/standards/ui/ui-component-design.md +34 -0
  237. package/src/standards/ui/ui-components-first.md +25 -0
  238. package/src/standards/ui/ui-layout-via-slot-composition.md +33 -0
  239. package/src/standards/ui/ui-library-is-domain-agnostic.md +20 -0
  240. package/src/standards/ui/ui-refactor-preserve-dont-redesign.md +25 -0
  241. package/src/standards/ui/ui-styleguide.md +30 -0
  242. package/src/standards/ui/ui-variants-by-function-not-by-color.md +23 -0
  243. package/src/standards/ui/validation-errors-fire-on-submit.md +20 -0
  244. package/src/standards/ui/walk-the-users-journey.md +29 -0
  245. package/src/standards/web/always-use-design-tokens-for-colors.md +24 -0
  246. package/src/standards/web/dark-mode-through-tokens.md +19 -0
  247. package/src/standards/web/hidden-attribute-loses-to-display.md +22 -0
  248. package/src/standards/web/overview.md +9 -0
  249. package/src/standards/web/scss-shared-partial-imports.md +16 -0
  250. package/src/standards/web/transitions-only-on-user-toggle.md +19 -0
  251. package/src/standards.md +66 -0
  252. package/src/tools/overview.md +22 -0
  253. package/src/tools/scripts/coentrify-update.py +242 -0
  254. package/src/tools/scripts/unlink-missing-standards.py +138 -0
  255. package/src/tools/specs/changelog-append.md +15 -0
  256. package/src/tools/specs/coentrify-json-check.md +21 -0
  257. package/src/tools/specs/commit-gate.md +32 -0
  258. package/src/tools/specs/healing-append.md +15 -0
  259. package/src/tools/specs/landing.md +29 -0
  260. package/src/tools/specs/refuse-wrap-up-questions.md +22 -0
  261. package/src/tools/specs/reload-core-rules.md +20 -0
@@ -0,0 +1,62 @@
1
+ # Feature Template
2
+
3
+ Per-feature functional docs follow the hierarchical page shape: summary, contents, a heading per item, aesthetics.
4
+
5
+ ## Purpose
6
+
7
+ The functional source of truth for a single feature, the product as decided: a reader should grasp what the feature does. Basis for the spec, the e2e tests and the feature's tickets. Pairs with a [spec](feature-spec-template.md).
8
+
9
+ ## Why
10
+
11
+ A feature doc stays true while the code changes.
12
+
13
+ ## Sections
14
+
15
+ - Title: `# <Feature Name>` in Title Case.
16
+ - The summary is no link hub. Cross-references go inline where the related concept is mentioned.
17
+ - Item headings are short Title Case noun phrases ("Profile", "Search"). Under each: one short sentence per thing it does ("Shows the orders the user placed"), each a spec that leads to a test.
18
+ - `## Edge Cases`: rules that fall out of the feature's boundaries with other features or contexts. `###` per edge case when needed.
19
+ - A part not built yet carries `(Not Yet Implemented)` and a link to its ticket.
20
+ - Optional closing pointer to the matching spec.
21
+
22
+ ## Files
23
+
24
+ - A simple feature is one file, `docs/features/<feature>.md`, with its spec beside it as `<feature>.spec.md`.
25
+ - A feature whose items have pages of their own is a folder, `docs/features/<feature>/`, with `overview.md` as the feature's page, a page per item and its spec beside them.
26
+
27
+ ## Content Rules
28
+
29
+ - Order items logically: broad-to-specific (universal rules first, item-specific after) and cause-before-effect (trigger before effect).
30
+ - One feature = one feature doc. Behaviors that belong to a sibling feature live in that feature's own doc. Reference, don't duplicate.
31
+ - Skip baselines that aren't specific to the feature (e.g. "code is accessible") - they're quality bars, not features.
32
+ - Skip generic interaction patterns - submit buttons, validation and error states, toasts, loaders. A feature-specific constraint (e.g. "email must be a company address") is still a property. The generic mechanics around it are not.
33
+
34
+ ## Use Cases Live In The Spec
35
+
36
+ Don't write use cases, scenarios, or step-by-step flows in the feature doc. They go in the spec with stable IDs. The feature doc declares. The spec verifies.
37
+
38
+ ## Functional Only
39
+
40
+ No component names, library names, CSS terms, routes, framework detail, or status codes. Use functional UI vocabulary: "menu", never "hamburger button".
41
+
42
+ No work-tracking notes either - TODOs, placeholders, "copy to follow", plan-debt. State the functional fact ("an info callout explains the impact") and track the work left to do in a ticket.
43
+
44
+ ## No UI Copy
45
+
46
+ Don't quote button labels, error messages, field labels, or any literal UI strings. Reference actions by intent ("submits the form"), not by label ("clicks Save"). The doc is in English even when the UI isn't. Literal UI strings are allowed in the spec.
47
+
48
+ ## Don't Enumerate Values
49
+
50
+ Give one example of roles, statuses or types. List a value only when it carries an edge case. A full list rots.
51
+
52
+ ## Related
53
+
54
+ - [Docs Are Hierarchical, Explicit And Short](docs-are-hierarchical-explicit-and-short.md)
55
+ - [Feature Workflow](../behavior/feature-workflow.md)
56
+ - [No Faux Headers In Lists](no-faux-headers-in-lists.md)
57
+ - [UI Vocabulary](ui-vocabulary.md)
58
+ - [Work Tracking](../tickets-workflow/work-tracking.md)
59
+ - [Normal Dashes](../behavior/normal-dashes.md)
60
+ - [Documentation Philosophy](documentation-philosophy.md)
61
+ - [Docs Folder Structure](docs-folder-structure.md)
62
+ - [Application Template](application-template.md)
@@ -0,0 +1,20 @@
1
+ # File Names
2
+
3
+ A file is named after its title, in lowercase, with a dash between the words.
4
+
5
+ ## Why
6
+
7
+ A name that follows the title can be guessed, reads well in a link, and sorts the same way the titles do.
8
+
9
+ ## How To Apply
10
+
11
+ - Use lowercase letters, and a dash between words.
12
+ - Use no spaces, underscores or capitals.
13
+ - Name the file after the title of the page: `always-work-from-a-plan.md` for Always Work From A Plan.
14
+ - Rename the file when the title changes, and update every link to it.
15
+ - A file that a tool looks for by name keeps that name, such as `AGENTS.md`.
16
+ - A file whose name a template fixes keeps it: an `overview.md`, a spec, a dated or versioned record. A ticket's file leads with its id.
17
+
18
+ ## Related
19
+
20
+ - [A Name Describes Its Unit](../behavior/a-name-describes-its-unit.md)
@@ -0,0 +1,18 @@
1
+ # Glossary
2
+
3
+ A project keeps a glossary of the terms it uses most: one entry per term, with a description in plain words.
4
+
5
+ ## Why
6
+
7
+ A glossary makes the terms of a project easy to understand, and gives clarity.
8
+
9
+ ## How To Apply
10
+
11
+ - A description is plain and technical: it says what the term means, in words a reader already knows.
12
+ - A description uses another term of the project only when that term stands earlier in the glossary.
13
+ - A term that builds on another comes after it: gap stands before gap analysis.
14
+
15
+ ## Related
16
+
17
+ - [Documentation Philosophy](documentation-philosophy.md)
18
+ - [Docs Are Hierarchical, Explicit And Short](docs-are-hierarchical-explicit-and-short.md)
@@ -0,0 +1,20 @@
1
+ # Library Feedback
2
+
3
+ Friction with a library never gets a doc in the project. It is surfaced to the director in the report, or filed with a library the project contributes to, and a workaround in the code gets a why-comment where it sits ([Escape Hatch Comments](../code/escape-hatch-comments.md)).
4
+
5
+ ## Why
6
+
7
+ Feedback on a library belongs with that library, and the director has the relationship to take it there.
8
+
9
+ ## How To Apply
10
+
11
+ - The first time a friction point shows up (a missing data-testid, an unintuitive event, a bug, an API shape that forces a hack), name it in the report: the library, the friction, and the workaround if there is one.
12
+ - A workaround gets a why-comment at the code, naming the library's friction.
13
+ - Never prescribe the fix. That is the maintainer's call.
14
+ - A library the project contributes to, listed under `libraries` in `coentrify.json`, gets its friction filed at its source as an issue, one point each, the way its `filing` says ([File A Change With Coentrify](../behavior/file-a-change-with-coentrify.md)).
15
+ - What the friction costs the project in ongoing work is debt, a ticket of its own.
16
+ - Every brief to an agent that may hit library friction says so.
17
+
18
+ ## Related
19
+
20
+ - [Work Tracking](../tickets-workflow/work-tracking.md)
@@ -0,0 +1,18 @@
1
+ # No Faux Headers In Lists
2
+
3
+ Don't use **bold label** + dash + description as a fake header inside a bullet list.
4
+
5
+ ## Why
6
+
7
+ A real header gives navigation for free: a table of contents, an anchor and search.
8
+
9
+ ## How To Apply
10
+
11
+ - Short, scannable items: a flat dash list is correct.
12
+ - An item that is a heading-and-body pair (a label plus a sentence or more explaining it) becomes a `### Label` header with the body below as a paragraph.
13
+ - The test while drafting: if trimming an item's description would lose meaning, the item wants a header.
14
+
15
+ ## Related
16
+
17
+ - [Feature Template](feature-template.md)
18
+ - [Documentation Philosophy](documentation-philosophy.md)
@@ -0,0 +1,20 @@
1
+ # Overview
2
+
3
+ The Docs standards: documentation rules and templates.
4
+
5
+ - [Application Template](application-template.md) - per-app overview (users, features, views) and architecture
6
+ - [Docs Are Hierarchical, Explicit And Short](docs-are-hierarchical-explicit-and-short.md) - summary, contents with a fitting heading, a heading or page per item, name things outright
7
+ - [Docs Describe Behavior, Not Wiring](docs-describe-behavior-not-wiring.md) - describe behavior, not code wiring
8
+ - [Docs Folder Structure](docs-folder-structure.md) - root overview and architecture. Development, workspace, features. Every record under one records folder
9
+ - [Docs State Knowledge](docs-state-knowledge.md) - knowledge pages state what is true, without provenance
10
+ - [Documentation Philosophy](documentation-philosophy.md) - product-level, brief, one purpose per file, plain punctuation, reproducible from the docs
11
+ - [Feature Spec Template](feature-spec-template.md) - spec use cases with stable ids. Start state, action, confirms
12
+ - [Feature Template](feature-template.md) - a feature doc: summary, contents, a heading per item, aesthetics, edge cases. Functional only, no UI copy, use cases live in the spec
13
+ - [File Names](file-names.md) - a file is named after its title, in lowercase, with dashes
14
+ - [Glossary](glossary.md) - the terms a project uses most, one entry each, described in plain words
15
+ - [Library Feedback](library-feedback.md) - library friction is surfaced to the director in the report, or filed with a library the project contributes to, never kept as a doc in the project. A workaround gets a why-comment
16
+ - [No Faux Headers In Lists](no-faux-headers-in-lists.md) - no bold-label bullets. Promote them to headings
17
+ - [UI Vocabulary](ui-vocabulary.md) - functional UI names: drawer, sheet, never 'surface'
18
+ - [Workspace Levels](workspace-levels.md) - a maturity scale for a workspace, from unknown to suite complete
19
+ - [Workspace Suite](workspace-suite.md) - the deliverables of a complete workspace
20
+ - [Workspace Template](workspace-template.md) - workspace docs: functional overview, technical architecture, concern docs
@@ -0,0 +1,31 @@
1
+ # UI Vocabulary
2
+
3
+ Use functional names for UI patterns - terms that say what the thing does. Be consistent: one pattern, one name everywhere (prose, docs, commits, component class names).
4
+
5
+ A drawer is a drawer because of its role ("CreateUserDrawer"). Motion descriptors ("slide-in") and component-file names don't earn their keep at the product level.
6
+
7
+ ## Why
8
+
9
+ Functional names work for every reader without explaining the implementation.
10
+
11
+ ## Drawer Vs Sheet
12
+
13
+ Both are valid functional names for distinct patterns - don't collapse them into one. A panel can be a drawer on desktop and a sheet on mobile - call each by its role in that layout.
14
+
15
+ ### Drawer
16
+
17
+ Side-attached panel that opens from a screen edge (typically right or left), used alongside the main view on desktop. Example: a filter panel beside a list on desktop.
18
+
19
+ ### Sheet
20
+
21
+ Mobile-style panel that slides up from the bottom and modally covers the lower portion of the screen. Example: a filter panel on mobile.
22
+
23
+ ## Don't Use "Surface" As A UI-Area Noun
24
+
25
+ "The chat surface", "the conversation surface" - product-design jargon that reads as wordy and weirdly abstract. Use the feature's name or natural English: "the chat", "the settings screen", "in the chat". "Surface" the verb (to surface, surfaced) is fine - it means "bring up / show" and is unrelated.
26
+
27
+ ## Related
28
+
29
+ - [Things Of One Kind Are Consistent](../behavior/things-of-one-kind-are-consistent.md)
30
+ - [Docs Describe Behavior, Not Wiring](docs-describe-behavior-not-wiring.md)
31
+ - [Feature Template](feature-template.md)
@@ -0,0 +1,24 @@
1
+ # Workspace Levels
2
+
3
+ Place a workspace on a maturity scale, in the spirit of the Kardashev scale, where each level builds on the last, and push it upward.
4
+
5
+ ## Why
6
+
7
+ A level shows the director where a workspace stands, and from that what has priority. It helps an agent decide what to work on.
8
+
9
+ ## The Levels
10
+
11
+ - Level 0 - Unknown. Nobody can say what the product does, when or why.
12
+ - Level 1 - Documented. All workspace and app docs in place.
13
+ - Level 2 - Fully tested. Unit and e2e coverage in place.
14
+ - Level 3 - Primary framework on the latest release (e.g. latest Angular).
15
+ - Level 4 - Fully up to date. All dependencies current, not just the primary framework.
16
+ - Level 5 - Suite complete. Every deliverable of the [Workspace Suite](workspace-suite.md) exists and its deployment is green.
17
+
18
+ ## Tooling And The Levels
19
+
20
+ Heavyweight tooling (visual regression, contract testing, reporting dashboards, accessibility automation) comes once its absence costs something ([Defer Tooling Until The Cost Shows Up](../tooling/defer-tooling-until-the-cost-shows-up.md)).
21
+
22
+ ## Related
23
+
24
+ - [Workspace Suite](workspace-suite.md)
@@ -0,0 +1,24 @@
1
+ # Workspace Suite
2
+
3
+ A coentrified workspace grows until it holds every deliverable of the suite. A missing item becomes work the way [Workspace Template](workspace-template.md) says.
4
+
5
+ ## Why
6
+
7
+ A workspace should know what complete looks like.
8
+
9
+ ## The Suite
10
+
11
+ - Documentation
12
+ - READMEs
13
+ - Unit tests
14
+ - E2E tests
15
+ - UI styleguide
16
+ - Component library
17
+ - Design system
18
+ - Reports
19
+ - Docs wiki
20
+ - Demo videos
21
+
22
+ ## Related
23
+
24
+ - [Workspace Levels](workspace-levels.md)
@@ -0,0 +1,41 @@
1
+ # Workspace Template
2
+
3
+ A workspace is a collection of applications for one product and the people who use it, each in their own role. Workspace docs live at `docs/` and describe the whole repo at a cross-app level. Anything app-specific belongs in `docs/<app>/`.
4
+
5
+ ## Why
6
+
7
+ Every workspace's docs have the same structure, and keep the focus of the workspace.
8
+
9
+ ## overview.md
10
+
11
+ Functional only - what the product is, who it serves, what shared concerns exist at a product level. How it is built lives in architecture.md.
12
+
13
+ - Title: `# <Workspace Name>`.
14
+ - Subtitle: one sentence on the workspace's purpose.
15
+ - Sections: Audience (who the product serves, naming the client where there is one, the roles of the people who use it, and the brief scope), Applications (list of apps with one-line purpose), Shared Concerns (auth, design system, language, etc. - one-line functional summaries), External Services (third-party APIs / backends the workspace consumes).
16
+ - Optional: a tail-of-file pointer to architecture.md for readers who want to know how it is built.
17
+
18
+ ## architecture.md
19
+
20
+ Technical companion to overview.md, ordered by relevance / logical flow (not low-level-first). Leads with the core mental model, then catalogs, then conventions:
21
+
22
+ - Applications - how apps are bootstrapped and where shared code lives, for example thin shells under `apps/<app>/` and libs under `libs/` in an Nx workspace.
23
+ - Layers - the five-layer [App-Shield](../architecture/app-shield.md) briefly reiterated (app/ui/data/core/config + one-way dependency direction), mapping the `@my-application/*` libs onto their layer.
24
+ - Libraries - external deps grouped by origin: Internal (your own or the organization's packages), General (third-party, for example `angular-auth-oidc-client` and `@jsverse/transloco`), Meta (tooling, for example nx, playwright, jest and vitepress).
25
+ - Conventions (path aliases, prefixes, mock toggles).
26
+
27
+ Cross-cutting concerns that outgrow a section graduate to their own flat file under `docs/workspace/` (authentication.md, design-system.md, component-library.md, testing.md - collected in one workspace folder, not per-concern folders). architecture.md links them and they surface in the wiki sidebar automatically. Don't re-merge them back into architecture.md. Skip a "documentation layout" map - the auto-generated wiki sidebar covers discovery.
28
+
29
+ A technical decision in another workspace doc moves here or into the matching concern doc, and its details stay in the code, so overview.md stays functional ([Docs Describe Behavior, Not Wiring](docs-describe-behavior-not-wiring.md)).
30
+
31
+ ## Work
32
+
33
+ - All work tracking lives in `docs/development/`.
34
+ - The roadmap's technical epics feed off the workspace suite: each missing suite item becomes an epic once it has a target.
35
+
36
+ ## Related
37
+
38
+ - [Documentation Philosophy](documentation-philosophy.md)
39
+ - [Things Of One Kind Are Consistent](../behavior/things-of-one-kind-are-consistent.md)
40
+ - [Workspace Suite](workspace-suite.md)
41
+ - [Work Tracking](../tickets-workflow/work-tracking.md)
@@ -0,0 +1,21 @@
1
+ # E2E Assert Before Interacting
2
+
3
+ An e2e test never assumes an element is there. Before any interaction or deeper assertion that depends on presence, it asserts presence first.
4
+
5
+ ## Why
6
+
7
+ Asserting the state before each interaction makes a failure point at where it starts: the missing element fails at its own line, by name.
8
+
9
+ ## How To Apply
10
+
11
+ - Before a fill, assert the input is editable, then fill.
12
+ - Before a click, assert the target is visible, then click.
13
+ - Before chained assertions on the contents of a dialog, sheet or drawer, assert the container is open.
14
+ - Before asserting a navigation result, assert the trigger landed (button gone, spinner shown, route in flight).
15
+ - Nullable returns from the test runner (bounding box, text content, attribute) go through a presence-asserting helper, never a bald cast or a manual throw.
16
+ - A missing, hidden or unsettled element fails on the presence assertion, with the locator named. Without the assertion the failure surfaces deeper, as a fill on an uneditable element or a URL check timing out on the wrong screen, which points at the wrong line and hides the cause.
17
+
18
+ ## Related
19
+
20
+ - [Implementation-Agnostic Locators](../tests/implementation-agnostic-locators.md)
21
+ - [E2E Tests Must Demonstrate Behavior](e2e-tests-must-demonstrate-behavior.md)
@@ -0,0 +1,20 @@
1
+ # E2E Mock Contract
2
+
3
+ Mock scenario values, storage keys and toggle flags are a shared contract between the mock layer (which lives inside the app) and any consumer that drives mock state (e2e tests, dev-mode toggles). They live in a single `.const.ts` in the mock module that every consumer imports.
4
+
5
+ ## Why
6
+
7
+ The constants are the protocol between the layers, so every side shares one copy.
8
+
9
+ ## How To Apply
10
+
11
+ - The const file exports grouped `as const` objects for storage keys, scenario values and the flag-on sentinel ([No Magic Values](../typescript/no-magic-values.md)).
12
+ - Mock interceptors and providers import them relatively within the module.
13
+ - E2E specs and helpers import them through a narrow path alias that points straight at the const file, never through an Angular barrel. The runner that loads spec files cannot bootstrap Angular, so a barrel that pulls Angular code crashes it with JIT-compile errors.
14
+ - Distinct use cases that represent distinct backend states get distinct scenarios, even when the UX outcome is the same. Two use cases driving one scenario exercise one code path, so only one is verified.
15
+ - Literals duplicated across the mock interceptor and the spec files drift: a renamed scenario or storage key leaves every spec type-checking against its own stale copy, and tests pass falsely on a broken flow.
16
+
17
+ ## Related
18
+
19
+ - [Develop Against Mocks](../tooling/develop-against-mocks.md)
20
+ - [E2E Tests Must Demonstrate Behavior](e2e-tests-must-demonstrate-behavior.md)
@@ -0,0 +1,18 @@
1
+ # E2E Runs On The Development Build
2
+
3
+ The e2e suites serve the app in the framework's development mode, so its development-only errors (Angular's NG0100 and the like) surface, stacks stay readable, and a shared fixture fails a case on such an error.
4
+
5
+ ## Why
6
+
7
+ The suites exist to catch development errors, and only the development build shows them.
8
+
9
+ ## How To Apply
10
+
11
+ - Never point the e2e web server at a production build. A slow dev server gets a prebuilt development build served statically instead.
12
+ - A trade-off that drops a class of errors from the checks is the director's call, asked before it lands.
13
+ - A production build steadies the suites on a busy machine, and drops the development errors.
14
+
15
+ ## Related
16
+
17
+ - [Start Playwright On A Clean Port](../tooling/start-playwright-on-a-clean-port.md)
18
+ - [Honest Assessments](../behavior/general-working-rules.md#honest-assessments)
@@ -0,0 +1,61 @@
1
+ # E2E Test Conventions
2
+
3
+ An e2e test walks a user route, sits in its feature's spec file, and is named and tagged after its use case.
4
+
5
+ ## Why
6
+
7
+ What the spec says and what the tests verify should be easy to check against each other.
8
+
9
+ ## User Routes Only
10
+
11
+ - An e2e case walks a route the user can take:
12
+ - In an app, a sign-in or a search.
13
+ - In a game, a new game or a continue.
14
+ - A developer tool, such as a debug panel or a seed endpoint, may seed the state a case starts from. Its own routes (a jump, a scenario, a reset) are never the flow under test.
15
+ - A bug only a tool can reach belongs to the tool and gets a unit test of the tool.
16
+
17
+ ## File And Describe
18
+
19
+ - One spec file per feature. Happy and error variants are siblings in the same file.
20
+ - Every test sits in a `describe('<Feature Name>', ...)` block, so the report heading reads as the feature ("User List", "Search User") instead of the file name. The describe names the feature, never the flow.
21
+
22
+ ## Title
23
+
24
+ The test title is the use-case name, as its spec's heading has it: no "happy path", no flow prefix, no ID prefix.
25
+
26
+ - Happy path is the use case as-is: `Create User`, `Edit User`, `User List`.
27
+ - Edge cases append ` - <Variant>` with a spaced dash: `Create User - Invalid Email`, `Edit User - Error`, `Delete User - Cancel`.
28
+ - The per-feature overview is `<Feature> - Overview`, one per feature spec ([Per-Feature Overview Test](per-feature-overview-test.md)).
29
+ - The cross-feature application overview, one per application, is `<Application> - Overview`, the same as a feature's. The describe block and its single test carry the same name.
30
+
31
+ ## Tags
32
+
33
+ - `@<use-case-id>` - the stable ID from the feature's spec.md (`@create-user-1`), always present on per-flow tests ([Feature Spec Template](../docs/feature-spec-template.md)).
34
+ - `@<feature-id>-overview` - the per-feature overview, no use-case number.
35
+ - `@<application-id>-overview` - the application overview, with an optional variant suffix: `@<application-id>-overview-<variant>`.
36
+ - Both overview tags also prefix the narrated demo reel's output filename. No separate ticket tag is needed.
37
+ - `@demo` - on the per-feature overview and the application overview.
38
+ - `@error` - only on unhappy paths. Reports color the chip red. Happy is the absence of `@error`, so there is no `@happy`.
39
+ - Modular features: once an application needs module folders (`features/users/`, `features/authentication/`), the feature takes its module as a prefix, `@users-create-user-1`, renaming every id and tag of the feature at once. Flat until that earns its keep.
40
+ - Pattern tags - only for a cross-feature, user-perceived category that filtering benefits from:
41
+ - `@list` - collection or list view.
42
+ - `@empty` - empty state.
43
+ - `@detail` - single-entity detail view.
44
+ - `@edge` - edge-case behavior (off the happy path, unusual state, persisted-state quirk).
45
+ - New patterns stay functional and user-perceived, never a tag for a feature name (the spec file is the feature), an implementation mechanic (redirects, pickers, layouts) or a single-test category.
46
+ - No application-name tag on per-flow tests. The test-runner project name already labels every test by application.
47
+
48
+ ## Helpers And Shared Data
49
+
50
+ - Spec-side helpers (URL builder, named timeouts, locator factories) live next to the specs they support.
51
+ - Tests that assert on seeded data import it from the application's testing lib ([Realistic Test Data Variance](../tests/realistic-test-data-variance.md)). Never hardcode the seeded values.
52
+
53
+ ## Filtering
54
+
55
+ - Pre-push runs the full affected e2e set, no filter.
56
+ - Local exploration greps by tag (`--grep "@error"`, `--grep "@list"`, `--grep "@create-user-1"`).
57
+
58
+ ## Related
59
+
60
+ - [No Magic Values](../typescript/no-magic-values.md)
61
+ - [Always Add Explicit Types](../typescript/always-add-explicit-types.md)
@@ -0,0 +1,28 @@
1
+ # E2E Tests Must Demonstrate Behavior
2
+
3
+ After writing an e2e test, check stills of the moments before and after the action, and confirm they show the user-visible behavior the test claims to exercise ([Reels And Video Proof](../reporting/reels-and-video-proof.md)).
4
+
5
+ ## Why
6
+
7
+ A green test shows the feature working, to anyone who watches the recording.
8
+
9
+ ## How To Apply
10
+
11
+ - Pick scenario data that makes the change visible. A searched term is in the seed (a row narrows or stays) or not in it (the empty state appears). Both shapes are usually worth their own test.
12
+ - Cover the opposite cases. Lookups: hit and no hit. Mutations: success and the matching error variant (4xx, 5xx). Toggles: enabled and disabled, visible in the rendered UI, in one bracketed test ([Bracket State Changes With Contrast Assertions](../tests/bracket-state-changes-with-contrast-assertions.md)).
13
+ - Wait for tick completions after an action: rely on the test runner's auto-wait (`expect(...).toBeVisible()`, `toHaveCount()`, `waitForRequest()`) over instant assertions.
14
+ - When the trigger needs an explicit confirm (search button, save button), drive that gesture. Rely on auto-submit only when the component documents it.
15
+ - Check the stills. If they don't show the change, the test is wrong however green it is, often asserting a network contract instead of the behavior. Reshape the assertions toward the visible behavior.
16
+
17
+ ## Bug Found Behind Green Tests
18
+
19
+ A bug or behavior gap that surfaces while the tests are green means the suite has a gap too:
20
+
21
+ - Write a test case for the failing behavior and file the bug ticket per [Note Issues](../behavior/note-issues.md).
22
+ - The case becomes the bug's reproducing test and lands with the fix. It is never marked to fail or skipped on main ([Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)).
23
+
24
+ ## Related
25
+
26
+ - [Bracket State Changes With Contrast Assertions](../tests/bracket-state-changes-with-contrast-assertions.md)
27
+ - [A Bug's Test Reproduces With Real Input](../tests/a-bugs-test-reproduces-with-real-input.md)
28
+ - [Reels And Video Proof](../reporting/reels-and-video-proof.md)
@@ -0,0 +1,17 @@
1
+ # One Check For Many Canvas Clicks
2
+
3
+ When an e2e test has to click a WebGL or 2D canvas many times, resolve the canvas bounding box once and click through the mouse at coordinates.
4
+
5
+ ## Why
6
+
7
+ A test with many canvas clicks stays inside its timeout, also on a loaded machine.
8
+
9
+ ## How To Apply
10
+
11
+ - Assert the canvas is visible once, read `boundingBox()`, then loop `page.mouse.click(x, y)`.
12
+ - Keep the helper in the e2e helpers folder as the one gesture helper for that canvas.
13
+ - A locator click repeats its actionability checks on every click, which on a rendering canvas under parallel workers can take seconds each and blow the test timeout.
14
+
15
+ ## Related
16
+
17
+ - [Implementation-Agnostic Locators](../tests/implementation-agnostic-locators.md)
@@ -0,0 +1,14 @@
1
+ # Overview
2
+
3
+ The E2E standards: end-to-end tests.
4
+
5
+ - [E2E Assert Before Interacting](e2e-assert-before-interacting.md) - assert presence before interacting
6
+ - [E2E Mock Contract](e2e-mock-contract.md) - mock scenario constants shared through one const file
7
+ - [E2E Runs On The Development Build](e2e-runs-on-the-development-build.md) - suites run on the development build, never a production build
8
+ - [E2E Test Conventions](e2e-test-conventions.md) - one spec per feature, use-case titles, @use-case tags
9
+ - [E2E Tests Must Demonstrate Behavior](e2e-tests-must-demonstrate-behavior.md) - check stills of the change, cover the opposite cases
10
+ - [One Check For Many Canvas Clicks](one-check-for-many-canvas-clicks.md) - many canvas clicks get one visibility check, then go through page.mouse
11
+ - [Per-Feature Overview Test](per-feature-overview-test.md) - every spec ends with a one-take overview test
12
+ - [Real Input For Frame Races](real-input-for-frame-races.md) - frame races need real mouse input, not dispatched events
13
+ - [Substring Locator Collisions](substring-locator-collisions.md) - new UI text can collide with substring locators
14
+ - [Use The E2E Pipeline For Browser Probing](use-the-e2e-pipeline-for-browser-probing.md) - probe live DOM through a Playwright spec, not ad-hoc scripts
@@ -0,0 +1,30 @@
1
+ # Per-Feature Overview Test
2
+
3
+ For every feature with e2e tests, the spec file ends with one overview test that chains the happy-path actions into a single scenario, so the recording becomes a one-take view of the feature. It strings the per-flow flows together without duplicating their assertions.
4
+
5
+ ## Why
6
+
7
+ An overview video per feature isolates that feature: for onboarding a user or a director, for showing a stakeholder and for visual testing.
8
+
9
+ ## How To Apply
10
+
11
+ - One overview test per feature spec, at the bottom of the file. Living in the same spec keeps it in step with the code on every run.
12
+ - Title `<Feature> - Overview`, tagged `@demo`, `@<feature-id>-overview` and the pattern tags the per-flow tests use ([E2E Test Conventions](e2e-test-conventions.md)). The overview tag carries no use-case number, since it identifies the take.
13
+ - Reuse the locators and boot helper of the per-flow tests. No new helpers, no new scenarios.
14
+ - The application overview (`<Application> - Overview`) stays a separate, broader take ([E2E Test Conventions](e2e-test-conventions.md)).
15
+ - The overview narrates the happy path and skips the bracketing.
16
+ - The strict per-flow tests carry the contrast assertions.
17
+ - Per-flow tests are short and atomic, which is good for diagnosis, and their recordings come out fragmented.
18
+
19
+ ## Keep It In Step With The Use Cases
20
+
21
+ When a use case is added to or removed from a feature spec, re-read the spec's Overview case and decide whether it should absorb the change. The case changes first, and the test follows it ([Feature Spec Template](../docs/feature-spec-template.md)).
22
+
23
+ - Adding a use case: extend the Overview case when a viewer benefits from seeing it (a new state, branch or outcome). An edge case, error variant or no-op stays with its per-flow test.
24
+ - Removing or renaming a use case: update or drop the overview steps that referenced it.
25
+ - The overview tells one coherent story. A use case that doesn't thread into it is skipped in the take, or a sign it belongs to another feature.
26
+
27
+ ## Related
28
+
29
+ - [Bracket State Changes With Contrast Assertions](../tests/bracket-state-changes-with-contrast-assertions.md)
30
+ - [Reels And Video Proof](../reporting/reels-and-video-proof.md)
@@ -0,0 +1,25 @@
1
+ # Real Input For Frame Races
2
+
3
+ A case that proves an animation starts on a click, or any handler that races a requestAnimationFrame loop, clicks with the real pointer at the element's bounding box, never with a dispatched click event.
4
+
5
+ ## Why
6
+
7
+ Tests stay as close to real usage as possible, down to the timing of a click.
8
+
9
+ ## How To Apply
10
+
11
+ - When a component's frame loop reads an input that a click sets, never reset or derive state from the input not being set yet inside the loop. Take the input's arrival as the start instead.
12
+ - The regression case uses the real mouse. If the target moves, read its bounding box right before the click.
13
+ - Assert the user-visible outcome, a canvas pixel at the center or a visible element, never the internal timestamp.
14
+ - Reels and helpers that dispatch events are fine for everything else. The helper that deviates says why.
15
+ - A dispatched event never gives the frame the head start a real click does, so the bug never shows.
16
+
17
+ ## Examples
18
+
19
+ - After real input, Chromium gives the next frame priority over the timers, and Angular's coalesced change detection runs in a race between a timeout and a frame. With a real click the frame wins, so a component's own frame loop runs before the new input values arrive. A dispatched event never triggers that priority, so the timer wins.
20
+ - An entry animation can play in every reel driven by dispatched clicks and never in the app.
21
+
22
+ ## Related
23
+
24
+ - [E2E Tests Must Demonstrate Behavior](e2e-tests-must-demonstrate-behavior.md)
25
+ - [Implementation-Agnostic Assertions](../tests/implementation-agnostic-assertions.md)
@@ -0,0 +1,23 @@
1
+ # Substring Locator Collisions
2
+
3
+ New UI text is checked against the substring locators in the e2e specs before it ships. `getByText('X')` matches by substring, so any new UI string that contains `X` makes the locator match two nodes, and Playwright's strict mode then fails.
4
+
5
+ ## Why
6
+
7
+ A locator finds one element, whatever other text is on the page.
8
+
9
+ ## How To Apply
10
+
11
+ - Before introducing new UI text in app code, grep the e2e specs for `getByText\('<short>'` and similar. If the new text contains an existing literal, change the locator first.
12
+ - The same holds in reverse when a subtitle overlay or narration adds text containing a short literal used as a locator elsewhere.
13
+ - Substring matchers age badly because they depend implicitly on every other string in the rendered DOM. A collision shows up the moment the new text ships, long after the test was written.
14
+
15
+ ## Examples
16
+
17
+ - A new loading label that contains a panel heading's word breaks every spec that locates the heading by that word, demo reels included.
18
+ - Once the `Save` button is gone, `getByText('Save')` keeps finding `Save All`. A helper that waits for `Save` to disappear times out, and a check that `Save` shows passes silently on the wrong node.
19
+
20
+ ## Related
21
+
22
+ - [Playwright Video Recording](../tooling/playwright-video-recording.md)
23
+ - [Implementation-Agnostic Locators](../tests/implementation-agnostic-locators.md)
@@ -0,0 +1,18 @@
1
+ # Use The E2E Pipeline For Browser Probing
2
+
3
+ When investigating live browser DOM (e.g. how a third-party component renders, what roles its options expose, where a clear button lives), drop the probing into a Playwright spec in the project's e2e folder and run it through the project's e2e script.
4
+
5
+ ## Why
6
+
7
+ The project already has a browser harness, and using it asks the director for no extra permissions.
8
+
9
+ ## How To Apply
10
+
11
+ - Name the file with a clear probe prefix (e.g. `_probe-<topic>.spec.ts`) so it's easy to find and remove.
12
+ - Tag tests with a unique tag (e.g. `@probe`) and grep for it: `e2e -- --grep @probe`.
13
+ - Use `console.log` inside the test - Playwright surfaces it in the reporter output.
14
+ - Remove the probe file before declaring the work done, or commit it intentionally if it earns its keep.
15
+
16
+ ## Related
17
+
18
+ - [Non-Destructive Documenting And Test Automation](../behavior/non-destructive-documenting-and-test-automation.md)
@@ -0,0 +1,22 @@
1
+ # Electron Packaging And Suite
2
+
3
+ Packages are built unsigned, with the keychain untouched, and only when the director asks for a build. Day-to-day verification runs on the suites and the captures. A packaged suite launches the built app from a copy outside the project, where nothing resolves back into the project's node modules, and checks every platform's package for the shell and the website next to it.
4
+
5
+ ## Why
6
+
7
+ A package works away from the repository, and the packaged suite proves it on the build machine.
8
+
9
+ ## How To Apply
10
+
11
+ - A package that only works next to the repository's node modules breaks on every other machine. Building on request keeps the loop fast.
12
+ - A version guard refuses to package a version that is tagged already. A packaged build carries the version of its commit.
13
+ - All platform packages build from one machine where the packager allows it. When the app has no auto updater, its side files can go.
14
+ - The packaged suite probes what breaks silently in a package: the fonts, the icons, the store path.
15
+ - A build that goes out is signed, and on a Mac notarized, by the build itself in CI, from a certificate and an API key held as the CI's secrets, never through the director's keychain ([Keep Secrets Away From Agents](../security/keep-secrets-away-from-agents.md)). An unsigned build may not open on another machine.
16
+ - A release checklist names the steps around such a build: the debug tools stripped, the signing and notarization, the platforms tested by hand.
17
+
18
+ ## Related
19
+
20
+ - [Electron Shell Shape](electron-shell-shape.md)
21
+ - [Never Access The Keychain](../security/never-access-the-keychain.md)
22
+ - [Devbox](../gamedev/devbox.md)
@@ -0,0 +1,21 @@
1
+ # Electron Shell Shape
2
+
3
+ An Electron app is a website in a shell. The archive holds the main process, the preload and the Electron package's own dependencies, declared in the app folder's own package file. The browser build sits as plain files under the app's resources, served by the main process itself on a privileged app scheme so the index answers every route. The root package has development dependencies only, since the build is html, css, js and assets.
4
+
5
+ ## Why
6
+
7
+ The shell stays small: an update replaces the website, and Electron stays.
8
+
9
+ ## How To Apply
10
+
11
+ - The web framework, such as Angular or Vite, is a build-time tool: bundled into the shell, it drags the whole toolchain into the package and breaks on the next platform. Serving the build from the main process needs no serve package and no dev server in production.
12
+ - The main process registers the scheme as standard, secure, with fetch and streams, and answers a request with the file if it exists and the index otherwise.
13
+ - User data lives in an electron store under the user data folder. An environment variable overrides that folder so suites and testers never touch real user data.
14
+ - The packaged app opens in the window mode the product needs, with a key for the devtools so a tester can read the console. A windowed environment flag exists for the suites.
15
+ - A splash can be skipped by a flag for quick starts.
16
+ - Keep the shell thin: the app never imports from the shell.
17
+
18
+ ## Related
19
+
20
+ - [Electron Packaging And Suite](electron-packaging-and-suite.md)
21
+ - [Develop Against Mocks](../tooling/develop-against-mocks.md)