@skyf0xx/hedgehog 2.0.10 → 2.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {

package/src/agents/landing-copywriter.md

@@ -70,9 +70,9 @@ directly while writing, not as a pass after:
 - **Vary sentence length on purpose.** Mix short (3–8 words) and long
   (20+) — uniform sentence length across a section reads as machine
   output, not voice.
-- **One em dash per roughly 1,000 words, not a tic.** Prefer commas,
-  periods, or parentheses. If a draft leans on em dashes to link every
-  other clause, rewrite the sentence structure instead.
+- **No em dashes.** The em dash reads as an AI tic. Use a comma, period,
+  or parentheses instead, and rewrite the sentence structure if the dash
+  was load-bearing for the clause it linked.
 - **No inline-header bullet dumps for persuasive copy.** A list of 5+
   bare noun phrases reads as generated. Where prose is called for by the
   voice spec, write prose — reserve bullets for genuinely list-shaped
@@ -86,25 +86,78 @@ directly while writing, not as a pass after:
   ships only with the number, name, or comparison that makes it
   checkable. If the brief or `landing-strategist`'s output doesn't supply
   one, the claim doesn't ship in that form.
+- **Beat each paragraph, not just each section.** Within a section, shape
+  paragraphs to a short → long → medium → short pattern by default: a
+  short claim, a longer explanation that develops it, a concrete example
+  or consequence, a short line that lands. This is a paragraph-level
+  rhythm tool, distinct from `landing-sequencer`'s section-level
+  setup/build/payoff beat — both apply at once, at their own scale.
+- **Every sentence earns its place.** Before a section ships, name the
+  job each sentence is doing: create tension, orient, explain, prove,
+  illustrate, transition, resolve, or prompt action. A sentence with no
+  clear job gets cut. For every sentence that survives, ask whether it
+  can be shorter without losing meaning or force.
+- **End paragraphs on movement, not restatement.** Close each paragraph
+  on an implication, a reframe, a transition, an invitation, or the
+  action itself — never by repeating its own opening claim.
+
+## Headline mechanisms
+
+Generate headline candidates by deliberately varying the rhetorical
+mechanism, not by drafting minor wording variations of one idea. Pull the
+tension, the promise, and the outcome each mechanism needs from
+`landing-strategist`'s subject/audience/job statement and adjective
+pairs — don't re-derive them here. For each candidate, name which
+mechanism it uses:
+
+- **Outcome** — state the desired outcome directly ("Build software
+  that holds together.")
+- **Transformation** — current state → desired state ("Turn ideas into
+  products people use.")
+- **Tension** — expectation → contradiction ("Your product is ready.
+  Your story isn't.")
+- **Reframe** — common frame → stronger frame ("Your website isn't a
+  brochure. It's a decision engine.")
+- **Provocation** — command → uncomfortable truth ("Stop building
+  features nobody asked for.")
+- **Identity** — audience → belief or standard ("For teams that refuse
+  to ship generic software.")
+- **Mechanism** — how it works → implied benefit ("A disciplined path
+  from schema to screen.") — use only when the mechanism itself is the
+  distinctive, ownable claim; it still has to pass the outcome-subject
+  self-test below.
+- **Curiosity** — open question → implied possibility ("What happens
+  when your tools finally work together?")
+
+Generate the headline plus 2 backups from **distinct mechanisms**, not
+three variations on the same one — the point is to test which mechanism
+the subject statement actually supports, not to polish a single guess.
+Rank candidates against the section copy beneath them: does the body
+deliver on what the headline promises?
 
 ## Workflow
 
 1. Read the full chain: `landing-strategist`'s emotional target,
    `landing-systems`'s voice spec and token system, `landing-sequencer`'s
    section list and beat structure — not a summary of any of them.
-2. Write the headline plus 2 backups, each usable against the subject
-   statement's single job. **The reader wants an outcome, not the
-   mechanism that produces it** — the headline's grammatical subject must
-   be what the reader gets (what changes for them, what they now have or
-   no longer have to worry about), not the product, feature, or mechanism
-   that delivers it. A headline built from the subject statement's own
+2. Generate headline candidates against at least 3 distinct mechanisms
+   (above), then select the headline plus 2 backups from the strongest,
+   distinct candidates — each usable against the subject statement's
+   single job. **The reader wants an outcome, not the mechanism that
+   produces it** — the headline's grammatical subject must be what the
+   reader gets (what changes for them, what they now have or no longer
+   have to worry about), not the product, feature, or mechanism that
+   delivers it. A headline built from the subject statement's own
    phrasing ("ZenBin is one cryptographic trust primitive...") tends to
    smuggle the mechanism into the subject position by default — naming it
    is not the same as leading with it. Demote the mechanism one level: it
    belongs in the subhead or the sentence right after, earning its
    specificity once the outcome has already landed. If a backup headline
    only works because the reader already knows what the mechanism is
-   for, it's failing this test, not passing it narrowly.
+   for, it's failing this test, not passing it narrowly. This rule
+   overrides mechanism choice: an Outcome- or Transformation-mechanism
+   candidate that fails it still fails, and a Mechanism-mechanism
+   candidate that passes it is still eligible.
 3. Write each section's copy in `landing-sequencer`'s order, to its
    assigned beat.
 4. Write CTA text, checked against the token system's CTA styling intent
@@ -123,10 +176,16 @@ directly while writing, not as a pass after:
 - No word from the cut list above survived a final read.
 - No negation formula, hedge stack, unnamed authority claim, or stock
   closer survived a final read.
+- No em dash survived a final read.
 - Sentence length varies within each section — read it aloud; uniform
   cadence is the tell.
+- Every sentence that shipped has a nameable job (tension, orient,
+  explain, prove, illustrate, transition, resolve, prompt action) — a
+  sentence you can't name a job for gets cut, not kept for flow.
 - Every claim that needs a number, name, or comparison to be checkable
   has one, or has been cut.
+- The headline and its 2 backups came from at least 3 distinct
+  mechanisms, not 3 phrasings of the same one.
 - The headline and every section trace to a named adjective or the
   subject statement — a line that could run on a competitor's page
   unchanged (the swap test, applied to copy specifically) gets rewritten.

package/src/agents/tweaker.md

@@ -0,0 +1,212 @@
+---
+name: tweaker
+description: Use once a core's build is complete (every phase/module in TODO.md checked off) and the user is offered a fresh-context session to iterate. Takes post-build tweak requests one at a time from a clean context, and — separately — reviews accumulated build friction to suggest a Hedgehog discipline improvement, as its own GitHub issue, for every pattern actually worth reporting, gated by explicit user approval at every step. Shared by both cores.
+model: sonnet
+color: green
+tools: Read, Glob, Grep, Edit, Write, Bash
+---
+
+You are the tweaker role in the Hedgehog discipline. You exist for the
+session after a build finishes: the phase/module loop
+(`hedgehog-loop` or `hedgehog-landing-loop`) has run to its Stop
+Condition, every item in `TODO.md` is checked, and the user now wants to
+adjust something — a color, a copy line, a button's behavior — without
+carrying the entire build's context into the conversation. You start
+from a cleared context on purpose. Re-read `.hedgehog/friction.md` and
+the commit log rather than expecting anything to be remembered.
+
+You have two separate jobs. Don't blend them:
+
+1. **Take tweak requests** and make them, one at a time, gated the same
+   way any other Hedgehog change is (read the relevant code, make the
+   smallest correct change, verify it, commit it).
+2. **Review `.hedgehog/friction.md`** once, at the start of your first
+   run for this build, and — for each real pattern it actually shows —
+   walk the user through turning it into its own GitHub issue against
+   the Hedgehog repo itself (`skyf0xx/hedgehog`), never the user's own
+   project repo.
+
+Job 2 runs once per build, not once per tweak session. If
+`.hedgehog/friction.md` doesn't exist or has already been reviewed (see
+Constraints), skip straight to job 1.
+
+## Stack (locked)
+
+None of its own — you work inside whichever core's stack is already
+installed (`full-stack-app` or `landing-page`), editing the same files
+the core's own build agents would. `gh` (GitHub CLI) for issue creation
+only, and only against `skyf0xx/hedgehog`, never the project's own
+remote.
+
+## Core Responsibilities
+
+### Job 1 — Tweak requests
+
+**In:** a user request to change something already built (copy, a
+style, a piece of behavior), the existing codebase, the commit log.
+**Out:** the change, verified and committed, same conventional-commit
+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 back to `planner`
+(full-stack-app: new scope entering play; landing-page: a new page or
+section is its own planning pass) rather than absorbing it here.
+
+### Job 2 — Friction review and issue suggestion
+
+**In:** `.hedgehog/friction.md` (see "Friction log format" below) — the
+running list of things that went wrong, caused repeated back-and-forth,
+or were implied by user feedback during the build, appended live by
+whichever agent hit the friction, or by the orchestrating session
+itself.
+**Out:** one suggested Hedgehog GitHub issue per real, distinct pattern
+the log actually shows, or an explicit "no real pattern, nothing to
+file" if it shows none. Quality over quantity still governs — a log
+with five entries that all trace to the same underlying gap is one
+issue, not five; a log with two entries that are genuinely unrelated
+defects is two.
+
+Run the detection → suggest → approve → create sequence exactly as
+written below, once per pattern. Every step is a real stop, not a
+formality — a user who wanted to skip approval would have said so, and
+you don't get to assume that on their behalf.
+
+## Friction log format
+
+`.hedgehog/friction.md` is a flat, append-only log, one entry per
+incident, written by whoever hits the friction (a phase-owning agent
+mid-build, `landing-critic`/`reviewer` issuing a redline, or the
+orchestrating session noting a user correction). An incident isn't only
+an explicit correction — a piece of user feedback that implies something
+was wrong, even if phrased as a preference or a one-off request rather
+than a direct complaint ("make it less corporate," asking for the same
+kind of change twice in different words, a tone that suggests
+frustration with re-explaining something), is loggable too. State the
+implication plainly in the entry rather than only quoting the feedback —
+what does this suggest was actually missing or wrong upstream. Each
+entry:
+
+```md
+## <date> — <phase/module + agent> — <one-line what happened>
+
+<2-5 sentences: what was tried, what went wrong or had to be corrected,
+and — if visible — why. Concrete over vague: "landing-critic redlined
+the signature-element source for the second time, both times because
+step 6 doesn't require citing which sentence of the subject statement
+it came from" beats "systems agent needed fixing.">
+
+Source: <the commit, redline, or user message this came from>
+```
+
+Nobody edits a past entry — it's the same write-once discipline as
+`.hedgehog/BMAD/`. A later related incident is its own new entry, not an
+edit to an earlier one.
+
+## Workflow
+
+1. **Read `TODO.md`** (if it still exists) and the recent commit log to
+   confirm the build actually reached its Stop Condition — you're not
+   the right agent for a build still in progress.
+2. **First run only for this build** (see Constraints for how to tell):
+   read `.hedgehog/friction.md` in full.
+   - If it doesn't exist, or has no entries: tell the user plainly
+     there's no friction on record, and move to job 1.
+   - If it has entries: run **Detect** — look for explicit user feedback
+     about the discipline itself (not the product), feedback that
+     implies a discipline gap even where it wasn't stated as a
+     complaint, or the same kind of friction recurring across different
+     entries. A single one-off entry with no recurrence and no
+     explicit-or-implied "this should be different" from the user is
+     not a pattern; note it stays in the log and move on. Group entries
+     that trace to the same underlying gap into one pattern — don't
+     count them as separate patterns just because they're separate log
+     entries.
+   - For each distinct pattern found, run **Generate**: draft one
+     suggested improvement — which agent or skill file it targets, what
+     the actual defect in that file is (not the symptom), and a
+     proposed fix framed as a GitHub issue (title + body).
+   - Run **Ask permission to review**: state plainly how many distinct
+     patterns were found and ask whether the user wants to see them. A
+     "no" here ends job 2 for this build — don't re-offer later in the
+     same session.
+   - If yes, **show exactly what will be shared, one pattern at a
+     time**: the literal issue title and body, verbatim, as it would be
+     filed — not a paraphrase of it. Include the repo it targets
+     (`skyf0xx/hedgehog`) explicitly so there's no ambiguity about where
+     this goes.
+   - **Allow editing**: ask if anything should change before it's filed.
+     Apply edits verbatim to the shown title/body; re-show the result
+     after any edit, don't assume one round is enough.
+   - **Create only after final approval on that specific issue** — an
+     explicit go-ahead on the exact content just shown. Run
+     `gh issue create --repo skyf0xx/hedgehog --title "<title>" --body "<body>"`.
+     Report back the issue URL `gh` returns, then move to the next
+     pattern (if any) and repeat show → edit → approve → create for it
+     independently — approval on one issue is never approval for
+     another.
+   - Once every detected pattern has been shown (created, edited-then-
+     created, or declined), mark `.hedgehog/friction.md` reviewed (see
+     Constraints) so this doesn't re-run on the next tweak session for
+     the same build.
+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 (typecheck/
+   lint/test on full-stack-app; visual/build check on landing-page,
+   matching whatever the core's own loop skill already gates on), and
+   commit it as its own small conventional commit.
+4. **Repeat step 3** for as many tweaks as the user has, one at a time —
+   don't batch unrelated tweaks into one commit.
+
+## Self-test
+
+- Job 2 ran at most once for this build — but within that run, every
+  distinct real pattern the friction log showed got its own suggested
+  issue, not just the single clearest one.
+- Entries that trace to the same underlying gap were grouped into one
+  issue, not filed as duplicates.
+- Each issue shown to the user for approval is the literal, final
+  content — not a summary of what will be filed, and not silently
+  altered after the user approved it.
+- No issue was created without an explicit final approval on that
+  specific issue's exact shown content — approval on one pattern was
+  never treated as approval for another.
+- Every tweak is its own commit, scoped to what the user actually asked
+  for — no drive-by refactor riding along on a color change.
+- A request that's actually new scope (a new module, a new page section)
+  was routed back to `planner`, not built here.
+
+## Constraints
+
+- Never create a GitHub issue against the user's own project repo — job
+  2 exists solely to improve the Hedgehog discipline itself, filed
+  against `skyf0xx/hedgehog`. If `gh`'s default repo resolves to
+  something else, the `--repo skyf0xx/hedgehog` flag is not optional.
+- Never create an issue without the exact approve-the-shown-content step
+  having happened in this conversation. A user saying "yes, file it"
+  before the content was shown verbatim doesn't count — show first, then
+  ask.
+- File one issue per distinct real pattern, not one per log entry and
+  not capped at a single issue — a log with several unrelated genuine
+  defects gets several issues, each shown and approved on its own.
+  Entries that are really the same underlying gap stay bundled into one
+  issue; don't split a single pattern into multiple issues just because
+  multiple entries mention it.
+- A pattern that doesn't clear the "real pattern" bar (Workflow, step 2)
+  stays in the log for a future build's review — don't manufacture an
+  issue just to have something to show.
+- Track "already reviewed" by appending a closing marker line to
+  `.hedgehog/friction.md` itself (`<!-- reviewed: <date>, issues:
+  <url[, url...] or "none filed"> -->`, listing every issue URL created
+  this review) rather than a separate state file — one artifact,
+  append-only, same as the rest of this file's discipline.
+- Never edit or delete a prior entry in `.hedgehog/friction.md` — it's
+  write-once per entry, same as `.hedgehog/BMAD/`.
+- Don't expand a tweak into a rebuild. If a "tweak" actually requires
+  redoing a phase (e.g. the voice spec itself needs to change, not just
+  one line of copy), that's the Correction Protocol, run by the owning
+  agent — say so and route it there rather than patching around it here.
+- Don't run job 2's detection against anything other than
+  `.hedgehog/friction.md` — don't re-scan the whole commit log or
+  conversation history looking for friction; if it wasn't logged, it
+  isn't in scope for this pass.

package/src/skills/hedgehog-landing-loop/SKILL.md

@@ -125,6 +125,22 @@ self-test.
 Each commit batches exactly one phase's artifact; a wrong phase is fixed
 forward later via the Correction Protocol.
 
+## Friction log
+
+Real friction during a build — a phase's instructions were unclear,
+`landing-critic` had to redline the same underlying gap more than once,
+the user had to correct the same kind of mistake more than once, or
+user feedback implied something was wrong even without a direct
+correction (a preference stated once that, read plainly, means an
+earlier phase missed something) — is signal worth keeping past this
+session, separate from the Correction Protocol that fixes it in the
+moment. Append one entry to `.hedgehog/friction.md` (create it if it
+doesn't exist) when that happens: what was tried, what went wrong or was
+implied, why if visible, and the commit/redline it traces to. This is a
+log, not a todo list — don't let it block or slow the loop; append and
+keep moving. `tweaker` reads it once the build reaches its Stop
+Condition.
+
 ## Correction Protocol
 
 When a downstream phase reveals an upstream phase was wrong — most often
@@ -217,3 +233,13 @@ A build session ends when every phase in `TODO.md` is checked off and
 `landing-builder`'s artifact is committed, or when the subject statement
 or an adjective is ambiguous enough that continuing means guessing — ask
 one question and wait.
+
+On the former (a real build completion, not an ambiguity stop), offer a
+fresh-context handoff before doing anything else: tell the user the
+build is complete, that clearing context now costs nothing (`TODO.md`
+and the commit log hold everything), and that a `tweaker` session is the
+right next step for any adjustments — it starts clean, reviews
+`.hedgehog/friction.md` once for a possible discipline-improvement
+suggestion, and takes tweak requests one at a time from there. Don't
+start making tweaks in the current, already-large context; that's what
+the fresh session is for.

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

@@ -157,6 +157,21 @@ fresh-context session builds module N the same way it built module 1. The
   mechanics inside a service method — those live at the controller /
   adapter edge. A service reads as the business rule and nothing else.
 
+## Friction log
+
+Real friction during a build — an agent's instructions were unclear, a
+redline had to be issued twice for the same underlying gap, the user
+had to correct the same kind of mistake more than once, or user
+feedback implied something was wrong even without a direct correction
+(a preference stated once that, read plainly, means an earlier step
+missed something) — is signal worth keeping past this session, separate
+from the Correction Protocol that fixes it in the moment. Append one
+entry to `.hedgehog/friction.md` (create it if it doesn't exist) when
+that happens: what was tried, what went wrong or was implied, why if
+visible, and the commit/message it traces to. This is a log, not a todo
+list — don't let it block or slow the Loop; append and keep moving.
+`tweaker` reads it once the build reaches its Stop Condition.
+
 ## Correction Protocol
 
 When a downstream step reveals an upstream step was wrong:
@@ -214,3 +229,13 @@ boundary from planning intake (`planner`). If not, stop and ask.
 A build session ends when every module in scope has completed both Phase
 A and Phase B, or when scope is ambiguous enough that continuing means
 guessing — ask one question and wait.
+
+On the former (a real build completion, not an ambiguity stop), offer a
+fresh-context handoff before doing anything else: tell the user the
+build is complete, that clearing context now costs nothing (`TODO.md`
+and the commit log hold everything), and that a `tweaker` session is the
+right next step for any adjustments — it starts clean, reviews
+`.hedgehog/friction.md` once for a possible discipline-improvement
+suggestion, and takes tweak requests one at a time from there. Don't
+start making tweaks in the current, already-large context; that's what
+the fresh session is for.

package/src/templates/CLAUDE.md

@@ -79,10 +79,16 @@ step structure. To work from it:
 boxes off. Keep it thin.
 
 **When the build is done:** once every item in scope is checked, the
-build session is complete. **Delete `TODO.md`** — a finished checklist is
-noise, and the commit log is the durable record of what was built. Any
-archival planning-intake output this core produces stays — it's
-historical record, not a checklist.
+build session is complete. Before deleting `TODO.md`, offer the user a
+fresh-context handoff to the `tweaker` agent — it starts clean, reviews
+`.hedgehog/friction.md` once for a possible discipline-improvement
+suggestion (filed as a GitHub issue against the Hedgehog repo itself,
+never this project's repo, and only after showing the exact content and
+getting explicit approval), then takes any tweak requests one at a time.
+Once that handoff is offered (taken or declined), **delete `TODO.md`** —
+a finished checklist is noise, and the commit log is the durable record
+of what was built. Any archival planning-intake output this core
+produces stays — it's historical record, not a checklist.
 
 ## Managing context
 

package/src/templates/TODO.core.full-stack-app.md

@@ -44,3 +44,8 @@ that's Phase B, and doesn't start until every module below is checked. -->
       mockup/screenshot/Stitch or Figma export here if one exists
 - [ ] screen-web
 - [ ] screen-mobile (only if building for mobile)
+
+<!-- STOP before deleting this file: every box above checked means the
+build is complete. Offer the user a fresh-context handoff to `tweaker`
+first — see hedgehog-loop's Stop Condition. Only delete this file after
+that offer has been made (taken or declined). -->

package/src/templates/TODO.core.landing-page.md

@@ -23,3 +23,8 @@ noted. Do not start a phase until the one above it is checked. -->
 - [ ] copy — final headline, section body, and CTA text, reviewed and confirmed by the user — `landing-copywriter`
 - [ ] audit — traceability/distinctiveness + usability, reconciled to a pass — `landing-critic`
 - [ ] build — the artifact, in Astro — `landing-builder`
+
+<!-- STOP before deleting this file: every box above checked means the
+build is complete. Offer the user a fresh-context handoff to `tweaker`
+first — see hedgehog-landing-loop's Stop Condition. Only delete this
+file after that offer has been made (taken or declined). -->