KDL files should be full human readable, not quirky programmer shortcuts

coilysiren commented

2026-06-24 16:51:34 +00:00

Owner

Things that don't have builtin human understandable meaning:

argv0
$input.repo
...

Things that don't have builtin human understandable meaning: - `argv0` - `$input.repo` - ...

coilyco-ops added the

P3

interactive

labels

2026-06-24 17:20:18 +00:00

coilyco-ops commented

2026-06-24 17:30:41 +00:00

Member

Re-triage (goose-triage method, claude-macos-kais-macbook-pro-2 as the judgment engine, 2026-06-24)

P3 - Concrete legibility cleanup of KDL token names, kept but not urgent. Default-low keep.
interactive - Renaming argv0/$input.repo to human names is a design/naming call Kai should ratify, so the agent proposes and pauses.

**Re-triage** (goose-triage method, claude-macos-kais-macbook-pro-2 as the judgment engine, 2026-06-24) - **P3** - Concrete legibility cleanup of KDL token names, kept but not urgent. Default-low keep. - **interactive** - Renaming argv0/$input.repo to human names is a design/naming call Kai should ratify, so the agent proposes and pauses.

coilysiren added

consult

and removed

interactive

labels

2026-07-01 04:29:43 +00:00

coilyco-ops added

headless

and removed

consult

labels

2026-07-02 00:19:34 +00:00

coilyco-ops referenced this issue

2026-07-02 00:21:36 +00:00

Zero KDL code comments, force detail into 1st class description fields #205

coilyco-ops referenced this issue

2026-07-02 00:21:44 +00:00

compress the size of ward kdl specs #297

coilyco-ops commented

2026-07-02 00:21:49 +00:00

Member

Flipped headless: propose human-readable renames/aliases for the named offenders (argv0, $input.repo, ...) as a cli-guard PR. Pairs with #205/#297. Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops commented

2026-07-04 17:39:09 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-287 on host KAI-DESKTOP-TOWER is carrying this issue (reserved 2026-07-04T17:38:58Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-287` on host `KAI-DESKTOP-TOWER` is carrying this issue (reserved 2026-07-04T17:38:58Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh** — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-04 17:47:55 +00:00

docs(ward-kdl): propose human-readable KDL token renames + document the stepflow dialect (ward#287)

coilysiren closed this issue

2026-07-04 17:47:55 +00:00

coilysiren commented

2026-07-04 17:48:24 +00:00

Author

Owner

WARD-OUTCOME: done - proposal doc for human-readable KDL token renames + newly-documented stepflow/action dialect, landed on main.

The honest surprise here was that the fix isn't mine to fully make: the offending tokens (argv, the $input.repo-family $var refs) are grammar owned by cli-guard's specverb-gen, and this container only lands ward. So a straight rename would either break every guardfile or reach into a repo I'm not granted. The comment thread confirmed the intended shape anyway - "propose renames/aliases as a cli-guard PR" - so I split the work into the two halves ward genuinely owns: the proposal (docs/kdl-legibility.md, with concrete backward-compatible alias recommendations) and the legibility win that needs no engine change (documenting the previously-undocumented action/stepflow dialect and $var refs in guardfile-grammar.md, so $src.title and friends are decodable today).

What fought back: the 80-line/4000-char doc-size cap on new docs, and the issue-refs hook rejecting bare ward#287 even in frontmatter and an H1 - both just needed rewording. Confidence is high on the docs being correct and useful; the naming choices (invoke, launch, value, operation-id) are recommendations a human should ratify, exactly as the interactive->consult->headless label history asked. Follow-up worth filing: the actual cli-guard grammar PR that adds the aliases, at which point ward's guardfiles can adopt the new spelling and this proposal can be marked implemented.

WARD-OUTCOME: done - proposal doc for human-readable KDL token renames + newly-documented stepflow/action dialect, landed on main. The honest surprise here was that the fix isn't mine to fully make: the offending tokens (`argv`, the `$input.repo`-family `$var` refs) are grammar owned by cli-guard's specverb-gen, and this container only lands ward. So a straight rename would either break every guardfile or reach into a repo I'm not granted. The comment thread confirmed the intended shape anyway - "propose renames/aliases as a cli-guard PR" - so I split the work into the two halves ward genuinely owns: the proposal (docs/kdl-legibility.md, with concrete backward-compatible alias recommendations) and the legibility win that needs no engine change (documenting the previously-undocumented `action`/stepflow dialect and `$var` refs in guardfile-grammar.md, so `$src.title` and friends are decodable today). What fought back: the 80-line/4000-char doc-size cap on new docs, and the issue-refs hook rejecting bare `ward#287` even in frontmatter and an H1 - both just needed rewording. Confidence is high on the docs being correct and useful; the naming choices (invoke, launch, value, operation-id) are recommendations a human should ratify, exactly as the interactive->consult->headless label history asked. Follow-up worth filing: the actual cli-guard grammar PR that adds the aliases, at which point ward's guardfiles can adopt the new spelling and this proposal can be marked implemented.

Rows
Columns

KDL files should be full human readable, not quirky programmer shortcuts #287