@skyf0xx/hedgehog 6.1.1 → 6.1.3

package/bin/cli.mjs

@@ -41,7 +41,7 @@ import {
   reapExpiredLeases,
 } from '../src/db/claim.mjs';
 import { readyTasks, formatReady } from '../src/db/ready.mjs';
-import { graphStatus, formatStatus } from '../src/db/status.mjs';
+import { graphStatus, formatStatus, inFlightTasks, formatBrief } from '../src/db/status.mjs';
 import { boundaryState, formatBoundary, formatPosition, formatHandoff } from '../src/db/boundary.mjs';
 import { commitGateStatus, formatCommitGate } from '../src/db/gate.mjs';
 import { detectDrift, recompileTasks, formatRecompile } from '../src/db/drift.mjs';
@@ -559,6 +559,7 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog verify <task-id> --owner <owner>   run scope + verify checks, commit on pass
   npx @skyf0xx/hedgehog status                    graph overview: counts by status, ready list, in flight,
                                                    and any drift from core.yaml
+  npx @skyf0xx/hedgehog status --brief            one line: what is in flight, and nothing else
   npx @skyf0xx/hedgehog ready                     preview which ready tasks are claimable now vs held back
   npx @skyf0xx/hedgehog quiesce                   report whether anything is still in flight
   npx @skyf0xx/hedgehog boundary                  is this a moment to clear context? exits 0 only if it is,
@@ -2529,7 +2530,18 @@ async function coreWarningLines() {
   ];
 }
 
-async function statusCommand() {
+// `--brief` answers one question — is anything `building` or
+// `verifying` — and prints one line. It exists because `hedgehog-daily`
+// asks that question before every change request, including the ones
+// that end in a two-line edit, and the full report below costs a core
+// load, a drift comparison, a readiness simulation, an override scan,
+// a commit-gate probe and an update check to answer it. The default
+// report is unchanged: this adds a cheaper question, it does not
+// replace the existing one, and a "yes" here is the cue to read the
+// full report.
+async function statusCommand(args = []) {
+  const brief = args.includes('--brief');
+
   await ensureDb();
 
   if (!(await exists(DB_PATH))) {
@@ -2538,6 +2550,21 @@ async function statusCommand() {
     return;
   }
 
+  if (brief) {
+    const db = openDb();
+    let inFlight;
+    try {
+      // Same reaping contract as the full report — a dead agent's
+      // expired lease must not read as in-flight work on either path.
+      reapExpiredLeases(db);
+      inFlight = inFlightTasks(db);
+    } finally {
+      db.close();
+    }
+    console.log(formatBrief(inFlight));
+    return;
+  }
+
   // Drift needs the core definition to compare against. A project
   // without one yet (deferred install, pre-bootstrap) simply gets the
   // status it always got; an unparseable one is reported but never
@@ -3514,7 +3541,7 @@ async function main() {
   }
 
   if (cmd === 'status') {
-    await statusCommand();
+    await statusCommand(args.slice(1));
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "6.1.1",
+  "version": "6.1.3",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/agents/reviewer.md

@@ -18,7 +18,12 @@ commit — the gate already covers that.
 - **A transition check the core's loop skill defines** — the point where
   one phase or layer closes and the next opens. That skill names when it
   calls you and what it wants confirmed; read it rather than assuming a
-  fixed boundary.
+  fixed boundary. Mechanically, that point is where a layer's
+  `verify_radius` is wider than its own `scope`, or the layer is
+  `exclusive: true` (`core.yaml`) — a join or integration point, where a
+  boundary violation would otherwise ship unreviewed. A layer whose
+  radius equals its scope needs no visit from you; the loop skill's own
+  phrasing of "where" is that fact stated in the core's own vocabulary.
 - **Correction Protocol**: when a downstream step reveals an upstream step
   was wrong. Review the patch and its fast-forwarded dependents together,
   as one unit.

package/src/agents/tweaker.md

@@ -59,29 +59,29 @@ style, a piece of behavior), the existing codebase, the commit log.
 discipline as the rest of the build (`fix(<scope>): <what>` or
 `style(<scope>): <what>`, whichever fits).
 
-A tweak is a small, targeted edit to something that already exists —
-not a new module, not a new phase, not scope growth. If a request turns
-out to be either of those, say so and route it onward — a completed
-build is extendable, not sealed, and the user should not hear "no" where
-the answer is "that's a different session." Two destinations, and which
-one applies depends on whether the core has a module axis to hang new
-work on:
+**Size every request with the `hedgehog-daily` skill.** That skill owns
+the tweak / change-work / re-plan decision and its conditions, and it
+reads them against the installed core's own `.hedgehog/core.yaml` — run
+it rather than judging the size here. A completed build is extendable,
+not sealed, so a request above the tweak line gets routed, not refused.
 
-- **New scope on a module axis** routes to `planner`, which runs
-  `hedgehog-planning-intake`'s **Re-entry pass**: it adds intents for the
-  new work without re-running planning from scratch, and without
-  disturbing anything already built.
-- **Everything else** routes to the **Correction Protocol's post-build
-  entry**, in the core's own loop skill, which re-runs whichever phases
-  the change reaches and rebuilds the artifact.
+What each exit means for you:
 
-A core with no module axis has no intent for `planner` to add, so new
-work there is the second case, not the first — and the locked planning
-artifact that governs it (the brief, the design rationale, the layer
-sequence) is never rewritten to accommodate new scope. When that artifact
-genuinely no longer holds, the request is a different project and belongs
-in its own, not an edit to this one; say so rather than routing it. The
-core's own loop skill states which artifact governs and what the test is.
+- **Tweak** — make it here, per that skill's tweak exit and this file's
+  Workflow step 3.
+- **Change-work** — route it onward. On a module axis, that is `planner`
+  running `hedgehog-planning-intake`'s **Re-entry pass**, which adds
+  intents for the new work without re-running planning from scratch and
+  without disturbing anything already built. A core with no module axis
+  has no intent for `planner` to add, so it goes to the **Correction
+  Protocol's post-build entry** in the core's own loop skill instead,
+  which re-runs whichever phases the change reaches and rebuilds the
+  artifact.
+- **Re-plan** — the locked planning artifact no longer holds. Route to
+  `planner`'s re-entry pass, or, where that artifact's failure means the
+  request is a different project rather than an extension of this one,
+  say so plainly instead of routing. Never rewrite that artifact to
+  accommodate new scope.
 
 ### Job 2 — Friction review, user feedback, and issue suggestion
 
@@ -211,11 +211,11 @@ discipline as `.hedgehog/BMAD/`. A later related incident is its own new
      drop it either way; a "no" or no response is not a prompt to explain
      further or ask again later in this session. If the user says yes,
      hand off to the `hedgehog-contributing` skill.
-3. **Job 1, every run**: take the user's tweak request, read the actual
-   code it touches (not a summary), make the change, verify it with the
-   touched layer's own `verify` command from `.hedgehog/core.yaml` —
-   matching whatever the core's own loop skill already gates on — and
-   commit it as its own small conventional commit.
+3. **Job 1, every run**: run the `hedgehog-daily` skill on the user's
+   request. On its tweak exit, make the change there — read the actual
+   code it touches (not a summary), edit, verify with the touched layer's
+   own `verify` command from `.hedgehog/core.yaml`, commit as its own
+   small conventional commit. On either other exit, route as above.
 4. **Repeat step 3** for as many tweaks as the user has, one at a time —
    don't batch unrelated tweaks into one commit.
 
@@ -257,11 +257,11 @@ discipline as `.hedgehog/BMAD/`. A later related incident is its own new
   `reviewed:` row logged after every other row currently in the log?
 - Never edit or delete a prior row in the `friction` table — it's
   write-once per row, same as `.hedgehog/BMAD/`.
-- Don't expand a tweak into a rebuild. If a "tweak" actually requires
-  redoing a phase (the artifact an upstream phase locked has to change,
-  not just one line of what a later phase produced from it), that's the
-  Correction Protocol — say so and route it
-  there rather than patching around it here. Use its **post-build entry**
+- Don't expand a tweak into a rebuild. A request `hedgehog-daily` sizes
+  above the tweak line gets routed, never patched around here — and a
+  tweak that turns out mid-edit to reach a second layer or need a file
+  that doesn't exist stops and re-enters that gate.
+- When the route is the Correction Protocol, use its **post-build entry**
   (in this core's own loop skill): the build is already at its Stop
   Condition, so there's no task in flight to stop and no loop to resume,
   and the correction is fixed forward in new commits rather than by

package/src/db/core.mjs

@@ -180,9 +180,16 @@ function indentOf(line) {
   return line.length - line.trimStart().length;
 }
 
+// The only values `pattern` may declare — named in every rejection
+// message below, so a typo surfaces the valid set instead of silently
+// degrading to "unset" (which would turn conformance checking off with
+// no signal that anything is wrong).
+const VALID_PATTERNS = ['hexagonal', 'layered', 'vertical-slice', 'none'];
+
 // Parses the narrow subset of YAML a core definition needs:
 //   id: <scalar>
 //   pluralizes: <bool>            # optional, default true
+//   pattern: <scalar>             # optional, one of hexagonal|layered|vertical-slice|none
 //   layers:
 //     - id: <scalar>
 //       depends_on: <scalar>          # optional
@@ -202,7 +209,7 @@ export function parseCoreYaml(text) {
     lines.push({ indent: indentOf(noComment), text: noComment.trim() });
   }
 
-  const core = { id: undefined, pluralizes: true, layers: [] };
+  const core = { id: undefined, pluralizes: true, pattern: null, layers: [] };
   let i = 0;
 
   while (i < lines.length && lines[i].indent === 0) {
@@ -224,6 +231,21 @@ export function parseCoreYaml(text) {
     // advisory stops firing on it for good, rather than every user of
     // that core re-discovering the same false positive.
     if (key === 'pluralizes') core.pluralizes = parseScalar(value) === 'true';
+    // An architecture claim, checked by validateCore below — see that
+    // function's pattern-conformance block for what each value asserts.
+    // Rejected here, at parse time, rather than left to validateCore:
+    // an unrecognized value must never silently resolve to "unset" (the
+    // one value that turns conformance checking off), so a typo has to
+    // surface as a parse error, not a quietly-skipped check.
+    if (key === 'pattern') {
+      const declared = parseScalar(value);
+      if (!VALID_PATTERNS.includes(declared)) {
+        throw new Error(
+          `unknown pattern "${declared}" — must be one of: ${VALID_PATTERNS.join(', ')}`,
+        );
+      }
+      core.pattern = declared;
+    }
     i++;
   }
 
@@ -498,6 +520,132 @@ export function isModuleAxis(core) {
   return core.layers.some((layer) => layer.scope.join('').includes('{module}'));
 }
 
+// `layered`'s and `hexagonal`'s checks both anchor on "the head layer" —
+// the first-declared layer, by the same convention `core.layers[0]`
+// already carries informally everywhere else in this file (e.g. the
+// once-layer checks below walk `core.layers` in declaration order too).
+function headLayer(core) {
+  return core.layers[0];
+}
+
+// `pattern: layered` — a strict linear chain: every layer but the head
+// depends on exactly one other, no two layers share a depends_on parent
+// (that would be branching, not a chain), and every layer is reachable
+// from the head by walking depends_on forward. Throws naming the first
+// layer that breaks the shape, in the order the checks below run.
+function checkLayeredPattern(core) {
+  const head = headLayer(core);
+  const rest = core.layers.filter((layer) => layer.id !== head.id);
+
+  for (const layer of rest) {
+    if (!layer.depends_on) {
+      throw new Error(
+        `core "${core.id}" declares pattern: layered, but layer "${layer.id}" has no depends_on — every layer but the head ("${head.id}") must depend on exactly one other layer`,
+      );
+    }
+  }
+
+  const dependents = new Map(); // parent layer id -> the one layer that depends on it
+  for (const layer of rest) {
+    const prior = dependents.get(layer.depends_on);
+    if (prior) {
+      throw new Error(
+        `core "${core.id}" declares pattern: layered, but both "${prior}" and "${layer.id}" depend on "${layer.depends_on}" — a layered chain is linear, one dependent per layer`,
+      );
+    }
+    dependents.set(layer.depends_on, layer.id);
+  }
+
+  // Walk forward from the head (parent -> its one dependent) and confirm
+  // every layer gets visited. This also catches a chain disconnected from
+  // the head entirely — e.g. two layers depending on each other with
+  // neither reachable from the head — which the checks above don't rule
+  // out on their own: each layer still has exactly one depends_on and no
+  // parent is shared, they just never connect back to "${head.id}".
+  const visited = new Set([head.id]);
+  let current = head;
+  while (dependents.has(current.id)) {
+    current = core.layers.find((layer) => layer.id === dependents.get(current.id));
+    visited.add(current.id);
+  }
+  for (const layer of core.layers) {
+    if (!visited.has(layer.id)) {
+      throw new Error(
+        `core "${core.id}" declares pattern: layered, but layer "${layer.id}" is not reachable from the head layer "${head.id}" by following depends_on`,
+      );
+    }
+  }
+}
+
+// `pattern: hexagonal` — Hedgehog has no adapter marker today, so this
+// checks direction alone rather than an actual domain/adapter boundary:
+// the head layer (the domain, by convention) must have no depends_on, and
+// every other layer's depends_on chain must terminate at the head with no
+// cycle — i.e. dependencies all point one way, inward, and the head is the
+// sink every chain ends at. Weaker than the real hexagonal rule (nothing
+// stops an adapter depending on another adapter instead of the domain
+// directly), and deliberately so — see #314's "Not in this issue" for why
+// a real adapter-boundary marker is a separate design decision.
+function checkHexagonalPattern(core) {
+  const head = headLayer(core);
+  if (head.depends_on) {
+    throw new Error(
+      `core "${core.id}" declares pattern: hexagonal, but its head layer "${head.id}" has a depends_on — the domain layer must be the sink every dependency chain points to, not itself a dependent`,
+    );
+  }
+
+  const byId = new Map(core.layers.map((layer) => [layer.id, layer]));
+  for (const layer of core.layers) {
+    if (layer.id === head.id) continue;
+    if (!layer.depends_on) {
+      throw new Error(
+        `core "${core.id}" declares pattern: hexagonal, but layer "${layer.id}" has no depends_on — only the domain layer ("${head.id}") may have none`,
+      );
+    }
+    const seen = new Set([layer.id]);
+    let current = layer;
+    while (current.depends_on) {
+      const next = byId.get(current.depends_on);
+      if (seen.has(next.id)) {
+        throw new Error(
+          `core "${core.id}" declares pattern: hexagonal, but layer "${layer.id}"'s depends_on chain cycles back through "${next.id}" instead of terminating at the domain layer "${head.id}"`,
+        );
+      }
+      seen.add(next.id);
+      current = next;
+    }
+    if (current.id !== head.id) {
+      throw new Error(
+        `core "${core.id}" declares pattern: hexagonal, but layer "${layer.id}"'s depends_on chain terminates at "${current.id}", not the domain layer "${head.id}" — every layer must point inward toward the domain`,
+      );
+    }
+  }
+}
+
+// Dispatches on `core.pattern` to the check above matching what was
+// declared. `null` (never set) and `'none'` (set, explicitly no enforced
+// direction — the adopted-repo default) both skip checking entirely: an
+// absent pattern must validate exactly as it did before this field
+// existed, and `none` recording "no direction" is a fact, not a finding.
+function checkPatternConformance(core) {
+  if (!core.pattern || core.pattern === 'none') return;
+  if (core.pattern === 'vertical-slice') {
+    if (!isModuleAxis(core)) {
+      throw new Error(
+        `core "${core.id}" declares pattern: vertical-slice, but no layer's scope contains {module} — vertical-slice is a chain instantiated per module, so at least one layer must vary by module`,
+      );
+    }
+    return;
+  }
+  if (core.pattern === 'layered') {
+    checkLayeredPattern(core);
+    return;
+  }
+  if (core.pattern === 'hexagonal') {
+    checkHexagonalPattern(core);
+  }
+}
+
 // Enforces the interview's rule (spec: "Authored cores") — a layer without
 // scope or without a verify command is rejected. Applied uniformly to
 // shipped and authored cores alike; the loader has no shipped-core-only
@@ -575,6 +723,13 @@ export function validateCore(core) {
     }
   }
 
+  // An architecture claim, checked mechanically — an unchecked `pattern`
+  // is a comment, and a comment that can silently disagree with the graph
+  // is worse than no field at all. Depends on depends_on already being
+  // resolved to real layer ids (the loop just above), which every check
+  // below relies on.
+  checkPatternConformance(core);
+
   // A `once: true` layer compiles a single task for the whole build, so
   // there is no module to substitute into its templates. Left unchecked,
   // a stray {module} would survive verbatim into scope_globs — a glob

package/src/db/status.mjs

@@ -55,6 +55,27 @@ function loadInFlightTasks(db) {
   return db.prepare(IN_FLIGHT_TASKS_SQL).all();
 }
 
+// The in-flight list on its own, without the rest of graphStatus. The
+// full report costs a drift comparison against core.yaml, a readiness
+// simulation, an override scan, and two side-channel reads — everything
+// `hedgehog status` prints. `hedgehog-daily` asks only "is a build in
+// flight" and asks it before every change request, so it must not pay
+// for a report it discards. Same query and same reaping contract as the
+// full path; only the other sections are skipped.
+export function inFlightTasks(db) {
+  return loadInFlightTasks(db);
+}
+
+// One line for `hedgehog status --brief`: what is in flight, or that
+// nothing is. Deliberately not a subset of formatStatus's sections — a
+// caller reading this wants a verdict, and the full report stays the
+// right thing to read once the verdict is "something is".
+export function formatBrief(inFlight) {
+  if (inFlight.length === 0) return 'IN FLIGHT  0  — nothing building or verifying';
+  const ids = inFlight.map((task) => task.id).join(', ');
+  return `IN FLIGHT  ${inFlight.length}  — ${ids}`;
+}
+
 function countTasksByStatus(db) {
   const rows = db
     .prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status')

package/src/hosts/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hedgehog",
-  "version": "6.1.1",
+  "version": "6.1.3",
   "description": "Hedgehog build discipline: ordered, tested, verified build steps.",
   "contextFileName": "GEMINI.md"
 }

package/src/skills/filing-issues/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: filing-issues
+description: Use when filing one or more GitHub issues for planned work — "file an issue for this", "turn this plan into issues", "open a tracking issue". Covers filing everything on skyf0xx/hedgehog regardless of which repo's code changes, whether to split a plan into a tracking issue plus sub-issues, which account files the issue, labels, and acceptance criteria. For how to word an issue, see the pr-writing skill.
+---
+
+# Filing issues
+
+The mechanics of getting planned work into GitHub. `pr-writing` owns how
+an issue is worded — title shape, the Why/What structure, `<details>`
+folding, and style. This skill owns everything before and around that.
+
+## Which repo
+
+Every issue is filed on `skyf0xx/hedgehog`, never on a core's own repo
+(e.g. the one shipping `full-stack-app` or `pwa-app`) — one issue queue
+to track and review, regardless of which repo's code changes.
+
+When the fix actually lands in a core repo, open the issue body with a
+line naming that repo and linking it, so a contributor knows where the
+PR belongs even though the issue itself doesn't live there.
+
+## One issue or several
+
+Split when the parts have different reviewers, different repos, different
+risk, or can be worked in parallel. Keep one issue when the work is a
+single reviewable change, even a large one.
+
+A split gets a tracking issue plus sub-issues:
+
+- The tracking issue carries the Why, the scope boundary, and a numbered
+  list of sub-issues with a one-line description of each.
+- Each sub-issue is self-contained — someone picking it up should not
+  have to read the tracker to know what to do.
+- State the dependency edges explicitly, including their absence:
+  which can be picked up now, which blocks which, and which merely
+  prefer an order without blocking.
+- File the tracker first so sub-issues can reference its number, then
+  patch the tracker with the real numbers once they exist.
+- Comment `Part of #<tracker>` on each sub-issue.
+
+## Which account files it
+
+Issues go out as the user's own `gh` session by default.
+
+Some projects have a bot identity for maintainer actions. Use it only
+when the user asks for it by name. A bot voice tuned for short notes
+does not apply to a planned-work issue — write the issue at full length
+and say that is what you are doing.
+
+## Labels
+
+Read the target repo's labels before filing (`gh label list --repo
+<owner/repo>`) — the engine repo and the core repos carry overlapping but
+not identical sets.
+
+Apply what is verifiable at filing time: a type label (`feature`, `bug`,
+`documentation`) and any `risk:` label the change clearly earns.
+`good-first-issue` fits an issue that is genuinely self-contained with an
+obvious done state. Leave `size:` labels alone — they describe a diff
+that does not exist yet.
+
+## Acceptance criteria
+
+End every issue with a checkbox list a contributor ticks off and a
+reviewer checks against. Each line is one observable outcome, not a
+restatement of the task list.
+
+- Testable by inspection or a command, not by judgment. "`pnpm nx test
+  mobile -- src/{module}/` passes on generated output" — not "the
+  generator works well."
+- Include the things that must *not* change: the existing behavior that
+  still has to pass, the version that must not be bumped.
+- Cover the whole change. A criterion nobody can check is noise; a
+  missing one is a gap a reviewer has to find themselves.
+
+On a tracking issue, the criteria are the sub-issues plus the end-to-end
+outcome that proves the whole set landed.
+
+## Before filing
+
+Verify every claim the issue makes about existing behavior, and cite it
+`file:line`. An issue is public and durable — a wrong claim in one sends
+a contributor down a path that does not exist.
+
+Confirm the split and the identity with the user before creating
+anything — the repo is fixed, not a decision to make each time. Issue
+creation is public and hard to reverse.

package/src/skills/hedgehog-daily/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: hedgehog-daily
+description: Use when a change request lands on a project that already has `.hedgehog/` and no build in flight — a finished build being adjusted, or an adopted repo's next piece of work. Triggers on any "change this", "fix this", "add this" on such a project. Sizes the request against the installed core's own layers and routes it to one of three exits: a tweak made and committed here, change-work through `hedgehog intent add` and the core's loop, or a re-plan. Not for a build still in progress — that is the core's loop skill's own job.
+---
+
+# Daily change-work
+
+One gate, three exits, for every change request on a project whose build
+graph already exists. It reads the installed core's layer sequence,
+scope globs and verify commands out of `.hedgehog/core.yaml`, so it is
+the same gate on every core.
+
+The gate exists to stop pricing a two-line edit at the cost of the
+largest change the discipline can handle. Routing up is a real decision
+with a real cost, taken on stated conditions — not the safe default.
+
+## Entry
+
+1. **`.hedgehog/` exists.** Without it there is no core to read and no
+   graph to add to; this skill does not apply.
+2. **Nothing is in flight.** `hedgehog status --brief` — one line. If it
+   names any task, a build is mid-flight: this gate does not run. Read
+   the full `hedgehog status` and hand the request back to the core's own
+   loop skill, which owns work in progress.
+3. **Read `.hedgehog/core.yaml`.** The layer list is the input to every
+   decision below: each layer's `id`, `scope` globs, `verify` command,
+   `verify_radius` and `exclusive`. Read the file, not a memory of it.
+
+## The three exits
+
+Decide by the conditions, in order. The first one that holds is the exit.
+
+### Re-plan
+
+The locked planning artifact that governs this project no longer
+describes what is being asked for. The core's own loop skill names which
+artifact governs — the brief and layer sequence for a shipped core,
+`.hedgehog/core-design.md` for an authored one, `.hedgehog/adoption.md`
+for an adopted one.
+
+Route to `planner`'s re-entry pass, which adds intents for new work
+without re-running planning from scratch and without disturbing anything
+already built.
+
+Where the artifact's failure means the request is a different project
+rather than an extension of this one, say so plainly instead of routing.
+That artifact is never rewritten to accommodate new scope.
+
+### Change-work
+
+Either condition puts the request here:
+
+- It reaches more than one of the core's layers.
+- It introduces a file, module, or capability that does not exist yet.
+
+`hedgehog intent add`, then the installed core's own loop, unchanged.
+Nothing about that path changes because this gate ran.
+
+### Tweak
+
+Both conditions hold:
+
+- Every file it touches is inside one layer's `scope` globs — one
+  layer, not two.
+- Every file it touches already exists.
+
+Then, in this session, with no subagent dispatched:
+
+1. Read the code it touches. Not a summary of it.
+2. Make the smallest correct edit.
+3. Run that layer's own `verify` command from `core.yaml`, at the depth
+   the next section states.
+4. Commit as one conventional commit, in the format the
+   `conventional-commits` skill states.
+
+No `hedgehog intent add`, no `hedgehog plan`, no `hedgehog claim`, no
+subagent. Nothing is written to the build graph.
+
+### Tweak is the default under ambiguity
+
+When the conditions do not clearly place a request above the tweak line,
+it takes the tweak exit. A gate that escalates when unsure prices every
+change at its worst case, which is the failure this gate exists to
+avoid.
+
+An escalation the tweak reveals is cheap: a tweak that turns out to
+touch a second layer or need a file that does not exist stops there and
+re-enters this gate at the change-work exit, having cost one read.
+
+## Test and review depth on the tweak exit
+
+A tweak inherits the test and review bar of the layer it lands in.
+
+- A layer whose `verify_radius` equals its `scope`: run the layer's
+  `verify` command. No new tests, no `reviewer` pass.
+- A layer with a wider `verify_radius`, or `exclusive: true`: the same
+  real test bar and `reviewer` pass that layer gets in the loop.
+
+That is the loop's own rule — "Test depth follows verify radius. Review
+follows exclusivity", stated in full in the core's loop skill — applied
+to a layer instead of a compiled task. `verify_radius` and `exclusive`
+are declared on the layer in `core.yaml`, so both are readable on a path
+that compiles no task.
+
+**A tweak landing in a wide-radius or exclusive layer is a signal.**
+Integration layers are where behavior gets proven, so a change reaching
+one is rarely as small as it looked when it was asked for. Re-check that
+the tweak exit was the right exit. Do not bolt the loop's ceremony onto
+the tweak path instead.
+
+**The floor does not move.** A tweak to code with no tests does not get
+to leave it that way where the layer's own bar says otherwise.
+
+## Hard rules
+
+- Never take the tweak exit on a file that does not exist yet. A new
+  file is change-work by condition, whatever its size.
+- Never widen a layer's `scope` to make a change fit the tweak exit.
+  A change that needs a wider scope is change-work.
+- Never commit a tweak whose layer `verify` command fails. A failing
+  gate means the change is not done.
+- Never batch two unrelated tweaks into one commit.
+- Never rewrite the locked planning artifact to accommodate new scope —
+  that is the re-plan exit's decision, and its answer may be that this
+  is a different project.

package/src/skills/pr-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-writing
-description: Use whenever writing a PR title/description, a commit message body, a code review comment, or an issue — in Hedgehog's own repo or any consuming project. Triggers on "open a PR", "write the PR description", "comment on this PR", "file an issue". Covers writing style (terse, info-dense, Simplified Technical English) and the pre-open checklist (CI status, scope, verified claims only).
+description: Use whenever writing a PR title/description, a commit message body, a code review comment, or an issue — in Hedgehog's own repo or any consuming project. Triggers on "open a PR", "write the PR description", "comment on this PR", "file an issue". Covers writing style (terse, info-dense, Simplified Technical English), the Why/What shape, folding deep reasoning under `<details>`, and the pre-open checklist (CI status, scope, verified claims only).
 ---
 
 # PR Writing
@@ -47,13 +47,52 @@ as a record of the work session.
 
 ## Shape
 
-- **Title**: `<type>(<scope>): <summary>`, imperative mood, under ~70
+- **PR title**: `<type>(<scope>): <summary>`, imperative mood, under ~70
   chars.
-- **Description**: 1-3 bullets — what changed, why. A test plan section
+- **PR description**: 1-3 bullets — what changed, why. A test plan section
   listing what you actually ran, not what should theoretically pass.
+- **Issue title**: plain English a non-technical reader would say out
+  loud, not a commit-style `<type>(<scope>): <summary>`. Name the
+  outcome, not the mechanism — "Improve how Hedgehog tracks and enforces
+  a project's architecture", not "feat(core): add pattern field".
 - **Comments**: lead with the concrete finding, then (if needed) the fix
   requested. No preamble.
 
+## Why/What for issues
+
+An issue proposing a change — a feature, a fix worth explaining, a
+`ROADMAP.md` item being picked up — states **Why** before **What**:
+
+- **Why**: the problem, as a short list of plain-language facts. Each
+  bullet is one observation a reader can verify or disagree with, not a
+  justification wrapped in caveats. State the problem first, then (if
+  the fix isn't obvious from the problem) a short "to fix this" list of
+  intended outcomes.
+- **What**: the change itself — the concrete steps, fields, or sub-issues.
+  Numbered if sequenced, bulleted if not.
+
+Skip the Why section only when the title already states the problem in
+full (a one-line bug report needs no restatement). Never skip What.
+
+## Fold deep reasoning under `<details>`
+
+An issue or PR body written for a human reader stays short. Extended
+reasoning — architecture rationale, alternatives considered, prior
+decisions, anything aimed at an AI agent picking up the work or a reader
+who wants the full trail — goes under a collapsed section, not inline:
+
+```markdown
+<details>
+<summary>Full reasoning (for AI agents and anyone who wants the detail)</summary>
+
+...
+</details>
+```
+
+Ask first whether that detail needs to exist in the issue at all — a
+link to an existing doc or prior discussion is often enough. Only fold
+in content that has no better home.
+
 ## When NOT to apply
 
 - Internal scratch notes, planning docs, or anything not read by another