120 of 130 seam refusals give the user a token with no next step

john commented

2026-08-23 12:39:38 +00:00

Owner

The gap, counted

Seam refusals hand the user a machine token and nothing else.

Measured on 2026-08-23 across cadence-core/bin/:

130 sites set a reason
10 of them set a companion hint

So roughly 120 failure paths surface something like unprovable-queue,
partial-flip, symlinked-trace, count-disagreement or unresolved-range
with no plain-language next step. The workflows correctly say "relay
reason/hint", which means the kebab-case token is the error message a
user sees.

What good already looks like

The 10 existing hints are the model to copy:

make them readable and re-run - an unreadable queue refuses a land exactly as a member does

name a --base and --head this repository can resolve, then re-run this check

Each names the action, in the user's terms, without explaining the internals.

Why this is the right target

There are two prose surfaces in this tree and only one should get simpler.

Model-facing prose stays dense. workflows/, agent contracts and
references/ are weight-budgeted and load-bearing. workflows/plan.md sits at
22,638 B against a budget of 22,638 with zero headroom, and self-verify fails
the build on overrun. Simplifying that prose makes it longer and strips the
precision that makes gates falsifiable.

User-facing text is where accessibility lives, and hints are the cheapest,
most measurable slice of it. They live in bin/, which is not weight-budgeted,
so this costs no context bytes on any surface.

Scope

Every reason site gains a hint that names what to do next, in plain
language, without requiring the reader to know the internals.
A self-verify check asserts the invariant: a reason without a hint is a
reported problem. That is what stops this regressing, and it is why this is
a phase rather than a one-off sweep.

Explicitly not in scope

No change to any reason token. They are matched by tests and by callers.
No behavior change. Purely additive text plus one new check.
No rewrite of model-facing prose.

Two softer accessibility gaps found in the same pass, both prose-judgment work
with no test behind them, so they are deliberately left out:

The ask-user question templates are already plain ("Does this roadmap
structure work for you?"). The jargon comes from what the model fills in
around them at runtime. Would need a register rail in the seam, not a code
change.
The done step report blocks are dense field lists
(Traceability: {seeded ids | none seeded | orphan_ids | no_active_section}).

Target: v3.6.1.

Moved to GitHub: https://github.com/crenshawdev/cadence/issues/90

This project's tracker is now GitHub; this repository remains the public archive. Closed here as migrated, not as resolved.

## The gap, counted Seam refusals hand the user a machine token and nothing else. Measured on 2026-08-23 across `cadence-core/bin/`: - **130** sites set a `reason` - **10** of them set a companion `hint` So roughly 120 failure paths surface something like `unprovable-queue`, `partial-flip`, `symlinked-trace`, `count-disagreement` or `unresolved-range` with no plain-language next step. The workflows correctly say "relay `reason`/`hint`", which means the kebab-case token *is* the error message a user sees. ## What good already looks like The 10 existing hints are the model to copy: > `make them readable and re-run - an unreadable queue refuses a land exactly as a member does` > `name a --base and --head this repository can resolve, then re-run this check` Each names the action, in the user's terms, without explaining the internals. ## Why this is the right target There are two prose surfaces in this tree and only one should get simpler. **Model-facing prose stays dense.** `workflows/`, agent contracts and `references/` are weight-budgeted and load-bearing. `workflows/plan.md` sits at 22,638 B against a budget of 22,638 with zero headroom, and self-verify fails the build on overrun. Simplifying that prose makes it longer and strips the precision that makes gates falsifiable. **User-facing text is where accessibility lives**, and hints are the cheapest, most measurable slice of it. They live in `bin/`, which is not weight-budgeted, so this costs no context bytes on any surface. ## Scope 1. Every `reason` site gains a `hint` that names what to do next, in plain language, without requiring the reader to know the internals. 2. A self-verify check asserts the invariant: a `reason` without a `hint` is a reported problem. That is what stops this regressing, and it is why this is a phase rather than a one-off sweep. ## Explicitly not in scope - No change to any `reason` token. They are matched by tests and by callers. - No behavior change. Purely additive text plus one new check. - No rewrite of model-facing prose. ## Deferred, related Two softer accessibility gaps found in the same pass, both prose-judgment work with no test behind them, so they are deliberately left out: - The ask-user question templates are already plain ("Does this roadmap structure work for you?"). The jargon comes from what the model fills in around them at runtime. Would need a register rail in the seam, not a code change. - The `done` step report blocks are dense field lists (`Traceability: {seeded ids | none seeded | orphan_ids | no_active_section}`). Target: `v3.6.1`. --- **Moved to GitHub: https://github.com/crenshawdev/cadence/issues/90** This project's tracker is now GitHub; this repository remains the public archive. Closed here as migrated, not as resolved.

john added the

enhancement

label

2026-08-23 12:39:38 +00:00

john commented

2026-08-23 18:45:23 +00:00

Author

Owner

Retargeting: v3.7.0, not v3.6.1.

v3.6.1 opened at the v3.6.0 close as three measured defects in what v3.6.0 shipped (WHY-02, WHY-03, WHY-04, all in /cad-why). A 120-site text sweep plus a new blocking self-verify check is a different animal, and it carries its own thesis, so it gets a minor of its own rather than riding a patch cycle.

Re-measured against the tree after v3.6.0 merged: 17 hints now, not 10, and all 17 are in planning.mjs and skim.mjs. Every other seam is at zero. release-decision.mjs 17 reasons / 0 hints, text-transport.mjs 16 / 0, route.mjs 14 / 0, bulk-output.mjs 14 / 0. v3.6.0 added seam surface faster than it added hints, so the ratio is worse than when this was filed, not better.

Part 2 of the scope is what makes it a phase: without the self-verify check the sweep is written once and the next seam ships without a hint anyway.

Seeded in .planning/CAPTURE.md so the next milestone close reads it.

Retargeting: v3.7.0, not v3.6.1. v3.6.1 opened at the v3.6.0 close as three measured defects in what v3.6.0 shipped (WHY-02, WHY-03, WHY-04, all in /cad-why). A 120-site text sweep plus a new blocking self-verify check is a different animal, and it carries its own thesis, so it gets a minor of its own rather than riding a patch cycle. Re-measured against the tree after v3.6.0 merged: 17 hints now, not 10, and all 17 are in planning.mjs and skim.mjs. Every other seam is at zero. release-decision.mjs 17 reasons / 0 hints, text-transport.mjs 16 / 0, route.mjs 14 / 0, bulk-output.mjs 14 / 0. v3.6.0 added seam surface faster than it added hints, so the ratio is worse than when this was filed, not better. Part 2 of the scope is what makes it a phase: without the self-verify check the sweep is written once and the next seam ships without a hint anyway. Seeded in .planning/CAPTURE.md so the next milestone close reads it.

john commented

2026-08-23 20:43:47 +00:00

Author

Owner

Re-measured after v3.6.0 merged: 17 reason sites now carry a hint, up from 10 when this was filed. All 17 are in planning.mjs and skim.mjs; every other seam is at zero - release-decision.mjs 17 reasons / 0 hints, text-transport.mjs 16 / 0, route.mjs 14 / 0.

v3.6.0 added seam surface faster than it added hints, so the ratio is worse than at filing, not better. That is the argument for the second half being a self-verify check rather than a one-time sweep: a sweep fixes the 130 that exist, and a check is what stops the 131st shipping without one.

Scope note carried from triage: no reason-token changes (tests and callers match them), no behavior change, and no model-facing prose rewrite - workflows/plan.md sits at its 22,638 B budget with zero headroom. The hints land in bin/, which carries no weight-budget entry, so they cost no context bytes.

Re-measured after v3.6.0 merged: 17 reason sites now carry a hint, up from 10 when this was filed. All 17 are in `planning.mjs` and `skim.mjs`; every other seam is at zero - `release-decision.mjs` 17 reasons / 0 hints, `text-transport.mjs` 16 / 0, `route.mjs` 14 / 0. v3.6.0 added seam surface faster than it added hints, so the ratio is worse than at filing, not better. That is the argument for the second half being a self-verify check rather than a one-time sweep: a sweep fixes the 130 that exist, and a check is what stops the 131st shipping without one. Scope note carried from triage: no reason-token changes (tests and callers match them), no behavior change, and no model-facing prose rewrite - `workflows/plan.md` sits at its 22,638 B budget with zero headroom. The hints land in `bin/`, which carries no weight-budget entry, so they cost no context bytes.

john referenced this issue

2026-08-23 20:46:19 +00:00

User-facing surfaces put a vocabulary to the user without naming it #247

john commented

2026-08-23 20:46:28 +00:00

Author

Owner

Absorbed from #247, which was carrying this as a second cluster over the same lines.

Three refusal sites that name the condition and not the remedy, all inside this issue's counted set:

bin/lib/publish-decision.mjs - measured 6 reason: sites and 0 hints. decidePublish gates no-branch / bad-branch / protected-branch / bad-remote / remote-not-configured, and decideReap beside it. The file's own comment concedes only one gate per function carries a detail. This is on /cad-land's unattended auto_close path, so the reader is a user whose close just stopped with no next step.
planning.mjs:575 - fail('unparseable-cursor', 'STATE.md does not match the 4-line schema'). Names the schema it violated and neither the repair nor the pointer to templates/STATE.md. (#247 cited :537; the line has drifted since that inventory was taken, re-located here.)
cadence-core/bin/config.mjs - 3 reasons, 0 hints. See the milestone note on #249 below.

#247 keeps the risk-surface legend cluster, which is a different defect on model-facing prose files that are weight-budgeted.

Absorbed from #247, which was carrying this as a second cluster over the same lines. Three refusal sites that name the condition and not the remedy, all inside this issue's counted set: - `bin/lib/publish-decision.mjs` - measured 6 `reason:` sites and 0 hints. `decidePublish` gates `no-branch` / `bad-branch` / `protected-branch` / `bad-remote` / `remote-not-configured`, and `decideReap` beside it. The file's own comment concedes only one gate per function carries a detail. This is on /cad-land's unattended `auto_close` path, so the reader is a user whose close just stopped with no next step. - `planning.mjs:575` - `fail('unparseable-cursor', 'STATE.md does not match the 4-line schema')`. Names the schema it violated and neither the repair nor the pointer to `templates/STATE.md`. (#247 cited `:537`; the line has drifted since that inventory was taken, re-located here.) - `cadence-core/bin/config.mjs` - 3 reasons, 0 hints. See the milestone note on #249 below. #247 keeps the risk-surface legend cluster, which is a different defect on model-facing prose files that are weight-budgeted.

john added this to the v3.7.0 milestone

2026-08-23 20:46:36 +00:00

john referenced this issue

2026-08-23 20:46:46 +00:00

config.mjs set accepts a repo-scoped key at the global layer without complaint #249

john referenced this issue

2026-08-24 02:16:27 +00:00

v3.7.0 - the refusal that names the next step #251

john referenced this issue from a commit

2026-08-24 02:16:35 +00:00

docs: open v3.7.0, seed its three ids, add both phases

john closed this issue