codeassembly-guidance 0.0.0 → 0.2.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 (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,1001 @@
1
+ # Artifact conventions
2
+
3
+ Standards for AI-generated artifact storage, naming, and lifecycle.
4
+
5
+ ## Purpose
6
+
7
+ The artifact directory is the developer's audit trail of development. Its plans, reviews, change summaries, pull-request and merge records, devlogs, and chat summaries record what an agent produced and when, each as it stood at the moment of writing (see [Mutability](#mutability)). The directory is not a source of truth, and it is not a home for durable content:
8
+
9
+ - **Durable content.** Put instructions, a procedure, or a reference that a later session must find in the repository (its docs, `AGENTS.md`, or a README), or in a skill or rulebook when they apply across repositories. A later session looks there, not in the artifact directory.
10
+ - **Authority.** An artifact is not authority on the current state of code, design, or decisions. Treat what a search of artifacts turns up as history, and verify it against the repository, the tickets, and the pull requests.
11
+ - **Inputs to the same work.** A skill that reads an artifact as an input to the same piece of work, such as the plan that `implement-plan` executes or the change summary that `create-pr` publishes, uses the artifact as the workflow intends.
12
+
13
+ ## Directory structure
14
+
15
+ All artifacts are stored under a configurable base directory (`base_dir`, default `~/ai-artifacts`). Invoke the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) to resolve `artifact_base_dir`:
16
+
17
+ ```
18
+ {base_dir}/
19
+ └── projects/
20
+ └── {project-slug}/
21
+ ├── tickets/
22
+ │ └── {ticket-id}/
23
+ │ ├── {timestamp}_{slug}_{artifact-type}.md ← ticket-level artifacts (devlogs are written here when a ticket is in session)
24
+ │ ├── prototypes/ ← the ticket's prototype set, kept by `index-prototypes`
25
+ │ │ ├── manifest.json
26
+ │ │ ├── shots/{slug}-v{n}.png
27
+ │ │ └── {slug}-v{n}.html
28
+ │ ├── usability/ ← a usability assessment's lens reports and evidence, kept by `assess-usability`
29
+ │ │ ├── {lens}-report.md
30
+ │ │ └── {lens}/{finding-id}-{slug}.png
31
+ │ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
32
+ │ │ ├── findings.md
33
+ │ │ ├── inventory.md
34
+ │ │ ├── recommendations.md
35
+ │ │ ├── challenge.md
36
+ │ │ ├── dispositions.json
37
+ │ │ ├── preview/ ← the rendered comments shown at the confirmation
38
+ │ │ │ ├── dispositions-comment.md
39
+ │ │ │ └── comment-{issue}.md
40
+ │ │ └── rendered/ ← the rendered comments that are posted
41
+ │ │ ├── dispositions-comment.md
42
+ │ │ └── comment-{issue}.md
43
+ │ └── {run-id}/ ← review run directory
44
+ │ ├── {NN}_{role}_{artifact}.md
45
+ │ └── ...
46
+ ├── chats/
47
+ │ └── {timestamp}_{descriptive-title}.md
48
+ ├── deferred-findings/
49
+ │ └── {timestamp}_{slug}_deferred-findings.md ← project-scoped fallback when a ticket is not in session
50
+ ├── devlogs/
51
+ │ └── {timestamp}_{concise-title}.md ← project-scoped fallback when a ticket is not in session
52
+ └── plans/
53
+ └── {design-documents}.md
54
+ ```
55
+
56
+ ### Project slug
57
+
58
+ Always present under `projects/`, even when `{base_dir}/` is inside the project, so that an artifact's path has the same shape wherever `base_dir` lies. Invoke the bundled session-context deriver to obtain `project_slug`.
59
+
60
+ ### Ticket ID
61
+
62
+ Always present under `tickets/` within the project directory. If the work does not have a real ticket, auto-generate one: `{YYYYMMDD}-{4 random hex}` (e.g., `20260221-a3f2`).
63
+
64
+ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it names the directory: Under `ABC-`, branch `100` resolves to `tickets/ABC-100/`, the same directory as a branch containing the key `ABC-100`. A `#` prefix is dropped, because a GitHub issue's ID is its number, and branch `100` resolves to `tickets/100/`, as it does when the preference is not set. Changing the prefix sends later artifacts to a different directory; merge the two by moving the existing directory.
65
+
66
+ ### Prototype sets
67
+
68
+ `prototypes/` contains the ticket's one prototype set: the sources, the stored screenshots, and the manifest from which `index-prototypes` renders the set's index page. The page itself is rendered into the session's scratch directory for publishing and is not kept here.
69
+
70
+ ### Usability evidence
71
+
72
+ `usability/` contains the working files of the ticket's usability assessment: each lens's report and each lens's evidence, which is screenshots in a browser assessment and transcripts in a CLI assessment. The `usability-findings` artifact cites the evidence by paths relative to the ticket directory, so the evidence stays in the ticket directory. A CLI assessment's fixtures are scratch directories outside the ticket directory, and nothing keeps them.
73
+
74
+ ### Triage working files
75
+
76
+ `triage/` contains the working files of a triage of the ticket's findings: a local copy of the findings when they came from an artifact URL, the inventory, the recommendations that the challenger reads, the challenger's reply, the dispositions record from which the `dispositions` artifact is rendered, and the comments rendered from that record: `preview/` with placeholders for the confirmation, `rendered/` with every number for posting. The record stays here as a working file; the artifact is the rendered text.
77
+
78
+ ### Run directories
79
+
80
+ Run directories group artifacts from a review workflow cycle:
81
+
82
+ ```
83
+ projects/{project-slug}/tickets/{ticket-id}/{run-id}/
84
+ {timestamp}_{role}_{artifact}.md
85
+ ```
86
+
87
+ **Run ID format:** `{timestamp}-{mode}`
88
+
89
+ - **timestamp:** UTC, `YYYYMMDD-HHMMSSZ` (from the first artifact in the run)
90
+ - **mode:** `interactive`. Runs written by the retired orchestration engine have the historical mode `orchestrated`.
91
+
92
+ Example: `20260221-034100Z-interactive`
93
+
94
+ A ticket's **active run** is its newest run directory of mode `interactive`, by the timestamp in its name. A review is saved into the active run, and the author's response is saved into the run that contains the review, so a review, the response, and a re-review share one run. A new run directory is created, when the review is written, only when the ticket directory does not contain an active run. A run of mode `orchestrated` is never active. `resolve-review-run` applies this definition.
95
+
96
+ ## Path resolution
97
+
98
+ Skills resolve artifact directories by invoking the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) and reading `artifact_base_dir` and `project_slug` from the manifest JSON that it emits on stdout. This is the canonical method for all artifact path resolution. The deriver composes the manifest from the current preferences on every invocation and writes it to `.agents/{sanitized-branch}.branch-manifest.json` as a side effect.
99
+
100
+ When the deriver is not available (e.g., standalone scripts without Node.js), the manual fallback is:
101
+
102
+ 1. Read `artifacts.base_dir` from `.agents/preferences.yaml`
103
+ 2. If not found there, read from `~/.agents/preferences.yaml`
104
+ 3. If still not found, use the default base directory
105
+ 4. If `base_dir` is relative, resolve from project root. If absolute, use as-is.
106
+ 5. Read `project.slug` from `.agents/preferences.yaml`, falling back to `~/.agents/preferences.yaml`, then the bare directory name of the working directory.
107
+
108
+ ### Reader tolerance and authoring-time validation
109
+
110
+ The session-context deriver reads only the fields that it consumes (`artifacts.base_dir`, `artifacts.paths`, `project.slug`, `project.ticket_ref_prefix`, `scm`, `repository.slug`, `repository.default_remote.{name,default_branch}`). Unknown top-level keys, unknown nested keys, and keys for other tooling that shares `.agents/preferences.yaml` are silently tolerated: This file is a multi-tool surface (analogous to `.editorconfig` or `package.json`), not a codeassembly-owned namespace.
111
+
112
+ Schema validation against the `preferences.v1.json` schema is an authoring-time concern: Editor LSPs validate through the `$schema` reference at the top of the YAML, and `preferences-schema.unit.test.ts` validates the project-checked-in `.agents/preferences.yaml`. The reader does not validate against the schema at runtime; doing so would fail on legitimate keys owned by other tools.
113
+
114
+ The reader does still hard-fail on malformed YAML, missing git state, and shape problems on the fields that it consumes (e.g., `artifacts.base_dir` set to a non-string, `scm` set to a value outside the `github | bitbucket` enum). Per-field errors name the offending key path so that the user can locate the issue without reading the whole file.
115
+
116
+ ### Ticket-scoped paths
117
+
118
+ ```
119
+ {base_dir}/projects/{project-slug}/tickets/{ticket-id}/
120
+ ```
121
+
122
+ Ticket-level artifacts and run directories are both stored here. Invoke the bundled session-context deriver to obtain `ticket_id`, which includes any prefix other than `#` (see [Ticket ID](#ticket-id)).
123
+
124
+ ### Run paths
125
+
126
+ ```
127
+ {base_dir}/projects/{project-slug}/tickets/{ticket-id}/{run-id}/
128
+ ```
129
+
130
+ ### Non-ticket paths
131
+
132
+ | Category | Default path | Full default |
133
+ | ----------------- | ------------------- | ------------------------------------------------------- |
134
+ | chats | `chats` | `{base_dir}/projects/{project-slug}/chats/` |
135
+ | deferred-findings | `deferred-findings` | `{base_dir}/projects/{project-slug}/deferred-findings/` |
136
+ | devlogs | `devlogs` | `{base_dir}/projects/{project-slug}/devlogs/` |
137
+ | plans | `plans` | `{base_dir}/projects/{project-slug}/plans/` |
138
+
139
+ Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with one exception: `deferred-findings` is hardcoded and cannot be overridden.
140
+
141
+ Devlogs and deferred-findings artifacts are dual-homed: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket-id}/`; otherwise they fall back to the project-scoped paths above (`devlogs/` for devlogs, `deferred-findings/` for deferred-findings). All filenames in both types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
142
+
143
+ ## Naming conventions
144
+
145
+ ### Ticket-level artifacts
146
+
147
+ ```
148
+ {timestamp}_{slug}_{artifact-type}.md
149
+ ```
150
+
151
+ - **timestamp**: UTC, `YYYYMMDD-HHMMSSZ` format (e.g., `20260219-143000Z`)
152
+ - **slug**: Kebab-case descriptor drawn from work context, e.g., branch description (`improve-artifact-naming`) or commit subject (`fix-login-validation`). Max 60 chars, filesystem-safe.
153
+ - **artifact-type**: One of the registered types (see below)
154
+
155
+ When the ticket directory already contains artifacts for this change, reuse their slug; derive a fresh one only when the change's descriptor has changed. One change has one name, which keeps it legible where the enclosing path is not in view: an editor tab, a search result, an export.
156
+
157
+ ### Run artifacts (review workflow)
158
+
159
+ ```
160
+ {timestamp}_{role}_{artifact}.md
161
+ ```
162
+
163
+ - **timestamp**: UTC, `YYYYMMDD-HHMMSSZ` format
164
+ - **role**: `coder`, `overseer`, `reviewer` (extensible; this is a common roles list, not exhaustive)
165
+ - **artifact**: What the document is -- `change-summary`, `review`
166
+
167
+ Underscore separates all structural parts. Hyphens are free for use within any part (role names, artifact names, slugs).
168
+
169
+ Each role has a **roleType** classifying its workflow function. See the [roleType taxonomy](#roletype-taxonomy) in the run-index.json section below.
170
+
171
+ Artifact ordering follows the timestamp prefix.
172
+
173
+ Example run directory (a review, the author's response, and a re-review):
174
+
175
+ ```
176
+ {base_dir}/projects/codeassembly/tickets/1903/20261004-080000Z-interactive/
177
+ 20261004-080000Z_reviewer_review.md
178
+ 20261004-091500Z_coder_change-summary.md
179
+ 20261004-100000Z_reviewer_review.md
180
+ ```
181
+
182
+ Runs written by the retired orchestration engine name their artifacts `{NN}_{role}_{artifact}.md`, with a two-digit sequence number in place of the timestamp, and use historical roles and artifact types that only the engine wrote: the roles `architect`, `code-reviewer`, `code-simplification-reviewer`, `orchestrator`, `planner`, `silent-failure-reviewer`, and `test-reviewer`, and the artifact types listed under [Run artifacts](#run-artifacts-in-run-directories). `run-core` still parses them.
183
+
184
+ ## Universal artifact frontmatter
185
+
186
+ All skill- and subagent-authored artifacts begin with a YAML frontmatter block conforming to the canonical schema below. A single shape lets one parser serve every artifact type, and a single source of truth keeps the per-artifact sections free of duplication.
187
+
188
+ ```yaml
189
+ ---
190
+ provenance:
191
+ skill: <skill-name> # required: the skill or subagent that wrote this artifact
192
+ timestamp: <ISO 8601 UTC> # required: write time
193
+ baseSha: <short SHA> # optional: short SHA of origin/main; omit if unresolvable
194
+ isInteractive: true|false # required: true for interactive flows, false for a dispatched subagent
195
+ refinedBy: <skill-name> # optional: the skill that last processed/refined the artifact
196
+ model: <model id> # optional: present when an AI model authored the body
197
+ ticket_id: <id> # optional: omit when a ticket is not in session
198
+ ticket_ref: <display ref> # optional: omit when ticket_id is null
199
+ branch: <branch name> # required: raw branch_name from session context
200
+ commit: <short SHA of HEAD> # required: short HEAD SHA at write time
201
+ pr: <full URL> # optional: set only by PR-aware skills; omitted elsewhere
202
+ author: <name(s)> # optional: used by review artifacts
203
+ commits: [<sha>, ...] # optional: used by devlogs
204
+ run_id: <run id> # optional: set only by callers that write into, or link back to, a run directory
205
+ ---
206
+ ```
207
+
208
+ The `pull-request` and `merge` records do not have frontmatter. Each opens with a marker that names its reader and directs a reading agent to leave the record unedited, and the other artifacts do not state one:
209
+
210
+ <!-- include: ../../_partials/record-marker.md / -->
211
+
212
+ ### Field naming convention
213
+
214
+ Keys inside the `provenance:` block use **camelCase** (e.g., `baseSha`, `isInteractive`, `refinedBy`). All other top-level keys use **snake_case** (e.g., `ticket_id`, `ticket_ref`, `run_id`). This split preserves the existing convention used by 544+ historical artifacts and the consumer (`refine-plan`) that reads them, while keeping the rest of the schema consistent with the surrounding snake_case YAML.
215
+
216
+ ### Field definitions
217
+
218
+ The table below lists only the universal fields. Artifact-specific extensions (`provenance.iteration`, `session_type`, `tickets_created`, `title`, `scope`, `type`, `responding_to`, etc.) are documented in the per-artifact sections below.
219
+
220
+ | Field | Required | Description |
221
+ | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
222
+ | `provenance.skill` | yes | The skill or subagent that wrote the artifact (e.g., `create-devlog`, `plan-reviewer`). |
223
+ | `provenance.timestamp` | yes | ISO 8601 UTC timestamp of when the artifact was written. |
224
+ | `provenance.baseSha` | no | Short SHA of `origin/main` at write time. Omitted if unresolvable (no remote, shallow clone). |
225
+ | `provenance.isInteractive` | yes | `true` for interactive flows; `false` for a dispatched subagent. |
226
+ | `provenance.refinedBy` | no | The skill that last processed/refined the artifact (e.g., `refine-plan`). Records processing, not authorship. |
227
+ | `provenance.model` | no | The identifier of the model that authored the body (e.g., `claude-opus-4-7`). Omitted for human-authored or co-authored artifacts. |
228
+ | `ticket_id` | no | Ticket ID from session context, including any prefix other than `#` (see [Ticket ID](#ticket-id)). Omitted when a ticket is not in session. |
229
+ | `ticket_ref` | no | Human-readable ticket reference (e.g., `#537`, `MAC-68`). Omitted when `ticket_id` is omitted. |
230
+ | `branch` | yes | Current branch name from session context. Written as-is: no sanitization. |
231
+ | `commit` | yes | Short SHA of HEAD at write time. Resolved via `git rev-parse --short HEAD`. Distinct from `commits` (the devlog-specific list). |
232
+ | `pr` | no | Full PR URL (e.g., `https://github.com/{owner}/{repo}/pull/{n}`). Set only by PR-aware skills that have the URL; omitted by every other artifact; see [PR resolution](pr-resolution.md). |
233
+ | `author` | no | Human author of the work. Used by review artifacts when the reviewing surface records the code author. |
234
+ | `commits` | no | List of short SHAs summarized by the artifact. Used by devlogs. Distinct from `commit` (HEAD short SHA). |
235
+ | `run_id` | no | Run ID of the run directory to which the artifact belongs. Set only by the caller; `resolve-frontmatter.sh` emits it only from `--override run_id=<id>`. |
236
+
237
+ ### `commit` vs. `commits`
238
+
239
+ `commit` is a singular top-level field containing the short HEAD SHA at write time. Every artifact has one. `commits` is an optional list used only by devlogs, recording the SHAs whose changes the devlog summarizes. The two coexist and never conflict.
240
+
241
+ ### PR resolution
242
+
243
+ `resolve-frontmatter.sh` does not resolve `pr`. The field is set only by PR-aware skills that have the URL while composing frontmatter: `review-branch` and `respond-to-review` pass it via `--override pr=<url>`. Every other artifact omits `pr`. See [`pr-resolution.md`](pr-resolution.md) for the full contract.
244
+
245
+ ### Bespoke frontmatter composition
246
+
247
+ Most skills and subagents produce frontmatter by running `resolve-frontmatter.sh` in its default YAML mode and prepending the output verbatim. Two sites are deliberate exceptions and compose the YAML block themselves:
248
+
249
+ - `refine-plan`: The `provenance:` block is case-branched on the input artifact's existing provenance (preserving `skill`, `baseSha`, `isInteractive`, and `iteration` from the original authoring skill, with fallbacks when the input does not have provenance). The shell flag surface cannot express this conditional logic cleanly.
250
+ - `wrap-up` (deferred-findings artifact): `tickets_created` is a list of `{id, items}` objects, a structure that does not have a clean CLI expression and is best composed in the skill's own logic.
251
+
252
+ Both read the script's JSON output and write the YAML frontmatter themselves. The pattern is intentional, not a workaround; keep new skills on the YAML mode path unless they have a similarly structural reason to deviate.
253
+
254
+ ## Manifest creation
255
+
256
+ Frontmatter artifacts depend on `.agents/{sanitized-branch}.branch-manifest.json`. The manifest is composed by a bundled TypeScript helper at `{harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` (built from `packages/guidance/src/derive-session-context/` and deployed as a self-contained `.mjs`). Any caller can invoke it: main agents, subagents (whose tool set includes `{tool:Bash}`), and shell scripts like `resolve-frontmatter.sh`.
257
+
258
+ The manifest is not a dispatch-time precondition. `resolve-frontmatter.sh` invokes the bundled deriver itself on every call, so subagents that need a manifest do not depend on the dispatcher having run anything first.
259
+
260
+ Invocation surface:
261
+
262
+ ```bash
263
+ node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
264
+ ```
265
+
266
+ The deriver prints the manifest JSON to stdout and writes it to `.agents/{sanitized-branch}.branch-manifest.json` as a side effect. Because every invocation recomposes the derived fields from the current preferences and git state, a preference change takes effect on the next call. The file keeps `created_at` and the URLs written by the mutation flags (recorded in `explicit_urls`), and the deriver rewrites it only when its content changes. On the default branch, the deriver drops any stored `ticket_url` or `pr_url` per [Stored ticket URL](ticket-source-resolution.md#stored-ticket-url). Diagnostics are printed to stderr; exit 0 on success, 1 on hard failure (corrupt preferences, detached HEAD, schema-validation error).
267
+
268
+ When authoring a new skill that needs session-context fields: Invoke the bundled deriver and read the fields from the emitted JSON. Do not rely on any other caller having populated the manifest first: The deriver is the single derivation surface and is safe to call from any context.
269
+
270
+ ## Plan provenance
271
+
272
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extension:
273
+
274
+ | Field | Required | Description |
275
+ | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
276
+ | `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements. |
277
+
278
+ Plan-specific `provenance.skill` values include `design-and-plan`, `plan`, `plan-mode`, and `unknown` (when the authoring skill cannot be determined). `refinedBy` is the skill that last processed the plan (typically `refine-plan`).
279
+
280
+ ## Devlog frontmatter
281
+
282
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter). Devlogs typically include `commits` (the SHAs that the devlog summarizes) in addition to the universally-required fields. `provenance.skill` is `create-devlog`; `provenance.isInteractive` is `true`. `commits` is omitted for `working-tree` invocations.
283
+
284
+ ## Deferred-findings frontmatter
285
+
286
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extensions. The artifact is written when at least one finding became a created ticket or at least one finding was dropped; see [`wrap-up/SKILL.md`](../wrap-up/SKILL.md) Phase 4 Step 1 for the write conditions.
287
+
288
+ | Field | Required | Description |
289
+ | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
290
+ | `session_type` | yes | The session classification from wrap-up's Phase 1a (`interactive-dev`, `review`, or `research`). |
291
+ | `tickets_created` | no | List of `{id, items}` entries cross-referencing each created ticket to the wrap-up item IDs that it addresses. `items` is always a list (e.g., `[F1]` or `[F1, T2, R1]`). Omitted when empty. |
292
+
293
+ `provenance.skill` is `wrap-up`; `provenance.isInteractive` is `true`.
294
+
295
+ **Single-finding case**, a ticket addressing one finding:
296
+
297
+ ```yaml
298
+ tickets_created:
299
+ - id: '<number>'
300
+ items: [F1]
301
+ ```
302
+
303
+ **Batch case**, a single ticket addressing multiple findings, uses the same shape with additional IDs in `items`:
304
+
305
+ ```yaml
306
+ tickets_created:
307
+ - id: '<number>'
308
+ items: [F1, T2, R1]
309
+ ```
310
+
311
+ ## Change-summary frontmatter
312
+
313
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extensions consumed by downstream PR-creation skills (`create-pr`, `create-gh-pr`, `create-bitbucket-pr`):
314
+
315
+ | Field | Required | Description |
316
+ | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
317
+ | `title` | yes | The change-summary title, used as the proposed PR title. |
318
+ | `scope` | no | The consolidated record's scope (e.g., `agents`, `root`). Omitted if consolidation leaves other than one scope (see `title-templates.md`), or if entries are absent. |
319
+ | `type` | no | The consolidated record's work type (see `work-types.json`). Omitted if the change does not have entries. |
320
+ | `breaking` | no | `true` if the consolidated record is breaking. Omitted otherwise; it is never `false`. |
321
+ | `changes` | no | Each commit entry rendered through `commit.title_format`, oldest first. Omitted if the branch does not have a commit entry. |
322
+ | `ticket_type` | no | The work type that the linked ticket's labels name. Omitted if they name none or more than one, or if the labels were not read. |
323
+ | `override_scope` | no | The scope that the author set by hand, or `*` if the author did not set a scope. |
324
+ | `override_type` | no | The work type that the author set by hand, without a marker. |
325
+ | `override_breaking` | no | `true` if the author added the breaking marker by hand. Omitted otherwise. |
326
+
327
+ `scope`, `type`, and `breaking` contain the [consolidated record](change-record.md#terms), consolidated from the [change entries](change-record.md#terms) that the change summary drafted, so the labels, the pull-request title, and the `change-record` block all follow one record. `changes` is the separate commit-derived list: It records what the branch's commits declared, which a reviewer reads for a different question than the change entries answer.
328
+
329
+ Each override is recorded beside the field that it overrides rather than in its place. A skill that needs the effective record reads it from [`resolve-effective-record`](title-templates.md#resolve-effective-record) rather than applying the overrides itself.
330
+
331
+ **The change summary's body ends with the rendered `change-record` block**, which contains the change entries and the consolidated record for the pull request. `create-pr` copies the body from `## What` onward, so the block is copied into the pull-request body without being rendered again.
332
+
333
+ The frontmatter stays flat, whereas the `change-record` block nests the consolidated record, the overrides, and the entries, because the artifact store is an Obsidian vault and Obsidian's Properties editor does not handle nested maps. That is also why the entries are recorded in the block rather than as a nested frontmatter field.
334
+
335
+ The unified frontmatter shape places `provenance:` first, then top-level canonical fields (`branch`, `commit`, `pr`, `ticket_id`, `ticket_ref`, `run_id`), then the consumer extensions in the order the table above lists them. `commit:` and `ticket_id:` appear exactly once each and serve a dual role: canonical identity fields that downstream consumers may also read. This is the canonical example for any future skill that adds consumer-specific fields alongside canonical ones.
336
+
337
+ ## Ticket frontmatter
338
+
339
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extension, read by `review-branch` when it chooses between a local ticket snapshot and the remote issue:
340
+
341
+ | Field | Required | Description |
342
+ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
343
+ | `copies_remote` | no | `true` when the artifact's body is a copy of the ticket of record as written. Omitted otherwise; it is never `false`. |
344
+
345
+ **The field is a claim about the body, not a timestamp.** A remote that already contains the snapshot's content can only move ahead of it, so the claim stays true however far the remote later advances, and `review-branch` reads it as a precedence rule rather than as a value to compare. This is why the snapshot records _that_ it copied rather than _when_: An exact source timestamp would require a re-fetch after every remote write, since `gh issue edit` does not return an `updatedAt`, and would misstate what the snapshot contains when a concurrent edit was made between the write and that fetch.
346
+
347
+ **Omission is meaningful, and is the default.** The field is set when the artifact's body and the ticket of record's body are known to agree, whether because a remote write of that body succeeded or because the body was adopted from the remote unchanged. A snapshot whose body was neither written to the remote nor taken from it is the newer contract, which the absent field indicates: A write that failed, and a producer that deliberately kept its revision local, both leave the field off. A snapshot written before the field existed does not have the field either, and `review-branch` compares it by filename recency exactly as it does today.
348
+
349
+ `align-ticket-with-implementation`, `create-ticket`, and `design-and-plan` write the field, each from what it already knows at save time about that agreement; each states its own condition. All three emit it through the frontmatter script's `--extra copies_remote=true` flag, the extension surface that the consumer fields above already use.
350
+
351
+ ## run-index.json
352
+
353
+ Machine-readable metadata for a run directory. The retired orchestration engine wrote it; the current skills do not. `run-core` parses it.
354
+
355
+ Every example and value list in this section and in [V3 format](#v3-format-event-sourced-runs) describes runs written by the retired engine, so its roles, agents, phases, and modes are historical values.
356
+
357
+ ### Schema
358
+
359
+ > **Note:** The following examples show v2 format. The engine's last runs use v3 (event-sourced) -- see the [V3 format](#v3-format-event-sourced-runs) section below.
360
+
361
+ **Initial write** (at run start):
362
+
363
+ ```json
364
+ {
365
+ "version": 2,
366
+ "context": {
367
+ "runId": "20260221-034100Z-orchestrated",
368
+ "projectSlug": "williamthorsen-configs-macos",
369
+ "ticketId": "MAC-68",
370
+ "projectRoot": "/Users/william/repos/configs/macos",
371
+ "branch": "mac-68/feat/improve-artifact-naming",
372
+ "task": "Implement artifact naming improvements",
373
+ "startedAt": "2026-02-21T03:41:00Z",
374
+ "completedAt": null,
375
+ "status": "in_progress",
376
+ "phases": {},
377
+ "phaseDecisions": {}
378
+ },
379
+ "config": {
380
+ "pipeline": ["architecture", "planning", "implementation", "review-cycle"],
381
+ "externalPlan": false,
382
+ "mergeBaseSha": "abc1234",
383
+ "diffBase": "main",
384
+ "maxReviewRounds": 3,
385
+ "effort": "medium",
386
+ "approvalThreshold": "medium",
387
+ "budgetThreshold": "medium",
388
+ "mode": "orchestrated",
389
+ "model": "claude-opus-4-6"
390
+ },
391
+ "artifacts": []
392
+ }
393
+ ```
394
+
395
+ **Final state** (at run completion):
396
+
397
+ ```json
398
+ {
399
+ "version": 2,
400
+ "context": {
401
+ "runId": "20260221-034100Z-orchestrated",
402
+ "projectSlug": "williamthorsen-configs-macos",
403
+ "ticketId": "MAC-68",
404
+ "projectRoot": "/Users/william/repos/configs/macos",
405
+ "branch": "mac-68/feat/improve-artifact-naming",
406
+ "task": "Implement artifact naming improvements",
407
+ "startedAt": "2026-02-21T03:41:00Z",
408
+ "completedAt": "2026-02-21T04:16:00Z",
409
+ "status": "completed",
410
+ "phaseDecisions": {
411
+ "architecture": { "run": true, "disposition": "executed", "reason": "External plan requires validation" },
412
+ "planning": { "run": true, "disposition": "executed", "reason": "External plan present" },
413
+ "implementation": { "run": true, "disposition": "executed" },
414
+ "review-cycle": { "run": true, "disposition": "executed" },
415
+ "parallelReview": { "run": true, "disposition": "executed" },
416
+ "codeSimplifier": { "run": true, "disposition": "executed" },
417
+ "holisticReview": { "run": true, "disposition": "executed" }
418
+ },
419
+ "phases": {
420
+ "architecture": {
421
+ "status": "completed",
422
+ "impactLevel": "moderate",
423
+ "startedAt": "2026-02-21T03:41:30Z",
424
+ "completedAt": "2026-02-21T03:42:00Z"
425
+ },
426
+ "planning": {
427
+ "status": "completed",
428
+ "stepCount": 5,
429
+ "startedAt": "2026-02-21T03:42:10Z",
430
+ "completedAt": "2026-02-21T03:43:00Z"
431
+ },
432
+ "implementation": {
433
+ "status": "completed",
434
+ "startedAt": "2026-02-21T03:43:10Z",
435
+ "completedAt": "2026-02-21T03:45:00Z"
436
+ },
437
+ "parallelReview": {
438
+ "status": "completed",
439
+ "startedAt": "2026-02-21T03:45:10Z",
440
+ "completedAt": "2026-02-21T04:10:00Z",
441
+ "aggregatedCriticality": "medium",
442
+ "reviewers": {
443
+ "reviewer": {
444
+ "status": "completed",
445
+ "criticality": "medium",
446
+ "reReviewCriticality": "low",
447
+ "startedAt": "2026-02-21T03:45:10Z",
448
+ "completedAt": "2026-02-21T03:47:00Z"
449
+ },
450
+ "silent-failure-reviewer": {
451
+ "status": "completed",
452
+ "criticality": "low",
453
+ "startedAt": "2026-02-21T03:45:10Z",
454
+ "completedAt": "2026-02-21T03:47:00Z"
455
+ },
456
+ "test-reviewer": { "status": "skipped", "reason": "no source or test files changed" },
457
+ "code-reviewer": {
458
+ "status": "completed",
459
+ "criticality": "medium",
460
+ "reReviewCriticality": "none",
461
+ "startedAt": "2026-02-21T03:45:10Z",
462
+ "completedAt": "2026-02-21T03:47:00Z"
463
+ }
464
+ },
465
+ "coderFixCycleRan": true,
466
+ "selectiveReReview": {
467
+ "ran": true,
468
+ "reviewersDispatched": ["reviewer", "code-reviewer"],
469
+ "additionalFixCycleRan": false
470
+ },
471
+ "iterations": [
472
+ {
473
+ "reviewers": ["reviewer", "silent-failure-reviewer", "code-reviewer"],
474
+ "dispatchedAt": "2026-02-21T03:45:10Z",
475
+ "reviewsCompletedAt": "2026-02-21T03:47:00Z",
476
+ "coderFixStartedAt": "2026-02-21T03:47:30Z",
477
+ "coderFixCompletedAt": "2026-02-21T04:00:00Z"
478
+ },
479
+ {
480
+ "reviewers": ["reviewer", "code-reviewer"],
481
+ "dispatchedAt": "2026-02-21T04:00:30Z",
482
+ "reviewsCompletedAt": "2026-02-21T04:10:00Z"
483
+ }
484
+ ]
485
+ },
486
+ "codeSimplifier": {
487
+ "status": "completed",
488
+ "ran": true,
489
+ "actionableFindings": true,
490
+ "coderFixCycleRan": true,
491
+ "startedAt": "2026-02-21T04:10:10Z",
492
+ "completedAt": "2026-02-21T04:12:00Z"
493
+ },
494
+ "holisticReview": {
495
+ "status": "completed",
496
+ "criticality": "none",
497
+ "startedAt": "2026-02-21T04:12:10Z",
498
+ "completedAt": "2026-02-21T04:15:00Z"
499
+ }
500
+ }
501
+ },
502
+ "config": {
503
+ "pipeline": ["architecture", "planning", "implementation", "review-cycle"],
504
+ "externalPlan": false,
505
+ "mergeBaseSha": "abc1234",
506
+ "diffBase": "main",
507
+ "maxReviewRounds": 3,
508
+ "effort": "medium",
509
+ "approvalThreshold": "medium",
510
+ "budgetThreshold": "medium",
511
+ "mode": "orchestrated",
512
+ "model": "claude-opus-4-6"
513
+ },
514
+ "artifacts": [
515
+ {
516
+ "filename": "01_orchestrator_run-manifest.md",
517
+ "role": "orchestrator",
518
+ "roleType": "orchestrator",
519
+ "agent": "orchestrator",
520
+ "type": "run-manifest",
521
+ "phase": "initialization",
522
+ "createdAt": "2026-02-21T03:41:00Z"
523
+ },
524
+ {
525
+ "filename": "02_architect_architecture.md",
526
+ "role": "architect",
527
+ "roleType": "analyst",
528
+ "agent": "orchestrated-architect",
529
+ "type": "architecture",
530
+ "phase": "architecture",
531
+ "createdAt": "2026-02-21T03:42:00Z"
532
+ },
533
+ {
534
+ "filename": "03_planner_orchestration-plan.md",
535
+ "role": "planner",
536
+ "roleType": "planner",
537
+ "agent": "orchestrated-planner",
538
+ "type": "orchestration-plan",
539
+ "phase": "planning",
540
+ "createdAt": "2026-02-21T03:43:00Z"
541
+ },
542
+ {
543
+ "filename": "04_coder_change-summary.md",
544
+ "role": "coder",
545
+ "roleType": "author",
546
+ "agent": "orchestrated-coder",
547
+ "type": "change-summary",
548
+ "phase": "implementation",
549
+ "createdAt": "2026-02-21T03:45:00Z"
550
+ },
551
+ {
552
+ "filename": "05_reviewer_review.md",
553
+ "role": "reviewer",
554
+ "roleType": "reviewer",
555
+ "agent": "orchestrated-reviewer",
556
+ "type": "review",
557
+ "phase": "parallelReview",
558
+ "createdAt": "2026-02-21T03:47:00Z",
559
+ "iteration": 1
560
+ },
561
+ {
562
+ "filename": "06_silent-failure-reviewer_silent-failure-review.md",
563
+ "role": "silent-failure-reviewer",
564
+ "roleType": "reviewer",
565
+ "agent": "aspect-silent-failure-reviewer",
566
+ "type": "silent-failure-review",
567
+ "phase": "parallelReview",
568
+ "createdAt": "2026-02-21T03:47:00Z",
569
+ "iteration": 1
570
+ },
571
+ {
572
+ "filename": "07_code-reviewer_code-review.md",
573
+ "role": "code-reviewer",
574
+ "roleType": "reviewer",
575
+ "agent": "aspect-code-reviewer",
576
+ "type": "code-review",
577
+ "phase": "parallelReview",
578
+ "createdAt": "2026-02-21T03:47:00Z",
579
+ "iteration": 1
580
+ },
581
+ {
582
+ "filename": "08_coder_change-summary.md",
583
+ "role": "coder",
584
+ "roleType": "author",
585
+ "agent": "orchestrated-coder",
586
+ "type": "change-summary",
587
+ "phase": "parallelReview",
588
+ "createdAt": "2026-02-21T04:00:00Z",
589
+ "note": "Addresses aggregated findings from iteration 1"
590
+ },
591
+ {
592
+ "filename": "09_reviewer_review.md",
593
+ "role": "reviewer",
594
+ "roleType": "reviewer",
595
+ "agent": "orchestrated-reviewer",
596
+ "type": "review",
597
+ "phase": "parallelReview",
598
+ "createdAt": "2026-02-21T04:15:00Z",
599
+ "iteration": 2
600
+ },
601
+ {
602
+ "filename": "10_orchestrator_run-summary.md",
603
+ "role": "orchestrator",
604
+ "roleType": "orchestrator",
605
+ "agent": "orchestrator",
606
+ "type": "run-summary",
607
+ "phase": "summary",
608
+ "createdAt": "2026-02-21T04:16:00Z"
609
+ }
610
+ ]
611
+ }
612
+ ```
613
+
614
+ **Backward compatibility:** Old `run-index.json` data without top-level `status` fields on phase objects (e.g., `parallelReview` without a `status` field) is treated as completed by the factory visualization. The factory only blocks advancement past a phase when `status` is explicitly `"in_progress"`.
615
+
616
+ ### roleType taxonomy
617
+
618
+ Each role maps to one of five workflow-function types. Only the retired orchestration engine wrote the `orchestrator`, `analyst`, and `planner` types, and every `reviewer` role but `reviewer`:
619
+
620
+ | roleType | Description | Example roles |
621
+ | -------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
622
+ | `orchestrator` | Coordinates phases and manages run state | `orchestrator` |
623
+ | `analyst` | Assesses impact and provides architectural guidance | `architect` |
624
+ | `planner` | Produces implementation plans | `planner` |
625
+ | `author` | Writes or modifies project code | `coder` |
626
+ | `reviewer` | Evaluates code and produces findings | `reviewer`, `code-reviewer`, `code-simplification-reviewer`, `silent-failure-reviewer`, `test-reviewer` |
627
+
628
+ ### Artifact entry fields
629
+
630
+ | Field | Required | Description |
631
+ | ----------- | -------- | -------------------------------------------------------------------------------------- |
632
+ | `filename` | yes | Artifact filename (without directory path) |
633
+ | `role` | yes | Filename role segment (e.g., `reviewer`, `code-reviewer`) |
634
+ | `roleType` | yes | Workflow function (one of: `orchestrator`, `analyst`, `planner`, `author`, `reviewer`) |
635
+ | `agent` | yes | {tool:Task} `subagent_type` value (e.g., `plan-reviewer`) |
636
+ | `type` | yes | Artifact type (e.g., `review`, `change-summary`) |
637
+ | `phase` | yes | Phase that produced this artifact (camelCase, matches `phases` object keys) |
638
+ | `createdAt` | yes | ISO 8601 timestamp |
639
+ | `iteration` | no | Review iteration number (for `parallelReview` phase) |
640
+ | `note` | no | Free-text context about the artifact |
641
+
642
+ ### Phase values
643
+
644
+ Phase values use camelCase and match the keys in the `phases` object. Only the retired orchestration engine wrote them:
645
+
646
+ - `initialization`: Run setup and manifest creation
647
+ - `architecture`: Architectural impact assessment
648
+ - `planning`: Implementation planning
649
+ - `implementation`: Code authoring
650
+ - `parallelReview`: Parallel review and fix cycles
651
+ - `codeSimplifier`: Code simplification pass
652
+ - `holisticReview`: Final comprehensive review
653
+ - `summary`: Run summary generation
654
+
655
+ ### Version field
656
+
657
+ The `version` field distinguishes schema formats: absent = v1 (`status.json` era), `2` = v2 (inline state in `run-index.json`), `3` = v3 (event-sourced). The engine's last runs use v3. Runs in v1 and v2 remain valid.
658
+
659
+ ## V3 format: Event-sourced runs
660
+
661
+ V3 separates static run metadata from dynamic state. The `run-index.json` file contains only the header; all state transitions are recorded as events in a companion `run-log.jsonl` file. V3 is a read-only format: Only the retired orchestration engine wrote it, and run-core and the factory read it.
662
+
663
+ ### V3 header schema
664
+
665
+ `run-index.json` with `version: 3` contains only the header, without `phases`, `phaseDecisions`, `status`, or `completedAt` fields in `context`. `completedAt`, present once the run completed, is at the top level.
666
+
667
+ Context fields: `runId`, `projectSlug`, `ticketId?`, `projectRoot`, `branch`, `task`, `startedAt`.
668
+
669
+ Config fields: `externalPlan?`, `mergeBaseSha?`, `diffBase?`, `maxReviewRounds?`, `effort?`, `approvalThreshold?`, `budgetThreshold?`, `mode?`, `model?`. Additional fields are preserved (loose schema).
670
+
671
+ ### Run-log.jsonl
672
+
673
+ Companion file in the same run directory. Each line is a JSON object (JSONL format) representing one `RunEvent`. The engine appended events in order, timestamped each with field `t` (ISO 8601), and validated each against the `runEventSchema` discriminated union on the `event` field before appending it.
674
+
675
+ ### Event types
676
+
677
+ All 13 valid event types and their required fields. Fields suffixed with `?` are optional. Only the retired orchestration engine wrote these events. Usage fields (`tokens`, `toolUses`, `durationMs`) are present on its later runs, which recorded {tool:Task} result metrics; older runs omit them:
678
+
679
+ | Event type | Key fields |
680
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
681
+ | `run_started` | _(none beyond `t`, `event`)_ |
682
+ | `run_completed` | `status` (`completed`\|`failed`\|`needs_manual_review`) |
683
+ | `run_failed` | `status`, `reason?` |
684
+ | `phase_decision` | `phase` (string), `run` (boolean), `reason?` |
685
+ | `phase_started` | `phase` (one of: `architecture`\|`planning`\|`implementation`\|`review`\|`simplifier`\|`holistic`) |
686
+ | `phase_completed` | `phase`, `status` (one of: `completed`\|`skipped`\|`failed`\|`in_progress`\|`approved`), `data?` (record), `tokens?`, `toolUses?`, `durationMs?` |
687
+ | `reviewer_dispatched` | `reviewer` (string) |
688
+ | `reviewer_completed` | `reviewer`, `status` (`completed`\|`skipped`\|`failed`), `criticality` (`none`\|`low`\|`medium`\|`high`), `tokens?`, `toolUses?`, `durationMs?` |
689
+ | `coder_fix_started` | `iteration` (number) |
690
+ | `coder_fix_completed` | `iteration` (number), `tokens?`, `toolUses?`, `durationMs?` |
691
+ | `re_review_dispatched` | `reviewers` (string array) |
692
+ | `re_review_completed` | `criticalities` (record: reviewer name -> criticality), `tokens?`, `toolUses?`, `durationMs?` |
693
+ | `artifact_written` | `filename`, `role`, `roleType`, `agent`, `type`, `phase`, `iteration?`, `note?` |
694
+
695
+ ### Run directory layout (v3)
696
+
697
+ ```
698
+ {base_dir}/projects/{projectSlug}/tickets/{ticketId}/{runId}/
699
+ run-index.json <- v3 header (top-level completedAt once the run completed)
700
+ run-log.jsonl <- append-only event log (one JSON object per line)
701
+ {NN}_{role}_{artifact}.md <- artifact files (sequential counter)
702
+ ```
703
+
704
+ Runs are always nested under a ticket ID directory. When its caller did not provide a ticket ID, the engine generated one in the format `{YYYYMMDD}-{4 random hex}` (e.g., `20260302-a3f2`). Caller-supplied ticket IDs with a leading `#` were sanitized to bare numbers before use in file paths (e.g., `#152` became `152`).
705
+
706
+ ### Run ID format (v3)
707
+
708
+ `{yyyymmdd}-{hhmmss}Z`, generated by the engine. This differs from the historical v2 format `{yyyymmdd}-{hhmmss}Z-orchestrated`.
709
+
710
+ ### Event folding
711
+
712
+ Full run state (phases, artifacts, review rounds, criticalities) is reconstructed from `run-log.jsonl` by run-core's `foldEvents` function, which returns a `CanonicalRunStatus`.
713
+
714
+ ### Backward compatibility
715
+
716
+ V2 and v1 `run-index.json` formats remain supported by the Factory consumer.
717
+
718
+ ## Artifact types
719
+
720
+ The [Mutability](#mutability) rule applies to every type below: A saved artifact is a point-in-time record, corrected when it got its own subject wrong and never edited toward what has happened since, and a later flow that revises one writes a new artifact rather than editing it.
721
+
722
+ ### Run artifacts (in run directories)
723
+
724
+ | Artifact | Purpose | Dispositions? |
725
+ | ---------------- | --------------------------------------------------------- | -------------------------------------- |
726
+ | `change-summary` | What changed + dispositions on prior findings (if any) | Yes, when responding to a prior review |
727
+ | `review` | Code review findings + dispositions on own prior findings | Only for own prior findings |
728
+
729
+ Runs written by the retired orchestration engine also contain the historical types `architecture`, `code-review`, `code-simplification-review`, `holistic-review`, `orchestration-plan`, `plan`, `run-manifest`, `run-summary`, `silent-failure-review`, and `test-review`.
730
+
731
+ The first `coder_change-summary` in a run does not have dispositions (nothing to respond to). Subsequent ones embed dispositions alongside the change summary.
732
+
733
+ ### Ticket-level artifacts
734
+
735
+ - `brief`: The shared brief that a round of prototype builders receives; `prepare-prototype-brief` saves it at its checkpoint
736
+ - `change-summary`: Branch change summary for PRs
737
+ - `comparison`: Findings across a round of prototypes: the points on which they agree and those on which they diverge, a table of every distinctive idea with an empty decision, and which decisions the round leaves open; `prepare-prototype-brief` saves it after the index
738
+ - `deferred-findings`: Record of findings deferred during a `wrap-up` session, with cross-references to created tickets (falls back to non-ticket path when a ticket is not in session)
739
+ - `dispositions`: The rendered dispositions of a triage of findings, the text that `triage-spike-findings` posts on the triage ticket: every item with its disposition, its confidence and value, where it went, and its reason, with the challenge's summary; the JSON record from which it is rendered stays in `triage/`
740
+ - `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
741
+ - `idea-decisions`: The idea table of a round of prototypes with the decision on each idea filled; `prepare-prototype-brief` saves it after the developer decides each idea, and the end vision cites it
742
+ - `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
743
+ - `plan`: Implementation plan document
744
+ - `plan-review`: Plan review findings (completeness and correctness analysis)
745
+ - `plan-v2`: Refined implementation plan after review and revision
746
+ - `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
747
+ - `refinement-log`: The accepted changes of one session of `refine-prototype`, grouped under the id of the version that each one entered, with the transplants' sources and the open forks; the end vision reads it with the `idea-decisions` artifact
748
+ - `review`: Code review (ticket-level, commit scope)
749
+ - `ticket`: Issue ticket
750
+ - `usability-brief`: The brief that every lens of a usability assessment reads: the medium, the targets and their write rules, the lenses with their minimum use cases, and the exclusions; `assess-usability` saves it at its checkpoint
751
+ - `usability-findings`: The merged findings of a usability assessment, ranked by effect and reach, with the use-case outcomes, the ideas, the proposed groupings, the residual unknowns, and the lens reports; `assess-usability` saves it, and `triage-spike-findings` reads it
752
+
753
+ ### Non-ticket artifacts
754
+
755
+ - `chat-summary`: Conversation summary
756
+
757
+ ## Run lifecycle
758
+
759
+ ### Starting a run
760
+
761
+ Either role can produce a run's first artifact. Common patterns:
762
+
763
+ - Coder produces `coder_change-summary`, then reviewer produces `reviewer_review`
764
+ - Reviewer produces `reviewer_review` directly (human is the coder)
765
+
766
+ ### Iteration pattern
767
+
768
+ 1. `reviewer_review` contains findings
769
+ 2. `coder_change-summary` contains fixes + dispositions on prior findings
770
+ 3. `reviewer_review` reads all prior artifacts chronologically: Dispositions are embedded in the documents that contain them
771
+
772
+ ### Termination
773
+
774
+ Run ends when the parties do not have any further actionable input. The last artifact can be from any role.
775
+
776
+ ### Stacking
777
+
778
+ An iteration can contain multiple reviews (e.g., `reviewer_review` + `overseer_review`). The next `coder_change-summary` addresses all of them.
779
+
780
+ ## Disposition rules
781
+
782
+ ### Embedding
783
+
784
+ Dispositions are stated in the document produced by the responding role. No separate disposition artifact.
785
+
786
+ ### Scope
787
+
788
+ A role can only disposition findings directed at it or its own prior findings. The overseer is exempt (arbiter authority).
789
+
790
+ | Role | Can disposition | Cannot disposition |
791
+ | -------- | ------------------------------------------------------------ | -------------------------------------------------------- |
792
+ | Coder | Reviewer/overseer findings on the code | Own changes (self-review) |
793
+ | Reviewer | Own prior findings (revise/withdraw in light of new context) | Coder rejections (re-raise as escalated finding instead) |
794
+ | Overseer | Any finding (arbiter authority) | n/a |
795
+
796
+ ## Finding scheme (F/W/T/R/S + legacy suffix)
797
+
798
+ Used by review-producing skills and agents for structured code review findings. Every finding (F/W/T/R/S) must clear the [Proposed-change gate](#proposed-change-gate) and the [Actionability gate](#actionability-gate) before it is emitted.
799
+
800
+ | ID | Category | Icon | Criticality | Merge-blocking? |
801
+ | ------------------ | -------------- | ---- | ----------- | -------------------------- |
802
+ | `F{n}` | FIXME | 🚨 | `high` | Always |
803
+ | `W{n}` | Warning | ⚠️ | `medium` | Unless justified |
804
+ | `T{n}` | TODO | 📋 | `low` | Never (ticket if deferred) |
805
+ | `R{n}` | Recommendation | 🧠 | `low` | Never (note if deferred) |
806
+ | `S{n}` | Suggestion | ☝️ | `low` | Never (piggyback only) |
807
+ | `{F,W,T,R,S}{n}-L` | Legacy | 🔍 | excluded | Never |
808
+
809
+ Consumers that present or report findings (review skills, wrap-up, response artifacts) should render the icon alongside the prefix or category to give an at-a-glance severity cue. The Legacy row uses 🔍 regardless of underlying severity letter.
810
+
811
+ ### Proposed-change gate
812
+
813
+ A finding is a proposed change. Name the change before writing the finding: A problem is an observation, not a finding, when you cannot pair it with a change that you would make. Record it as an insight when it contains knowledge that a future reader needs (see [Insight gate](#insight-gate)), and drop it otherwise.
814
+
815
+ Naming the change is not settling it. When more than one change would resolve the problem and choosing among them depends on knowledge that the author has, such as which callers can recover or which of two contracts is the intended one, name the alternatives and leave the choice to them. That is a finding, and the reviewer states whose call it is rather than picking for them. Alternatives are named because the author knows something the reviewer does not, never because the reviewer could not settle on a fix.
816
+
817
+ A finding therefore has one of exactly two shapes, and consumers may rely on the pair being exhaustive: a single named change, or a choice among named alternatives for the author to make. Only the absence of any envisioned change disqualifies a finding.
818
+
819
+ ### Actionability gate
820
+
821
+ A named change still has to be worth making. Decide at this gate whether it is, having established at the [Proposed-change gate](#proposed-change-gate) that a change exists.
822
+
823
+ A finding costs more than its line length: the reader's time, the tokens spent asking you to reconsider it, the author's triage, and every later reader who reads both the finding and its rejection. Treat emitting any finding as taking on a burden of proof, weighed against that full cost, never against its line length.
824
+
825
+ This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail, costs every reader attention once that cost outweighs the decision that it enables.
826
+
827
+ **Hedging language is a delete trigger, not a softening device.** If a finding's own qualifiers make it irrelevant, it does not belong. Drop it. If the condition genuinely holds now, drop the qualifier instead and state the finding plainly. Disqualifying signs include:
828
+
829
+ - "No action this PR / no action required / not actionable here"
830
+ - "Just capturing a thought" / "mentioning so the next contributor…"
831
+ - "Call it out only if X" / "consider when Y" / "would matter once Z" / "revisit if/when…", when the named condition is not currently met
832
+ - A body that endorses the current state ("the current shape is correct") and then proposes a change anyway: incoherent, since the body does not have any recommendation left once you have endorsed the status quo
833
+
834
+ Self-test before writing each finding: _Would I make this change right now if it were my code?_ If no, it is not a finding.
835
+
836
+ Where dropped content goes: An observation with lasting value beyond this change belongs in a follow-up ticket, a `capture-event` note, or a prose section (e.g., Technical Assessment); otherwise drop it. Silence is the correct output.
837
+
838
+ This holds at the whole-review level too: A review that does not report any findings is a complete, valid, mergeable result, not a failure to find something. Rigor shows in the examination, not in the length of the findings list.
839
+
840
+ Apply this gate **hardest** to R and S, whose low criticality bar invites filler.
841
+
842
+ ### Category criteria
843
+
844
+ **Authored-choice gate (W/T/R/S):** A proposed change must be a genuine improvement, not merely an alternative: A valid authored choice is not a defect. The per-category criteria set the evidence bar.
845
+
846
+ **FIXME (F).** Must fix before merge:
847
+
848
+ - Bugs: Incorrect logic, unhandled error paths, data loss risks
849
+ - Security: Injection, auth bypass, exposed secrets
850
+ - Contract violations: Breaking API changes, type unsafety
851
+ - Test failures: Tests that don't pass or don't test what they claim
852
+
853
+ **Warning (W).** Questionable, may block merge:
854
+
855
+ - Missing edge case handling that could cause runtime errors
856
+ - Convention violations that affect maintainability
857
+ - Decisions that seem wrong but may be intentional (require justification)
858
+ - **Gate:** A warning must reflect a judgment call by the author about a defensible risk of functional or maintainability harm, not a mechanical oversight or a cosmetic issue. If automated tooling (linters, type-checkers, CI) would catch the issue, it is not a warning; classify as Suggestion at most. If the issue does not pose a defensible risk of functional or maintainability harm (e.g., a typo in a comment), do not raise it at any tier.
859
+
860
+ **TODO (T).** Should fix, not in this PR:
861
+
862
+ - Missing or inadequate tests for new functionality
863
+ - Performance issues with measurable impact
864
+ - Incomplete error handling that won't cause immediate failures
865
+
866
+ **Recommendation (R).** Advisable but discretionary:
867
+
868
+ - Better patterns available in the codebase
869
+ - Opportunities to reduce complexity
870
+ - Architectural improvements worth considering
871
+ - **Gate:** Raise only when the change is plausibly better: improved clarity, reduced complexity, better-aligned pattern. "Another valid way to write it" does not qualify. The finding must also clear the [Actionability gate](#actionability-gate).
872
+
873
+ **Suggestion (S).** Optional improvement:
874
+
875
+ - Better naming or code organization
876
+ - Additional test cases for edge cases
877
+ - Documentation improvements
878
+ - **Gate:** Raise only when the change aligns with a codebase convention violated by the code, has measurable improvement evidence (perf, correctness, readability with a concrete example), or follows a widely accepted external standard (linter rule, language spec, ecosystem norm with a citation). "Another valid way to write it" does not qualify. The finding must also clear the [Actionability gate](#actionability-gate).
879
+
880
+ **Legacy (`-L` suffix).** Pre-existing code observation:
881
+
882
+ - Issues in code not authored in this branch. Use the same severity letter as the equivalent author finding.
883
+ - The `-L` is a marker, not part of the ID: The ID is the number in front of it. Assign that number from the shared per-letter sequence as if this were an author finding, then append `-L`. Example: After author findings `F1`, `F2`, the first legacy FIXME is `F3-L`.
884
+ - Set the `**Severity:**` field to `{severity} (legacy)`, e.g., `critical (legacy)`, `warning (legacy)`, `suggestion (legacy)`
885
+ - Frame as future opportunities, not current defects
886
+ - Never count against the review score
887
+
888
+ ### Overall criticality mapping
889
+
890
+ | Highest finding present | Criticality | Meaning |
891
+ | ----------------------- | ----------- | -------------------------- |
892
+ | None, or only `-L` | `none` | No authored findings |
893
+ | S, R, and/or T (no W/F) | `low` | Deferrable items available |
894
+ | W (no F) | `medium` | Real issues to address |
895
+ | F | `high` | Must fix before merge |
896
+
897
+ Criticality classifies; it does not decide what a reviewer shows the user. Legacy-only maps to `none` because it does not contain any authored finding, while a legacy-only review still renders the post-review findings menu with its full option pool, in which a human can weigh a drive-by. The two axes differ on purpose.
898
+
899
+ ### Re-review severity escalation
900
+
901
+ `S → R → T → W → F`. Legacy (`-L`) findings are never escalated.
902
+
903
+ ## Knowledge items
904
+
905
+ Knowledge items capture observations and learnings worth preserving. They are not findings: They do not have a criticality and are never merge-blocking. They belong wherever knowledge is worth keeping: housekeeping artifacts (wrap-up inventories, chat summaries, devlogs) and, when they clear the Insight gate below, review artifacts.
906
+
907
+ | ID | Category | Icon | Kind |
908
+ | ------ | -------- | ---- | --------- |
909
+ | `I{n}` | Insight | 💡 | knowledge |
910
+
911
+ Consumers that present insights (`wrap-up`, `summarize-chat`, review skills and reviewer agents) should render the icon alongside the prefix or label to mirror the convention used for findings.
912
+
913
+ ### Insight gate
914
+
915
+ An insight is the deliberate complement to a finding: A finding gives the author a decision to act on now; an insight preserves knowledge that a future reader would otherwise rediscover. Reviewers may emit insights, but only through a gate as strict as the [Actionability gate](#actionability-gate): "no severity, no action" is exactly the low bar that invites filler.
916
+
917
+ Emit an insight only when it is **non-obvious knowledge without which a future reader is materially worse off**, and name that benefit. "A thing I noticed" does not qualify, nor does anything the code, its comments, or its tests already make plain.
918
+
919
+ **Insight vs. Suggestion (`S`).** Both are non-blocking, so they are easy to conflate; the test is whether an action is implied. An `S` proposes a change to make in this code now (and must clear the Actionability gate); an `I` records knowledge without an attached action. When an item implies a change that the author should weigh, it is an `S`, not an insight. When in doubt with any action implied, classify it as `S`.
920
+
921
+ Insights never have criticality, never block a merge, and never count toward a review score or the [Overall criticality mapping](#overall-criticality-mapping).
922
+
923
+ ## Artifact lifecycle
924
+
925
+ - **Active**: Artifact is current and relevant
926
+ - **Stale**: Branch has been merged or deleted, and artifact is 30+ days old
927
+
928
+ ### Mutability
929
+
930
+ A saved artifact is a point-in-time record of what its author produced at the moment of writing. Correct one that got its own subject wrong; never edit one toward what has happened since, whether a later human edit to the remote to which it was published, a rebase that leaves `baseSha` and `commit` unresolvable, or a subsequent turn of the session that wrote it. Divergence from current state is the artifact doing its job, so it is never reported as a defect or raised as a repair for the user to weigh. A step that discloses which of two candidate sources it measured against is reporting its own input, not proposing a reconciliation.
931
+
932
+ The `pull-request` and `merge` records contain a marker that directs a reading agent to leave the record unedited, stated in the file rather than left to standing guidance, because `capture-lede-decision` reads them and a rewrite corrupts it silently. The other artifacts do not have one.
933
+
934
+ A flow still composing its own artifact has not yet passed it to anything downstream, so overwriting that artifact finishes its record rather than revising a finished one.
935
+
936
+ A later flow that revises a finished record writes a new artifact rather than editing the old one. `refine-plan` saves its output as `plan-v2` under a later timestamp, leaving the plan that it refines intact.
937
+
938
+ Overwriting either of those records breaks `capture-lede-decision`. It derives the agent's side of a lede episode by diffing the `pull-request` artifact's `## What` against the `merge` artifact's `## Body`; if a `pull-request` body is rewritten to match a human's later edit, `capture-lede-decision` reports `differ: false` for a lede that was in fact revised, so it records an `accepted` verdict for a lede that the author rewrote. The corruption does not raise an error and is undetectable in any session that no longer has the original text. When a lede is genuinely needed and the artifacts do not contain it, `capture-lede-decision` takes `--agent-lede-file` and `--merged-lede-file`.
939
+
940
+ ## Portability
941
+
942
+ Every level degrades gracefully:
943
+
944
+ - Missing project `.agents/preferences.yaml` -> fall back to global `~/.agents/preferences.yaml`
945
+ - Missing global preferences -> fall back to the default base directory
946
+ - Missing `{base_dir}/` directory -> created automatically on first artifact save
947
+ - Missing `project.slug` in preferences -> use the bare directory name of the working directory
948
+
949
+ ## Migration from status.json (v1) to run-index.json (v2)
950
+
951
+ The retired orchestration engine wrote both formats. This section records how they differ, for readers of historical runs.
952
+
953
+ ### File rename
954
+
955
+ `status.json` → `run-index.json`. The new name reflects the file's expanded role as an artifact registry, not just a status tracker.
956
+
957
+ ### Schema changes
958
+
959
+ - **New `version` field** (value: `2`). Enables schema detection; absent version = v1.
960
+ - **`context` section** groups: `runId`, `projectSlug`, `ticketId`, `projectRoot`, `branch`, `task`, `startedAt`, `completedAt`, `status`, `phases`, `phaseDecisions`.
961
+ - **`config` section** groups: `externalPlan`, `mergeBaseSha` (new), `diffBase` (new), `maxReviewRounds` (new), `effort` (new), `approvalThreshold` (new), `budgetThreshold` (new), `mode`, `model`.
962
+ - **`phaseDecision` → `context.phaseDecisions`** (now keyed by phase name, each value is a `{ run, reason? }` object). Each entry now includes an optional `disposition` field (`executed` | `skipped` | `absent`).
963
+ - **New `pipeline` field in `config`**. Ordered list of phase names from the engine's pipeline specification (e.g., `["architecture", "planning", "implementation", "review-cycle"]`). Records which phases were configured for the run (intent, not outcome). The `review-cycle` pipeline entry is a module that expands into sub-phase keys (`parallelReview`, `codeSimplifier`, `holisticReview`) in `context.phaseDecisions` and `context.phases` at runtime.
964
+ - **New `artifacts` array**. Each entry includes `roleType` for workflow-function classification. See [artifact entry fields](#artifact-entry-fields) for the full schema.
965
+
966
+ ### Role and reviewer renames
967
+
968
+ Reviewer keys in `context.phases.parallelReview.reviewers`:
969
+
970
+ | v1 key | v2 key |
971
+ | ----------------------- | ------------------------- |
972
+ | `core` | `reviewer` |
973
+ | `aspect-silent-failure` | `silent-failure-reviewer` |
974
+ | `aspect-test` | `test-reviewer` |
975
+ | `aspect-code` | `code-reviewer` |
976
+
977
+ Role segments in artifact filenames:
978
+
979
+ | v1 role | v2 role |
980
+ | -------- | ------------------------------ |
981
+ | `aspect` | `silent-failure-reviewer` |
982
+ | `aspect` | `test-reviewer` |
983
+ | `aspect` | `code-reviewer` |
984
+ | `aspect` | `code-simplification-reviewer` |
985
+
986
+ ### Timestamp format
987
+
988
+ All timestamps (run IDs and artifact filenames): `YYYYMMDD-HHMMZ` → `YYYYMMDD-HHMMSSZ` (adds seconds).
989
+
990
+ ### Known consumers (codeassembly)
991
+
992
+ The following codeassembly files reference the run metadata schema and will need updates:
993
+
994
+ - `project-scanner.ts`: Filename patterns for artifact discovery
995
+ - `status-adapter.ts`: Schema parsing and normalization
996
+ - `runs.ts`: Artifact filtering and run enumeration
997
+ - `canonical.ts`: Type definitions
998
+
999
+ ### Backward compatibility
1000
+
1001
+ During the transition period, scanners should check for both `run-index.json` and `status.json`. The presence of a `version` field distinguishes v2 from v1.