add-setup-contract

name	add-setup-contract
description	Use when a state-materializing command starts or is asked to upgrade — reads the setup receipt, compares the recorded contract against the shipped one, executes the declared upgrade deltas sequentially, and rewrites the receipt even on a verified-current no-op. Consumed by /add.qa-setup STEP 1.5 and STEP 11.

Setup Contract Reconciliation

Overview

Procedure for reconciling a project's materialized state with the contract the framework currently ships. It compares two integers, executes a declared delta list, and refuses when the declaration is incomplete. It never reads a changelog and never decides what to improve — an agent interpreting prose produces a different upgrade on every run, which is the failure this procedure exists to prevent.

When to Use

• A state-materializing command starts and must establish whether the project is first-run, current, behind, or unreceipted.
• The user passes --upgrade to such a command.
• A command finishes materializing and must write or advance its receipt.

When NOT to Use

• Corpus-derived staleness (the project wiki) — that is git-based and owned by {{skill:add-wiki-maintenance/SKILL.md}}. Two staleness mechanisms coexist deliberately: contract-based for materialized state, git-based for derived docs.
• Deciding whether a feature is worth adopting. This procedure executes declared deltas; it takes no product decisions.

Inputs

Input	Source
RECEIPT_PATH	<command's doc root>/<command name without `add.`>.md — add.qa-setup → docs/qa/qa-setup.md
RECORDED	setup-contract in the receipt frontmatter
CURRENT	contracts.<command>.version in {{addpath:contracts.json}}
RECIPES	contracts.<command>.recipes — a path relative to the active provider's resource root, e.g. .claude/skills/add-qa/references/setup-contract.md on Claude Code. ⛔ NOT under .codeadd/: skills install into per-provider directories, and .codeadd/ carries only scripts, fragments, templates, plugins and the sidecars
SIGNAL	SETUP_QA: / SETUP_QA_CONTRACT: / SETUP_QA_BEHIND: from status.sh

Procedure

1. Classify the project state

Receipt	Materialized state	Classification	Action
absent	absent	FIRST-RUN	Materialize normally, then write the receipt at CURRENT
absent	present	UNRECEIPTED	Backfill: reconstruct the receipt from observed state at setup-contract: 1, change no other file, log the backfill. Then continue at step 2
present	any	RECEIPTED	Continue at step 2

Materialized state is "present" when any owner: setup path declared in the command's contract exists.

⛔ Never treat an UNRECEIPTED project as FIRST-RUN. Re-materializing over an existing installation destroys the user's configuration.

2. Compare

Condition	Action
CURRENT unreadable (no sidecar)	Pre-contracts install. Skip reconciliation entirely, report it, continue. Never guess a version
RECORDED > CURRENT	REFUSE. The framework was downgraded, or the receipt is corrupt. Report both values and stop — do not downgrade materialized state
RECORDED == CURRENT	Verified-current. Go to step 4 (drift check), then step 5
RECORDED < CURRENT	Behind by CURRENT - RECORDED. Go to step 3

3. Execute the deltas (behind only)

1. Read RECIPES. Collect sections ## v(RECORDED+1) through ## v(CURRENT), in order.
2. If any section in that range is missing → REFUSE. Report which version is absent and stop. Never skip a version, never jump straight to CURRENT, never infer a delta from the difference between two ### Materializes tables.
3. Present the collected deltas to the user as one list, grouped by version, and WAIT for explicit confirmation — reconciliation is confirm-then-execute, like every other mutation these commands perform.
4. On confirmation, execute sequentially, one version at a time: apply every item of v(N-1) → vN before reading vN → v(N+1). After each version, set setup-contract: N in the receipt. A run interrupted mid-chain leaves a truthful receipt at the last fully applied version.
5. On decline, stop. Record the decline as a Decision Log row and leave setup-contract unchanged.

4. Drift check

For every materialized entry with owner: setup, recompute the file hash and compare with the recorded one:

Result	Action
Match	Nothing to report
Mismatch	Report the drift; do not silently overwrite. Offer to regenerate the file from the current contract, and only rewrite the recorded hash after the user confirms which side wins
File missing	Report it as a gap; offer to re-materialize

⛔ Entries with owner: shared carry hash: null and are checked for existence only. They are co-owned by another command and a content difference is expected, not drift.

5. Rewrite the receipt — always

Rewrite the receipt on every run, including a verified-current no-op with no drift. A verified-current run is information, not nothing.

• Advance last-run and updated to today.
• Preserve first-run and created byte-identically.
• Refresh framework-version from the manifest (informational only).
• Refresh owner: setup hashes for any file this run rewrote.
• Append one Decision Log row per behaviour-changing decision taken this run — never for the no-op itself.

Schema and field vocabulary: {{skill:add-doc-schemas/SKILL.md}} → references/receipt.md.

Refusal Rules (hard)

Situation	Response
Recipe chain has a hole in RECORDED+1 .. CURRENT	Refuse, name the missing version, stop
RECORDED > CURRENT	Refuse, report both values, stop
Receipt frontmatter is unparseable	Refuse to guess. Offer to rebuild it as a backfill at contract 1, with user confirmation
A delta item is ambiguous	Refuse to improvise. Surface the item verbatim and ask

An improvised upgrade is worse than no upgrade: it produces state no recipe describes, which no later version can reconcile.

Rules

ALWAYS:

• Apply deltas sequentially, one contract version at a time
• Rewrite the receipt on every run, including no-ops
• Treat owner: shared paths as existence-checked only
• Confirm before executing any delta

NEVER:

• Read a changelog, release notes, or command diff to decide what to upgrade
• Skip a version or infer a delta not declared in the recipe file
• Overwrite a drifted owner: setup file without the user choosing which side wins
• Re-materialize over an UNRECEIPTED project as if it were first-run
• Edit or remove an existing Decision Log row