feat(gatorwalk-factory): description fields on gates and work; lifecycle comments move into fields (swamp-club #2804) #382

Merged

seth merged 1 commit from cue/2804-gatorwalk-factory-description into main

2026-09-30 17:16:23 +00:00

seth commented

2026-09-30 17:13:40 +00:00

Owner

Closes swamp-club #2804.

Why

The studio is read-only: edits come only from the agent. It shows description fields, not YAML comments, and agents may still rewrite the lifecycle YAML, which drops comments. So what is worth keeping moves into descriptions.

What

Schema: every gate variant (all nine) and work take an optional description (_lib/lifecycle_schema.ts). The lifecycle, stages, transitions, artifacts and evidence already had one.
Never sent to an agent: dispatch.ts doesn't read descriptions. A new dispatch_test.ts case puts a marker in every description (and in a payload schema's description and $comment) and checks it never reaches the dispatch packet in any of the four work modes.
Design page: GateView.description and WorkView.description. A gate's description renders under the gate and work's above the Handoff table. Both are covered by the escaping test and kept out of the diagram.
Comments moved into fields: in the four skill examples and the three testdata lifecycles. A guard test in examples_test.ts keeps comment lines out of them.
Opening comment block: the examples' name / For / Change first block (added by #2767) now lives in the lifecycle description. examples_test.ts, SKILL.md and driving.md are updated to match.
DESIGN.md: a short "Descriptions, not comments" note in the design page section.

Where each comment went

File	Comment	Now in
all four examples	opening name / For / Change first block	lifecycle `description` (multi-paragraph). The "`<name>:`" prefix was dropped since it restated the name
swamp-club-swamp-extensions	header: what the process is, the adapter, who decides where, CEL notes	lifecycle `description`
swamp-club-swamp-extensions	triage `maxCycles` note; "one exit per type" on triage's transitions	`triage` stage description
swamp-club-swamp-extensions	regression branch inside the classification schema's `allOf`	`$comment` on that subschema
swamp-club-swamp-extensions	regression-review guard	that `human-approval` gate's `description`
swamp-club-swamp-extensions	`maxCycles` notes on plan, implement, pull-request	each stage's description
swamp-club-swamp-extensions	notify's `prUrl` binding	notify `work.description`
build-swamp-extension	header: release routes, who decides, CEL rule	lifecycle `description`
build-swamp-extension, starter	"An overall pass cannot contain a failed result."	`$comment` on the checks schema
feature-factory, sdlc-classic, retry-feedback	one-line header	lifecycle `description`
sdlc-classic	test-run evidence restates resultEvidence	that evidence entry's `description`
retry-feedback	`feedback` binding is null-safe	`work.description`

Nothing else was dropped.

Verification

Pre-PR verification passed on 4da8bbb5: build 7d5af55b-2601-4a24-b711-8b368b7a8f0a, reviews 104ea562-1edc-4f89-a097-818ec68a9441. The attestation is posted.

Both reviews raised one low finding: the guard only catches whole-line comments, so a comment at the end of a line would get through. No file has one, and the acceptance criterion is about comment lines.

🤖 Generated with Claude Code

Closes swamp-club #2804. ## Why The studio is read-only: edits come only from the agent. It shows `description` fields, not YAML comments, and agents may still rewrite the lifecycle YAML, which drops comments. So what is worth keeping moves into descriptions. ## What - **Schema:** every gate variant (all nine) and `work` take an optional `description` (`_lib/lifecycle_schema.ts`). The lifecycle, stages, transitions, artifacts and evidence already had one. - **Never sent to an agent:** `dispatch.ts` doesn't read descriptions. A new `dispatch_test.ts` case puts a marker in every description (and in a payload schema's `description` and `$comment`) and checks it never reaches the dispatch packet in any of the four work modes. - **Design page:** `GateView.description` and `WorkView.description`. A gate's description renders under the gate and work's above the Handoff table. Both are covered by the escaping test and kept out of the diagram. - **Comments moved into fields:** in the four skill examples and the three testdata lifecycles. A guard test in `examples_test.ts` keeps comment lines out of them. - **Opening comment block:** the examples' name / For / Change first block (added by #2767) now lives in the lifecycle `description`. `examples_test.ts`, `SKILL.md` and `driving.md` are updated to match. - **DESIGN.md:** a short "Descriptions, not comments" note in the design page section. ## Where each comment went | File | Comment | Now in | | --- | --- | --- | | all four examples | opening name / For / Change first block | lifecycle `description` (multi-paragraph). The "`<name>:`" prefix was dropped since it restated the name | | swamp-club-swamp-extensions | header: what the process is, the adapter, who decides where, CEL notes | lifecycle `description` | | swamp-club-swamp-extensions | triage `maxCycles` note; "one exit per type" on triage's transitions | `triage` stage description | | swamp-club-swamp-extensions | regression branch inside the classification schema's `allOf` | `$comment` on that subschema | | swamp-club-swamp-extensions | regression-review guard | that `human-approval` gate's `description` | | swamp-club-swamp-extensions | `maxCycles` notes on plan, implement, pull-request | each stage's description | | swamp-club-swamp-extensions | notify's `prUrl` binding | notify `work.description` | | build-swamp-extension | header: release routes, who decides, CEL rule | lifecycle `description` | | build-swamp-extension, starter | "An overall pass cannot contain a failed result." | `$comment` on the checks schema | | feature-factory, sdlc-classic, retry-feedback | one-line header | lifecycle `description` | | sdlc-classic | test-run evidence restates resultEvidence | that evidence entry's `description` | | retry-feedback | `feedback` binding is null-safe | `work.description` | Nothing else was dropped. ## Verification Pre-PR verification passed on `4da8bbb5`: build `7d5af55b-2601-4a24-b711-8b368b7a8f0a`, reviews `104ea562-1edc-4f89-a097-818ec68a9441`. The attestation is posted. Both reviews raised one low finding: the guard only catches whole-line comments, so a comment at the end of a line would get through. No file has one, and the acceptance criterion is about comment lines. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

seth added 1 commit

2026-09-30 17:13:40 +00:00

feat(gatorwalk-factory): description fields on gates and work; lifecycle comments move into fields (swamp-club #2804 )

CI / Review Integrity (pull_request) Successful in 1m6s

Details

CI / Validate Attestation (pull_request) Successful in 1m11s

Details

4da8bbb53e

Every gate variant and work take an optional author-facing description,
carried through designView and shown on the design page. No engine path
sends a description to an agent; a dispatch test pins that across all four
work modes.

The comments in the skill's example lifecycles and the testdata lifecycles
move into description fields: the opening name/For/Change first block into
the lifecycle description, cycle-limit notes into stage descriptions, gate
notes into gate descriptions, binding notes into the work description, and
notes inside payload schemas into $comment. A guard test keeps comments out
of lifecycle files. The studio is read-only and shows descriptions, not
comments, and agents may still rewrite the YAML, which drops comments.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

seth merged commit 89705f202e into main

2026-09-30 17:16:23 +00:00

seth referenced this pull request from a commit

2026-09-30 17:16:25 +00:00

feat(gatorwalk-factory): description fields on gates and work; lifecycle comments move into fields (swamp-club #2804) (#382)

seth deleted branch cue/2804-gatorwalk-factory-description

2026-09-30 17:16:33 +00:00