unic / unic/unic-agents-plugins
feat(unic-archon-dlc): the /specs gate asks for approval of an artefact nobody reads
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 1
- Forks
- 0
- Avg merge
- 16h 43m
- Merged PRs (30d)
- 19
Description
The problem
/specs ends at gate: open-pr. The gate opens a pull request and waits for a human to approve the PRD and the design contracts.
The human it waits for does not read them, and that is by design. The maintainer's stated practice is that the grilling carries the shared understanding, so the produced artefacts are not read afterwards. That is a reasonable stance — reading three generated contracts per feature does not scale, and the grilling is where the alignment happens. It is also exactly why an ungrilled artefact is dangerous: the contracts are never grilled, and defects reach /build through them.
So the gate is a human approval on an artefact nobody reads. It records consent it did not obtain.
The worked example, 2026-08-31
A second full run of the chain on profile-card in DXP-DesignSystem (ADO WI 43004, PR 5825).
docs/agents/figma.md § The override rule declares a mechanical test: export the SVG, take the colour literals, normalise, compare against the resolved values get_variable_defs returns. A literal outside the resolved set is a defect, not a specification.
The run did not perform it. All three contracts said Findings: none, resting on the weaker claim that every recorded value arrived as a token name — true as written, and not the documented test.
When the test was eventually run, it failed: icon/interface/User2 Style=line strokes a bare black, get_variable_defs on that node returns {}, so the literal has no backing token. No code change fixes it; it needs a token binding in Figma. The defect was real, it was in the design, and three contracts had asserted its absence.
Nothing in the chain would have caught this. It surfaced because an orchestrating session measured the new contracts against the previous run's, asked for a per-section audit, and then refused the two options the audit produced — disclose the unrun check, or note it in the report — because both shipped the test unrun. That is one seat, on one day, with spare attention. It is not a repeatable safeguard.
Why the existing review does not cover it
unic-dlc-pr-review runs on a pull request and reviews a diff. This defect is not visible in a diff: the contract is internally consistent, well formed, and states something false about the world. Only a reader who knows which checks the documentation declares, and asks which of them ran, finds it.
/build-feature's review loop runs after the contracts are already the input to /build.
What this is not
Not a request for the maintainer to read the contracts. That is the practice the design already, correctly, assumes away.
Not a request for another test module. This repository's product is prose and its bar is a run and a read.
The open question, to be grilled before criteria are written
What reads a produced artefact before a human is asked to approve it, and what does it check?
Candidates worth putting under pressure, none of them decided:
- A self-audit step inside
/specs, before the gate: the command lists the checks its own documentation declares and states, per check, whether this run performed it. Today's evidence is specific about which half of an audit pays — counting rows against the required sections found nothing; asking which documented checks did I actually run found everything. Headings are cheap to satisfy and prove nothing. - A reviewing agent at the gate, reading the artefact against the documents it was generated from rather than against a diff.
- Making the gate's question specific.
open-prasks a human to approve. It could instead ask them to answer one or two questions the artefact's own content generates, which fails loudly when nobody reads it.
Evidence
- ADO WI 43004 and PR 5825 in
DXP-DesignSystem; commita0105b5is the correction,675e70fthe original. - Run 1's artefacts for comparison are addressable at
a71e19f7a6e18d3ffca22c271781e25e0c0db987. - Four other
/specsdefects from the same run are filed separately.
Scope after #441's grilling, 2026-09-02
Blocked by #441 (native edge added 2026-09-02). Two of the three candidates above moved there; this ticket keeps the third.
- Kept here: make the gate's question specific. The gate asks a human to approve. It should instead ask one or two questions the artefact's own content generates, so it fails loudly when nobody reads. #441 gives it two things to ask about: whether the answers quoted in the PRD's Confirmations section are the reader's own words, and what the review of the produced artefacts returned.
- Moved to #441: the self-audit step, now a per-halt record plus a fail-closed gate check; and the reviewing agent at the gate, now the pull-request review Box running on the specs pull request with the design-conventions doc in its intent brief.
- The opening premise needs narrowing. "The human it waits for does not read them, and that is by design" is true under
specs.discuss_mode: discussand false underassumptions, where the human reading the artefacts is the alignment — the maintainer's stated intent for that value, 2026-09-02. So this ticket is properly underdiscuss, the gate has no reader, and nothing tells the gate which mode it is in. No new config value is needed; the two values already carry the two practices. - #441 is half a mechanism without this ticket. Its per-halt record is authored by the same agent that would skip the halt, so a gate reading it catches only the honest omission. A fabricated quote is caught by the one witness who knows — which is this ticket's question.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the /specs gate: open-pr entry point and inspect how specs.discuss_mode distinguishes discuss from assumptions. Read #441 for the related per-halt and review mechanisms. Done means the gate asks questions generated from the artefact, including the confirmations and review result, and fails loudly when those answers are not actually read.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100