@litfamily/litopencode 1.0.31 → 1.0.32

package/skills/lit-hijack/references/clean-room-build.md

@@ -0,0 +1,111 @@
+# Clean-room build
+
+The build separates two roles. The spec writer reads the sources and writes `SPEC.md`. The implementer reads `SPEC.md` and the target, and builds. The spec is the only artifact that crosses from one role to the other. This mirrors the classic two-team method for compatible reimplementation, where one team studied the original and wrote a functional specification and a second team, with zero exposure, built from that specification alone.
+
+## Why the split matters
+
+A writer who has just read a source reproduces its phrasing, its examples and its order without noticing. A writer who has seen none of it is spared that. The split does two things: it keeps expression out of the target, and it forces the spec to be complete, because anything missing from the spec reaches the implementer by no route at all.
+
+Be honest about its limits. The model that implements may have met the source during training, the person running the port has read it, and a skill-shaped source often states its mechanism in one obvious way. The result is therefore described as *independently re-expressed*, with an exposure note in the report, and the claim of being untouched by the source stays off the page.
+
+## Roles in an OpenCode session
+
+| Role | Who | Sees | Writes |
+| --- | --- | --- | --- |
+| Spec writer | the root session that ran capture, distil and gap | sources, ledger, target | `SPEC.md`, the ledger |
+| Planner | `lit-plan` (planning-only agent) | `SPEC.md`, the target | the plan, returned in chat for the root to save |
+| Implementer | a fresh `task` lane on `lit-forge`, in a separate `git worktree` | the brief (spec + target root), the worktree | target files, left uncommitted |
+| Executor discipline | `start-work` | the plan, the ledger of rows | row evidence |
+| Gatekeeper | `hijack.mjs check` | everything | pass or fail |
+
+## Step 1: plan with lit-plan
+
+Load `lit-plan` with the native `skill` tool and give it `SPEC.md` as the brief. The `lit-plan` agent is planning-only: edit and bash are denied for it, in yolo mode as much as elsewhere. It returns the plan as text, and the root session (or the operator) writes the plan file. Granting that agent write access to save a step breaks a product rule, so the plan file always comes from the root.
+
+Plan rows follow lit-plan's grammar. Under a `## TODOs` heading, each task is a column-zero line:
+
+```text
+- [ ] 1. <title> — Action: <action>; Output: <output>; Verification: <verification>
+```
+
+numbered from 1 without gaps. Under `## Final verification`, each closing check is a column-zero `- [ ] F1. <title> — Verification: <verification>` line, numbered from F1. Rows inside a fenced example are ignored by the parser, so a plan that quotes the grammar in a fence needs real rows outside it.
+
+Each task row names the SPEC section it implements (`M1`, `M4`), the target files, the test it adds, and the real-surface check. The build gate requires a plan in this grammar and a citation of every taken mechanism. Plan rows refer to the spec and the target, and the build gate reads the plan file and fails when it names `sources/` or a source URL. Record the path:
+
+```json
+"build": { "plan": "plans/<slug>.md" }
+```
+
+## Step 2: execute with start-work
+
+Run the plan with `/start-work plans/<slug>.md`. For a small port (one or two SPEC sections in one or two files) a short plan in the run folder, in the same row grammar, executed directly by the isolated implementer lane is enough; the report says which path ran. `start-work` keeps its per-row gates: a failing test first, the smallest change that passes, a real-surface check, cleanup. `lit-hijack` adds one constraint: the person or lane that edits target files works from the brief.
+
+## Step 3: brief the implementer
+
+```text
+$H brief <run>
+```
+
+prints a packet that starts with `TASK:` and carries `DELIVERABLE`, `SCOPE` and `VERIFY`, then the full text of `SPEC.md`. It names the target root and the sections to build, and it tells the implementer to stay out of any `.litopencode/hijack/` folder, to leave the original material unsought, and to return a question when a section is ambiguous. It refuses to print while the spec gate fails, so a spec that leaks the sources never reaches an implementer.
+
+### The fence on OpenCode
+
+OpenCode's `task` tool starts a subagent in the session's own working directory, and it offers no host-managed worktree for the lane. The skill therefore builds the fence by hand, and it works as a convention for cooperative agents rather than as a sandbox:
+
+```text
+git -C <target> worktree add <dir outside .litopencode/> -b hijack/<slug> <base_ref>
+```
+
+Give the lane the absolute path of `<dir>` as the one place it edits and runs commands. The worktree holds the target's tracked files at the base revision. Your run folder is untracked and ignored, so the captured sources sit outside the checkout. A subagent that has a shell can still read any absolute path, which is why three further fences stay in force: the brief mentions the sources nowhere, the spec gate screens the spec for source text, and the overlap gate screens every changed file. Say this limit in the report's exposure note.
+
+When the change spans independent areas, give each area its own worktree, its own lane and its own brief section.
+
+### Bringing the change back
+
+The implementer leaves its edits uncommitted. The root then:
+
+1. stages them inside the worktree: `git -C <worktree> add -A` (this changes the index and leaves history alone);
+2. reviews `git -C <worktree> diff --cached --binary`;
+3. applies that patch to the target: `git -C <target> apply` with the patch on stdin or in a file under the scratch area;
+4. removes the lane: `git -C <target> worktree remove --force <dir>` and `git -C <target> branch -D hijack/<slug>`.
+
+A commit in the target waits for the user's approval. List every changed file:
+
+```json
+"build": { "plan": "plans/<slug>.md", "changed": ["skills/<id>/SKILL.md", "skills/<id>/scripts/<tool>.mjs", "test/<id>.test.mjs"] }
+```
+
+## Degraded path
+
+When the `task` tool or `git worktree` is unavailable, the separation cannot be enforced. Say so once, then:
+
+1. Close the sources. Work from `SPEC.md`, the mechanism cards' `what` and `why`, and the target.
+2. Write in the target's order with the target's examples.
+3. Rely on the overlap gate as the remaining fence, and record `build.separation: "single-context"` in the ledger so the report's exposure note is accurate.
+
+## The overlap gate
+
+`hijack.mjs overlap` and the spec and build phases of `check` compare text against every capture of the run, including every text file of a captured repo.
+
+- Text is normalised (Unicode compatibility form, lower case) and split into words of letters and digits, so punctuation, Markdown and line breaks cannot hide a copy. Hangul and other scripts work the same way.
+- Every run of `min_words` consecutive words (12 by default, kept in `ledger.min_words`) that also appears in a capture is reported with the file, the line, the length and the source id.
+- Three or more identical headings between a target file and a source produce a warning: matching structure is copying too, even with new sentences.
+
+How to respond to a hit:
+
+| Hit | Response |
+| --- | --- |
+| A sentence or paragraph from the source | Rewrite from the mechanism card, in the target's order and with the target's example. |
+| A long shared run inside code | Re-implement from the spec; renaming variables over copied logic fixes nothing. |
+| A standard phrase both texts need (a licence name, an API name, a protocol field) | Shorten the run below the threshold, or name it once and refer to it. Record the case in the report. |
+| Headings that match | Restructure around the target's flow. |
+
+Lowering `min_words` makes the gate stricter; raising it to silence a hit defeats it. Keep the default unless the report explains why.
+
+## What the gate misses
+
+A paraphrase that follows the source sentence by sentence with synonyms passes a word-run check. So does copied logic with renamed identifiers. Two habits close most of that gap: write from the mechanism cards with the sources closed, and let the implementer be someone who opened none of them. For a high-stakes port, add a `lit-oracle` lane that reads the source, the spec and the diff side by side and reports structural echoes the script cannot detect.
+
+## Attribution in the build
+
+When any taken mechanism rests on an `ideas-credit` source, the build adds the target's attribution notice. Follow the target's existing pattern first: a target that keeps a provenance record gets a new entry there. Otherwise an `ATTRIBUTION.md` beside `SKILL.md` names, per source: the work, the author, the URL, the licence, what idea was adapted, and a sentence stating the port reused text or code from the source in zero places. Record its path in `ledger.attribution.path`; the report gate checks it names every `ideas-credit` source that fed a taken mechanism. The notice is the one file the overlap gate skips, because it must carry titles and URLs.

package/skills/lit-hijack/references/distil-and-licence.md

@@ -0,0 +1,100 @@
+# Distil and licence
+
+Distilling turns sources into mechanism cards: what a technique does, why it works, and how sure anyone can be. The licence gate then decides, per source, what the port may take. Both steps separate the transferable method from the author's expression of it.
+
+## Mechanism, evidence, opinion
+
+A source usually mixes three things. Keep them apart on every card.
+
+| Part | What it looks like | Where it goes |
+| --- | --- | --- |
+| Mechanism | A step, rule, structure, check or default that produces an effect | `what` and `why` |
+| Evidence | A measurement, a before/after, a reproducible example, a failure story with a cause | `evidence` and `evidence_note` |
+| Opinion | Taste, prediction, preference, a confident claim that lacks support | a card marked `opinion`, or dropped |
+
+Evidence classes:
+
+- `evidenced`: someone measured it, showed comparable outputs, or you reproduced the mechanism from the description.
+- `anecdotal`: a practitioner reports it worked for them, with enough detail to understand why, and with a measurement missing.
+- `opinion`: a stance or a style choice. Still worth porting when it fits the target, and the report says it was taken on taste.
+
+A post that is mostly opinion can still carry one solid mechanism. A post full of numbers can carry nothing you can use. Judge each card on its own.
+
+## Writing a card
+
+```json
+{
+  "id": "M1",
+  "title": "Production brief before any render",
+  "sources": ["S1", "S3"],
+  "locator": "S1 section 1; S3 pages 4-6",
+  "what": "A short production note fixes the takeaway, the allowed references, the real assets and the rejection condition before the first frame is drawn.",
+  "why": "Any decision left open gets filled by the model's default, and those defaults are why unrelated outputs look alike.",
+  "evidence": "anecdotal",
+  "evidence_note": "Two practitioners report it; neither measured it."
+}
+```
+
+Write `what` as behaviour someone could observe in the target after the port, and `why` as the failure the mechanism prevents. If the only phrasing you can find is the author's sentence, you hold the sentence and the mechanism is still ahead of you; reread the source, close it, and explain it as you would to a colleague.
+
+Merge cards that describe one technique from several sources, and name every source on the merged card. Keep a card that only one source has. Split a card that bundles two techniques with different evidence.
+
+## What is worth porting
+
+Four questions decide whether a card earns a place in the target:
+
+1. **Is it new?** Run the target's typical task once unaided and see whether the base model already does this. A mechanism the model follows by itself is a zero gain.
+2. **Is it a mechanism or a mood?** "Make it feel premium" is a mood. "Limit the palette to three tokens declared before the build" is a mechanism.
+3. **Can the target hold it?** Some techniques need surfaces the target lacks (a renderer, a hook event, a runtime). Note the missing surface and skip the imitation.
+4. **Can its effect be seen?** If every output would stay the same after the port, the parity step has nothing to prove. Find the marker before you take it.
+
+## Good theft, as a checklist
+
+The old distinction between good and bad theft maps onto this skill:
+
+| Good | Bad | In a hijack run |
+| --- | --- | --- |
+| Honour the source | Degrade it | Credit in the report; represent the source's claims fairly |
+| Study it | Skim it | Read every captured source in full before writing cards |
+| Steal from many | Steal from one | Merge techniques across sources; compare them |
+| Credit | Plagiarise | Provenance rows, and a shipped credit line where the licence asks |
+| Transform | Imitate | Re-express in the target's idiom, structure and examples |
+| Remix | Rip off | Combine with what the target already does well |
+
+## The licence table
+
+Ideas, procedures, methods and facts sit outside copyright in most legal systems, and the expression of them is protected. That split is why every decision below permits mechanisms and every one of them withholds wording. `hijack.mjs licence` applies this table from the captured licence evidence:
+
+| Licence evidence | Class | Decision | Reason |
+| --- | --- | --- | --- |
+| MIT, ISC, BSD-2/3-Clause, Apache-2.0, Zlib, BSL-1.0 | permissive | `ideas-credit` | Reuse is allowed; the port takes mechanisms only and ships a credit line |
+| 0BSD, Unlicense, CC0-1.0 | permissive | `ideas-credit` | Conditions are absent; credit is a courtesy the target still pays |
+| CC BY | attribution | `ideas-credit` | The licence asks for credit when material is shared; credit the ideas too |
+| GPL, LGPL, AGPL, MPL, EPL, CC BY-SA | copyleft | `ideas-only` | Copying would pull the target under the source's terms; keep the implementer away from the source |
+| CC BY-NC, CC BY-ND | restricted | `ideas-only` | Commercial use or shared adaptations are barred; mechanisms only |
+| Empty result (`NOASSERTION`) | unlicensed | `ideas-only` | Default copyright applies, all rights reserved; posts, blogs, PDFs and most gists land here |
+| Anything else | unrecognised | `ideas-only` | Treated as all rights reserved until a person says otherwise |
+| Text that states reuse terms | restricted-terms | `needs-review` | "do not copy", "no part of this", "source-available", "proprietary", "confidential" |
+
+The reuse-term scan reads rights-related lines (copyright, licence, terms, permission, rights) and skips running prose, so an article that warns readers "DO NOT COPY this config blindly" stays `ideas-only`.
+
+`needs-review` blocks the licence phase until a person decides:
+
+```text
+$H licence <run> --set S4=ideas-only --reason "copyright page restricts reproduction; we take the method only"
+$H licence <run> --set S5=no-go --reason "material was shared privately"
+```
+
+A user decision is kept on later `licence` runs. Record the reason in plain words.
+
+`no-go` applies whatever the licence says when the capture crossed a login or paywall, when the material is leaked, private or confidential, or when terms forbid the use you intend. A mechanism that rests only on no-go sources stays out; one that also has an allowed source may be taken on that source alone, and its card says so.
+
+## Credit lines
+
+For `ideas-credit` sources the target ships a short notice, in the style the target already uses (an `ATTRIBUTION.md` beside a skill is common). Each entry names the work, the author, the URL, the licence, and one sentence on what idea was adapted and that the port reused text or code from the source in zero places. For `ideas-only` sources the report carries the credit, and the target carries it too when the user wants it; ask once.
+
+Credit is ethics and courtesy. The legal position of a copy stays as it was, which is why the build avoids copying in the first place.
+
+## Jurisdiction and limits
+
+Quotation rules, moral rights and the line between idea and expression differ between countries, and close paraphrase or copied structure can still infringe where the words differ. This procedure lowers risk and certifies nothing. When a source matters commercially and its terms are murky, tell the user once and let them decide. Patents and trademarks sit outside this gate: re-expressing a method leaves a patent on it standing, and a source's product names stay the source's.

package/skills/lit-hijack/references/gap-and-port-design.md

@@ -0,0 +1,126 @@
+# Gap analysis and port design
+
+The gap analysis decides which mechanisms the target needs; the port design decides what each one becomes inside the target. Both are written against the target as it was at the base revision.
+
+## Read the target first
+
+Before judging any gap, read:
+
+- the target's `AGENTS.md` and README, for its rules and its voice;
+- every file of the skill or module being changed: the entrypoint, every reference, every script, every asset that carries behaviour;
+- every test that names the target, and the guards that pin its files (payload pins, corpus floors, route tests);
+- for an OpenCode plugin, how a neighbouring skill of similar weight is enrolled, so you know which surfaces a complete port touches.
+
+For a new target (`init --new`), read the neighbouring skills of the product it will join, and treat every mechanism as `lacks` with `gap.searched` naming what you compared against.
+
+## Gap fields
+
+```json
+"gap": {
+  "status": "weak",
+  "refs": ["skills/motion/SKILL.md:120-134", "skills/motion/scripts/render.mjs:88"],
+  "note": "The skill asks for a treatment in prose; the render script starts while the treatment is still missing."
+}
+```
+
+- `status` is `has`, `weak` or `lacks`.
+- `refs` are `path:line` or `path:start-end`, relative to the target root. The gate resolves each one at the base revision (`git show <base>:<path>`) and fails when the file or the line is missing, so a gap claim always points at text that existed when you judged it.
+- A `lacks` claim with empty refs needs `searched`: the terms and places you searched ("grep for brief|treatment in skills/motion/ and its tests; the render step has no gate").
+- `note` is one sentence a reviewer can check against the refs.
+
+How to judge the status:
+
+| Status | The target… |
+| --- | --- |
+| `has` | does it, and something enforces it: a script, a hook, a test, a gate |
+| `weak` | does part of it, does it only sometimes, or states it in prose while nothing enforces it |
+| `lacks` | omits it entirely, in behaviour and in prose |
+
+Prose that tells the model to do something, with a mechanism missing behind it, is usually `weak`. In this product family, measured A/B runs found contract prose alone left behaviour unchanged, while mechanical checks moved it. A gap that a gate would close is often the most valuable port.
+
+## Port decisions
+
+```json
+"port": { "decision": "adapt", "reason": "Strengthen the existing treatment step with a render gate." }
+```
+
+- `take`: the target lacks it and should gain it.
+- `adapt`: the target has part of it; strengthen or complete it.
+- `leave`: keep it out, with the reason. Good reasons: the target already has it; the base model already does it unaided; the licence gate forbids it; it conflicts with the target's design; its evidence is too thin for its cost; the target lacks a surface it needs.
+
+The gate rejects `take` on a `has` gap (use `adapt` or `leave`) and any taken mechanism whose sources are all `no-go`.
+
+## Re-expressing in the target's idiom
+
+A port lands well when a reader of the target cannot tell which parts came from elsewhere, because everything is in the target's own terms. For each taken mechanism decide:
+
+| Question | Answer from the target, drawing on the target alone |
+| --- | --- |
+| What is it called? | The target's naming pattern and vocabulary |
+| Where does it live? | The file the target would naturally put it in |
+| What enforces it? | The target's own script, hook, gate or test style |
+| How is it invoked? | The target's routes, commands, flags or events |
+| How is it tested? | The target's test framework and fixtures |
+| How does it ship? | The target's manifest, payload pins and package rules |
+| How do users learn of it? | The target's help, listing, README and docs |
+
+Map the source's idea onto the target's surfaces and leave the source's surfaces behind. When a source describes a folder layout or a file format, design the target's own, shaped by the target's existing conventions.
+
+## Enrollment surfaces for an OpenCode plugin target
+
+A capability in an OpenCode plugin is reachable through the surfaces the host and the plugin read. When the target is a plugin skill, list every surface the port touches:
+
+- the skill entrypoint (`skills/<id>/SKILL.md`) and its references, scripts and assets;
+- the plugin's skill and feature catalogs, the managed-skill asset list and manifest, and any payload pins the plugin keeps;
+- the command registry entry, when the capability has a slash command;
+- the `chat.message` route and its mode contract, when it has a natural-language route;
+- agents, settings defaults and tool registrations, when the capability uses them;
+- user-facing listings: README skill tables, guides, help and doctor output;
+- the package's file list and pack guard, so the installed copy carries the new files;
+- tests that fail when any of the above loses the capability (an orphan test).
+
+For other systems, find the equivalent list first: the registry, the router, the config, the installer, the docs and the tests. A port that skips one of them is a ghost: the file exists and the surface cannot reach it.
+
+Each product in a family is its own target. A port into one product copies zero files into a sibling and adds zero dependencies between them; when the user wants the same capability elsewhere, each sibling gets its own run and its own re-expression.
+
+## SPEC.md template
+
+```markdown
+# <target>: <one-line purpose of this port>
+
+Target root: <path> · base revision: <rev>
+Taken: M1, M4 · left: M2, M3, M5 (see the run report)
+
+## M1 <title in the target's words>
+
+Behaviour: <what the target will do afterwards, observable>
+Lives in: <files and surfaces in the target>
+Enforced by: <script, hook, gate or test>
+Acceptance:
+- <check 1, runnable>
+- <check 2, runnable>
+Parity: <criterion> · marker: <text the new behaviour leaves in its output>
+Enrollment: <catalog, route, docs, pins, tests this section touches>
+Out of scope: <what this section leaves alone>
+
+## M4 <title>
+…
+```
+
+Write the spec from the mechanism cards and the target, with the sources closed. Use the target's examples and the target's order. The spec gate rejects a section-less mechanism, a path into `sources/`, a source URL, and any run of 12 or more words shared with a capture; it warns when three or more headings match a source's headings, because copied structure is still copying.
+
+## Fields the parity step needs from the spec
+
+Fill these while writing the spec, so the proof is designed before the build:
+
+```json
+"parity": {
+  "criterion": "A brief from the skill names the takeaway and the rejection condition.",
+  "red": "Old skill: brief has neither field.",
+  "green": "New skill: brief has both fields in every run.",
+  "surface": "opencode run in a throwaway workspace, old and new skill loaded the same way",
+  "artifact": "parity/contact-sheet.png"
+}
+```
+
+and on the ledger, `parity.markers`: short strings the new behaviour leaves in its output and the old behaviour leaves out. Pick markers that only the mechanism produces (a field name, a gate's refusal line, a file the new step writes), so a marker in a baseline output means contamination.

package/skills/lit-hijack/references/parity-and-report.md

@@ -0,0 +1,110 @@
+# Parity proof and report
+
+A port is proven by two observations: the capability fires on the surface a user touches, and the new target behaves differently from the old one on the same prompt. Green tests and new files are necessary and fall short of proof. Ports in this product family have passed every gate while sitting unreachable, and A/B runs have measured an empty difference because the baseline could read the treatment; this step exists to catch both.
+
+## 1. Reachability
+
+Drive the real entry point, read what comes back, then break the wiring and watch the probe fail.
+
+| Target surface | Probe | Break it by |
+| --- | --- | --- |
+| Chat route | Run the `chat.message` hook (or an isolated `opencode run` with a fake provider) on a prompt that should route, and assert the skill pointer appears in the captured request | Removing the route entry |
+| Slash command | Run the command hook and read the injected prompt, or run the host and read the transcript | Deleting the command row |
+| Skill discovery | An `opencode run` prompt that should load the skill, with the transcript showing the `skill` tool call | Changing the description |
+| Script or gate | Run the installed copy's script on a fixture that should fail and one that should pass | Reverting the gate |
+| Package payload | Pack the package and list the files (read the JSON listing, since the human listing wraps long paths) | Removing the file from the allowlist |
+
+A probe that cannot fail proves little; record the broken run beside the passing one.
+
+## 2. An isolated baseline
+
+The baseline is the target at the base revision, in a place where the new work cannot be read:
+
+```text
+git -C <target root> worktree add <lane folder>/parity-base <base_ref>
+```
+
+or the snapshot copied in Phase 0. Check the isolation before running anything: the baseline folder holds none of the new files, `git log` inside it stops at the base revision, and the run folder, the spec and the diff sit outside any path the baseline session can reach. When the target lives in a repo the baseline session could explore, run the baseline from a copy outside that repo.
+
+## 3. Running both arms
+
+Choose prompts the spec never used as examples: a held-out prompt shows the behaviour generalises, while a prompt copied from the spec shows that the spec was followed.
+
+For an OpenCode skill target, run each arm as a real session in its own throwaway workspace. The installed LitOpenCode is switched off for both arms by pointing the profile at a scratch directory, so it cannot add routes, agents or hooks to either side:
+
+```text
+mkdir -p <scratch>/{home,xdg/config,xdg/data,tmp}
+cd <arm workspace>   # holds .opencode/skills/<id>/ with this arm's copy of the target
+env -i PATH="$PATH" HOME=<scratch>/home XDG_CONFIG_HOME=<scratch>/xdg/config XDG_DATA_HOME=<scratch>/xdg/data TMPDIR=<scratch>/tmp OPENCODE_DISABLE_AUTOUPDATE=1 \
+  opencode run --pure --model <provider/model> "<held-out prompt>"
+```
+
+- Load both arms the same way (a project skill folder in each workspace), so the only difference is the port.
+- Use a fresh scratch profile per run. Provider credentials then have to be supplied on purpose, which is why the run waits for the user's approval: it spends the user's model quota.
+- Point the workspace at a copy you control, and leave the installed plugin root of the host alone.
+- Keep the runs cheap: a small prompt, one model, a few turns.
+- Run each arm at least twice when its output varies. One sample can mislead.
+
+For a code target, run the target's tests and its real command on both revisions, and save the outputs.
+
+Save every output under `parity/` (`baseline-1.md`, `treatment-1.md`, …) and list them:
+
+```json
+"parity": {
+  "baseline_outputs": ["parity/baseline-1.md", "parity/baseline-2.md"],
+  "treatment_outputs": ["parity/treatment-1.md", "parity/treatment-2.md"],
+  "markers": ["Rejection condition"]
+}
+```
+
+The parity gate then requires every marker in every treatment output and in every baseline output absent. A marker missing from a treatment output means the port changed behaviour unreliably. A marker in a baseline output means the baseline saw the new work, or the target already had the behaviour and the gap was imaginary. Either way the proof is void until fixed. Before trusting a tie or a surprising win, grep the baseline transcript for the treatment's distinctive identifiers (file names, section names, the skill's own terms); any hit voids the comparison.
+
+## 4. Visual outputs
+
+When the target makes images, films, slides, documents or pages, the user judges them by eye. Render the baseline and treatment outputs side by side on one contact sheet (rows for arms, columns for runs), save it under `parity/`, and show it. Machine checks such as overlap or layout scores are geometry checks; call them that. Headless browsers used for renders take `--use-mock-keychain --password-store=basic` so a keychain dialog never interrupts the user.
+
+The sample output is evidence that the port works. Polishing that one sample is a different task; offer it when the user asks.
+
+## 5. The report
+
+`REPORT.md` lives in the run folder. The gate requires the three headings, every mechanism id, every source's URL or path, and a credit notice for every `ideas-credit` source that fed a taken mechanism.
+
+```markdown
+# Port report: <title>
+
+Target: <root> at <base revision> → <new revision or working tree>
+Run: .litopencode/hijack/<slug>/ · gate: check --phase report PASS
+
+## Taken
+- M1 <title>: <where it lives now> · parity: marker in 2/2 treatment runs, 0/2 baseline runs
+- M4 <title>: …
+
+## Left
+- M2 <title>: the target already enforces it (<path:line>)
+- M3 <title>: opinion with zero gain over the base model in a probe run
+- M5 <title>: rests only on S5, which is no-go
+
+## Provenance
+| Id | Source | Author | Published | Retrieved | Licence | Decision |
+| --- | --- | --- | --- | --- | --- | --- |
+| S1 | https://… | … | … | … | NOASSERTION | ideas-only |
+
+## Exposure
+The spec writer read every source. The implementer worked from SPEC.md in a separate git worktree
+(a convention for cooperative agents, since the task tool offers no host isolation), or in the
+same context on the degraded path. The model may have met these sources before. The overlap gate
+found no run of 12 or more words shared with any capture; headings were checked for structural echoes.
+
+## Credit
+<attribution notice path, or "credit lives in this report">
+
+## Review by
+<date, and what would make this port stale: a model change, a target redesign, a new source>
+```
+
+## 6. Closing the run
+
+1. `hijack.mjs check <run> --phase report` passes.
+2. The reply to the user says what was taken and left, the parity result in a sentence, the contact sheet when there is one, and the report path.
+3. Offer `review-work` for a work review of the diff; its provenance lane reads the run folder.
+4. The run folder stays local and out of commits. Commits, pushes and releases wait for the user.