A describe on a spec-resolved can leaf is silently ignored, so guardfile prose can be written and never render #1406

New issue

Open

opened 2026-08-29 11:06:05 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-29 11:06:05 +00:00

Owner

Found while building and diffing aosguard for #1375.

What happens

A describe inside a spec-resolved can leaf is accepted by the parser, changes nothing in the built binary, and reports no warning. The swagger summary wins.

Measured against a build with the pinned specgen 0.184.0:

can pin issue {
    op pinIssue
    describe "pin one issue (POST ...). Needs repository admin, which coilyco-ops now holds."
}

$ aosguard ops forgejo issue pin --help
NAME:
   aosguard ops forgejo issue pin - POST /repos/{owner}/{repo}/issues/{index}/pin
DESCRIPTION:
   POST /repos/{owner}/{repo}/issues/{index}/pin

It is not hypothetical, and it is already in the tree

.specgen/guardfiles/aosguard/forgejo.kdl carries at least one today:

can search repo {
    describe "cross-repo repo finder (GET /repos/search)"
}

$ aosguard ops forgejo repo search --help
NAME:
   aosguard ops forgejo repo search - GET /repos/search

Somebody wrote that sentence for an operator and no operator has ever read it.

Where it does work

describe renders on an action block (the issue create guard's long describe is visible in --help) and on exec-dialect leaves (action-run list shows "List Actions runs with a safe page-1 default.").

So the rule is real but unwritten: describe is for action and exec leaves; on a spec-resolved can it is dead text.

Why it belongs in this milestone

Same class as the rest of it. A guard, a budget, or a doc string that reads as doing something and does nothing. The author gets no signal, and the failure is invisible from inside the file.

What a fix could be

Either surface it - let describe override the swagger summary on a can leaf, which is what an author writing one plainly intends - or refuse it at flatten time, the way an override lifting no never is already a build error. Refusing is cheaper and matches the existing precedent for a clause that does nothing.

Whichever way it goes, can search repo's dead describe should be removed or made to render.

Found while building and diffing aosguard for #1375. ## What happens A `describe` inside a spec-resolved `can` leaf is accepted by the parser, changes nothing in the built binary, and reports no warning. The swagger summary wins. Measured against a build with the pinned specgen 0.184.0: ```kdl can pin issue { op pinIssue describe "pin one issue (POST ...). Needs repository admin, which coilyco-ops now holds." } ``` ``` $ aosguard ops forgejo issue pin --help NAME: aosguard ops forgejo issue pin - POST /repos/{owner}/{repo}/issues/{index}/pin DESCRIPTION: POST /repos/{owner}/{repo}/issues/{index}/pin ``` ## It is not hypothetical, and it is already in the tree `.specgen/guardfiles/aosguard/forgejo.kdl` carries at least one today: ```kdl can search repo { describe "cross-repo repo finder (GET /repos/search)" } ``` ``` $ aosguard ops forgejo repo search --help NAME: aosguard ops forgejo repo search - GET /repos/search ``` Somebody wrote that sentence for an operator and no operator has ever read it. ## Where it does work `describe` renders on an `action` block (the `issue create` guard's long describe is visible in `--help`) and on exec-dialect leaves (`action-run list` shows "List Actions runs with a safe page-1 default."). So the rule is real but unwritten: **describe is for `action` and exec leaves; on a spec-resolved `can` it is dead text.** ## Why it belongs in this milestone Same class as the rest of it. A guard, a budget, or a doc string that reads as doing something and does nothing. The author gets no signal, and the failure is invisible from inside the file. ## What a fix could be Either surface it - let `describe` override the swagger summary on a `can` leaf, which is what an author writing one plainly intends - or refuse it at flatten time, the way an `override` lifting no `never` is already a build error. Refusing is cheaper and matches the existing precedent for a clause that does nothing. Whichever way it goes, `can search repo`'s dead describe should be removed or made to render.

coilyco-ops added the

autonomy

headless

priority

labels

2026-08-29 11:06:06 +00:00

coilyco-ops referenced this issue

2026-08-29 11:12:10 +00:00

#1349 breaks 65 existing aosguard ops kubectl call sites at rebuild, including two live-mutation scripts #1352