MagentaDolphin
ecd87ac96d
Phase 0 of the handoff plan, as a marketplace rather than a flat skills/ directory. Content moved out of the LyraResearch archive and depersonalised: addresses stay in the archive, recipes ship. - plugins/ue-design-skills: 17 skills, 232 failure-mode entries, each with the six required fields; catalog.json as the harness-neutral source of truth and .claude-plugin/ as one adapter over it. - _gate: 16 rules, one poisoned fixture per rule, plus surface coverage so a declared file cannot silently miss the line rules. - ADR-0002 (harness-neutral bundle behind a marketplace) and ADR-0003 (split licensing: CC BY-ND 4.0 prose, Apache-2.0 code and metadata). - LICENSE files at both levels, CONTRIBUTING.md, docs/licensing-options.md as the material the licence decision grew from. Verified: gate.py 0 violations; test_gate.py 16/16 rules redden on their fixtures with a clean baseline and 2 root files reaching the line rules. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
# Contributing
|
|
|
|
Thanks for reading this far. Two things are unusual about this repository, and both
|
|
change how a contribution is judged. Read them before opening a pull request.
|
|
|
|
## 1. Prose and code are licensed differently
|
|
|
|
| Path | License |
|
|
|---|---|
|
|
| `plugins/ue-design-skills/skills/**` and the bundle README | CC BY-ND 4.0 |
|
|
| `catalog.json`, `.claude-plugin/**`, `_gate/**`, Detect recipes | Apache-2.0 |
|
|
| Everything else in this repository | Apache-2.0 |
|
|
|
|
See [ADR-0003](docs/architecture/decisions/0003-split-licensing-prose-and-code.md) for
|
|
why, and `plugins/ue-design-skills/LICENSE` for the exact grants.
|
|
|
|
**NoDerivatives does not block contribution.** Publishing a fork in order to propose a
|
|
change back is explicitly permitted (additional permission 7). What it blocks is
|
|
publishing a modified version as a separate product.
|
|
|
|
### Inbound licensing
|
|
|
|
By opening a pull request you agree that your contribution may be distributed under the
|
|
license that already applies to the file you changed — CC BY-ND 4.0 for prose,
|
|
Apache-2.0 for code and metadata — and you confirm that you have the right to grant
|
|
this.
|
|
|
|
If your employer owns your work, get clearance before submitting. This matters more than
|
|
usual here: a bundle under NoDerivatives has to be able to state a single copyright
|
|
holder, and an unclear contribution is worse than a missing one.
|
|
|
|
## 2. A claim without a source you can point at is not a contribution
|
|
|
|
The whole bundle rests on one invariant, and it applies to changes as much as to the
|
|
original material:
|
|
|
|
> A skill that is confident and wrong is worse than a missing one.
|
|
|
|
Read `skills/ue-evidence-discipline/SKILL.md` first. It is short, and it is the standard
|
|
the review will use. In particular:
|
|
|
|
- **Every Detect recipe must have been run**, against a real tree, in both directions:
|
|
it finds the known instance, and it stays quiet where there is none. A recipe that has
|
|
not been run is a hypothesis. Say which tree you ran it against.
|
|
- **An empty search result proves the pattern, not the absence.** A negative claim must
|
|
state the searches that produced it.
|
|
- **Measured, derived and open are never mixed in one sentence.**
|
|
- **Counts state their scope.** "94 definitions in 31 files across Source and Plugins" is
|
|
a fact; "94 definitions" is a number waiting to be misused.
|
|
|
|
Corrections to existing entries are the most welcome kind of change, especially ones
|
|
that show a recipe failing. If you found a case where a recipe returns a false negative,
|
|
that is a finding, not a nuisance — the bundle documents three of its own.
|
|
|
|
## 3. Before you open the pull request
|
|
|
|
```bash
|
|
cd plugins/ue-design-skills
|
|
python _gate/gate.py . # must print 0 violations
|
|
python _gate/test_gate.py # must print all rules reddening on their fixtures
|
|
claude plugin validate . --strict
|
|
```
|
|
|
|
The gate is not advisory. It enforces, among other things: no absolute paths, no source
|
|
citations, no donor project name outside a Provenance section, no Cyrillic, no vendor or
|
|
harness name anywhere under `skills/`, and the six required fields on every failure-mode
|
|
entry.
|
|
|
|
If you add a rule to the gate, **add a poisoned fixture that makes it fire.** The
|
|
self-test fails if any declared rule has no fixture. This is deliberate: the validator
|
|
this gate replaced ran green for months while checking a condition that could never
|
|
become true.
|
|
|
|
### Adding a failure-mode entry
|
|
|
|
Every entry carries six fields, in this order:
|
|
|
|
```
|
|
**Mechanism.**
|
|
**Why it is silent.**
|
|
**Why the obvious check misses it.**
|
|
**Symptom.**
|
|
**Detect.**
|
|
**Guardrail.**
|
|
```
|
|
|
|
Three of them — silence, why the obvious check misses it, and a Detect recipe that has
|
|
been run — cannot be written by someone who has not done the work. That is the point.
|
|
Entries missing any field are rejected by rule P09 before a human reads them.
|
|
|
|
Entry identifiers are sequential in document order (P15) and their prefix is unique
|
|
across skills (P16). If you insert an entry in the middle, renumber.
|
|
|
|
## 4. What is likely to be declined
|
|
|
|
- A recipe that has not been run, or whose output is not shown.
|
|
- An entry whose "why it is silent" restates the mechanism in other words.
|
|
- A skill that names a specific agent runtime, path variable or command syntax. The
|
|
bundle must work with any harness; this is enforced by rule P13.
|
|
- Reformatting passes that touch many files without changing a claim.
|
|
- A new skill proposed before a discussion issue. Open the issue first — the bundle is
|
|
deliberately small, and a sixteenth subsystem needs a reason.
|
|
|
|
## 5. Reporting something you cannot fix
|
|
|
|
Open an issue. A well-reported false negative in a Detect recipe is worth more than a
|
|
patch, because it usually means the recipe is wrong in a way the author could not see.
|
|
|
|
Include the tree you ran against (engine version is enough — no source needed), the
|
|
command, the output you got and the output you expected.
|