@appchy/jarvis 0.1.36 → 0.1.39

package/harness/presets/appchy/references/research.md

@@ -0,0 +1,216 @@
+# Research procedure — sources + raw + take + synthesis
+
+The canonical way to run research. Load this when a task needs external
+findings (prior art, market/tech survey, an unfamiliar domain) — i.e. whenever
+a `research.md` or `research/<dir>/` artifact is called for (see
+[`artifacts.md`](../../../references/artifacts.md) §Conditional task-level files / §shared pool).
+
+## Who researches is the REPO's choice, not this skill's
+
+`research.agent` in `work.config.json` names the subagent that runs it. **This
+skill names no model and no vendor** — which model researches is a repo
+preference, and baking one in here would ship a bias into every repo that
+loads the plugin, exactly as naming a test command in `verify` would.
+
+Any addressable agent is a legal value — a Codex one, a Claude one, another
+family's. **A Claude researcher costs you the independent read**: its take and
+the synthesis you write on top come from the same model, so their agreement
+tells the founder nothing. That is a trade to make knowingly, not a rule
+against it, and the way to make it knowingly is to name the researcher in
+`00-report.md` so the founder can see whose agreement they are looking at.
+
+Unset is fully supported: pick a researcher, follow the identical contract
+below, and **say which one you used** in `00-report.md`, so no finding is ever
+traceable to an unnamed reader.
+
+**One researcher per run.** If you want two families' reads, run it twice
+against the same `sources/` — which the layering below is built for — rather
+than letting one researcher sub-contract the other mid-run. Two models sharing
+one run means no snapshot has a single reader you can hold to it.
+
+What does NOT vary, ever, is everything below this line.
+
+## The contract (D172 workflow; founder rule)
+
+**The researcher delivers raw material; Claude authors the synthesis.** The two
+never blur — you always keep the raw sources *and* the researcher's opinion
+*separate* so the founder can judge whether anything was missed.
+
+Four output layers, distinct owners:
+
+| Layer | Owner | File(s) |
+|---|---|---|
+| **The sources themselves, verbatim** | researcher | `sources/<vendor>-<slug>.md` — one per source actually read |
+| Raw, source-cited findings | researcher | `01-*.md`, `02-*.md`, … (one per sub-topic; real URLs/authors/tools) |
+| The researcher's opinionated take | researcher | **`<researcher>-take.md`** — named for the model that wrote it; quarantined, labelled "not authoritative" |
+| The synthesis (decisions-relevant) | **Claude** | `00-report.md` (≤30 lines) — the read-order entry point |
+
+The researcher **never** writes `00-report.md`; Claude **never** lets its take
+leak into the synthesis unattributed. This keeps the synthesis free of the
+researcher's bias while preserving its opinion for the founder to weigh.
+
+**The two lower layers are model-neutral; only the take carries a name, and it
+carries the researcher's own.** `codex-take.md` when Codex researched,
+`claude-take.md` when Claude did. That is not bookkeeping — it is what lets a
+second model go over the *same* raw material months later and file its opinion
+**beside** the first rather than on top of it:
+
+```
+work/research/<topic>/
+  00-report.md          Claude's synthesis — says which researcher produced the raw layer
+  sources/              verbatim snapshots — belong to no model, re-readable by any
+  01-*.md, 02-*.md      raw findings — same
+  codex-take.md         what Codex concluded from them
+  claude-take.md        what Claude concluded from the same files, added later
+```
+
+Two takes over one raw layer is a **feature**, and it is the cheap way to get a
+second family's read: the sources are already fetched, so the second pass is
+opinion only. Two takes that disagree is the most useful thing this directory
+can hand a founder — which is only legible because each is filed under the name
+of whoever wrote it.
+
+**`sources/` IS NOT OPTIONAL, and this is the founder rule that keeps getting
+dropped** (restated 2026-08-12 after an audit found it in only 7 of 18 research
+dirs, with two that had decayed to a single summary file and no raw layer at
+all). Every source the researcher actually reads is snapshotted verbatim into
+`sources/`, so the founder and Claude can **read the original and reach their
+own conclusion** rather than inheriting the researcher's. A findings file is
+already one layer of interpretation; a summary of a findings file is two. When
+the source disappears, changes, or turns out to have been misread, the snapshot
+is the only thing that settles it.
+
+Each snapshot opens with the same header, then the content as it was:
+
+```markdown
+# Snapshot: <page or doc title>
+
+Source: <exact URL>
+Retrieved: <YYYY-MM-DD>
+
+<the content, as close to verbatim as the format allows>
+```
+
+Paraphrasing a source inside `sources/` defeats the whole point. Trim
+navigation, ads and boilerplate; never trim the substance, and never rewrite it
+in your own words.
+
+**Keep the raw files CLEAN (the rule the founder cares most about).** Each
+`0N-*.md` findings file holds the **actual substantive content** of each
+finding — the specific facts, figures, quotes, code examples and API/tool
+details the researcher actually found — **each attributed to its source URL** (or an
+explicit `[knowledge-only]` tag when a claim rests on model knowledge, not a
+source). It is **NOT a bare list of links**: a findings file must read as
+genuine, self-contained research material — enough that the founder and Claude
+can judge the substance without re-fetching the sources. And it carries **NO
+recommendations, opinions, or "how our code should change" mappings** — every
+one of the researcher's own takes, recommendations and code-change suggestions
+goes in its `<researcher>-take.md` and nowhere else. A single merged file, or a
+file of bare URLs with the real content missing, are both failures this contract
+exists to prevent — the raw content and the take are **separate files**, always,
+and the raw files carry the real material, not just citations.
+
+The reason the split is worth this much insistence is the one above: a raw layer
+with an opinion mixed into it is no longer re-usable by a second reader, so the
+cheap second read stops being available the moment somebody merges the files.
+
+## How to run it
+
+1. **Pick the home.** `work/research/<topic>/` for shared/cross-task research;
+   a task-local `research/` subfolder for task-scoped work.
+2. **Forward to the researcher named by `research.agent`** (unset → pick one and
+   say so). Assume the runner enforces **no** file layout — the output is 100%
+   whatever the prompt asks for. So the prompt must carry the contract, and
+   **you must paste the block below VERBATIM** (filling only the bracketed
+   slots). **Never hand-write or paraphrase the contract from memory** — that is
+   exactly how the raw/take split collapses into one merged file. Load THIS file
+   and copy it:
+
+   ```
+   <structured_output_contract>
+   Research task — deliver RAW, source-cited findings ONLY. I (Claude) author the
+   synthesis; you do not. Write ONLY inside work/research/<TOPIC>/ (read-only
+   everywhere else — no source/config/build edits). Produce exactly these files:
+
+   - sources/<vendor>-<slug>.md   (MANDATORY — one per source you actually read)
+     A VERBATIM snapshot of the source, so we can read the original ourselves and
+     reach our own conclusion. Open each with:
+         # Snapshot: <page or doc title>
+         (blank)
+         Source: <exact URL>
+         Retrieved: <YYYY-MM-DD>
+     then the content as it was. Trim navigation/ads/boilerplate; NEVER trim the
+     substance and NEVER paraphrase it — a rewritten snapshot is worthless to us.
+     If you could not fetch a source, say so in the findings file rather than
+     writing a snapshot from memory.
+   - 01-<subtopic>.md, 02-<subtopic>.md, …  (one file per sub-topic)
+     RAW findings only, with the ACTUAL CONTENT of each finding — the specific
+     fact, figure, quote, code example or API detail — attributed to its source
+     URL (or an explicit [knowledge-only] tag), and pointing at the matching
+     sources/ file. NOT a bare list of links: write the real substance so it can
+     be judged without re-fetching. NO recommendations, NO opinions, NO "how our
+     code should change" in these files.
+   - <RESEARCHER>-take.md
+     ALL of your opinions, recommendations and code-change suggestions go here,
+     and ONLY here. Label it clearly as YOUR take, not authoritative. The file is
+     named for YOU because another model may later read the same raw files and
+     file its own take beside yours — so keep the layers above free of opinion,
+     or you have spent its read for it.
+
+   Do NOT write 00-report.md or any summary/synthesis file — I author that myself
+   from your raw files. Do NOT merge findings and opinion into one file. A run
+   that returns conclusions without sources/ has not done the job.
+   </structured_output_contract>
+   ```
+
+   Replace `<TOPIC>` with the research dir, `<RESEARCHER>` with that agent's own
+   short name (`codex`, `claude`, …), and `<subtopic>` with real sub-topic names;
+   add as many `0N-*.md` files as there are sub-topics.
+3. **Poll from the main session**, by whatever means that researcher offers.
+   The forwarder must not poll itself — control stays Claude-side.
+4. **Read + synthesize.** Read the raw files + the take, then author
+   `00-report.md` in Claude's own voice: decisions-relevant only, citing the
+   raw files, naming the researcher used and noting explicitly where the
+   synthesis diverges from its take.
+5. **Point the task's read-order at `00-report.md`**; drill into the rest only
+   when a question demands it (Output budgets: research is read by summary).
+
+**Later, for a second read:** point another model at the existing `sources/` and
+`0N-*.md` and ask for **only** a `<researcher>-take.md`. No re-fetching, no new
+raw layer, nothing overwritten — the whole cost is one opinion. Where the two
+takes disagree is worth more than either on its own.
+
+## Worked reference
+
+`work/research/spec-as-source-of-truth/` is the canonical example: `01`–`05`
+raw + the take quarantined + Claude's `00-report.md` synthesis.
+
+## What a failed run looks like
+
+Any of these means the contract was not followed, and the fix is to re-run it
+rather than to work from what came back:
+
+- **No `sources/` directory** — conclusions with nothing to check them against.
+- **`00-report.md` and nothing else.** Two dirs decayed to exactly this.
+- **One merged file** carrying findings and opinion together.
+- **Findings that are bare links**, or snapshots rewritten in the researcher's words.
+- **A take under a generic name** (`take.md`, `researcher-take.md`) — the second
+  reader then has nowhere to put its own without a collision.
+
+## Why off-load research at all, rather than read it in-session
+
+Two reasons, and neither names a vendor:
+
+- **It costs the session nothing.** A researcher on its own CLI and its own
+  quota is usually the single biggest weekly saving in a model-routing setup —
+  research is token-heavy and its output is a file, not a conversation.
+- **A different model family is an independent read**, which the founder can
+  cross-check against the synthesis. A sub-agent of the same model that writes
+  `00-report.md` agrees with itself for free, and that agreement means nothing.
+
+Neither reason forbids a same-family researcher — the second one prices it.
+Configure it if the first reason is what you are buying, and let the named take
+file say plainly whose opinion the founder is reading.
+
+Which one is `research.agent`. See [`../SKILL.md`](../PRESET.md) *Model routing*
+for the wider tiering.

package/harness/schema/work.config.schema.json

@@ -0,0 +1,401 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/appchy-ai/plugins/work.config.schema.json",
+  "title": "work.config.json",
+  "description": "Per-repo configuration for the `work` harness, committed at .claude/work.config.json. This is the ONLY configuration path: Claude Code has deliberately ignored `pluginConfigs` in project settings since v2.1.207, because a cloned repo could otherwise inject values into hook commands and MCP configs. Treat it as a security surface — a value that reaches a shell command is the same injection wearing different clothes.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "ids": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The durable-rule id vocabulary. Ids are permanent; only their home moves.",
+      "properties": {
+        "prefix": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9]+$",
+          "default": "D",
+          "description": "The prefix this repo's rules carry — D, G, ADR. Alphanumeric only: it is compiled into a regex, so punctuation would change what counts as an id."
+        },
+        "recognised": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9]+$"
+          },
+          "default": [],
+          "description": "Extra prefixes accepted on READ but never generated. How a migration window stays readable without the lint going silent."
+        },
+        "undashed": {
+          "type": "boolean",
+          "default": false,
+          "description": "Read `D12` as well as `D-12`. Off by default: a short prefix collides with ordinary data — `priority: P0` was read as a citation to a rule `P-0` that does not exist. Turn on only where an interface really publishes undashed ids."
+        },
+        "foreign": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Sibling repos whose ids may legally appear here, e.g. \"acme D-147\". Empty by default: a fresh repo has no siblings, and shipping somebody else's repo names would silently excuse a real dangling citation in every consumer."
+        }
+      }
+    },
+    "domains": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "order": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "product",
+            "architecture",
+            "design",
+            "quality",
+            "security",
+            "operations",
+            "support",
+            "commercial",
+            "legal"
+          ],
+          "description": "Reading order of the org-domain map, not alphabetical. A domain not on the list still scans; it sorts last."
+        }
+      }
+    },
+    "spine": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The conventions a plan must fit, read before planning.",
+      "properties": {
+        "standards": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Repo-relative path to the standards doc, or null."
+        },
+        "conventions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Repo-relative paths to convention docs, nearest first."
+        }
+      }
+    },
+    "plans": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "dir": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Repo-relative directory holding approved plan files, or null. `work.py plan` records a POINTER into it, never the plan body. Null is a full mode, not a missing setting: with no directory configured `plan` requires an explicit --file, so a repo that deliberately keeps no plans directory is never handed a pointer into one."
+        }
+      }
+    },
+    "product": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tiers": {
+          "type": "string",
+          "enum": [
+            "flat"
+          ],
+          "default": "flat",
+          "description": "`flat` — a feature is product/<feature>.md and its bare name is its whole address. The only shape implemented today; the key exists so a repo that grows an app tier has somewhere to say so rather than forking."
+        }
+      }
+    },
+    "instructions": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How this repo's guidance is composed. The harness ships an ENGINE (the tree, the ids, the buckets, the delivery gate — what work.py enforces) and, separately, a PRESET: one organisation's methodology on top of it. Contradict the engine and the tool refuses you; contradict the preset and you have merely chosen to work differently. Shipping them fused made every consumer inherit one org's opinions as though they were mechanics. This is the shareable-config pattern — eslint's engine vs eslint-config-*: the engine never enumerates its consumers, and whoever holds an opinion publishes it themselves.",
+      "properties": {
+        "preset": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "A shipped preset by name, a repo-relative path to your own, or null for the bare engine. NULL BY DEFAULT: this shipped naming the author's own preset, so a repo that installed the harness and said nothing inherited one organisation's methodology as though it came with the mechanics. A preset is somebody's opinion, and whose opinion runs in a repo is that repo's call — the engine ships, the methodology is one key away."
+        },
+        "extend": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Repo-relative files layered ON TOP, in order. Later wins on conflict: engine < preset < extend[0] < extend[1] … Layering rather than named section overrides, deliberately — a slug API would owe every consumer a stable set of headings forever, so renaming a section would break repos that never asked to be coupled to our table of contents."
+        },
+        "skill": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What a session runs to load this repo's method — the line every kickoff prompt opens with. Null for a prompt that names none."
+        }
+      }
+    },
+    "tags": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allowed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Area tags a task's `tags:` field may carry, for grouping the board by capability or market. EMPTY MEANS NO VOCABULARY IS CONFIGURED, and then any tag is accepted — name a list and it becomes closed, so an unknown tag is refused against it. It is config rather than a shipped list because an area vocabulary is the most repo-specific thing a task carries: the tuple that used to live in the payload shipped one consumer's product names to every other repo AND refused their own. Compare `code:`, whose vocabulary is DERIVED from the systems in work/architecture/*.md — a fact that can be derived is never written, and this one cannot be."
+        }
+      }
+    },
+    "research": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "The subagent that runs external research for this repo — a Codex agent such as \"codex:codex-rescue\", a Claude one, or anything else the session can address. NAMED HERE RATHER THAN IN THE SKILL because which model researches is a repo's own preference, and hardcoding one would ship a bias — the same reason `verify` names no test command. The PROCEDURE and its output contract (verbatim sources/ + raw findings + a take filed under the researcher's own name + Claude's synthesis) are the skill's and do not vary. A Claude agent is legal, with the trade stated openly: it is not an independent read, so its take and the synthesis agree with each other for free. Null is fully supported: the session picks a researcher, follows the same contract, and SAYS which one it used, so a finding is never traceable to an unnamed reader."
+        }
+      }
+    },
+    "verify": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "default": {},
+      "description": "Commands run to verify work, by name — e.g. {\"test\": \"<this repo's test command>\"}. Free-form because toolchains differ, and naming one here would ship a bias. EXECUTED by `work verify` and required by the completion gate: a task cannot reach complete/ without a passing record. Each is split with shlex and run with shell=False, so shell operators (&&, ||, ;, |, >, $(), backticks) are REFUSED at load rather than passed to the first binary as literal arguments — put the composition in a script and call that."
+    },
+    "autonomy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What an unattended run may do on its own. The harness runs on a schedule, so the decision boundary has to be a value rather than a habit.",
+      "properties": {
+        "ceiling": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 3,
+          "default": 2,
+          "description": "The highest task `tier:` an unattended run acts on alone. 0 reversible and local · 1 ordinary change behind existing tests · 2 new behaviour or a reversible migration · 3 irreversible, or it touches money, secrets, personal data or the law. Default 2: the shift does ordinary work and parks the rest with `work ask`. 3 means \"decide everything\" and is deliberately never the shipped default."
+        },
+        "lease_minutes": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 240,
+          "description": "How long one instance's claim on a task holds before another may take it. Long enough that real work finishes inside it; short enough that a crashed shift's task is takeable the same day."
+        }
+      }
+    },
+    "graph": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mcp": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "The MCP server serving this repo's governance↔code graph, or null. Null is fully supported: the planning loop degrades to grep-wide and says so. It never implies a complete map it did not get."
+        }
+      }
+    },
+    "session": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Starting the NEXT session — the wrap's last act. A SEPARATE key from graph.mcp even where the same server answers both: serving a graph and starting a session are different capabilities, and a repo can have either without the other. Riding on the graph's key would mean a repo that installed a map silently gained the power to spawn sessions.",
+      "properties": {
+        "mcp": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "description": "The MCP server whose tool opens a session in this repo, or null. Null is the default and a fully supported mode: `work kickoff` prints the prompt and a person carries it across, which is what the wrap always did. The value is composed into `mcp__<server>__<tool>` and is validated as a plain name for that reason."
+        },
+        "tool": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "description": "The tool on that server that starts the session. NO DEFAULT, deliberately: a default here would be one vendor's tool name compiled into a repo-agnostic payload and shipped to every consumer as though it were a fact about how sessions start. Naming a server therefore obliges you to name its tool — session.mcp without session.tool is refused at load. The tool must take a `prompt` and a `cwd`, and its answer must say whether the started session outlives the caller."
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The hook points this plugin owns, and what a repo may do to each. The declaration in the plugin's hooks.json is the plugin's and a consumer cannot change it; what a consumer needs is to change what is SAID there. Keyed by Claude Code's own event names rather than by what the harness does at each, so an installer writes the key it already has a name for.",
+      "properties": {
+        "session_start": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The standing obligations a fresh session is given.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether the harness says its OWN lines here. false silences them; paired with `extend` that is how a repo REPLACES this hook's output rather than adding to it, and alone it switches the point off."
+            },
+            "extend": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Commands the harness runs at this point, whose output is folded in after its own. Run with shell=False after a shlex split and never interpolated, so shell operators are refused at load — put any composition in a script and name that. A command that fails, is missing, or runs long is REPORTED in place of its lines, never silently dropped."
+            }
+          }
+        },
+        "stop": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The end-of-turn wrap reminder. This is the HOOK; `wrap.at_percent` is when it fires, and they are separate because a repo can want the threshold without the harness's wording, or the reverse.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether the harness says its OWN lines here. false silences them; paired with `extend` that is how a repo REPLACES this hook's output rather than adding to it, and alone it switches the point off."
+            },
+            "extend": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Commands the harness runs at this point, whose output is folded in after its own. Run with shell=False after a shlex split and never interpolated, so shell operators are refused at load — put any composition in a script and name that. A command that fails, is missing, or runs long is REPORTED in place of its lines, never silently dropped."
+            }
+          }
+        }
+      }
+    },
+    "git": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Whether a board write lands in git. OFF BY DEFAULT: this harness is shared, and a repo that never asked for it must not start committing on its own. Where it is on, the commit's trailers are the activity record and no work/.events.jsonl is written.",
+      "properties": {
+        "commit": {
+          "type": "boolean",
+          "default": false,
+          "description": "Commit every board write, the moment it happens. No debounce and no window — the window is the bug: an item created inside one existed in no git history anywhere."
+        },
+        "push": {
+          "type": "boolean",
+          "default": false,
+          "description": "Pull before, push after. Needs `commit`. Off separately so a repo with no shared origin still gets the half that makes a write unloseable."
+        },
+        "remote": {
+          "type": "string",
+          "default": "origin",
+          "description": "The remote a board write is pushed to."
+        },
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "default": [
+            "work"
+          ],
+          "description": "What a board write commits. Repo-relative, and refused if it could point outside the repo — these become pathspecs on a real commit. A hold (.claim) is never committed whatever this says."
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "shard": {
+          "type": "string",
+          "default": ".work/coverage",
+          "description": "Where runners drop coverage shards. Gitignored on purpose — evidence is a fresh run, not a file somebody checked in."
+        }
+      }
+    },
+    "hygiene": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "review": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "The command this repo runs for its bug pass, or null to skip it. NULL BY DEFAULT: the shipped defaults used to name two commands, which was wrong twice over — nothing read the keys, so a repo that set its own was silently ignored, while the prose named those two to every consumer regardless of what it had. Where it is set, the SessionStart block names it; where it is null there is no pass and the harness invents none."
+        },
+        "simplify": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "The command this repo runs for its quality pass, or null to skip it. NULL BY DEFAULT: the shipped defaults used to name two commands, which was wrong twice over — nothing read the keys, so a repo that set its own was silently ignored, while the prose named those two to every consumer regardless of what it had. Where it is set, the SessionStart block names it; where it is null there is no pass and the harness invents none."
+        }
+      }
+    },
+    "wrap": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Finishing a session cleanly before the context window runs out. OFF unless a repo opts in: the Stop hook behind it speaks up at the end of a turn, and a hook that interrupts somebody's session is theirs to switch on — the same reasoning that keeps hooks/guard.py inert.",
+      "properties": {
+        "at_percent": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1,
+          "maximum": 99,
+          "default": null,
+          "description": "Share of the context window past which the session is reminded to wrap up — write the handoff, bring task/epic docs current, move statuses, and leave a kickoff prompt for the next session. Null is off. 100 is refused along with 0: a reminder arriving once the window is full has nowhere left to write the handoff it asks for."
+        },
+        "context_tokens": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1,
+          "default": null,
+          "description": "The window at_percent is measured against. NO DEFAULT, and at_percent requires it: a hook cannot ask Claude Code how large the context is, so any shipped number is a guess about somebody else's session. 200000 nagged a long-context consumer from its first turn; 1000000, which replaced it, would let a standard 200k session reach 100% having been told it was at 20%. Both fail silently. State the window you actually run. Usage itself is never estimated — it is read from the API's own `usage` record, so the percentage is exact."
+        },
+        "command": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What to run to wrap a session up, named in the reminder. Null to remind without naming a command."
+        }
+      }
+    },
+    "skip_dirs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Extra generated or vendored directories to skip, beyond the built-in rule (any dot-directory except .claude, plus the standard build dirs). Scanning a generated cache mints phantom test bindings — one snapshot dir of 1,521 files did exactly that."
+    }
+  }
+}