codeassembly-guidance 0.3.0 → 0.5.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.
- package/.meta/changelog.json +385 -272
- package/CHANGELOG.md +39 -0
- package/README.md +8 -40
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/codeassembly-content.yaml +2 -0
- package/content/collections/recommended.md +1 -1
- package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/skills/_data/artifact-conventions.md +9 -423
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/_partials/plan-template.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +1 -1
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/kb-add/kb-add.mjs +53 -53
- package/content/skills/kb-curate/kb-curate.mjs +64 -64
- package/content/skills/kb-edit/kb-edit.mjs +61 -61
- package/content/skills/kb-update-events/kb-update-events.mjs +19 -19
- package/content/skills/lesson-clusters/lesson-clusters.mjs +47 -47
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/refine-guidance/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +66 -66
- package/content/skills/save-artifact/SKILL.md +2 -2
- package/content/skills/streamline-guidance/streamline-guidance.mjs +30 -30
- package/content/skills/triage-feedback/SKILL.md +8 -23
- package/content/skills/triage-feedback/triage-feedback.mjs +7 -7
- package/content/skills/triage-spike-findings/SKILL.md +1 -1
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +10 -5
- package/content/subagents/plan-reviewer.md +8 -7
- package/package.json +6 -6
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
|
@@ -54,6 +54,9 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
|
|
|
54
54
|
│ └── {timestamp}_{slug}_deferred-findings.md ← project-scoped fallback when a ticket is not in session
|
|
55
55
|
├── devlogs/
|
|
56
56
|
│ └── {timestamp}_{concise-title}.md ← project-scoped fallback when a ticket is not in session
|
|
57
|
+
├── feedback-curation/
|
|
58
|
+
│ ├── {timestamp}_{slug}_feedback-curation.md ← project-scoped fallback when a ticket is not in session
|
|
59
|
+
│ └── {timestamp}_work/ ← the run's working files
|
|
57
60
|
├── feedback-triage/
|
|
58
61
|
│ ├── {timestamp}_{slug}_feedback-triage.md ← project-scoped fallback when a ticket is not in session
|
|
59
62
|
│ └── {timestamp}_work/ ← the run's working files
|
|
@@ -146,12 +149,13 @@ Ticket-level artifacts and run directories are both stored here. Invoke the bund
|
|
|
146
149
|
| chats | `chats` | `{base_dir}/projects/{project-slug}/chats/` |
|
|
147
150
|
| deferred-findings | `deferred-findings` | `{base_dir}/projects/{project-slug}/deferred-findings/` |
|
|
148
151
|
| devlogs | `devlogs` | `{base_dir}/projects/{project-slug}/devlogs/` |
|
|
152
|
+
| feedback-curation | `feedback-curation` | `{base_dir}/projects/{project-slug}/feedback-curation/` |
|
|
149
153
|
| feedback-triage | `feedback-triage` | `{base_dir}/projects/{project-slug}/feedback-triage/` |
|
|
150
154
|
| plans | `plans` | `{base_dir}/projects/{project-slug}/plans/` |
|
|
151
155
|
|
|
152
|
-
Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with
|
|
156
|
+
Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with three exceptions: `deferred-findings`, `feedback-curation`, and `feedback-triage` are hardcoded and cannot be overridden.
|
|
153
157
|
|
|
154
|
-
Devlogs, deferred-findings, and feedback-triage 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/`, `deferred-findings/`, and `feedback-triage/`). All filenames in these types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
|
|
158
|
+
Devlogs, deferred-findings, feedback-curation, and feedback-triage 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/`, `deferred-findings/`, `feedback-curation/`, and `feedback-triage/`). All filenames in these types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
|
|
155
159
|
|
|
156
160
|
## Naming conventions
|
|
157
161
|
|
|
@@ -179,8 +183,6 @@ When the ticket directory already contains artifacts for this change, reuse thei
|
|
|
179
183
|
|
|
180
184
|
Underscore separates all structural parts. Hyphens are free for use within any part (role names, artifact names, slugs).
|
|
181
185
|
|
|
182
|
-
Each role has a **roleType** classifying its workflow function. See the [roleType taxonomy](#roletype-taxonomy) in the run-index.json section below.
|
|
183
|
-
|
|
184
186
|
Artifact ordering follows the timestamp prefix.
|
|
185
187
|
|
|
186
188
|
Example run directory (a review, the author's response, and a re-review):
|
|
@@ -361,372 +363,9 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
|
|
|
361
363
|
|
|
362
364
|
`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.
|
|
363
365
|
|
|
364
|
-
##
|
|
365
|
-
|
|
366
|
-
Machine-readable metadata for a run directory. The retired orchestration engine wrote it; the current skills do not. `run-core` parses it.
|
|
367
|
-
|
|
368
|
-
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.
|
|
369
|
-
|
|
370
|
-
### Schema
|
|
371
|
-
|
|
372
|
-
> **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.
|
|
373
|
-
|
|
374
|
-
**Initial write** (at run start):
|
|
375
|
-
|
|
376
|
-
```json
|
|
377
|
-
{
|
|
378
|
-
"version": 2,
|
|
379
|
-
"context": {
|
|
380
|
-
"runId": "20260221-034100Z-orchestrated",
|
|
381
|
-
"projectSlug": "williamthorsen-configs-macos",
|
|
382
|
-
"ticketId": "MAC-68",
|
|
383
|
-
"projectRoot": "/Users/william/repos/configs/macos",
|
|
384
|
-
"branch": "mac-68/feat/improve-artifact-naming",
|
|
385
|
-
"task": "Implement artifact naming improvements",
|
|
386
|
-
"startedAt": "2026-02-21T03:41:00Z",
|
|
387
|
-
"completedAt": null,
|
|
388
|
-
"status": "in_progress",
|
|
389
|
-
"phases": {},
|
|
390
|
-
"phaseDecisions": {}
|
|
391
|
-
},
|
|
392
|
-
"config": {
|
|
393
|
-
"pipeline": ["architecture", "planning", "implementation", "review-cycle"],
|
|
394
|
-
"externalPlan": false,
|
|
395
|
-
"mergeBaseSha": "abc1234",
|
|
396
|
-
"diffBase": "main",
|
|
397
|
-
"maxReviewRounds": 3,
|
|
398
|
-
"effort": "medium",
|
|
399
|
-
"approvalThreshold": "medium",
|
|
400
|
-
"budgetThreshold": "medium",
|
|
401
|
-
"mode": "orchestrated",
|
|
402
|
-
"model": "claude-opus-4-6"
|
|
403
|
-
},
|
|
404
|
-
"artifacts": []
|
|
405
|
-
}
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
**Final state** (at run completion):
|
|
409
|
-
|
|
410
|
-
```json
|
|
411
|
-
{
|
|
412
|
-
"version": 2,
|
|
413
|
-
"context": {
|
|
414
|
-
"runId": "20260221-034100Z-orchestrated",
|
|
415
|
-
"projectSlug": "williamthorsen-configs-macos",
|
|
416
|
-
"ticketId": "MAC-68",
|
|
417
|
-
"projectRoot": "/Users/william/repos/configs/macos",
|
|
418
|
-
"branch": "mac-68/feat/improve-artifact-naming",
|
|
419
|
-
"task": "Implement artifact naming improvements",
|
|
420
|
-
"startedAt": "2026-02-21T03:41:00Z",
|
|
421
|
-
"completedAt": "2026-02-21T04:16:00Z",
|
|
422
|
-
"status": "completed",
|
|
423
|
-
"phaseDecisions": {
|
|
424
|
-
"architecture": { "run": true, "disposition": "executed", "reason": "External plan requires validation" },
|
|
425
|
-
"planning": { "run": true, "disposition": "executed", "reason": "External plan present" },
|
|
426
|
-
"implementation": { "run": true, "disposition": "executed" },
|
|
427
|
-
"review-cycle": { "run": true, "disposition": "executed" },
|
|
428
|
-
"parallelReview": { "run": true, "disposition": "executed" },
|
|
429
|
-
"codeSimplifier": { "run": true, "disposition": "executed" },
|
|
430
|
-
"holisticReview": { "run": true, "disposition": "executed" }
|
|
431
|
-
},
|
|
432
|
-
"phases": {
|
|
433
|
-
"architecture": {
|
|
434
|
-
"status": "completed",
|
|
435
|
-
"impactLevel": "moderate",
|
|
436
|
-
"startedAt": "2026-02-21T03:41:30Z",
|
|
437
|
-
"completedAt": "2026-02-21T03:42:00Z"
|
|
438
|
-
},
|
|
439
|
-
"planning": {
|
|
440
|
-
"status": "completed",
|
|
441
|
-
"stepCount": 5,
|
|
442
|
-
"startedAt": "2026-02-21T03:42:10Z",
|
|
443
|
-
"completedAt": "2026-02-21T03:43:00Z"
|
|
444
|
-
},
|
|
445
|
-
"implementation": {
|
|
446
|
-
"status": "completed",
|
|
447
|
-
"startedAt": "2026-02-21T03:43:10Z",
|
|
448
|
-
"completedAt": "2026-02-21T03:45:00Z"
|
|
449
|
-
},
|
|
450
|
-
"parallelReview": {
|
|
451
|
-
"status": "completed",
|
|
452
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
453
|
-
"completedAt": "2026-02-21T04:10:00Z",
|
|
454
|
-
"aggregatedCriticality": "medium",
|
|
455
|
-
"reviewers": {
|
|
456
|
-
"reviewer": {
|
|
457
|
-
"status": "completed",
|
|
458
|
-
"criticality": "medium",
|
|
459
|
-
"reReviewCriticality": "low",
|
|
460
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
461
|
-
"completedAt": "2026-02-21T03:47:00Z"
|
|
462
|
-
},
|
|
463
|
-
"silent-failure-reviewer": {
|
|
464
|
-
"status": "completed",
|
|
465
|
-
"criticality": "low",
|
|
466
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
467
|
-
"completedAt": "2026-02-21T03:47:00Z"
|
|
468
|
-
},
|
|
469
|
-
"test-reviewer": { "status": "skipped", "reason": "no source or test files changed" },
|
|
470
|
-
"code-reviewer": {
|
|
471
|
-
"status": "completed",
|
|
472
|
-
"criticality": "medium",
|
|
473
|
-
"reReviewCriticality": "none",
|
|
474
|
-
"startedAt": "2026-02-21T03:45:10Z",
|
|
475
|
-
"completedAt": "2026-02-21T03:47:00Z"
|
|
476
|
-
}
|
|
477
|
-
},
|
|
478
|
-
"coderFixCycleRan": true,
|
|
479
|
-
"selectiveReReview": {
|
|
480
|
-
"ran": true,
|
|
481
|
-
"reviewersDispatched": ["reviewer", "code-reviewer"],
|
|
482
|
-
"additionalFixCycleRan": false
|
|
483
|
-
},
|
|
484
|
-
"iterations": [
|
|
485
|
-
{
|
|
486
|
-
"reviewers": ["reviewer", "silent-failure-reviewer", "code-reviewer"],
|
|
487
|
-
"dispatchedAt": "2026-02-21T03:45:10Z",
|
|
488
|
-
"reviewsCompletedAt": "2026-02-21T03:47:00Z",
|
|
489
|
-
"coderFixStartedAt": "2026-02-21T03:47:30Z",
|
|
490
|
-
"coderFixCompletedAt": "2026-02-21T04:00:00Z"
|
|
491
|
-
},
|
|
492
|
-
{
|
|
493
|
-
"reviewers": ["reviewer", "code-reviewer"],
|
|
494
|
-
"dispatchedAt": "2026-02-21T04:00:30Z",
|
|
495
|
-
"reviewsCompletedAt": "2026-02-21T04:10:00Z"
|
|
496
|
-
}
|
|
497
|
-
]
|
|
498
|
-
},
|
|
499
|
-
"codeSimplifier": {
|
|
500
|
-
"status": "completed",
|
|
501
|
-
"ran": true,
|
|
502
|
-
"actionableFindings": true,
|
|
503
|
-
"coderFixCycleRan": true,
|
|
504
|
-
"startedAt": "2026-02-21T04:10:10Z",
|
|
505
|
-
"completedAt": "2026-02-21T04:12:00Z"
|
|
506
|
-
},
|
|
507
|
-
"holisticReview": {
|
|
508
|
-
"status": "completed",
|
|
509
|
-
"criticality": "none",
|
|
510
|
-
"startedAt": "2026-02-21T04:12:10Z",
|
|
511
|
-
"completedAt": "2026-02-21T04:15:00Z"
|
|
512
|
-
}
|
|
513
|
-
}
|
|
514
|
-
},
|
|
515
|
-
"config": {
|
|
516
|
-
"pipeline": ["architecture", "planning", "implementation", "review-cycle"],
|
|
517
|
-
"externalPlan": false,
|
|
518
|
-
"mergeBaseSha": "abc1234",
|
|
519
|
-
"diffBase": "main",
|
|
520
|
-
"maxReviewRounds": 3,
|
|
521
|
-
"effort": "medium",
|
|
522
|
-
"approvalThreshold": "medium",
|
|
523
|
-
"budgetThreshold": "medium",
|
|
524
|
-
"mode": "orchestrated",
|
|
525
|
-
"model": "claude-opus-4-6"
|
|
526
|
-
},
|
|
527
|
-
"artifacts": [
|
|
528
|
-
{
|
|
529
|
-
"filename": "01_orchestrator_run-manifest.md",
|
|
530
|
-
"role": "orchestrator",
|
|
531
|
-
"roleType": "orchestrator",
|
|
532
|
-
"agent": "orchestrator",
|
|
533
|
-
"type": "run-manifest",
|
|
534
|
-
"phase": "initialization",
|
|
535
|
-
"createdAt": "2026-02-21T03:41:00Z"
|
|
536
|
-
},
|
|
537
|
-
{
|
|
538
|
-
"filename": "02_architect_architecture.md",
|
|
539
|
-
"role": "architect",
|
|
540
|
-
"roleType": "analyst",
|
|
541
|
-
"agent": "orchestrated-architect",
|
|
542
|
-
"type": "architecture",
|
|
543
|
-
"phase": "architecture",
|
|
544
|
-
"createdAt": "2026-02-21T03:42:00Z"
|
|
545
|
-
},
|
|
546
|
-
{
|
|
547
|
-
"filename": "03_planner_orchestration-plan.md",
|
|
548
|
-
"role": "planner",
|
|
549
|
-
"roleType": "planner",
|
|
550
|
-
"agent": "orchestrated-planner",
|
|
551
|
-
"type": "orchestration-plan",
|
|
552
|
-
"phase": "planning",
|
|
553
|
-
"createdAt": "2026-02-21T03:43:00Z"
|
|
554
|
-
},
|
|
555
|
-
{
|
|
556
|
-
"filename": "04_coder_change-summary.md",
|
|
557
|
-
"role": "coder",
|
|
558
|
-
"roleType": "author",
|
|
559
|
-
"agent": "orchestrated-coder",
|
|
560
|
-
"type": "change-summary",
|
|
561
|
-
"phase": "implementation",
|
|
562
|
-
"createdAt": "2026-02-21T03:45:00Z"
|
|
563
|
-
},
|
|
564
|
-
{
|
|
565
|
-
"filename": "05_reviewer_review.md",
|
|
566
|
-
"role": "reviewer",
|
|
567
|
-
"roleType": "reviewer",
|
|
568
|
-
"agent": "orchestrated-reviewer",
|
|
569
|
-
"type": "review",
|
|
570
|
-
"phase": "parallelReview",
|
|
571
|
-
"createdAt": "2026-02-21T03:47:00Z",
|
|
572
|
-
"iteration": 1
|
|
573
|
-
},
|
|
574
|
-
{
|
|
575
|
-
"filename": "06_silent-failure-reviewer_silent-failure-review.md",
|
|
576
|
-
"role": "silent-failure-reviewer",
|
|
577
|
-
"roleType": "reviewer",
|
|
578
|
-
"agent": "aspect-silent-failure-reviewer",
|
|
579
|
-
"type": "silent-failure-review",
|
|
580
|
-
"phase": "parallelReview",
|
|
581
|
-
"createdAt": "2026-02-21T03:47:00Z",
|
|
582
|
-
"iteration": 1
|
|
583
|
-
},
|
|
584
|
-
{
|
|
585
|
-
"filename": "07_code-reviewer_code-review.md",
|
|
586
|
-
"role": "code-reviewer",
|
|
587
|
-
"roleType": "reviewer",
|
|
588
|
-
"agent": "aspect-code-reviewer",
|
|
589
|
-
"type": "code-review",
|
|
590
|
-
"phase": "parallelReview",
|
|
591
|
-
"createdAt": "2026-02-21T03:47:00Z",
|
|
592
|
-
"iteration": 1
|
|
593
|
-
},
|
|
594
|
-
{
|
|
595
|
-
"filename": "08_coder_change-summary.md",
|
|
596
|
-
"role": "coder",
|
|
597
|
-
"roleType": "author",
|
|
598
|
-
"agent": "orchestrated-coder",
|
|
599
|
-
"type": "change-summary",
|
|
600
|
-
"phase": "parallelReview",
|
|
601
|
-
"createdAt": "2026-02-21T04:00:00Z",
|
|
602
|
-
"note": "Addresses aggregated findings from iteration 1"
|
|
603
|
-
},
|
|
604
|
-
{
|
|
605
|
-
"filename": "09_reviewer_review.md",
|
|
606
|
-
"role": "reviewer",
|
|
607
|
-
"roleType": "reviewer",
|
|
608
|
-
"agent": "orchestrated-reviewer",
|
|
609
|
-
"type": "review",
|
|
610
|
-
"phase": "parallelReview",
|
|
611
|
-
"createdAt": "2026-02-21T04:15:00Z",
|
|
612
|
-
"iteration": 2
|
|
613
|
-
},
|
|
614
|
-
{
|
|
615
|
-
"filename": "10_orchestrator_run-summary.md",
|
|
616
|
-
"role": "orchestrator",
|
|
617
|
-
"roleType": "orchestrator",
|
|
618
|
-
"agent": "orchestrator",
|
|
619
|
-
"type": "run-summary",
|
|
620
|
-
"phase": "summary",
|
|
621
|
-
"createdAt": "2026-02-21T04:16:00Z"
|
|
622
|
-
}
|
|
623
|
-
]
|
|
624
|
-
}
|
|
625
|
-
```
|
|
626
|
-
|
|
627
|
-
**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"`.
|
|
628
|
-
|
|
629
|
-
### roleType taxonomy
|
|
630
|
-
|
|
631
|
-
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`:
|
|
632
|
-
|
|
633
|
-
| roleType | Description | Example roles |
|
|
634
|
-
| -------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
635
|
-
| `orchestrator` | Coordinates phases and manages run state | `orchestrator` |
|
|
636
|
-
| `analyst` | Assesses impact and provides architectural guidance | `architect` |
|
|
637
|
-
| `planner` | Produces implementation plans | `planner` |
|
|
638
|
-
| `author` | Writes or modifies project code | `coder` |
|
|
639
|
-
| `reviewer` | Evaluates code and produces findings | `reviewer`, `code-reviewer`, `code-simplification-reviewer`, `silent-failure-reviewer`, `test-reviewer` |
|
|
640
|
-
|
|
641
|
-
### Artifact entry fields
|
|
642
|
-
|
|
643
|
-
| Field | Required | Description |
|
|
644
|
-
| ----------- | -------- | -------------------------------------------------------------------------------------- |
|
|
645
|
-
| `filename` | yes | Artifact filename (without directory path) |
|
|
646
|
-
| `role` | yes | Filename role segment (e.g., `reviewer`, `code-reviewer`) |
|
|
647
|
-
| `roleType` | yes | Workflow function (one of: `orchestrator`, `analyst`, `planner`, `author`, `reviewer`) |
|
|
648
|
-
| `agent` | yes | {tool:Task} `subagent_type` value (e.g., `plan-reviewer`) |
|
|
649
|
-
| `type` | yes | Artifact type (e.g., `review`, `change-summary`) |
|
|
650
|
-
| `phase` | yes | Phase that produced this artifact (camelCase, matches `phases` object keys) |
|
|
651
|
-
| `createdAt` | yes | ISO 8601 timestamp |
|
|
652
|
-
| `iteration` | no | Review iteration number (for `parallelReview` phase) |
|
|
653
|
-
| `note` | no | Free-text context about the artifact |
|
|
654
|
-
|
|
655
|
-
### Phase values
|
|
656
|
-
|
|
657
|
-
Phase values use camelCase and match the keys in the `phases` object. Only the retired orchestration engine wrote them:
|
|
658
|
-
|
|
659
|
-
- `initialization`: Run setup and manifest creation
|
|
660
|
-
- `architecture`: Architectural impact assessment
|
|
661
|
-
- `planning`: Implementation planning
|
|
662
|
-
- `implementation`: Code authoring
|
|
663
|
-
- `parallelReview`: Parallel review and fix cycles
|
|
664
|
-
- `codeSimplifier`: Code simplification pass
|
|
665
|
-
- `holisticReview`: Final comprehensive review
|
|
666
|
-
- `summary`: Run summary generation
|
|
366
|
+
## Run data format
|
|
667
367
|
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
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.
|
|
671
|
-
|
|
672
|
-
## V3 format: Event-sourced runs
|
|
673
|
-
|
|
674
|
-
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.
|
|
675
|
-
|
|
676
|
-
### V3 header schema
|
|
677
|
-
|
|
678
|
-
`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.
|
|
679
|
-
|
|
680
|
-
Context fields: `runId`, `projectSlug`, `ticketId?`, `projectRoot`, `branch`, `task`, `startedAt`.
|
|
681
|
-
|
|
682
|
-
Config fields: `externalPlan?`, `mergeBaseSha?`, `diffBase?`, `maxReviewRounds?`, `effort?`, `approvalThreshold?`, `budgetThreshold?`, `mode?`, `model?`. Additional fields are preserved (loose schema).
|
|
683
|
-
|
|
684
|
-
### Run-log.jsonl
|
|
685
|
-
|
|
686
|
-
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.
|
|
687
|
-
|
|
688
|
-
### Event types
|
|
689
|
-
|
|
690
|
-
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:
|
|
691
|
-
|
|
692
|
-
| Event type | Key fields |
|
|
693
|
-
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
694
|
-
| `run_started` | _(none beyond `t`, `event`)_ |
|
|
695
|
-
| `run_completed` | `status` (`completed`\|`failed`\|`needs_manual_review`) |
|
|
696
|
-
| `run_failed` | `status`, `reason?` |
|
|
697
|
-
| `phase_decision` | `phase` (string), `run` (boolean), `reason?` |
|
|
698
|
-
| `phase_started` | `phase` (one of: `architecture`\|`planning`\|`implementation`\|`review`\|`simplifier`\|`holistic`) |
|
|
699
|
-
| `phase_completed` | `phase`, `status` (one of: `completed`\|`skipped`\|`failed`\|`in_progress`\|`approved`), `data?` (record), `tokens?`, `toolUses?`, `durationMs?` |
|
|
700
|
-
| `reviewer_dispatched` | `reviewer` (string) |
|
|
701
|
-
| `reviewer_completed` | `reviewer`, `status` (`completed`\|`skipped`\|`failed`), `criticality` (`none`\|`low`\|`medium`\|`high`), `tokens?`, `toolUses?`, `durationMs?` |
|
|
702
|
-
| `coder_fix_started` | `iteration` (number) |
|
|
703
|
-
| `coder_fix_completed` | `iteration` (number), `tokens?`, `toolUses?`, `durationMs?` |
|
|
704
|
-
| `re_review_dispatched` | `reviewers` (string array) |
|
|
705
|
-
| `re_review_completed` | `criticalities` (record: reviewer name -> criticality), `tokens?`, `toolUses?`, `durationMs?` |
|
|
706
|
-
| `artifact_written` | `filename`, `role`, `roleType`, `agent`, `type`, `phase`, `iteration?`, `note?` |
|
|
707
|
-
|
|
708
|
-
### Run directory layout (v3)
|
|
709
|
-
|
|
710
|
-
```
|
|
711
|
-
{base_dir}/projects/{projectSlug}/tickets/{ticketId}/{runId}/
|
|
712
|
-
run-index.json <- v3 header (top-level completedAt once the run completed)
|
|
713
|
-
run-log.jsonl <- append-only event log (one JSON object per line)
|
|
714
|
-
{NN}_{role}_{artifact}.md <- artifact files (sequential counter)
|
|
715
|
-
```
|
|
716
|
-
|
|
717
|
-
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`).
|
|
718
|
-
|
|
719
|
-
### Run ID format (v3)
|
|
720
|
-
|
|
721
|
-
`{yyyymmdd}-{hhmmss}Z`, generated by the engine. This differs from the historical v2 format `{yyyymmdd}-{hhmmss}Z-orchestrated`.
|
|
722
|
-
|
|
723
|
-
### Event folding
|
|
724
|
-
|
|
725
|
-
Full run state (phases, artifacts, review rounds, criticalities) is reconstructed from `run-log.jsonl` by run-core's `foldEvents` function, which returns a `CanonicalRunStatus`.
|
|
726
|
-
|
|
727
|
-
### Backward compatibility
|
|
728
|
-
|
|
729
|
-
V2 and v1 `run-index.json` formats remain supported by the Factory consumer.
|
|
368
|
+
The files that describe a run directory, `run-index.json`, `run-log.jsonl`, and the v1 `status.json`, are specified in [run data format](https://github.com/williamthorsen/codeassembly/blob/main/packages/run-core/docs/run-data-format.md), beside the run-core schemas that implement them. The retired orchestration engine wrote them; the current skills do not.
|
|
730
369
|
|
|
731
370
|
## Artifact types
|
|
732
371
|
|
|
@@ -753,6 +392,7 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
|
|
|
753
392
|
- `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)
|
|
754
393
|
- `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/`
|
|
755
394
|
- `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
|
|
395
|
+
- `feedback-curation`: The record of a `curate-feedback` run: the count of events in each bin, the guidance commits against which the judges read, each mark with its result, and every event with its bin, reference, and reason; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
|
|
756
396
|
- `feedback-triage`: The record of a `triage-feedback` run: each surfaced cluster of feedback events with its signals, priority, challenge, disposition, and result, and the remainder left in the pool. A deferred event's `addressed-by` names the artifact, whose filename timestamp dates the deferral; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
|
|
757
397
|
- `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
|
|
758
398
|
- `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
|
|
@@ -961,57 +601,3 @@ Every level degrades gracefully:
|
|
|
961
601
|
- Missing global preferences -> fall back to the default base directory
|
|
962
602
|
- Missing `{base_dir}/` directory -> created automatically on first artifact save
|
|
963
603
|
- Missing `project.slug` in preferences -> use the bare directory name of the working directory
|
|
964
|
-
|
|
965
|
-
## Migration from status.json (v1) to run-index.json (v2)
|
|
966
|
-
|
|
967
|
-
The retired orchestration engine wrote both formats. This section records how they differ, for readers of historical runs.
|
|
968
|
-
|
|
969
|
-
### File rename
|
|
970
|
-
|
|
971
|
-
`status.json` → `run-index.json`. The new name reflects the file's expanded role as an artifact registry, not just a status tracker.
|
|
972
|
-
|
|
973
|
-
### Schema changes
|
|
974
|
-
|
|
975
|
-
- **New `version` field** (value: `2`). Enables schema detection; absent version = v1.
|
|
976
|
-
- **`context` section** groups: `runId`, `projectSlug`, `ticketId`, `projectRoot`, `branch`, `task`, `startedAt`, `completedAt`, `status`, `phases`, `phaseDecisions`.
|
|
977
|
-
- **`config` section** groups: `externalPlan`, `mergeBaseSha` (new), `diffBase` (new), `maxReviewRounds` (new), `effort` (new), `approvalThreshold` (new), `budgetThreshold` (new), `mode`, `model`.
|
|
978
|
-
- **`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`).
|
|
979
|
-
- **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.
|
|
980
|
-
- **New `artifacts` array**. Each entry includes `roleType` for workflow-function classification. See [artifact entry fields](#artifact-entry-fields) for the full schema.
|
|
981
|
-
|
|
982
|
-
### Role and reviewer renames
|
|
983
|
-
|
|
984
|
-
Reviewer keys in `context.phases.parallelReview.reviewers`:
|
|
985
|
-
|
|
986
|
-
| v1 key | v2 key |
|
|
987
|
-
| ----------------------- | ------------------------- |
|
|
988
|
-
| `core` | `reviewer` |
|
|
989
|
-
| `aspect-silent-failure` | `silent-failure-reviewer` |
|
|
990
|
-
| `aspect-test` | `test-reviewer` |
|
|
991
|
-
| `aspect-code` | `code-reviewer` |
|
|
992
|
-
|
|
993
|
-
Role segments in artifact filenames:
|
|
994
|
-
|
|
995
|
-
| v1 role | v2 role |
|
|
996
|
-
| -------- | ------------------------------ |
|
|
997
|
-
| `aspect` | `silent-failure-reviewer` |
|
|
998
|
-
| `aspect` | `test-reviewer` |
|
|
999
|
-
| `aspect` | `code-reviewer` |
|
|
1000
|
-
| `aspect` | `code-simplification-reviewer` |
|
|
1001
|
-
|
|
1002
|
-
### Timestamp format
|
|
1003
|
-
|
|
1004
|
-
All timestamps (run IDs and artifact filenames): `YYYYMMDD-HHMMZ` → `YYYYMMDD-HHMMSSZ` (adds seconds).
|
|
1005
|
-
|
|
1006
|
-
### Known consumers (codeassembly)
|
|
1007
|
-
|
|
1008
|
-
The following codeassembly files reference the run metadata schema and will need updates:
|
|
1009
|
-
|
|
1010
|
-
- `project-scanner.ts`: Filename patterns for artifact discovery
|
|
1011
|
-
- `status-adapter.ts`: Schema parsing and normalization
|
|
1012
|
-
- `runs.ts`: Artifact filtering and run enumeration
|
|
1013
|
-
- `canonical.ts`: Type definitions
|
|
1014
|
-
|
|
1015
|
-
### Backward compatibility
|
|
1016
|
-
|
|
1017
|
-
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.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
An inventory is clustered in batches, because one clusterer cannot place every event of a large store. Each batch is clustered on its own, and when there is more than one, a merge pass groups the batch clusters that teach the same lesson.
|
|
2
|
+
|
|
3
|
+
1. Run `lesson-clusters inventory --store <store> --out {work}/inventory.json`. Report each `skipped` file, and stop when `pool` and `deferred` are both zero: Nothing awaits attention.
|
|
4
|
+
2. Run `lesson-clusters batch --inventory {work}/inventory.json --out {work}/batches`. Its `batches` list gives each batch's `path` and the `map` path to which its clusterer writes.
|
|
5
|
+
3. Send one {tool:Task} call per batch, all in one message, `subagent_type: lesson-clusterer`, each with this block and nothing else composed into it:
|
|
6
|
+
|
|
7
|
+
```dispatch
|
|
8
|
+
inventory: {batch path}
|
|
9
|
+
output: {batch map path}
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
4. When there is one batch, its map is the event map: Copy `{work}/batches/map-01.json` to `{work}/map.json`, and skip sub-steps 5 to 7.
|
|
13
|
+
5. Run `lesson-clusters lessons --batches {work}/batches --out {work}/lessons.json`. On `invalid-map`, resume the clusterer of each batch that the `violations` name once, sending it that batch's violations and asking it to correct its map; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. Run `lessons` again, and on a second failure, stop and report the violations.
|
|
14
|
+
6. Send one more {tool:Task} call, `subagent_type: lesson-clusterer`, for the merge pass:
|
|
15
|
+
|
|
16
|
+
```dispatch
|
|
17
|
+
inventory: {work}/lessons.json
|
|
18
|
+
output: {work}/merge.json
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
7. Run `lesson-clusters combine --batches {work}/batches --lessons {work}/lessons.json --map {work}/merge.json --out {work}/map.json`. On `invalid-map`, resume the merge clusterer once with the violations, run `combine` again, and on a second failure, stop and report them.
|
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
|
|
61
61
|
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
|
|
62
62
|
|
|
63
|
-
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge.
|
|
63
|
+
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge. When a verdict from an agent decides such a write, the acceptance criteria of the task that implements the verdict name the evidence and the script that checks it before the write. When the work adds or changes a skill that writes to shared state, `## Verification` runs the skill against the real data up to its approval checkpoint or as a dry run, and reviews each verdict that the run would act on.
|
|
64
64
|
|
|
65
65
|
**Per-task invoked-skill guidance:** When a task invokes a skill, read that skill while planning the task and record in the task's key decisions what the skill declares under three headings: its ordering relative to other skills, its default target when the task does not pass an argument, and the preconditions that it states. Read every skill that the plan's tasks name, and record a skill declaring none of the three as declaring none, so that a reader can tell a completed check from an absent one. A skill that cannot be read is recorded as unread, never as declaring none. When an ordering constraint names a skill that the plan's tasks do not invoke, add the task rather than record the constraint alone.
|
|
66
66
|
|
|
@@ -4,4 +4,4 @@
|
|
|
4
4
|
|
|
5
5
|
**Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must be merged before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
|
|
6
6
|
|
|
7
|
-
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration.
|
|
7
|
+
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration. When the ticket adds or changes a skill that writes to shared state, include a criterion that the skill runs against the real data before merge and stops before the write, and when a verdict from an agent decides that write, a criterion that a script checks the verdict's evidence before the write.
|