unic / unic/unic-agents-plugins

feat(unic-archon-dlc): the /specs gate asks for approval of an artefact nobody reads

Open
#437 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app:unic-archon-dlc feature needs-specs p1
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-pr asks 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; commit a0105b5 is the correction, 675e70f the original.
  • Run 1's artefacts for comparison are addressable at a71e19f7a6e18d3ffca22c271781e25e0c0db987.
  • Four other /specs defects 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: discuss and false under assumptions, 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 under discuss, 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.