Sd Port Fidelity

# sd-port-fidelity

Cross-project port fidelity policy for specwright. A port reproduces a donor implementation inside
a host repo; the donor's form is the specification, and every departure from it is a citable
decision rather than a preference. Authored into port specs by `sd-spec-architect` and enforced
against the changeset by `sd-reviewer`.

Read the section matching your role. The core rule and the deviation allowlist apply to everyone.

---

## The core rule

**Mirror the donor structurally. Every departure is a row in the deviation table, or it is a
defect.**

Structural mirror means the host reproduces, as far as the target permits: the donor's file
layout, member set, member order, symbol names, local variable names, step order within each
member, attribute order, and log message text. Judgement is not the mechanism here. A departure
carrying a deviation row is legal; a departure carrying none is a defect; and nobody is asked to
decide which of the two a given hunk is.

---

## Deviation allowlist

Exactly four groups force a departure. Each requires its own citation - a row citing nothing is
invalid, and the hunk it claims to cover is unjustified.

| Group | Forced by | Citation required |
|---|---|---|
| 1 | Compiler, namespace, or assembly conflict | the conflicting identifier |
| 2 | Host constitution | the constitution section, `§N.M` |
| 3 | Host precedent | `file:line` in the host |
| 4 | Behavior parity fix on an agreed donor defect | the parity criterion it satisfies |

Anything outside these four reverts to the donor form. "Cleaner", "more idiomatic to me", and "the
host does it differently somewhere" are not groups.

---

## Anti-simplification rules

These bind the implementer through the task blocks the architect writes, not by the implementer
loading this file: `sd-spec-architect` puts each applicable rule into the port task's `Acceptance`
and cites the donor `file:line` in `Pattern refs` (see **sd-atomic-task-format**).

- **No unrequested simplification.** Shorter is not better. Collapsing branches, merging members,
  or replacing a loop with a library call is a departure and needs a row.
- **No gratuitous rename.** Donor identifier names carry over even where host style would differ.
  Group 1, group 3, or nothing.
- **No reordering.** Statement order, parameter order, and member order follow the donor, even
  where another order reads better.
- **No opportunistic fix.** A donor defect is reproduced as-is and recorded for a follow-up spec.
  Fixing it inline is group 4 only when the fix was agreed at the gate before implementation began.
- **Host constitution beats donor precedent.** "It is only a copy" exempts nothing. A donor form
  that violates the host constitution is a cited group 2 deviation, never a verbatim import.

---

## Gate tables (sd-spec-architect)

A port spec carries three tables. Each has a completeness condition the gate evaluates
mechanically - it counts and matches, it never assesses whether a reason is good. A table failing
its condition is incomplete and the gate refuses it.

The spec must also carry a **fidelity acceptance criterion**: the criterion these tables are
evidence for. It is what review findings anchor to, and without it a fidelity finding has no legal
anchor (see **sd-severity-taxonomy**). A port spec missing it fails the gate.

### Path mapping table

| Column | Contents |
|---|---|
| `Donor path` | repo-relative path in the donor |
| `Host path` | repo-relative destination in the host |
| `Kind` | `mirror` / `merge` / `omit` |
| `Reason` | required when `Kind` is not `mirror`; `-` when it is |

**Complete when**: one row per file in the declared donor scope and no others; every `Host path`
unique; no empty cell; every non-`mirror` row carries a non-empty `Reason`.

### Member manifest

| Column | Contents |
|---|---|
| `Donor path` | the donor file the member comes from |
| `Member` | donor symbol name, verbatim |
| `Ordinal` | 1-based position of the member within that donor file |
| `Host path` | destination, copied from the path mapping table |
| `Status` | `ported` / `deviated` / `omitted` |
| `Deviation ID` | `D<NN>` when `Status` is not `ported`; `-` when it is |

**Complete when**: one row per member of every non-`omit` donor file; the `Ordinal` values within
each `Donor path` form `1..N` with no gap and no duplicate; each `Host path` equals the mapping row
for its `Donor path`; every non-`ported` row names a `Deviation ID` present in the deviation table.

### Deviation table

| Column | Contents |
|---|---|
| `ID` | `D<NN>`, unique, ascending |
| `Donor form` | the donor name, order, or text departed from |
| `Host form` | what the host uses instead |
| `Group` | `1`, `2`, `3`, or `4` from the allowlist |
| `Citation` | the citation that group requires, verbatim |

**Complete when**: every `ID` unique; every `Group` is one of `1` to `4`; every `Citation` is
non-empty and in the shape its group requires; every `Deviation ID` named in the member manifest
appears here exactly once; no row here is unreferenced by the manifest.

---

## Snapshot artifacts (sd-spec-architect)

Under a port spec's `04-artifacts/source/`: the bridged contract always, and under
`snapshot: contract+source`, the donor files too. `MANIFEST.md` sits at that directory's root.

### Snapshot manifest format

- **Donor**: <repo url or path>
- **Commit**: <full sha>
- **Captured**: <YYYY-MM-DD>
- **Mode**: contract | contract+source
- **Hash algorithm**: sha256, lowercase hex, over the bytes as captured

| Snapshot path | Donor path | Commit | Bytes | SHA-256 | Member ranges |
|---|---|---|---|---|---|
| `orders/order-intake` | `src/orders/order-intake` | `<sha>` | 4821 | `3f9a...` | `1: CreateOrder 12-58; 2: ValidateTotals 60-93` |

One row per captured file. `Member ranges` is `<ordinal>: <member> <firstLine>-<lastLine>`,
semicolon-separated, ordinals contiguous from 1 - the same ordinals the Member manifest table uses.

### Two snapshot rules

1. **Cite the snapshot, not the donor.** Path mapping and Member manifest rows cite `Snapshot
   path`, never a donor-repo path - donor line numbers rot the moment the donor changes; the
   snapshot is frozen. Donor paths, the commit, and line ranges live only in `MANIFEST.md`,
   addressed by `(Snapshot path, Ordinal)` - the Member manifest table carries no line-range
   column of its own.
2. **Quarantine.** The snapshot directory is evidence, never a copy source handed to an
   implementer without a Member manifest row and an allowed-deviation list scoping it.

### Immutability

At freeze, every file under `04-artifacts/source/` plus `MANIFEST.md` is appended as an
**individual literal string** to `paths.protected` in `.claude/project-config.json`. Both
`spec-gate` hooks match `paths.protected` by exact string equality, not glob - the enumeration
*is* the mechanism, not a workaround for one. The append must be idempotent. `/sd:spec` cannot
perform this step itself (it never touches `.claude/`); `/sd:port` Phase 2 performs the freeze.
Outside that pipeline it stays a documented manual step. `spec-gate` guards `Edit`/`Write` only -
it does not stop a shell delete.

Per-file hashes are recorded now so a later drift check (re-hashing the donor at a newer commit)
remains possible; consuming them is out of scope for this story.

---

## Parity artifacts (main thread)

The diff `sd-reviewer` adjudicates is produced by the main thread, never by an agent. The reviewer
has no `Bash` and no write tool - that allowlist is what structurally stops the adjudicator from
fixing what it judges - so the diff must already be a file on disk when the reviewer is invoked.

Output root is `04-artifacts/parity/`, a sibling of the frozen `04-artifacts/source/`: same spec,
same artifacts folder, evidence produced at a later phase by a different actor. Nothing under
`parity/` is frozen or appended to `paths.protected` - it is regenerated on every parity run and
overwrites the previous one.

- One diff per non-`omit` path mapping row, snapshot side first, host side second, unified format,
  at least 3 lines of context. File name is the `Host path` with `/` replaced by `__`, suffix
  `.diff`.
- A mapping row whose `Host path` does not exist still gets its diff - an all-deletion one. That is
  what makes a `missing` member visible without the reviewer listing the host tree itself.
- Every changeset file with no mapping row gets an all-addition diff, named the same way. Path
  conformance is then a property of the diff set rather than a second traversal.
- `INDEX.md` at the parity root, one row per diff file: `Diff file`, `Snapshot path`, `Host path`,
  `Mapping row` (the path mapping row number, or `-` when there is none).

`INDEX.md` is the reviewer's `DIFF_REF`. A run that cannot produce a diff for a row says so in that
row's `Mapping row` cell instead of dropping the row - a silently absent row reads as a clean file.

---

## Hunk classification (sd-reviewer)

Classify every hunk of the port changeset into exactly one class. The vocabulary is closed - there
is no sixth class and no "probably fine".

| Class | Condition | Verdict |
|---|---|---|
| `justified` | maps to a deviation row whose citation satisfies its group | accept |
| `unjustified` | departs from the donor form with no deviation row covering it | BLOCK |
| `missing` | a manifest member has no host counterpart and no `omitted` status | BLOCK |
| `extra` | host content with no donor counterpart and no deviation row | BLOCK |
| `overreached` | a deviation row covers the hunk, but the hunk changes more than that row's `Host form` states | BLOCK |

`overreached` is where a rubber stamp hides: one legitimately cited rename carrying an unrelated
reordering in the same hunk. Judge the hunk against the row's `Host form` text, never against the
mere existence of a row.

A `justified` hunk is a PASS and is not written up as a finding - report the count in the summary
line. Listing them individually buries the BLOCKs they outnumber.

Anchor every fidelity BLOCK to the port spec's fidelity acceptance criterion - a spec acceptance
criterion is a legal anchor for a code target under **sd-severity-taxonomy**. Cite the deviation
row, or its absence, as the supporting `file:line` per **sd-evidence-citation**. A deviation row is
evidence; it is never the anchor by itself.

### Whole-artifact checks

Two checks no hunk class can express, because each is a property of the changeset as a whole. Both
run once per parity review, both are BLOCK, and both are reported even when they pass - the count
is the evidence the check ran.

| Check | Question | Reported as |
|---|---|---|
| Member completeness | does every manifest row with `Status` `ported` or `deviated` have a host counterpart? | `<n>/<total> members present`, plus one BLOCK naming the `Donor path`, `Member` and `Ordinal` of each absent row |
| Path conformance | does every changeset file appear as a `Host path` in the path mapping table? | one BLOCK per unmapped file, citing the file and the table it is missing from |

Both belong to the reviewer rather than to `/sd:verify`, which decides everything from the spec's
own artifacts and reads no host source - the reasoning is recorded in `docs/architecture.md`.

### The parity gate

A HARD gate. Any BLOCK from the classification or from either whole-artifact check refuses
close-out. Two resolutions exist: revert the host toward the snapshot, or add a deviation row whose
group and citation hold up, then regenerate the parity artifacts and re-run. There is no third, and
no override - a gate that can be waived measures nothing. Deriving the missing rows from the
unexplained hunks is not a resolution either; it makes the diff justify itself.

---

## Anti-patterns

- **Improving the donor while porting.** The port is not the moment. Reproduce it, record it, and
  raise the follow-up.
- **A deviation row citing nothing.** "Host style" is not a citation; group 3 needs `file:line`.
- **Renaming to local taste.** Taste is not one of the four groups.
- **Reordering for readability.** Donor order is the order, attribute order included.
- **Waving a table through because it looks right.** The completeness conditions are counted, not
  judged. An incomplete table is refused without a discussion of intent.
- **Treating a donor defect as an invitation.** Record it; fix it in its own spec.