# Redesign mode - the contract Loaded only when `state.analysisSpec.options.redesign` is true, the same way `analysis/review.md` is loaded only by a reviewer subagent. A run that is not a redesign never pays for this file. ## What the mode is for A redesign is not a feature. The thing already exists, somebody is going to replace it, and the question a reader has is not "what should v2 do" but "what does v1 do that v2 must not lose". A normal analysis answers the first question and is silent on the second, so the losses surface in production: a validation rule nobody wrote down, an error state only the old screen had, a query parameter one caller still sends. So the mode adds exactly three artefacts, and every one of them is a claim about v1 rather than a plan for v2. ## Why it is an option and not a mode `mode` says how many sections the document carries. `redesign` says which content is required. They are different axes, and collapsing them costs real checks: `mode === "full"` branches in four places inside `validate-analysis-doc.mjs`, so a `mode: redesign` value would silently switch off the traceability matrix, the Test Plan requirement and the business-rule to test-scenario cross-check - in the documents that need them most. A small screen can also have a lite redesign, and that is a real thing to want. The shape therefore matches `options.uiTests` and `options.a11yDepth` exactly: an intake opt-in, written into the front-matter, enforced by the validator's "front-matter says so, the section must exist" rule. ## The three artefacts Section numbers are per profile. The global profile uses sub-sections of existing sections (4.5, 4.6, 9.5) and the corporate profile uses 2.1, 2.3 and 5.N+4; no new top-level section is introduced in either, because section numbers are quoted in 172 places and renumbering them to add a mode is a worse trade than nesting. ### 1. Current behaviour Every behaviour v1 has that a reader could otherwise only find by reading v1. One row per behaviour, with a stable `CB--NN` id and a `repo/file:line` citation. | Column | Contract | |---|---| | Id | `CB--NN`, `` the same feature slug the `BR-` ids use | | Behaviour | one sentence, present tense, no v2 language | | Evidence | `/:`, or the evidence label when no line can be named | | Certainty | `confirmed` or `uncertain` | `Evidence` and `Certainty` are **derived by the renderer** from `state.analysisSpec.evidence.repoEvidence`, never asked of the author and never written by the model from its own impression. A `direct-match` or `same-domain` hit yields `confirmed` with its path and line; a `cross-cutting` hit yields `uncertain` with the module name. Letting the writer grade its own evidence is the failure Locked 24 already refuses for the concept table, and it is the same failure here. ### 2. Endpoint mapping The v1 call and the v2 call side by side, one row per endpoint, plus what changed in the shape. A redesign that keeps the same paths still gets the table, with the rows saying so: "unchanged" is an answer, and its absence is not. ### 3. Difference list Where each v1 behaviour went. One row per `CB-` id, and the status comes from a closed five-value vocabulary: | Status | Meaning | |---|---| | `Moved` | v2 keeps the behaviour, in a different place; the row names where | | `Partial` | v2 keeps part of it; the row names what is dropped | | `Missing` | v2 does not have it, and nobody has decided that yet | | `New` | v2 behaviour with no v1 counterpart | | `Out of scope` | deliberately dropped, with the decision recorded | The cell is bilingual in the same shape Section 20 uses for `Açık / Open`, so a Turkish document reads as Turkish while the machine-checked half stays a fixed English token. `Missing` and `Partial` are the two that mean work is unfinished, so each owes a Section 20 row by `AS-NN`. That is the reason the mode exists: a behaviour that v2 drops without a decision is exactly the thing that gets found in production. ## The eight checks All in `validate-analysis-doc.mjs`, all live only when the front-matter says `redesign: true`. | Check | Severity | What it catches | |---|---|---| | the three sections exist | ERROR | Without the sections the row checks below pass over nothing, which is the defect that shows a gate green | | a row has no `file:line` and is not marked `uncertain` | ERROR | An unmarked guess. Prose can only ask an author to mark it; this finds the row that was not marked | | evidence is `cross-cutting` only, yet `confirmed` | WARN | A legitimate rule in a shared module reads this way, so it must not block - but Phase 4 runs `--strict`, so it blocks in review | | a status value outside the vocabulary | ERROR | A controlled vocabulary decaying into free text | | a `Missing` or `Partial` row with no Section 20 counterpart | ERROR | The reason the mode exists | | a `CB-` id in one table and not the other, both directions | ERROR | A behaviour that is in the code and on nobody's difference list: the thing that disappears in a redesign and is found in production | | the endpoint table's column count, then a half-written row | ERROR | A renderer that adds a column silently disabling the row checks | | the sections are present but the front-matter does not say `redesign` | WARN | Drift | ## The cache, and the silent failure to avoid `evidence_digest` (Locked 27) summarises `featureName || platforms || repoEvidence || conventions`, with a 24-hour TTL. `options.redesign` **is a digest input**. Without it, a redesign started within a day of a normal run on the same feature hits that run's cache, skips Phase 1b entirely, and renders a redesign document whose current-behaviour table is empty - at which point all eight checks above pass over nothing. This is the most likely quiet failure in the whole mode, and one digest input is the whole fix.