coentrify 0.0.2 → 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 +2 -1
  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,31 @@
1
+ # Todo Template
2
+
3
+ `docs/development/todo.md` uses a fixed shape.
4
+
5
+ ## Purpose
6
+
7
+ What the director decided to do soon, as concrete one-liners, follow-ups and cleanups from larger work among them ([The Simple Workflow](the-simple-workflow.md#the-lists)).
8
+
9
+ ## Sections
10
+
11
+ - Title: `# Todo`.
12
+ - Flat dash list of one-liner items. No overview list - the file is already an overview.
13
+
14
+ ## Item Shape
15
+
16
+ - Default: a single-line task. Reference a file or doc inline with backticks or a link when useful.
17
+ - No periods on bullet items.
18
+ - Strip items as soon as they're done. Git history preserves what was there.
19
+ - When an item needs more explanation, promote it to a `## <task title>` subheading with a short paragraph or list underneath. Don't bloat one-liners with parenthetical context - if it doesn't fit on one line, give it its own section ([No Faux Headers In Lists](../docs/no-faux-headers-in-lists.md)).
20
+
21
+ ## What Doesn't Belong On The Todo
22
+
23
+ - User-facing bugs - [Bugs Template](bugs-template.md).
24
+ - Roadmap items - [Roadmap Template](roadmap-template.md).
25
+ - Debt with no concrete next step - the debt list ([Technical Debt Template](technical-debt-template.md)).
26
+
27
+ ## Related
28
+
29
+ - [Workspace Template](../docs/workspace-template.md)
30
+ - [Documentation Philosophy](../docs/documentation-philosophy.md)
31
+ - [No Faux Headers In Lists](../docs/no-faux-headers-in-lists.md)
@@ -0,0 +1,18 @@
1
+ # A Bug's Test Reproduces With Real Input
2
+
3
+ A test that guards a reported bug reproduces the director's own steps with real input: key presses one by one, select-all and delete, a click on the close button, Escape. Never Playwright's `fill()` or a call into the app for what the user types. Before the fix counts as verified, the test is run against the pre-fix code and seen to fail.
4
+
5
+ ## Why
6
+
7
+ A bug from real use becomes an edge case the tests guard, as it happened.
8
+
9
+ ## How To Apply
10
+
11
+ - Write the case from the director's words before the fix: red on the old code, green after.
12
+ - When the director reports a bug the tests say is fixed, check what the running app serves (the dev server's bundle, the stored state) before hunting in the code.
13
+ - `fill()` and a call into the app skip what real typing fires.
14
+
15
+ ## Related
16
+
17
+ - [Real Input For Frame Races](../e2e/real-input-for-frame-races.md)
18
+ - [E2E Tests Must Demonstrate Behavior](../e2e/e2e-tests-must-demonstrate-behavior.md)
@@ -0,0 +1,37 @@
1
+ # Bracket State Changes With Contrast Assertions
2
+
3
+ For any test that observes a state change - a toggle, a switch, an open/close, a navigation, a selection - assert both axes on both sides of the change. Before: A is true, B is false. After: A is false, B is true.
4
+
5
+ ## Why
6
+
7
+ A test proves that the new state replaced the old one.
8
+
9
+ ## How To Apply
10
+
11
+ - Toggle (collapse/expand, open/close):
12
+ - Before, closed visible and open not.
13
+ - After, open visible and closed not.
14
+ - Switch (app, theme, mode):
15
+ - Before, A active and B not.
16
+ - After, B active and A not.
17
+ - Navigation:
18
+ - Before, source page visible and destination not.
19
+ - After, destination visible and source not.
20
+ - Selection in a list:
21
+ - Before, nothing selected.
22
+ - After, the picked item selected and the rest not.
23
+ - No-op: identical assertions before and after prove the action changed nothing.
24
+ - Assert both axes with [Implementation-Agnostic Assertions](implementation-agnostic-assertions.md).
25
+ - Overview tests skip the bracketing ([Per-Feature Overview Test](../e2e/per-feature-overview-test.md)).
26
+
27
+ ## Combine Simple Opposites Into One Bracketed Test
28
+
29
+ Two tests for opposite sides of one binary toggle (`hidden when disabled` and `visible when enabled`, `locked before the previous step` and `unlocked after it`, `closed by default` and `open after click`) become one bracketed test of the transition. It carries both use-case ids, so the mapping in the feature spec stays intact and a search by either id finds it.
30
+
31
+ - Two single-axis tests both pass on an implementation that always shows the positive state. One bracketed test catches it.
32
+ - It halves boot and teardown cost and reads as the behavior the user sees: flip the flag, see the change.
33
+ - Opposite cases that are functionally distinct scenarios with different inputs keep separate tests: lookup hit and miss, mutation success, server error and validation error, normal flow and auth error.
34
+
35
+ ## Related
36
+
37
+ - [E2E Tests Must Demonstrate Behavior](../e2e/e2e-tests-must-demonstrate-behavior.md)
@@ -0,0 +1,35 @@
1
+ # Gestures In Tests
2
+
3
+ A feature that offers several ways to trigger one action (send via Enter or the send button) gets its gestures tested once, through one dispatcher test, while every helper defaults to the gesture a real user makes at that viewport.
4
+
5
+ ## Why
6
+
7
+ Tests stay as close to real usage as possible.
8
+
9
+ ## One Test Per Dispatcher
10
+
11
+ Two tests that differ only in how the user triggers the same dispatcher exercise the dispatcher twice and add nothing for the gestures. Collapse them into one test that drives the dispatcher with both gestures in sequence.
12
+
13
+ - Fold two tests whose bodies differ only in `press('Enter')` versus `button.click()`. The natural home for the alternative gesture is a multi-step happy path (first action via Enter, follow-up via click).
14
+ - Keep the tests separate when the alternative gesture trips a different code path (Enter picks a dropdown option, a click triggers a route change). That is a different dispatcher.
15
+ - Validation that routes through a shared submit handler gets no "via X" variant. Test the handler once.
16
+
17
+ ## Every Edge Case Keeps Its Test
18
+
19
+ Collapsing applies only to same-dispatcher, same-outcome tests. Every edge case is tested: outcomes that differ in result, state or user-facing message (a failed hide and a failed show, each with its own error copy) are distinct edge cases, each with its own test. Never drop a distinct edge's coverage, or delete its now-unused fixture or export, as redundant. Add the missing test instead.
20
+
21
+ ## Gesture By Device
22
+
23
+ Multi-gesture helpers default to the gesture a real user makes at that viewport: mobile users tap the send button, tablet and desktop users press Enter or click. On a phone, Enter in a message field adds a line, so users tap the send button, and a mobile test pressing Enter misses the path they take.
24
+
25
+ - Compare the viewport width with the tablet breakpoint:
26
+ - Below is mobile and clicks.
27
+ - At or above uses keyboard or click.
28
+ - Keep an explicit `gesture` parameter so the dispatcher test can drive both paths in sequence.
29
+ - The same holds anywhere a test touches the UI: swipe or scroll wheel, long-press or right-click.
30
+
31
+ ## Related
32
+
33
+ - [Bracket State Changes With Contrast Assertions](bracket-state-changes-with-contrast-assertions.md)
34
+ - [Validation Errors Fire On Submit](../ui/validation-errors-fire-on-submit.md)
35
+ - [E2E Tests Must Demonstrate Behavior](../e2e/e2e-tests-must-demonstrate-behavior.md)
@@ -0,0 +1,20 @@
1
+ # Implementation-Agnostic Assertions
2
+
3
+ Any test that asserts on rendered UI should assert what the user perceives. Prefer visibility, enabled, editable and visible-text checks over DOM count, attached-state and attribute checks.
4
+
5
+ ## Why
6
+
7
+ A test fails only when what the user perceives changes.
8
+
9
+ ## How To Apply
10
+
11
+ - For presence: `toBeVisible` (and `not.toBeVisible` for absence).
12
+ - For interaction state: `toBeEnabled` / `toBeDisabled`, `toBeEditable`, `toBeChecked`, `toBeFocused`.
13
+ - For content: `toHaveText` / `toContainText`, `toHaveValue`.
14
+ - Reach for `toHaveCount` only when the assertion is about cardinality ("the list shows exactly three results"), never as a stand-in for "this element is gone".
15
+ - Reach for `toHaveAttribute` only when the attribute is part of the user-facing contract (`aria-label`, `href`, `for`), never for internal data attributes.
16
+ - A change in how visibility is achieved leaves these assertions passing: a conditional render swapped for `display: none`, a lazy render, an exit animation, a portal.
17
+
18
+ ## Related
19
+
20
+ - [Implementation-Agnostic Locators](implementation-agnostic-locators.md)
@@ -0,0 +1,18 @@
1
+ # Implementation-Agnostic Locators
2
+
3
+ Any test that touches the DOM (e2e, integration, styleguide) locates elements by what the user perceives: role, accessible label, placeholder and visible text. Avoid component tag selectors, class selectors and internal attribute names.
4
+
5
+ ## Why
6
+
7
+ A test fails only when what the user perceives changes.
8
+
9
+ ## How To Apply
10
+
11
+ - An element that lacks a role (a custom dropdown trigger that isn't a button yet) gets its implementation selector wrapped in exactly one helper per user gesture (`openRowActionMenu`, `openRoleFilter`). Specs only call the helper. When the UI is upgraded, only the helper changes.
12
+ - Don't match on translated strings inside boot or async wait code: translations load asynchronously and create races. Wait for a stable non-translated marker first. Translated text is safe for assertions after that.
13
+ - Role and label locators make the app expose proper accessibility, which it needs anyway.
14
+
15
+ ## Related
16
+
17
+ - [Implementation-Agnostic Assertions](implementation-agnostic-assertions.md)
18
+ - [Substring Locator Collisions](../e2e/substring-locator-collisions.md)
@@ -0,0 +1,13 @@
1
+ # Overview
2
+
3
+ The Tests standards: test design.
4
+
5
+ - [A Bug's Test Reproduces With Real Input](a-bugs-test-reproduces-with-real-input.md) - a bug's test uses real input and is seen failing first
6
+ - [Bracket State Changes With Contrast Assertions](bracket-state-changes-with-contrast-assertions.md) - assert both states before and after a change
7
+ - [Gestures In Tests](gestures-in-tests.md) - one dispatcher test for both gestures, device-appropriate defaults
8
+ - [Implementation-Agnostic Assertions](implementation-agnostic-assertions.md) - assert what the user perceives
9
+ - [Implementation-Agnostic Locators](implementation-agnostic-locators.md) - locate by role, label and text
10
+ - [Realistic Test Data Variance](realistic-test-data-variance.md) - seeds vary every dimension a feature acts on
11
+ - [Seed Surfaces Every State On Page 1](seed-surfaces-every-state-on-page-1.md) - the seed's first page shows every state a test names
12
+ - [Test Design](test-design.md) - a test profile per app-shield layer, independent tests, one mock layer
13
+ - [Test The System Behind A Mock](test-the-system-behind-a-mock.md) - a spec test of its own for the real system. Where none can run, a spec and recorded manual tests are the proof
@@ -0,0 +1,24 @@
1
+ # Realistic Test Data Variance
2
+
3
+ Test datasets should mirror production variance across every dimension a feature filters, sorts, groups, or branches on. Uniform seeds hide bugs.
4
+
5
+ ## Why
6
+
7
+ A bug that only shows in varied data is caught before production.
8
+
9
+ ## How To Apply
10
+
11
+ - Vary every dimension a feature acts on: role, status, organization, owner, dates, counts.
12
+ - Factories spread these dimensions across the dataset by design, the same on every run. Tests pin specific values only when the assertion requires them.
13
+ - For any feature that filters or branches on a property, the dataset must contain at least one matching and one non-matching record - otherwise the test can't distinguish "works" from "is a no-op".
14
+
15
+ ## Examples
16
+
17
+ - A role filter that does nothing still looks fine when every seeded user is an admin.
18
+ - A status sort gives the right order when every record has the same status.
19
+ - A "show mine" toggle passes when every record has the same owner.
20
+
21
+ ## Related
22
+
23
+ - [Seed Surfaces Every State On Page 1](seed-surfaces-every-state-on-page-1.md)
24
+ - [Bracket State Changes With Contrast Assertions](bracket-state-changes-with-contrast-assertions.md)
@@ -0,0 +1,17 @@
1
+ # Seed Surfaces Every State On Page 1
2
+
3
+ When a feature paginates and a test asserts states side by side (A and B visible at the same time), the first page of the test seed includes every state the test mentions. Otherwise the test has to navigate, filter or sort first just to put those states on screen, which makes it a test of pagination instead of the property under test.
4
+
5
+ ## Why
6
+
7
+ A test fails only for the property it tests.
8
+
9
+ ## How To Apply
10
+
11
+ - Before writing an e2e test that combines pagination and states side by side, scan the seed and confirm every state the test names is in the first-page slice.
12
+ - If reordering the seed isn't an option (shared fixture data ordered for another reason), open with a filter or sort that surfaces those states first, then assert.
13
+ - An "element not found" for a state past the first page looks like a broken assertion, while the fault is the seed's order.
14
+
15
+ ## Related
16
+
17
+ - [Realistic Test Data Variance](realistic-test-data-variance.md)
@@ -0,0 +1,47 @@
1
+ # Test Design
2
+
3
+ Tests are organized along the [App-Shield](../architecture/app-shield.md) layers. Each layer has its own test profile and tests only what that layer is responsible for. Lower-layer behavior is assumed to work because it has its own tests there.
4
+
5
+ ## Why
6
+
7
+ A failing test points at the layer that broke.
8
+
9
+ ## Test Profile Per Layer
10
+
11
+ - ui - presentational components, design tokens. Unit + integration + styleguide.
12
+ - app - app shells, routing, feature wiring. Unit + e2e.
13
+ - data - API clients, mappers, caches. Scenario tests, one per request and response variant against the client.
14
+ - core - generic services, guards, interceptors, stores and utilities. Unit only.
15
+ - config - types and tokens, with no logic of their own. Scenario tests vary the configuration to catch drift.
16
+
17
+ ## Honor Each Test Type's Implied Principles
18
+
19
+ Unit, integration, e2e, scenario and styleguide tests each carry implied principles for what they cover and what they leave alone. Stick to those instead of bending a type to plug a coverage gap. An awkward fit signals that the design needs adjusting.
20
+
21
+ ## Tests Must Be Independent
22
+
23
+ No test depends on state, fixtures or side effects left behind by another. Each test owns its setup and cleanup, so ordering, parallelism and partial reruns all produce the same result.
24
+
25
+ ## One Mock Layer Per Test Type
26
+
27
+ Each test type mocks the backend at exactly one layer, never at two for the same flow. Doubling up multiplies setup, hides which mock is answering and makes the test brittle to either layer changing.
28
+
29
+ ## Execution Strategy
30
+
31
+ - A fast subset (affected or critical path) runs on every change.
32
+ - The full suite runs on a nightly schedule.
33
+ - Reports upload as build artifacts every run.
34
+ - Expensive diagnostics (traces, videos, screenshots) upload only on failure.
35
+
36
+ ## How To Apply
37
+
38
+ - When adding a test, pick the profile from its layer.
39
+ - A check that needs no browser is a unit test, never an e2e case.
40
+ - When behavior spans layers, test it once at the highest layer involved (usually app via e2e).
41
+ - Set coverage thresholds only after the test design has stabilized. Start with critical-path coverage and tighten over time.
42
+
43
+ ## Related
44
+
45
+ - [App-Shield](../architecture/app-shield.md)
46
+ - [Test The System Behind A Mock](test-the-system-behind-a-mock.md)
47
+ - [Lightweight Test Reporting Only](../tooling/lightweight-test-reporting-only.md)
@@ -0,0 +1,21 @@
1
+ # Test The System Behind A Mock
2
+
3
+ A system that a mock stands in for gets a spec test of its own. Where no test can run, as with a third-party API, a spec and recorded manual tests are the proof.
4
+
5
+ ## Why
6
+
7
+ A test against a mock says nothing about the system behind it.
8
+
9
+ ## How To Apply
10
+
11
+ - The system is tested against its own spec, apart from the tests that run on the mock.
12
+ - The spec follows the [Feature Spec Template](../docs/feature-spec-template.md): use cases with stable ids.
13
+ - Every manual run gets a dated page in `docs/records/manual-tests/`, named `<date>-<system>.md`.
14
+ - The page lists the ids that were run, each with its outcome.
15
+
16
+ ## Related
17
+
18
+ - [Develop Against Mocks](../tooling/develop-against-mocks.md)
19
+ - [Test Design](test-design.md)
20
+ - [Playtest Files](../records/playtest-files.md)
21
+ - [Docs Folder Structure](../docs/docs-folder-structure.md)
@@ -0,0 +1,54 @@
1
+ # Agent Roles
2
+
3
+ In project work the main session is the conductor, which runs the other agents. The other roles are the builder, the docs agent and the scout. Agents go by their role. A name for an agent never enters the docs or the standards.
4
+
5
+ ## Why
6
+
7
+ Every message from the director is handled at once, while the work keeps landing.
8
+
9
+ ## The Conductor
10
+
11
+ - Its own page is [The Conductor](the-conductor.md): what it does, what it says to the director, and what it checks before and at a landing.
12
+
13
+ ## The Builder
14
+
15
+ - Its own page is [The Builder](the-builder.md), and how it builds a ticket is in [Building A Ticket](building-a-ticket.md) and [The Done Part](the-done-part.md).
16
+
17
+ ## The Docs Agent
18
+
19
+ - Runs only for a docs sweep or to process a queue of tickets.
20
+ - A docs sweep is docs work, with its go and its plan section.
21
+ - It grooms under a docs ticket of its own, and the tickets it edits while doing so stay unassigned.
22
+ - Its commit passes hygiene and the wiki build, since hygiene misses a dead link.
23
+
24
+ ## The Scout
25
+
26
+ - Works the spikes: how something is now, found by runs, measurements and reproductions, so the grooming stays fast.
27
+ - Writes its findings into the spike's Done part, a line per question with how it was checked.
28
+
29
+ ## How Many
30
+
31
+ - The number of agents running at once follows token and machine capacity. Nothing else fixes it.
32
+ - The machine's capacity counts only the agents that run browser suites. An agent whose checks are hygiene, types, unit and the wiki build starts whatever the machine's load: a docs agent, and a builder on a light debt story ([Work Tracking](work-tracking.md#stories)).
33
+ - One builder per story. Stories run side by side only where the files they touch are disjoint.
34
+ - A large job, a hundred tickets say, goes to one docs agent with the whole queue, in the background.
35
+ - Read-only lookups the conductor can do itself are done there, without an agent.
36
+ - The suites share the director's machine ([Playwright Parallel Runs](../tooling/playwright-parallel-runs.md)). The worktrees, ports and landing scripts are in [Parallel Agents](../tooling/parallel-agents.md).
37
+
38
+ ## Every Brief Says
39
+
40
+ - The ticket it works, linked. Its acceptance criteria are the target ([Work Workflow](work-workflow.md)).
41
+ - The setup commands, exact and with absolute paths.
42
+ - Never a list of standards to read in full, and never a summary of them: the Core Rules and the index load by themselves, and the agent opens the standards its work touches, [The Builder](the-builder.md) and [Building A Ticket](building-a-ticket.md) among them.
43
+ - An agent adding use cases to a spec gets a fixed id range of its own, written in the brief and read from the specs' own ids per prefix across every spec file.
44
+ - The director's log entry is cited by the time its append printed, so the log is written before the brief goes out.
45
+ - The director's words and the conductor's own calls are kept apart in the brief ([Docs State Knowledge](../docs/docs-state-knowledge.md)).
46
+
47
+ ## Related
48
+
49
+ - [The Conductor](the-conductor.md)
50
+ - [The Builder](the-builder.md)
51
+ - [Building A Ticket](building-a-ticket.md)
52
+ - [Work Workflow](work-workflow.md)
53
+ - [Parallel Agents](../tooling/parallel-agents.md)
54
+ - [Library Feedback](../docs/library-feedback.md)
@@ -0,0 +1,6 @@
1
+ {
2
+ "building-a-ticket.md": {
3
+ "words": 604,
4
+ "reason": "the Definition of Done is one list, and its lines hold together"
5
+ }
6
+ }
@@ -0,0 +1,47 @@
1
+ # Building A Ticket
2
+
3
+ The builder's page: how a ticket with its go is built, and when it counts as done. The path around it is in [Work Workflow](work-workflow.md).
4
+
5
+ ## Why
6
+
7
+ The director can trust a ticket that is called done.
8
+
9
+ ## Building
10
+
11
+ - Work comes from the plan only, and the plan holds only ready stories with a go and an agent. Every commit traces to a planned story's ticket and starts with its id ([Commits](../commits/commits.md)). Something found mid-work that is not on the plan becomes a ticket first ([Note Issues](../behavior/note-issues.md)), apart from a fix that [Don't Introduce Tech Debt](../behavior/dont-introduce-tech-debt.md) makes in the same pass.
12
+ - One ticket in flight per agent: the next in its story's order ([Work Tracking](work-tracking.md#stories)).
13
+ - Every word and number a change shows, configuration data included, is weighed along the ticket's entry points by what it means to the user at that moment ([Walk The User's Journey](../ui/walk-the-users-journey.md)). A text the user reads speaks the product's own words, never the workspace's internal terms.
14
+ - A feature runs the feature workflow inside its ticket ([Feature Workflow](../behavior/feature-workflow.md)).
15
+ - Per ticket, only what the change affects runs: the cases of every feature that uses what it touched, and the reels and captures that cross it. The whole touched suites run at the end of the story, and the full suites at the version's close.
16
+ - Easy-to-change choices are made and written under Veto.
17
+ - Only costly-to-undo choices wait, as a question in their ticket.
18
+
19
+ ## A Ticket Lands Right
20
+
21
+ - A ticket leaves the codebase no worse: no new risk, debt or bad code, and no lower quality or value.
22
+ - Whatever its own work needs to be right is done in it, taking the time it takes: a design risk mitigated by design belongs in the ticket, and so does a small, relevant fix.
23
+ - The right solution is solved now, never pushed out as a follow-up. A follow-up ticket exists only when the work outgrows one ticket, which is a split, named under Veto when the build finds it.
24
+
25
+ ## Definition Of Done
26
+
27
+ A ticket is done only when every one of these holds. Until then it stays on the plan.
28
+
29
+ - Every acceptance criterion is met and verified, and the spec covers each one.
30
+ - The cases that touch the change, hygiene, types and the development build are green, each by its own exit code ([Gate Commits On Exit Codes](../commits/gate-commits-on-exit-codes.md)).
31
+ - A bug's test reproduces the director's steps with real input and was seen failing before the fix ([A Bug's Test Reproduces With Real Input](../tests/a-bugs-test-reproduces-with-real-input.md)).
32
+ - A new hygiene check lands with its implementation, and its builder's report shows the run that failed before the change.
33
+ - The Done part holds proof the director can open and verify ([The Done Part](the-done-part.md), [Review Every Capture Before Reporting](../behavior/review-every-capture-before-reporting.md)).
34
+ - Visual work meets its Visual Quality points and the project's visual checklist.
35
+ - The docs are synced: the feature doc, the spec, and every reference to a changed name ([Sync The Docs After Every Change](../behavior/sync-the-docs-after-every-change.md)).
36
+ - No new tech debt: what the change made unused or duplicated is cleaned in the same commit.
37
+ - The agent's own decisions stand under Veto ([Flag Every Addition Of Your Own](../behavior/flag-every-addition-of-your-own.md)).
38
+ - The change is squashed into one commit on the story's branch, its landing commit, which reaches main with the story's merge ([Verify Staging Before Committing](../commits/verify-staging-before-committing.md)).
39
+ - Captures and archive moves are never batched for later. The version's changelog lists the ticket by itself ([Changelog Per Version](../records/changelog-per-version.md)).
40
+ - A debt ticket is archived in its landing commit ([Work Tracking](work-tracking.md#the-archive)).
41
+
42
+ ## Related
43
+
44
+ - [Work Workflow](work-workflow.md)
45
+ - [The Done Part](the-done-part.md)
46
+ - [Work Tracking](work-tracking.md)
47
+ - [Gate Commits On Exit Codes](../commits/gate-commits-on-exit-codes.md)
@@ -0,0 +1,15 @@
1
+ # Overview
2
+
3
+ The Tickets Workflow standards: the work tracked in tickets.
4
+
5
+ - [Agent Roles](agent-roles.md) - the conductor runs the agents, a builder per story until its verdict, a docs agent for sweeps and queues, a scout for spikes. The number of agents follows token and machine capacity. No agent names in the docs
6
+ - [Building A Ticket](building-a-ticket.md) - the builder's page: work comes from the plan only, one ticket in flight. A ticket lands right, solved now, a follow-up only as a split. The Definition of Done: every criterion met and verified, checks green by exit code, proof in the Done part, docs synced, no new debt, own decisions under Veto, a commit of its own
7
+ - [The Builder](the-builder.md) - builds one story in a worktree of its own, ticket by ticket, until the director's verdict, or the merge of a debt story
8
+ - [The Conductor](the-conductor.md) - the conductor processes every message and builds nothing. Its chat reads as a log, a line per event: the ticket id, its context and a title of a few words. Whatever it surfaces is filed first, and what stands in a ticket is never repeated
9
+ - [The Done Part](the-done-part.md) - the builder's Done part: a bullet per thing the user can now do, see or hear, each with proof the director opens or does: a capture, a video, a link or where to try it. Never case ids or a tests line. Then the Veto. A long one carries a mark
10
+ - [Stabilize Before Adding](stabilize-before-adding.md) - while stabilizing, only bugs and tweaks. New things go later
11
+ - [Ticket Template](ticket-template.md) - a ticket is one file of sections that each answer one question. The sections each type carries, the front matter fields, the file layout
12
+ - [Work Item Names](work-item-names.md) - work names show type, topic and direction, in Title Case. A changed behavior is named by its end state, subject first
13
+ - [Work Tracking](work-tracking.md) - docs/development: phases and areas over epics over stories over tickets, an id per ticket kept for life, a type that never changes, every list generated from the tickets, archive at the verdict, no status field
14
+ - [Work Workflow](work-workflow.md) - log -> ticket -> grooming -> the director's go -> plan -> Definition of Done -> the director's verdict -> archive, debt excepted. Where a finding goes. Everything needs a go. Strict, self-tightening
15
+ - [Writing A Ticket](writing-a-ticket.md) - how a ticket is written: say each fact once, a summary that says what should change, a small ticket, acceptance criteria as spec lines
@@ -0,0 +1,18 @@
1
+ # Stabilize Before Adding
2
+
3
+ While a version is being made stable and clean, its plan holds bugs and tweaks to what exists only. Anything new, a feature, a look, a preset, goes into its epic and phase, off the plan, even when the director mentions it in the middle of a playtest or a user test.
4
+
5
+ ## Why
6
+
7
+ Every version reaches stable and clean.
8
+
9
+ ## How To Apply
10
+
11
+ - Stable and clean comes first, then the roadmap's current phase, then new things.
12
+ - New things ride in from playtest and user test notes easily, and a version that mixes them with its fixes is never stable.
13
+ - When parsing a note, ask whether the thing exists in the product today. If not, it is new and goes into its epic, unless the director explicitly pulls it into the version.
14
+
15
+ ## Related
16
+
17
+ - [Gamedev Working Cadence](../gamedev/gamedev-working-cadence.md)
18
+ - [Dev Tiers](../behavior/dev-tiers.md)
@@ -0,0 +1,28 @@
1
+ # The Builder
2
+
3
+ The builder builds one story in a worktree of its own, ticket by ticket, until the director's verdict on the story, or its merge for a debt story. How it builds a ticket is in [Building A Ticket](building-a-ticket.md).
4
+
5
+ ## Why
6
+
7
+ A story is built whole by one agent, whose context holds that story alone.
8
+
9
+ ## How To Apply
10
+
11
+ - Builds one story in a worktree of its own: the story's tickets in order, one in flight, each ticket squashed into one commit of its own.
12
+ - Stays until the story's verdict: it works the director's findings in as they come back as tickets, and ends once the story is accepted. A debt story gets no verdict, so its builder ends at the merge.
13
+ - Never carries on into a next story and is never compacted: a next story gets a fresh builder, since the code, the docs and the Done parts hold what it needs.
14
+ - Never judges its own context: a story is sized in refinement to fit one. A builder that stops anyway is replaced by a fresh one on the same worktree, the commits and the Done parts its handover.
15
+ - While one of its tickets waits on a question ([Building A Ticket](building-a-ticket.md#building)), it reports the question to its conductor and builds the story's ready tickets on.
16
+ - Builds the story's tickets on one branch, each next ticket on its own last finished one, keeps going and reports every ticket it finishes. Once the story is built, it rebases onto main and runs the main checks green, and the conductor only merges ([Parallel Agents](../tooling/parallel-agents.md#landing)).
17
+ - The stack never falls far behind main: it is rebased onto main after each commit, so a conflict stays small ([Parallel Agents](../tooling/parallel-agents.md)).
18
+ - Never merges into main itself.
19
+ - A criterion is measured once and proved from that run. A measure that cannot hold goes back to the conductor, who restates it under Veto or asks the director.
20
+ - A fact about the product's content is grepped in the docs and the log first, never recalled.
21
+ - A builder on debt takes debt that was found, never a mess another agent just made ([Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)).
22
+
23
+ ## Related
24
+
25
+ - [Agent Roles](agent-roles.md)
26
+ - [Building A Ticket](building-a-ticket.md)
27
+ - [The Done Part](the-done-part.md)
28
+ - [Parallel Agents](../tooling/parallel-agents.md)
@@ -0,0 +1,44 @@
1
+ # The Conductor
2
+
3
+ In project work the main session is the conductor, the controller between the director and the agents: it takes in everything the director says, delegates it, keeps the lists moving and reports the progress back ([Agent Roles](agent-roles.md)). Toward the director it reads as a log and an overview of the work.
4
+
5
+ ## Why
6
+
7
+ The director has an always open line to all of the work: every thought goes in at once, and all progress comes back.
8
+
9
+ ## What It Does
10
+
11
+ - Processes every message of the director: logs it, turns it into tickets and briefs at once, so the director's next message never waits on a ticket being written.
12
+ - Builds nothing and never opens an item's files. Its hands stay on the log, the lists, the landings and the director's messages.
13
+ - Settles the small things itself: a recommended answer taken, a builder assigned, a drop or a promotion.
14
+ - Records the director's go in the `go` field when the director gives one.
15
+ - Sets a ticket's `feedback` field the moment the director gives feedback on it, and clears it once the feedback is worked in ([Work Tracking](work-tracking.md#the-lists)).
16
+ - Archives a ticket at its verdict ([Work Tracking](work-tracking.md#the-archive)).
17
+ - Briefs a story with its go to a fresh builder once capacity allows ([Agent Roles](agent-roles.md#how-many)) and every story it waits on is accepted, which puts it on the plan. A ticket outside a story gets a builder of its own.
18
+ - Addresses agents through a roster written at launch (area, id, branch), each id read from it, never recalled.
19
+
20
+ ## What It Says
21
+
22
+ - The director's time is the bottleneck, so the chat is a log: a line per event, holding the ticket's id, its context and a short title.
23
+ - A message of the director's is answered with a line per ticket filed: `Filed BUG-33 - Fix The Login Redirect`, `Filed FEAT-123 - Add The Header in STORY-2: User Onboarding`.
24
+ - A landing is one line: `STORY-2 - User Onboarding - is ready for acceptance`. A debt story's line names its Veto lines: `STORY-5 - Upgrade The Build - merged. Veto: <line>`.
25
+ - A finding is filed first and then named by its id: `Critical bug found - BUG-123 - Fix Draft Loss On Reload`. Nothing is surfaced in the chat alone, since a chat can close at any moment ([Note Issues](../behavior/note-issues.md)).
26
+ - What stands in a ticket is never repeated in the chat: what was built, a builder's decisions, what is unverified. The conductor's own decisions stand in the ticket's Veto section.
27
+ - Past these lines the chat carries only a call the director has to make now, or a failure, each with its ticket's id.
28
+
29
+ ## Before Anything Lands
30
+
31
+ - Every premise is checked against the feature doc and the log before it is briefed.
32
+ - An agent's pick that departs from an existing component or pattern is sent back before landing, never passed on as a Veto line.
33
+ - An agent that did exactly what the director named and asks whether the words reach further gets the status quo, never the conductor's wider reading.
34
+ - An agent's "your call" goes into its ticket as a question only after it is weighed. Small picks are the agents' to make.
35
+ - The conductor reviews an agent's captures itself, never trusting a file name ([Review Every Capture Before Reporting](../behavior/review-every-capture-before-reporting.md)).
36
+
37
+ ## Landing
38
+
39
+ - After every commit of its own, the conductor runs the main checks. A story's checks run in its builder's worktree before it merges. What else a landing asks for is in [Parallel Agents](../tooling/parallel-agents.md#landing).
40
+
41
+ ## Related
42
+
43
+ - [Gamedev Working Cadence](../gamedev/gamedev-working-cadence.md)
44
+ - [Work Workflow](work-workflow.md)
@@ -0,0 +1,23 @@
1
+ # The Done Part
2
+
3
+ The builder writes the Done part into a ticket in its landing commit: a bulleted list of what was functionally achieved, short and fast to read. The rest of the ticket is in [Writing A Ticket](writing-a-ticket.md).
4
+
5
+ ## Why
6
+
7
+ The director can tell quickly whether the work is really done.
8
+
9
+ ## How To Apply
10
+
11
+ - Proof holds a bullet per thing the user can now do, see or hear, a few words each, with its proof beside it.
12
+ - A proof is something the director opens or does: a capture, a video, a link to a page changed, or where to try it and the scenario that starts it. Words about tests or spec cases are never proof. "Search added to the user list", linked, is a whole bullet.
13
+ - A change in how something looks or moves always shows a capture, a before and after pair for a change in what is seen, a video where it moves. That is where the director looks closest.
14
+ - No spec case ids, no tests line, no checks and no parts list: those go in the builder's report and the commits. A hygiene check fails a Done part holding a spec case id.
15
+ - Past about 100 words a Done part counts as long. One kept long carries `long-done: true`, which a hygiene check requires, so its length is always a choice.
16
+ - Veto: each choice the build made that the ticket did not and the director could want undone, in a few words. A departure from a criterion is a Veto line. Placement, wording that follows the page and bookkeeping are no decisions.
17
+ - Code details stay in the commit messages.
18
+ - A spike's Proof holds its findings, a line per criterion with how it was checked.
19
+ - Commits are never listed in a ticket: every commit made for it starts with its id ([Commits](../commits/commits.md#ticket-prefix)), so `git log --grep FEAT-214` finds them.
20
+
21
+ ## Related
22
+
23
+ - [Building A Ticket](building-a-ticket.md)