codeassembly-guidance 0.0.0 → 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 (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,969 @@
1
+ # Artifact conventions
2
+
3
+ Standards for AI-generated artifact storage, naming, and lifecycle.
4
+
5
+ ## Directory structure
6
+
7
+ 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`:
8
+
9
+ ```
10
+ {base_dir}/
11
+ └── projects/
12
+ └── {project-slug}/
13
+ ├── tickets/
14
+ │ └── {ticket-id}/
15
+ │ ├── {timestamp}_{slug}_{artifact-type}.md ← ticket-level artifacts (devlogs are written here when a ticket is in session)
16
+ │ ├── prototypes/ ← the ticket's prototype set, kept by `index-prototypes`
17
+ │ │ ├── manifest.json
18
+ │ │ ├── shots/{slug}-v{n}.png
19
+ │ │ └── {slug}-v{n}.html
20
+ │ └── {run-id}/ ← review run directory
21
+ │ ├── {NN}_{role}_{artifact}.md
22
+ │ └── ...
23
+ ├── chats/
24
+ │ └── {timestamp}_{descriptive-title}.md
25
+ ├── deferred-findings/
26
+ │ └── {timestamp}_{slug}_deferred-findings.md ← project-scoped fallback when a ticket is not in session
27
+ ├── devlogs/
28
+ │ └── {timestamp}_{concise-title}.md ← project-scoped fallback when a ticket is not in session
29
+ └── plans/
30
+ └── {design-documents}.md
31
+ ```
32
+
33
+ ### Project slug
34
+
35
+ Always present under `projects/`, even when `{base_dir}/` is inside the project. Constant structure enables simple directory sync for export. Invoke the bundled session-context deriver to obtain `project_slug`.
36
+
37
+ ### Ticket ID
38
+
39
+ 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`).
40
+
41
+ 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.
42
+
43
+ ### Prototype sets
44
+
45
+ `prototypes/` holds 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.
46
+
47
+ ### Run directories
48
+
49
+ Run directories group artifacts from a review workflow cycle:
50
+
51
+ ```
52
+ projects/{project-slug}/tickets/{ticket-id}/{run-id}/
53
+ {timestamp}_{role}_{artifact}.md
54
+ ```
55
+
56
+ **Run ID format:** `{timestamp}-{mode}`
57
+
58
+ - **timestamp:** UTC, `YYYYMMDD-HHMMSSZ` (from the first artifact in the run)
59
+ - **mode:** `interactive`. Runs written by the retired orchestration engine have the historical mode `orchestrated`.
60
+
61
+ Example: `20260221-034100Z-interactive`
62
+
63
+ A ticket's **active run** is its newest run directory of mode `interactive`, by the timestamp in its name. A review saves into the active run, and the author's response saves into the run that holds 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.
64
+
65
+ ### Persistent export destination
66
+
67
+ Artifacts under `{base_dir}/` are ephemeral when `base_dir` is a git-ignored path (the default). In worktrees, they are lost on deletion. The `export-ai-artifacts.sh` script copies them to `~/ai-artifacts/projects/{project-slug}/` for long-term retention, preserving the same directory structure. Exported artifacts are immutable (first export wins).
68
+
69
+ ## Path resolution
70
+
71
+ 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.
72
+
73
+ When the deriver is not available (e.g., standalone scripts without Node.js), the manual fallback is:
74
+
75
+ 1. Read `artifacts.base_dir` from `.agents/preferences.yaml`
76
+ 2. If not found there, read from `~/.agents/preferences.yaml`
77
+ 3. If still not found, use the default base directory
78
+ 4. If `base_dir` is relative, resolve from project root. If absolute, use as-is.
79
+ 5. Read `project.slug` from `.agents/preferences.yaml`, falling back to `~/.agents/preferences.yaml`, then the bare directory name of the working directory.
80
+
81
+ ### Reader tolerance and authoring-time validation
82
+
83
+ 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.
84
+
85
+ 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.
86
+
87
+ 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.
88
+
89
+ ### Ticket-scoped paths
90
+
91
+ ```
92
+ {base_dir}/projects/{project-slug}/tickets/{ticket-id}/
93
+ ```
94
+
95
+ 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)).
96
+
97
+ ### Run paths
98
+
99
+ ```
100
+ {base_dir}/projects/{project-slug}/tickets/{ticket-id}/{run-id}/
101
+ ```
102
+
103
+ ### Non-ticket paths
104
+
105
+ | Category | Default path | Full default |
106
+ | ----------------- | ------------------- | ------------------------------------------------------- |
107
+ | chats | `chats` | `{base_dir}/projects/{project-slug}/chats/` |
108
+ | deferred-findings | `deferred-findings` | `{base_dir}/projects/{project-slug}/deferred-findings/` |
109
+ | devlogs | `devlogs` | `{base_dir}/projects/{project-slug}/devlogs/` |
110
+ | plans | `plans` | `{base_dir}/projects/{project-slug}/plans/` |
111
+
112
+ 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.
113
+
114
+ 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.
115
+
116
+ ## Naming conventions
117
+
118
+ ### Ticket-level artifacts
119
+
120
+ ```
121
+ {timestamp}_{slug}_{artifact-type}.md
122
+ ```
123
+
124
+ - **timestamp**: UTC, `YYYYMMDD-HHMMSSZ` format (e.g., `20260219-143000Z`)
125
+ - **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.
126
+ - **artifact-type**: One of the registered types (see below)
127
+
128
+ When the ticket directory already contains artifacts for this change, reuse their slug; derive a fresh one only when the change's descriptor has moved. 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.
129
+
130
+ ### Run artifacts (review workflow)
131
+
132
+ ```
133
+ {timestamp}_{role}_{artifact}.md
134
+ ```
135
+
136
+ - **timestamp**: UTC, `YYYYMMDD-HHMMSSZ` format
137
+ - **role**: `coder`, `overseer`, `reviewer` (extensible; this is a common roles list, not exhaustive)
138
+ - **artifact**: What the document is -- `change-summary`, `review`
139
+
140
+ Underscore separates all structural parts. Hyphens are free for use within any part (role names, artifact names, slugs).
141
+
142
+ Each role has a **roleType** classifying its workflow function. See the [roleType taxonomy](#roletype-taxonomy) in the run-index.json section below.
143
+
144
+ Artifact ordering follows the timestamp prefix.
145
+
146
+ Example run directory (a review, the author's response, and a re-review):
147
+
148
+ ```
149
+ {base_dir}/projects/codeassembly/tickets/1903/20261004-080000Z-interactive/
150
+ 20261004-080000Z_reviewer_review.md
151
+ 20261004-091500Z_coder_change-summary.md
152
+ 20261004-100000Z_reviewer_review.md
153
+ ```
154
+
155
+ 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.
156
+
157
+ ## Universal artifact frontmatter
158
+
159
+ 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.
160
+
161
+ ```yaml
162
+ ---
163
+ provenance:
164
+ skill: <skill-name> # required: the skill or subagent that wrote this artifact
165
+ timestamp: <ISO 8601 UTC> # required: write time
166
+ baseSha: <short SHA> # optional: short SHA of origin/main; omit if unresolvable
167
+ isInteractive: true|false # required: true for interactive flows, false for a dispatched subagent
168
+ refinedBy: <skill-name> # optional: the skill that last processed/refined the artifact
169
+ model: <model id> # optional: present when an AI model authored the body
170
+ ticket_id: <id> # optional: omit when a ticket is not in session
171
+ ticket_ref: <display ref> # optional: omit when ticket_id is null
172
+ branch: <branch name> # required: raw branch_name from session context
173
+ commit: <short SHA of HEAD> # required: short HEAD SHA at write time
174
+ pr: <full URL> # optional: set only by PR-aware skills; omitted elsewhere
175
+ author: <name(s)> # optional: used by review artifacts
176
+ commits: [<sha>, ...] # optional: used by devlogs
177
+ run_id: <run id> # optional: set only by callers that write into, or link back to, a run directory
178
+ ---
179
+ ```
180
+
181
+ 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:
182
+
183
+ <!-- include: ../../_partials/record-marker.md / -->
184
+
185
+ ### Field naming convention
186
+
187
+ 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.
188
+
189
+ ### Field definitions
190
+
191
+ 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.
192
+
193
+ | Field | Required | Description |
194
+ | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195
+ | `provenance.skill` | yes | The skill or subagent that wrote the artifact (e.g., `create-devlog`, `plan-reviewer`). |
196
+ | `provenance.timestamp` | yes | ISO 8601 UTC timestamp of when the artifact was written. |
197
+ | `provenance.baseSha` | no | Short SHA of `origin/main` at write time. Omitted if unresolvable (no remote, shallow clone). |
198
+ | `provenance.isInteractive` | yes | `true` for interactive flows; `false` for a dispatched subagent. |
199
+ | `provenance.refinedBy` | no | The skill that last processed/refined the artifact (e.g., `refine-plan`). Records processing, not authorship. |
200
+ | `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. |
201
+ | `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. |
202
+ | `ticket_ref` | no | Human-readable ticket reference (e.g., `#537`, `MAC-68`). Omitted when `ticket_id` is omitted. |
203
+ | `branch` | yes | Current branch name from session context. Written as-is: no sanitization. |
204
+ | `commit` | yes | Short SHA of HEAD at write time. Resolved via `git rev-parse --short HEAD`. Distinct from `commits` (the devlog-specific list). |
205
+ | `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). |
206
+ | `author` | no | Human author of the work. Used by review artifacts when the reviewing surface records the code author. |
207
+ | `commits` | no | List of short SHAs summarized by the artifact. Used by devlogs. Distinct from `commit` (HEAD short SHA). |
208
+ | `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>`. |
209
+
210
+ ### `commit` vs. `commits`
211
+
212
+ `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.
213
+
214
+ ### PR resolution
215
+
216
+ `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.
217
+
218
+ ### Bespoke frontmatter composition
219
+
220
+ 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:
221
+
222
+ - `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.
223
+ - `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.
224
+
225
+ 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.
226
+
227
+ ## Manifest creation
228
+
229
+ 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`.
230
+
231
+ 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.
232
+
233
+ Invocation surface:
234
+
235
+ ```bash
236
+ node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
237
+ ```
238
+
239
+ The deriver prints the manifest JSON to stdout and writes it to `.agents/{sanitized-branch}.branch-manifest.json` as a side effect. Every invocation recomposes the derived fields from the current preferences and git state, so 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).
240
+
241
+ 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.
242
+
243
+ ## Plan provenance
244
+
245
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extension:
246
+
247
+ | Field | Required | Description |
248
+ | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
249
+ | `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements. |
250
+
251
+ 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`).
252
+
253
+ ## Devlog frontmatter
254
+
255
+ 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.
256
+
257
+ ## Deferred-findings frontmatter
258
+
259
+ 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.
260
+
261
+ | Field | Required | Description |
262
+ | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
263
+ | `session_type` | yes | The session classification from wrap-up's Phase 1a (`interactive-dev`, `review`, or `research`). |
264
+ | `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. |
265
+
266
+ `provenance.skill` is `wrap-up`; `provenance.isInteractive` is `true`.
267
+
268
+ **Single-finding case**, a ticket addressing one finding:
269
+
270
+ ```yaml
271
+ tickets_created:
272
+ - id: '<number>'
273
+ items: [F1]
274
+ ```
275
+
276
+ **Batch case**, a single ticket addressing multiple findings, uses the same shape with additional IDs in `items`:
277
+
278
+ ```yaml
279
+ tickets_created:
280
+ - id: '<number>'
281
+ items: [F1, T2, R1]
282
+ ```
283
+
284
+ ## Change-summary frontmatter
285
+
286
+ 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`):
287
+
288
+ | Field | Required | Description |
289
+ | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
290
+ | `title` | yes | The change-summary title, used as the proposed PR title. |
291
+ | `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. |
292
+ | `type` | no | The consolidated record's work type (see `work-types.json`). Omitted if the change does not have entries. |
293
+ | `breaking` | no | `true` if the consolidated record is breaking. Omitted otherwise; it is never `false`. |
294
+ | `changes` | no | Each commit entry rendered through `commit.title_format`, oldest first. Omitted if the branch does not have a commit entry. |
295
+ | `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. |
296
+ | `override_scope` | no | The scope that the author set by hand, or `*` if the author did not set a scope. |
297
+ | `override_type` | no | The work type that the author set by hand, without a marker. |
298
+ | `override_breaking` | no | `true` if the author added the breaking marker by hand. Omitted otherwise. |
299
+
300
+ `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.
301
+
302
+ 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.
303
+
304
+ **The change summary's body ends with the rendered `change-record` block**, which carries the change entries and the consolidated record to the pull request. `create-pr` copies the body from `## What` onward, so the block reaches the pull-request body without being rendered again.
305
+
306
+ 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.
307
+
308
+ 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.
309
+
310
+ ## Ticket frontmatter
311
+
312
+ 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:
313
+
314
+ | Field | Required | Description |
315
+ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
316
+ | `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`. |
317
+
318
+ **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.
319
+
320
+ **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.
321
+
322
+ `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.
323
+
324
+ ## run-index.json
325
+
326
+ Machine-readable metadata for a run directory. The retired orchestration engine wrote it, and no current skill does. `run-core` parses it.
327
+
328
+ 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.
329
+
330
+ ### Schema
331
+
332
+ > **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.
333
+
334
+ **Initial write** (at run start):
335
+
336
+ ```json
337
+ {
338
+ "version": 2,
339
+ "context": {
340
+ "runId": "20260221-034100Z-orchestrated",
341
+ "projectSlug": "williamthorsen-configs-macos",
342
+ "ticketId": "MAC-68",
343
+ "projectRoot": "/Users/william/repos/configs/macos",
344
+ "branch": "mac-68/feat/improve-artifact-naming",
345
+ "task": "Implement artifact naming improvements",
346
+ "startedAt": "2026-02-21T03:41:00Z",
347
+ "completedAt": null,
348
+ "status": "in_progress",
349
+ "phases": {},
350
+ "phaseDecisions": {}
351
+ },
352
+ "config": {
353
+ "pipeline": ["architecture", "planning", "implementation", "review-cycle"],
354
+ "externalPlan": false,
355
+ "mergeBaseSha": "abc1234",
356
+ "diffBase": "main",
357
+ "maxReviewRounds": 3,
358
+ "effort": "medium",
359
+ "approvalThreshold": "medium",
360
+ "budgetThreshold": "medium",
361
+ "mode": "orchestrated",
362
+ "model": "claude-opus-4-6"
363
+ },
364
+ "artifacts": []
365
+ }
366
+ ```
367
+
368
+ **Final state** (at run completion):
369
+
370
+ ```json
371
+ {
372
+ "version": 2,
373
+ "context": {
374
+ "runId": "20260221-034100Z-orchestrated",
375
+ "projectSlug": "williamthorsen-configs-macos",
376
+ "ticketId": "MAC-68",
377
+ "projectRoot": "/Users/william/repos/configs/macos",
378
+ "branch": "mac-68/feat/improve-artifact-naming",
379
+ "task": "Implement artifact naming improvements",
380
+ "startedAt": "2026-02-21T03:41:00Z",
381
+ "completedAt": "2026-02-21T04:16:00Z",
382
+ "status": "completed",
383
+ "phaseDecisions": {
384
+ "architecture": { "run": true, "disposition": "executed", "reason": "External plan requires validation" },
385
+ "planning": { "run": true, "disposition": "executed", "reason": "External plan present" },
386
+ "implementation": { "run": true, "disposition": "executed" },
387
+ "review-cycle": { "run": true, "disposition": "executed" },
388
+ "parallelReview": { "run": true, "disposition": "executed" },
389
+ "codeSimplifier": { "run": true, "disposition": "executed" },
390
+ "holisticReview": { "run": true, "disposition": "executed" }
391
+ },
392
+ "phases": {
393
+ "architecture": {
394
+ "status": "completed",
395
+ "impactLevel": "moderate",
396
+ "startedAt": "2026-02-21T03:41:30Z",
397
+ "completedAt": "2026-02-21T03:42:00Z"
398
+ },
399
+ "planning": {
400
+ "status": "completed",
401
+ "stepCount": 5,
402
+ "startedAt": "2026-02-21T03:42:10Z",
403
+ "completedAt": "2026-02-21T03:43:00Z"
404
+ },
405
+ "implementation": {
406
+ "status": "completed",
407
+ "startedAt": "2026-02-21T03:43:10Z",
408
+ "completedAt": "2026-02-21T03:45:00Z"
409
+ },
410
+ "parallelReview": {
411
+ "status": "completed",
412
+ "startedAt": "2026-02-21T03:45:10Z",
413
+ "completedAt": "2026-02-21T04:10:00Z",
414
+ "aggregatedCriticality": "medium",
415
+ "reviewers": {
416
+ "reviewer": {
417
+ "status": "completed",
418
+ "criticality": "medium",
419
+ "reReviewCriticality": "low",
420
+ "startedAt": "2026-02-21T03:45:10Z",
421
+ "completedAt": "2026-02-21T03:47:00Z"
422
+ },
423
+ "silent-failure-reviewer": {
424
+ "status": "completed",
425
+ "criticality": "low",
426
+ "startedAt": "2026-02-21T03:45:10Z",
427
+ "completedAt": "2026-02-21T03:47:00Z"
428
+ },
429
+ "test-reviewer": { "status": "skipped", "reason": "no source or test files changed" },
430
+ "code-reviewer": {
431
+ "status": "completed",
432
+ "criticality": "medium",
433
+ "reReviewCriticality": "none",
434
+ "startedAt": "2026-02-21T03:45:10Z",
435
+ "completedAt": "2026-02-21T03:47:00Z"
436
+ }
437
+ },
438
+ "coderFixCycleRan": true,
439
+ "selectiveReReview": {
440
+ "ran": true,
441
+ "reviewersDispatched": ["reviewer", "code-reviewer"],
442
+ "additionalFixCycleRan": false
443
+ },
444
+ "iterations": [
445
+ {
446
+ "reviewers": ["reviewer", "silent-failure-reviewer", "code-reviewer"],
447
+ "dispatchedAt": "2026-02-21T03:45:10Z",
448
+ "reviewsCompletedAt": "2026-02-21T03:47:00Z",
449
+ "coderFixStartedAt": "2026-02-21T03:47:30Z",
450
+ "coderFixCompletedAt": "2026-02-21T04:00:00Z"
451
+ },
452
+ {
453
+ "reviewers": ["reviewer", "code-reviewer"],
454
+ "dispatchedAt": "2026-02-21T04:00:30Z",
455
+ "reviewsCompletedAt": "2026-02-21T04:10:00Z"
456
+ }
457
+ ]
458
+ },
459
+ "codeSimplifier": {
460
+ "status": "completed",
461
+ "ran": true,
462
+ "actionableFindings": true,
463
+ "coderFixCycleRan": true,
464
+ "startedAt": "2026-02-21T04:10:10Z",
465
+ "completedAt": "2026-02-21T04:12:00Z"
466
+ },
467
+ "holisticReview": {
468
+ "status": "completed",
469
+ "criticality": "none",
470
+ "startedAt": "2026-02-21T04:12:10Z",
471
+ "completedAt": "2026-02-21T04:15:00Z"
472
+ }
473
+ }
474
+ },
475
+ "config": {
476
+ "pipeline": ["architecture", "planning", "implementation", "review-cycle"],
477
+ "externalPlan": false,
478
+ "mergeBaseSha": "abc1234",
479
+ "diffBase": "main",
480
+ "maxReviewRounds": 3,
481
+ "effort": "medium",
482
+ "approvalThreshold": "medium",
483
+ "budgetThreshold": "medium",
484
+ "mode": "orchestrated",
485
+ "model": "claude-opus-4-6"
486
+ },
487
+ "artifacts": [
488
+ {
489
+ "filename": "01_orchestrator_run-manifest.md",
490
+ "role": "orchestrator",
491
+ "roleType": "orchestrator",
492
+ "agent": "orchestrator",
493
+ "type": "run-manifest",
494
+ "phase": "initialization",
495
+ "createdAt": "2026-02-21T03:41:00Z"
496
+ },
497
+ {
498
+ "filename": "02_architect_architecture.md",
499
+ "role": "architect",
500
+ "roleType": "analyst",
501
+ "agent": "orchestrated-architect",
502
+ "type": "architecture",
503
+ "phase": "architecture",
504
+ "createdAt": "2026-02-21T03:42:00Z"
505
+ },
506
+ {
507
+ "filename": "03_planner_orchestration-plan.md",
508
+ "role": "planner",
509
+ "roleType": "planner",
510
+ "agent": "orchestrated-planner",
511
+ "type": "orchestration-plan",
512
+ "phase": "planning",
513
+ "createdAt": "2026-02-21T03:43:00Z"
514
+ },
515
+ {
516
+ "filename": "04_coder_change-summary.md",
517
+ "role": "coder",
518
+ "roleType": "author",
519
+ "agent": "orchestrated-coder",
520
+ "type": "change-summary",
521
+ "phase": "implementation",
522
+ "createdAt": "2026-02-21T03:45:00Z"
523
+ },
524
+ {
525
+ "filename": "05_reviewer_review.md",
526
+ "role": "reviewer",
527
+ "roleType": "reviewer",
528
+ "agent": "orchestrated-reviewer",
529
+ "type": "review",
530
+ "phase": "parallelReview",
531
+ "createdAt": "2026-02-21T03:47:00Z",
532
+ "iteration": 1
533
+ },
534
+ {
535
+ "filename": "06_silent-failure-reviewer_silent-failure-review.md",
536
+ "role": "silent-failure-reviewer",
537
+ "roleType": "reviewer",
538
+ "agent": "aspect-silent-failure-reviewer",
539
+ "type": "silent-failure-review",
540
+ "phase": "parallelReview",
541
+ "createdAt": "2026-02-21T03:47:00Z",
542
+ "iteration": 1
543
+ },
544
+ {
545
+ "filename": "07_code-reviewer_code-review.md",
546
+ "role": "code-reviewer",
547
+ "roleType": "reviewer",
548
+ "agent": "aspect-code-reviewer",
549
+ "type": "code-review",
550
+ "phase": "parallelReview",
551
+ "createdAt": "2026-02-21T03:47:00Z",
552
+ "iteration": 1
553
+ },
554
+ {
555
+ "filename": "08_coder_change-summary.md",
556
+ "role": "coder",
557
+ "roleType": "author",
558
+ "agent": "orchestrated-coder",
559
+ "type": "change-summary",
560
+ "phase": "parallelReview",
561
+ "createdAt": "2026-02-21T04:00:00Z",
562
+ "note": "Addresses aggregated findings from iteration 1"
563
+ },
564
+ {
565
+ "filename": "09_reviewer_review.md",
566
+ "role": "reviewer",
567
+ "roleType": "reviewer",
568
+ "agent": "orchestrated-reviewer",
569
+ "type": "review",
570
+ "phase": "parallelReview",
571
+ "createdAt": "2026-02-21T04:15:00Z",
572
+ "iteration": 2
573
+ },
574
+ {
575
+ "filename": "10_orchestrator_run-summary.md",
576
+ "role": "orchestrator",
577
+ "roleType": "orchestrator",
578
+ "agent": "orchestrator",
579
+ "type": "run-summary",
580
+ "phase": "summary",
581
+ "createdAt": "2026-02-21T04:16:00Z"
582
+ }
583
+ ]
584
+ }
585
+ ```
586
+
587
+ **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"`.
588
+
589
+ ### roleType taxonomy
590
+
591
+ 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`:
592
+
593
+ | roleType | Description | Example roles |
594
+ | -------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
595
+ | `orchestrator` | Coordinates phases and manages run state | `orchestrator` |
596
+ | `analyst` | Assesses impact and provides architectural guidance | `architect` |
597
+ | `planner` | Produces implementation plans | `planner` |
598
+ | `author` | Writes or modifies project code | `coder` |
599
+ | `reviewer` | Evaluates code and produces findings | `reviewer`, `code-reviewer`, `code-simplification-reviewer`, `silent-failure-reviewer`, `test-reviewer` |
600
+
601
+ ### Artifact entry fields
602
+
603
+ | Field | Required | Description |
604
+ | ----------- | -------- | -------------------------------------------------------------------------------------- |
605
+ | `filename` | yes | Artifact filename (without directory path) |
606
+ | `role` | yes | Filename role segment (e.g., `reviewer`, `code-reviewer`) |
607
+ | `roleType` | yes | Workflow function (one of: `orchestrator`, `analyst`, `planner`, `author`, `reviewer`) |
608
+ | `agent` | yes | {tool:Task} `subagent_type` value (e.g., `plan-reviewer`) |
609
+ | `type` | yes | Artifact type (e.g., `review`, `change-summary`) |
610
+ | `phase` | yes | Phase that produced this artifact (camelCase, matches `phases` object keys) |
611
+ | `createdAt` | yes | ISO 8601 timestamp |
612
+ | `iteration` | no | Review iteration number (for `parallelReview` phase) |
613
+ | `note` | no | Free-text context about the artifact |
614
+
615
+ ### Phase values
616
+
617
+ Phase values use camelCase and match the keys in the `phases` object. Only the retired orchestration engine wrote them:
618
+
619
+ - `initialization`: Run setup and manifest creation
620
+ - `architecture`: Architectural impact assessment
621
+ - `planning`: Implementation planning
622
+ - `implementation`: Code authoring
623
+ - `parallelReview`: Parallel review and fix cycles
624
+ - `codeSimplifier`: Code simplification pass
625
+ - `holisticReview`: Final comprehensive review
626
+ - `summary`: Run summary generation
627
+
628
+ ### Version field
629
+
630
+ 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.
631
+
632
+ ## V3 format: Event-sourced runs
633
+
634
+ 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.
635
+
636
+ ### V3 header schema
637
+
638
+ `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.
639
+
640
+ Context fields: `runId`, `projectSlug`, `ticketId?`, `projectRoot`, `branch`, `task`, `startedAt`.
641
+
642
+ Config fields: `externalPlan?`, `mergeBaseSha?`, `diffBase?`, `maxReviewRounds?`, `effort?`, `approvalThreshold?`, `budgetThreshold?`, `mode?`, `model?`. Additional fields are preserved (loose schema).
643
+
644
+ ### Run-log.jsonl
645
+
646
+ 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.
647
+
648
+ ### Event types
649
+
650
+ 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:
651
+
652
+ | Event type | Key fields |
653
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
654
+ | `run_started` | _(none beyond `t`, `event`)_ |
655
+ | `run_completed` | `status` (`completed`\|`failed`\|`needs_manual_review`) |
656
+ | `run_failed` | `status`, `reason?` |
657
+ | `phase_decision` | `phase` (string), `run` (boolean), `reason?` |
658
+ | `phase_started` | `phase` (one of: `architecture`\|`planning`\|`implementation`\|`review`\|`simplifier`\|`holistic`) |
659
+ | `phase_completed` | `phase`, `status` (one of: `completed`\|`skipped`\|`failed`\|`in_progress`\|`approved`), `data?` (record), `tokens?`, `toolUses?`, `durationMs?` |
660
+ | `reviewer_dispatched` | `reviewer` (string) |
661
+ | `reviewer_completed` | `reviewer`, `status` (`completed`\|`skipped`\|`failed`), `criticality` (`none`\|`low`\|`medium`\|`high`), `tokens?`, `toolUses?`, `durationMs?` |
662
+ | `coder_fix_started` | `iteration` (number) |
663
+ | `coder_fix_completed` | `iteration` (number), `tokens?`, `toolUses?`, `durationMs?` |
664
+ | `re_review_dispatched` | `reviewers` (string array) |
665
+ | `re_review_completed` | `criticalities` (record: reviewer name -> criticality), `tokens?`, `toolUses?`, `durationMs?` |
666
+ | `artifact_written` | `filename`, `role`, `roleType`, `agent`, `type`, `phase`, `iteration?`, `note?` |
667
+
668
+ ### Run directory layout (v3)
669
+
670
+ ```
671
+ {base_dir}/projects/{projectSlug}/tickets/{ticketId}/{runId}/
672
+ run-index.json <- v3 header (top-level completedAt once the run completed)
673
+ run-log.jsonl <- append-only event log (one JSON object per line)
674
+ {NN}_{role}_{artifact}.md <- artifact files (sequential counter)
675
+ ```
676
+
677
+ 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`).
678
+
679
+ ### Run ID format (v3)
680
+
681
+ `{yyyymmdd}-{hhmmss}Z`, generated by the engine. This differs from the historical v2 format `{yyyymmdd}-{hhmmss}Z-orchestrated`.
682
+
683
+ ### Event folding
684
+
685
+ Full run state (phases, artifacts, review rounds, criticalities) is reconstructed from `run-log.jsonl` by run-core's `foldEvents` function, which returns a `CanonicalRunStatus`.
686
+
687
+ ### Backward compatibility
688
+
689
+ V2 and v1 `run-index.json` formats remain supported by the Factory consumer.
690
+
691
+ ## Artifact types
692
+
693
+ 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.
694
+
695
+ ### Run artifacts (in run directories)
696
+
697
+ | Artifact | Purpose | Dispositions? |
698
+ | ---------------- | --------------------------------------------------------- | -------------------------------------- |
699
+ | `change-summary` | What changed + dispositions on prior findings (if any) | Yes, when responding to a prior review |
700
+ | `review` | Code review findings + dispositions on own prior findings | Only for own prior findings |
701
+
702
+ 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`.
703
+
704
+ The first `coder_change-summary` in a run does not have dispositions (nothing to respond to). Subsequent ones embed dispositions alongside the change summary.
705
+
706
+ ### Ticket-level artifacts
707
+
708
+ - `brief`: The shared brief that a round of prototype builders receives; `prepare-prototype-brief` saves it at its checkpoint
709
+ - `change-summary`: Branch change summary for PRs
710
+ - `comparison`: Findings across a round of prototypes: where they agree, where they diverge, which ideas to carry forward, and which decisions the round leaves open; `prepare-prototype-brief` saves it after the index
711
+ - `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)
712
+ - `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
713
+ - `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
714
+ - `plan`: Implementation plan document
715
+ - `plan-review`: Plan review findings (completeness and correctness analysis)
716
+ - `plan-v2`: Refined implementation plan after review and revision
717
+ - `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
718
+ - `review`: Code review (ticket-level, commit scope)
719
+ - `ticket`: Issue ticket
720
+
721
+ ### Non-ticket artifacts
722
+
723
+ - `chat-summary`: Conversation summary
724
+
725
+ ## Run lifecycle
726
+
727
+ ### Starting a run
728
+
729
+ Either role can produce a run's first artifact. Common patterns:
730
+
731
+ - Coder produces `coder_change-summary`, then reviewer produces `reviewer_review`
732
+ - Reviewer produces `reviewer_review` directly (human is the coder)
733
+
734
+ ### Iteration pattern
735
+
736
+ 1. `reviewer_review` contains findings
737
+ 2. `coder_change-summary` contains fixes + dispositions on prior findings
738
+ 3. `reviewer_review` reads all prior artifacts chronologically: Dispositions are embedded in the documents that contain them
739
+
740
+ ### Termination
741
+
742
+ Run ends when the parties do not have any further actionable input. The last artifact can be from any role.
743
+
744
+ ### Stacking
745
+
746
+ An iteration can contain multiple reviews (e.g., `reviewer_review` + `overseer_review`). The next `coder_change-summary` addresses all of them.
747
+
748
+ ## Disposition rules
749
+
750
+ ### Embedding
751
+
752
+ Dispositions are stated in the document produced by the responding role. No separate disposition artifact.
753
+
754
+ ### Scope
755
+
756
+ A role can only disposition findings directed at it or its own prior findings. The overseer is exempt (arbiter authority).
757
+
758
+ | Role | Can disposition | Cannot disposition |
759
+ | -------- | ------------------------------------------------------------ | -------------------------------------------------------- |
760
+ | Coder | Reviewer/overseer findings on the code | Own changes (self-review) |
761
+ | Reviewer | Own prior findings (revise/withdraw in light of new context) | Coder rejections (re-raise as escalated finding instead) |
762
+ | Overseer | Any finding (arbiter authority) | n/a |
763
+
764
+ ## Finding scheme (F/W/T/R/S + legacy suffix)
765
+
766
+ 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.
767
+
768
+ | ID | Category | Icon | Criticality | Merge-blocking? |
769
+ | ------------------ | -------------- | ---- | ----------- | -------------------------- |
770
+ | `F{n}` | FIXME | 🚨 | `high` | Always |
771
+ | `W{n}` | Warning | ⚠️ | `medium` | Unless justified |
772
+ | `T{n}` | TODO | 📋 | `low` | Never (ticket if deferred) |
773
+ | `R{n}` | Recommendation | 🧠 | `low` | Never (note if deferred) |
774
+ | `S{n}` | Suggestion | ☝️ | `low` | Never (piggyback only) |
775
+ | `{F,W,T,R,S}{n}-L` | Legacy | 🔍 | excluded | Never |
776
+
777
+ 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.
778
+
779
+ ### Proposed-change gate
780
+
781
+ 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.
782
+
783
+ 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.
784
+
785
+ 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.
786
+
787
+ ### Actionability gate
788
+
789
+ 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.
790
+
791
+ 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.
792
+
793
+ 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.
794
+
795
+ **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:
796
+
797
+ - "No action this PR / no action required / not actionable here"
798
+ - "Just capturing a thought" / "mentioning so the next contributor…"
799
+ - "Call it out only if X" / "consider when Y" / "would matter once Z" / "revisit if/when…", when the named condition is not currently met
800
+ - 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
801
+
802
+ 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.
803
+
804
+ 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.
805
+
806
+ 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.
807
+
808
+ Apply this gate **hardest** to R and S, whose low criticality bar invites filler.
809
+
810
+ ### Category criteria
811
+
812
+ **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.
813
+
814
+ **FIXME (F).** Must fix before merge:
815
+
816
+ - Bugs: Incorrect logic, unhandled error paths, data loss risks
817
+ - Security: Injection, auth bypass, exposed secrets
818
+ - Contract violations: Breaking API changes, type unsafety
819
+ - Test failures: Tests that don't pass or don't test what they claim
820
+
821
+ **Warning (W).** Questionable, may block merge:
822
+
823
+ - Missing edge case handling that could cause runtime errors
824
+ - Convention violations that affect maintainability
825
+ - Decisions that seem wrong but may be intentional (require justification)
826
+ - **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.
827
+
828
+ **TODO (T).** Should fix, not in this PR:
829
+
830
+ - Missing or inadequate tests for new functionality
831
+ - Performance issues with measurable impact
832
+ - Incomplete error handling that won't cause immediate failures
833
+
834
+ **Recommendation (R).** Advisable but discretionary:
835
+
836
+ - Better patterns available in the codebase
837
+ - Opportunities to reduce complexity
838
+ - Architectural improvements worth considering
839
+ - **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).
840
+
841
+ **Suggestion (S).** Optional improvement:
842
+
843
+ - Better naming or code organization
844
+ - Additional test cases for edge cases
845
+ - Documentation improvements
846
+ - **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).
847
+
848
+ **Legacy (`-L` suffix).** Pre-existing code observation:
849
+
850
+ - Issues in code not authored in this branch. Use the same severity letter as the equivalent author finding.
851
+ - 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`.
852
+ - Set the `**Severity:**` field to `{severity} (legacy)`, e.g., `critical (legacy)`, `warning (legacy)`, `suggestion (legacy)`
853
+ - Frame as future opportunities, not current defects
854
+ - Never count against the review score
855
+
856
+ ### Overall criticality mapping
857
+
858
+ | Highest finding present | Criticality | Meaning |
859
+ | ----------------------- | ----------- | -------------------------- |
860
+ | None, or only `-L` | `none` | No authored findings |
861
+ | S, R, and/or T (no W/F) | `low` | Deferrable items available |
862
+ | W (no F) | `medium` | Real issues to address |
863
+ | F | `high` | Must fix before merge |
864
+
865
+ 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.
866
+
867
+ ### Re-review severity escalation
868
+
869
+ `S → R → T → W → F`. Legacy (`-L`) findings are never escalated.
870
+
871
+ ## Knowledge items
872
+
873
+ 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.
874
+
875
+ | ID | Category | Icon | Kind |
876
+ | ------ | -------- | ---- | --------- |
877
+ | `I{n}` | Insight | 💡 | knowledge |
878
+
879
+ 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.
880
+
881
+ ### Insight gate
882
+
883
+ 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.
884
+
885
+ 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.
886
+
887
+ **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`.
888
+
889
+ Insights never have criticality, never block a merge, and never count toward a review score or the [Overall criticality mapping](#overall-criticality-mapping).
890
+
891
+ ## Artifact lifecycle
892
+
893
+ - **Active**: Artifact is current and relevant
894
+ - **Stale**: Branch has been merged or deleted, and artifact is 30+ days old
895
+
896
+ ### Mutability
897
+
898
+ 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.
899
+
900
+ The `pull-request` and `merge` records carry 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.
901
+
902
+ A flow still composing its own artifact has reached nothing downstream of it, so overwriting that artifact finishes its record rather than revising a finished one.
903
+
904
+ 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.
905
+
906
+ 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`.
907
+
908
+ ## Portability
909
+
910
+ Every level degrades gracefully:
911
+
912
+ - Missing project `.agents/preferences.yaml` -> fall back to global `~/.agents/preferences.yaml`
913
+ - Missing global preferences -> fall back to the default base directory
914
+ - Missing `{base_dir}/` directory -> created automatically on first artifact save
915
+ - Missing `project.slug` in preferences -> use the bare directory name of the working directory
916
+
917
+ ## Migration from status.json (v1) to run-index.json (v2)
918
+
919
+ The retired orchestration engine wrote both formats. This section records how they differ, for readers of historical runs.
920
+
921
+ ### File rename
922
+
923
+ `status.json` → `run-index.json`. The new name reflects the file's expanded role as an artifact registry, not just a status tracker.
924
+
925
+ ### Schema changes
926
+
927
+ - **New `version` field** (value: `2`). Enables schema detection; absent version = v1.
928
+ - **`context` section** groups: `runId`, `projectSlug`, `ticketId`, `projectRoot`, `branch`, `task`, `startedAt`, `completedAt`, `status`, `phases`, `phaseDecisions`.
929
+ - **`config` section** groups: `externalPlan`, `mergeBaseSha` (new), `diffBase` (new), `maxReviewRounds` (new), `effort` (new), `approvalThreshold` (new), `budgetThreshold` (new), `mode`, `model`.
930
+ - **`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`).
931
+ - **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.
932
+ - **New `artifacts` array**. Each entry includes `roleType` for workflow-function classification. See [artifact entry fields](#artifact-entry-fields) for the full schema.
933
+
934
+ ### Role and reviewer renames
935
+
936
+ Reviewer keys in `context.phases.parallelReview.reviewers`:
937
+
938
+ | v1 key | v2 key |
939
+ | ----------------------- | ------------------------- |
940
+ | `core` | `reviewer` |
941
+ | `aspect-silent-failure` | `silent-failure-reviewer` |
942
+ | `aspect-test` | `test-reviewer` |
943
+ | `aspect-code` | `code-reviewer` |
944
+
945
+ Role segments in artifact filenames:
946
+
947
+ | v1 role | v2 role |
948
+ | -------- | ------------------------------ |
949
+ | `aspect` | `silent-failure-reviewer` |
950
+ | `aspect` | `test-reviewer` |
951
+ | `aspect` | `code-reviewer` |
952
+ | `aspect` | `code-simplification-reviewer` |
953
+
954
+ ### Timestamp format
955
+
956
+ All timestamps (run IDs and artifact filenames): `YYYYMMDD-HHMMZ` → `YYYYMMDD-HHMMSSZ` (adds seconds).
957
+
958
+ ### Known consumers (codeassembly)
959
+
960
+ The following codeassembly files reference the run metadata schema and will need updates:
961
+
962
+ - `project-scanner.ts`: Filename patterns for artifact discovery
963
+ - `status-adapter.ts`: Schema parsing and normalization
964
+ - `runs.ts`: Artifact filtering and run enumeration
965
+ - `canonical.ts`: Type definitions
966
+
967
+ ### Backward compatibility
968
+
969
+ 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.