@litfamily/lithermes 1.0.28 → 1.0.30

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

@@ -0,0 +1,128 @@
+# 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 are
+about separating 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 without support | a card marked `opinion`, or nowhere |
+
+Evidence classes:
+
+- `evidenced`: someone measured it, showed comparable outputs, or the mechanism can be reproduced
+  from the description and you reproduced it.
+- `anecdotal`: a practitioner reports it worked for them, with enough detail to understand why, and
+  without a measurement.
+- `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
+none 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 way you can phrase a card is the author's sentence, you
+have the sentence and not yet the mechanism; 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 can earn a place in the target:
+
+1. **Is it new?** Run the target's typical task once without help and see whether the base model
+   already does this. A mechanism the model follows unaided is no 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 rather than faking it.
+4. **Can its effect be seen?** If no output would differ after the port, the parity step cannot prove
+   it. Find the marker before you take it.
+
+## Good theft, as a checklist
+
+The old artist's distinction between good and bad theft maps cleanly 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 are outside copyright in most legal systems; the expression of
+them is protected. That split is why every decision below permits mechanisms and none permits
+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` | No conditions; 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 |
+| None found (`NOASSERTION`) | unlicensed | `ideas-only` | Default copyright: 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" |
+
+`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 no text or code was reused. 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. It leaves the legal position of a copy unchanged, which is why the
+build never copies 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 words differ. This procedure
+lowers risk; it does not certify anything. When a source matters commercially and its terms are
+unclear, tell the user once and let them decide. Patents and trademarks sit outside this gate:
+re-expressing a method leaves a patent on it untouched, and a source's product names are not yours
+to reuse.

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

@@ -0,0 +1,152 @@
+# 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`, `CLAUDE.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 a plugin, how a neighbouring skill of similar weight is enrolled, so you know which surfaces a
+  complete port must touch.
+
+For a new target (`init --new`), read the neighbouring skills of the product it will join instead,
+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 without one."
+}
+```
+
+- `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; no gate before render").
+- `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 with nothing enforcing it |
+| `lacks` | neither does nor states it |
+
+Prose that tells the model to do something, with no mechanism behind it, is usually `weak`. In this
+product, 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 only
+sources are `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, not the source |
+| --- | --- |
+| 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; never carry the source's surfaces across. 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 a Hermes plugin target
+
+A capability in a Hermes plugin is reachable only 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 catalog and any resource or payload pins the plugin keeps;
+- the slash command file, when the capability has a command;
+- the prompt hook's routes and mode contract, when it has a natural-language route;
+- agents, settings defaults and MCP or LSP config, when the capability uses them;
+- user-facing listings: README skill tables, guides, help or 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
+nothing reaches it.
+
+Each product in a family is its own target. A port into one product never copies files into a
+sibling and never adds a dependency 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": "host CLI in a throwaway workspace with a throwaway HERMES_HOME, 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 does not. 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/assets/lithermes-plugin/skills/lit-hijack/references/parity-and-report.md

@@ -0,0 +1,131 @@
+# 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 never sufficient. Ports in this product have passed every gate while being
+unreachable, and A/B runs have measured nothing 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 |
+| --- | --- | --- |
+| Prompt-hook route | Pipe a `UserPromptSubmit` JSON payload into the hook and assert the skill is named in the returned context | Removing the route entry |
+| Slash command | Run the host with the plugin loaded and the command, and read the transcript | Deleting the command file |
+| Skill discovery | A host CLI prompt that should load the skill, with the transcript showing the skill loaded | 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, not the human text) | Removing the file from the allowlist |
+
+A probe that cannot fail proves nothing; 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 has none of the new files, `git log` inside it stops at the base revision, and the run
+folder, the spec and the diff are 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 only shows the spec was followed.
+
+For a Hermes skill or plugin target, run each arm as a real session in its own throwaway
+workspace, each with its own throwaway `HERMES_HOME` holding only that arm's plugin copy:
+
+```text
+HERMES_HOME=<baseline home> <host CLI> "<held-out prompt naming the skill id>"
+HERMES_HOME=<treatment home> <host CLI> "<held-out prompt naming the skill id>"
+```
+
+- Load both arms the same way, so the only difference is the port.
+- Keep any other installed copy of the same plugin out of both homes, or two versions of its hooks will both fire.
+- Install from a copy you control, never from the host's installed plugin cache.
+- For a project skill, give each arm its own workspace holding its own skill copy.
+- Keep the runs cheap: a small prompt, one model.
+- 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 no baseline output. 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 no keychain dialog interrupts the user.
+
+The sample output is evidence that the port works. Polishing that one sample is a different task;
+offer it only 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: .hermes/lithermes/runs/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 no 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 an isolated worktree
+(or: in the same context, degraded path). The model may have met these sources before. No run of
+12 or more words is 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.