Skip to content

[defect·contract] The instruction floor says two question kinds may be re-worded; the code and its own reference say six #657

Description

@atomchung

Status

Defect. Found while reviewing PR #653; not introduced by it. Two surfaces disagree about which questions an agent may re-word, and the one that disagrees is the only file every supported client is guaranteed to read.

The contradiction

AGENTS.md's workflow step 4 — the shared always-on instruction floor:

validate and freeze private surfaces only for add_thesis and headline_motive through review.py resume, use the unchanged engine fallback otherwise

The code, and the reference the same sentence routes to, both say six:

  • engine/question_surface.py's ELIGIBLE_KINDS: add_thesis, headline_motive, initial_thesis, exit_consistency, condition_crossing, condition_basis.
  • references/interaction-delivery.md, "Author a question surface, or use the engine's": the same six by name, and it goes further — a condition_crossing's engine fallback is described as deliberately the flattest sentence it can write, because that kind specifically needs an authored stem.

So a client that loads AGENTS.md and stops there will use the engine fallback for four kinds the product built an authoring path for, including the one whose fallback is documented as intentionally inadequate.

AGENTS.md's own instruction-authority section says a genuine contradiction of this shape is a repository defect: "Stop, record it on the owning issue, and resolve the authority. Do not silently follow whichever file loaded last." Its rule 1 puts deterministic code above prose describing it, which points at the floor being the stale side — but that is the resolution to ratify, not to assume, because the floor is the one file with guaranteed delivery and shrinking what it promises is a real product decision.

Why it is worth fixing rather than tolerating

The visible effect is a silent per-client experience split. Two agents given the same review plan produce measurably different question surfaces depending on which instruction file they happened to read, and neither one is doing anything wrong. Nothing detects it: ELIGIBLE_KINDS is not drift-tested against either prose surface, so this can only be found by reading all three.

The second half, which is #636's problem

question_surface's opportunity for initial_thesis supplies only context.ticker and context.asked_because, and schemas/question-surface.schema.json's grounding_ref enum has no member for a recalled statement.

PR #653 makes the engine's initial_thesis stem quote the user's own stored words back at them instead of asking them to reconstruct an entry motive from memory. On the authored path, that stem is replaced by the agent's — and the agent is handed neither the statement nor a grounding ref that could cite it. The recall is not weakened there; it disappears, and the whole point of #636's first cut with it.

Under the floor's two-kind reading initial_thesis is never authored, so PR #653 reaches the user as intended and this is latent. Under the code's six-kind reading it is live today. Which of those is true is exactly what the contradiction above leaves undecided — the two halves have to be resolved together.

What resolving this means

  1. Decide which surface is authoritative for the eligible set, and make the other match. If the code's six is correct, AGENTS.md's sentence names six or stops enumerating and routes; if two is correct, ELIGIBLE_KINDS and references/interaction-delivery.md shrink and the condition_crossing paragraph loses its premise.
  2. Add a drift test locking ELIGIBLE_KINDS against whichever prose surfaces name the set, the same discipline review.CONSIDER_DECISIONS and the decision enum already have. Without it the next divergence is found by reading, not by failing.
  3. If initial_thesis stays authorable, the opportunity must carry the recalled statement and grounding_ref must gain a member for it — otherwise an authored stem for that kind is structurally unable to preserve what the engine's own stem now says.

Non-goals

  • No change to what any question asks, or to the question-density band.
  • No new question kind, and no widening of what an authored surface may claim.
  • Not a redesign of the authoring contract; this is a disagreement about one set plus one missing grounding member.

Acceptance

  • AGENTS.md, references/interaction-delivery.md and ELIGIBLE_KINDS state the same eligible set.
  • A test fails if any one of them changes without the others.
  • If initial_thesis remains eligible: an authored stem for it can cite the recalled statement, and a test proves an authored surface does not silently drop what the engine stem carried.
  • Existing authored-surface freeze/resume behaviour and receipts are unchanged.

Refs #636, PR #653, #398, #396.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions