feat: add DIFFERENTIATORS section + require business goals in PURPOSE (#14)

Two complementary changes, both driven by real-use feedback:

## 1. PURPOSE must include business goals (v0.1.14 Deliverable 1 update)

Previous PURPOSE spec: "product one-liner + essential philosophy".
A gh repo description (1-sentence marketing tagline) passed the
"substantive" test and was preserved — which meant users got terse
PURPOSE that doesn't tell an agent WHY the project exists or what
success looks like.

New spec requires all three:
  1. WHAT the project is (product pitch)
  2. WHY it exists — business goal / success criterion
  3. Essential philosophy or hard constraint

Marketing-tagline PURPOSE now classifies as placeholder and gets
regenerated by `revive suggest`. The placeholder-marker list
explicitly flags "marketing-style 1-liner that doesn't spell out why
it exists / what success looks like" as a placeholder indicator.

## 2. New STATIC section: DIFFERENTIATORS

Competitive positioning and deliberate design choices that contradict
what an "obvious" project in the space would do. This class of signal
prevents an agent from suggesting "why not just use X?" for an X you
already evaluated and rejected.

Format: "<alternative> → <our choice/rationale>" or "unlike X, we Y
because Z".

Brief layout: PURPOSE → DIFFERENTIATORS → INVARIANTS → GOTCHAS.

Full integration:
- `revive init` scaffolds DIFFERENTIATORS placeholder alongside the
  existing sections.
- `revive show` suppresses placeholder DIFFERENTIATORS bullets the
  same way it already suppresses placeholder INVARIANTS/GOTCHAS.
- `revive init --force` preserves user-edited DIFFERENTIATORS
  alongside INVARIANTS/GOTCHAS when regenerating PURPOSE.
- `revive suggest` prompt: new Deliverable 2 (DIFFERENTIATORS);
  INVARIANTS → 3, GOTCHAS → 4. Placeholder markers list updated.
  Output-format example and STEP 2 ordering include the new section.

Agent is explicitly told: "If you genuinely don't see meaningful
differentiation signals in the artefacts (ADRs comparing approaches,
README 'vs' sections, rejected-alternatives notes), leave this
section with its placeholder — better empty than filler."

## Tests (+7, 100 total)

- PURPOSE deliverable requires business goals
- init scaffolds DIFFERENTIATORS + correct section ordering
- show skips placeholder DIFFERENTIATORS bullets
- show keeps substantive DIFFERENTIATORS bullets
- init --force preserves substantive DIFFERENTIATORS across PURPOSE regen
- suggest prompt introduces DIFFERENTIATORS as Deliverable 2
- suggest prompt lists DIFFERENTIATORS placeholder marker

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: justi

bin/revive

@@ -3,7 +3,7 @@
 # https://github.com/justi/context-revive
 set -euo pipefail
 
-VERSION="0.1.13"
+VERSION="0.1.14"
 STATIC_FILE=".revive/static.md"
 COMMANDS_FILE=".revive/commands.md"
 BRIEF_CHAR_BUDGET=2200
@@ -20,12 +20,14 @@ usage() {
 Usage: revive <command> [options]
 
 Commands:
-  init              Generate .revive/static.md (PURPOSE, INVARIANTS, GOTCHAS).
-                    Use `init --force` to regenerate PURPOSE from the chain
-                    while preserving user-edited INVARIANTS and GOTCHAS.
+  init              Generate .revive/static.md (PURPOSE, DIFFERENTIATORS,
+                    INVARIANTS, GOTCHAS). Use `init --force` to regenerate
+                    PURPOSE from the chain while preserving user-edited
+                    DIFFERENTIATORS, INVARIANTS, and GOTCHAS.
   suggest           Print an LLM-ready prompt that, when pasted into any
-                    coding agent, generates PURPOSE + INVARIANTS + GOTCHAS
-                    for this project. Tailored to the actual files in the repo.
+                    coding agent, generates PURPOSE + DIFFERENTIATORS +
+                    INVARIANTS + GOTCHAS for this project. Tailored to the
+                    actual files in the repo.
   show              Print the brief that would be injected (force-emit)
   refresh           Hook entry point — cadence-gated, silent on failure
   install-hook      Wire UserPromptSubmit into .claude/settings.json
@@ -341,7 +343,7 @@ EOF
       }
       NR_buf = 0
     }
-    /^(PURPOSE|INVARIANTS|GOTCHAS):/ { flush(); buf[++NR_buf] = $0; next }
+    /^(PURPOSE|DIFFERENTIATORS|INVARIANTS|GOTCHAS):/ { flush(); buf[++NR_buf] = $0; next }
     { buf[++NR_buf] = $0 }
     END { flush() }
   ' "$STATIC_FILE"
@@ -620,40 +622,51 @@ cmd_init() {
     exit 1
   fi
 
-  # Preserve user-edited INVARIANTS and GOTCHAS across a --force regenerate;
-  # only PURPOSE is replaced. This is the common flow after upgrading
-  # revive — the chain got smarter, user rules haven't changed.
+  # Preserve user-edited DIFFERENTIATORS / INVARIANTS / GOTCHAS across a
+  # --force regenerate; only PURPOSE is replaced. This is the common flow
+  # after upgrading revive — the chain got smarter, user rules haven't
+  # changed.
+  local differentiators="  - (what sets this project apart; edit this file)"
   local invariants="  - (top-5 architectural rules; edit this file)"
   local gotchas="  - (landmines you keep stepping on; edit this file)"
   if (( force )) && [[ -f "$STATIC_FILE" ]]; then
     local preserved
     preserved=$(awk '
-      /^INVARIANTS:/ { cap="inv"; next }
-      /^GOTCHAS:/    { cap="got"; next }
-      /^[A-Z][A-Z_]*:/ { cap="" }
-      cap == "inv" { inv = inv $0 "\n" }
-      cap == "got" { got = got $0 "\n" }
-      END { printf "INV_START\n%sINV_END\nGOT_START\n%sGOT_END\n", inv, got }
+      /^DIFFERENTIATORS:/ { cap="diff"; next }
+      /^INVARIANTS:/      { cap="inv"; next }
+      /^GOTCHAS:/         { cap="got"; next }
+      /^[A-Z][A-Z_]*:/    { cap="" }
+      cap == "diff" { diff = diff $0 "\n" }
+      cap == "inv"  { inv = inv $0 "\n" }
+      cap == "got"  { got = got $0 "\n" }
+      END {
+        printf "DIFF_START\n%sDIFF_END\nINV_START\n%sINV_END\nGOT_START\n%sGOT_END\n",
+               diff, inv, got
+      }
     ' "$STATIC_FILE")
-    local saved_inv saved_got
+    local saved_diff saved_inv saved_got
+    saved_diff=$(awk '/^DIFF_START$/{p=1;next} /^DIFF_END$/{p=0} p' <<<"$preserved" | sed '/^$/d')
     saved_inv=$(awk '/^INV_START$/{p=1;next} /^INV_END$/{p=0} p' <<<"$preserved" | sed '/^$/d')
     saved_got=$(awk '/^GOT_START$/{p=1;next} /^GOT_END$/{p=0} p' <<<"$preserved" | sed '/^$/d')
-    [[ -n "$saved_inv" ]] && invariants="$saved_inv"
-    [[ -n "$saved_got" ]] && gotchas="$saved_got"
+    [[ -n "$saved_diff" ]] && differentiators="$saved_diff"
+    [[ -n "$saved_inv" ]]  && invariants="$saved_inv"
+    [[ -n "$saved_got" ]]  && gotchas="$saved_got"
   fi
 
   mkdir -p "$(dirname "$STATIC_FILE")"
   local purpose
   purpose=$(compute_purpose)
   {
     printf 'PURPOSE: %s\n' "$purpose"
+    echo "DIFFERENTIATORS:"
+    printf '%s\n' "$differentiators"
     echo "INVARIANTS:"
     printf '%s\n' "$invariants"
     echo "GOTCHAS:"
     printf '%s\n' "$gotchas"
   } > "$STATIC_FILE"
   if (( force )); then
-    echo "regenerated: $STATIC_FILE (INVARIANTS/GOTCHAS preserved)"
+    echo "regenerated: $STATIC_FILE (DIFFERENTIATORS/INVARIANTS/GOTCHAS preserved)"
   else
     echo "created: $STATIC_FILE"
   fi
@@ -699,17 +712,24 @@ PROMPT_META
   cat <<'PROMPT_HEADER'
 Read the following artefacts in the current project, then fill any
 placeholder sections of .revive/static.md. Treat existing human-
-curated content as sacred: PURPOSE, INVARIANTS, and GOTCHAS that
-already contain real content must be preserved verbatim — do not
-rewrite substantive sections just because you can.
+curated content as sacred: PURPOSE, DIFFERENTIATORS, INVARIANTS,
+and GOTCHAS that already contain real content must be preserved
+verbatim — do not rewrite substantive sections just because you can.
 
 Regenerate ONLY sections that are still in their `revive init`
 placeholder state. Recognise a placeholder by these markers:
 
   - PURPOSE: literal `(describe this project in 1-3 sentences)`,
-    OR a single short fragment clearly extracted from a manifest/
-    README without context (a one-sentence pitch under ~80 chars
-    that doesn't frame the project).
+    OR a marketing-style 1-liner that states WHAT the project does
+    but doesn't spell out WHY it exists / what success looks like.
+    A gh repo description or README tagline typically falls in this
+    category — it's readable, but doesn't give an agent enough to
+    understand the business value or operating priorities.
+    Rule of thumb: if the current PURPOSE could fit on a single
+    marketing banner and a reader couldn't answer "what does success
+    for this project look like?" from it alone, treat as placeholder.
+  - DIFFERENTIATORS: bullets containing `(what sets this project
+    apart; edit this file)` or `(none defined)`.
   - INVARIANTS: bullets containing `(top-5 architectural rules;
     edit this file)` or `(none defined)`.
   - GOTCHAS: bullets containing `(landmines you keep stepping on;
@@ -752,30 +772,63 @@ Strict rules (violations are failures, not stylistic preferences):
      incident, OMIT it. Placeholder > false confidence.
 
 Deliverable 1 — PURPOSE (single line, ≤ 400 chars):
-  A tight 2-3 sentence summary that answers:
-    - what the project IS (product one-liner)
-    - its essential philosophy or hard constraint (what makes it different)
-  Include just enough context that someone reading only the brief could
-  pick up work without reading README/CLAUDE.md first.
+  A tight 2-3 sentence summary that answers ALL THREE of:
+    1. WHAT the project is (product one-liner)
+    2. WHY it exists — business goal or success criterion the project
+       is optimizing for (e.g. "cut X hours from weekly ops",
+       "unlock audience Y", "prevent incident class Z", "reclaim
+       DORMANT side projects")
+    3. Its essential philosophy or hard constraint (what makes it
+       different, the one thing every design decision must respect)
+
+  All three must be present. A gh-style 1-liner that covers only (1)
+  is NOT enough — it's a marketing tagline, not operating context.
 
   Bad examples:
-    - "A Flutter app."                    (useless, inferable)
-    - single terse fragment under 60 chars (too terse)
+    - "A Flutter app."                    (only 1, useless)
+    - "Never forget a side project."      (only 1, marketing tagline)
     - 800-char pasted README intro        (too long, buries signal)
 
   Good examples (generic):
     - "A CLI that turns Markdown invoices into tax-compliant PDFs.
-       Zero-config for sole traders in EU/UK; one-flag override for
-       custom templates."
-    - "Background-job scheduler for Go services. Unlike cron,
-       schedules are defined in code and survive deploys; job state
-       lives in the same Postgres the app already uses."
+       Saves sole traders ~3h/month of invoicing; success = zero
+       manual edits to the generated PDF. Zero-config by default;
+       customization only via explicit template flag."
+    - "Background-job scheduler for Go services. Goal: replace ops-
+       managed cron with code-defined schedules that survive
+       deploys; success = zero surprise job failures after a deploy.
+       Constraint: job state lives in the app's own Postgres — no
+       new infrastructure."
+
+Deliverable 2 — DIFFERENTIATORS (up to 5, or empty):
+  What makes this project different from the obvious alternatives.
+  Competitive positioning, deliberate design choices that contradict
+  what another project in the space would do. This class of signal
+  prevents an agent from suggesting "why not just use X?" for an X
+  you've already evaluated and rejected.
+
+  Each bullet: "<alternative> → <what we do instead>" or "unlike
+  <alternative>, we <choice> because <reason>".
 
-  If the CURRENT PURPOSE line in .revive/static.md is already a good
-  2-3 sentence summary (clearly readable, frames the project well),
-  keep it verbatim — don't rewrite for its own sake.
+  Bad examples:
+    - "We're open source."           (not differentiation)
+    - "Better than the rest."        (empty marketing)
+    - Anything an agent can discover by reading competitor READMEs.
 
-Deliverable 2 — INVARIANTS (up to 5):
+  Good examples:
+    - "Unlike cron — schedules defined in code, survive deploys; no
+       ops-managed crontab to drift from the repo."
+    - "repomix / code2prompt: one-shot dump → we inject small briefs
+       on cadence, no token flood."
+    - "Cursor Rules: static prepend → we regenerate DYNAMIC sections
+       per refresh from git + fs; recent work stays visible."
+
+  If you genuinely don't see meaningful differentiation signals in
+  the artefacts (ADRs comparing approaches, README "vs" sections,
+  CLAUDE.md rejected-alternatives notes), leave this section with
+  its placeholder — better empty than filler.
+
+Deliverable 3 — INVARIANTS (up to 5):
   Architectural or operational rules whose breakage causes non-obvious
   damage. Examples of the *class* of content to produce:
     - decisions captured in ADRs that contradict "obvious" approaches
@@ -794,7 +847,7 @@ Deliverable 2 — INVARIANTS (up to 5):
     - "Never run data migrations on Monday; the cron vacuum window
        overlaps and rollbacks stall."
 
-Deliverable 3 — GOTCHAS (3 to 5):
+Deliverable 4 — GOTCHAS (3 to 5):
   Landmines whose fix is not obvious from code alone. Dependency quirks,
   rate limits, migrations needing manual steps, config that looks like a
   bug but is deliberate, platform-specific behaviour.
@@ -813,10 +866,13 @@ Deliverable 3 — GOTCHAS (3 to 5):
 Quality bar: 3 strong rules beat 5 weak ones. Same for gotchas.
 
 Required output format (exact indentation, no code fences, no
-commentary). PURPOSE is a single line; INVARIANTS/GOTCHAS are bullet
-lists with two-space indent:
+commentary). PURPOSE is a single line; DIFFERENTIATORS, INVARIANTS,
+and GOTCHAS are bullet lists with two-space indent:
 
 PURPOSE: <single 2-3 sentence summary, ≤ 400 chars>
+DIFFERENTIATORS:
+  - <alternative → our choice / rationale>
+  - <...>
 INVARIANTS:
   - <rule 1>
   - <rule 2>
@@ -839,10 +895,10 @@ Do two things, in order — do NOT stop after step 1:
 
   STEP 2 — Open .revive/static.md and edit it in place: replace
   ONLY the sections you identified as placeholders. Preserve file
-  ordering (PURPOSE → INVARIANTS → GOTCHAS). Do NOT touch sections
-  you decided to preserve. Use your editor tool (Edit / Write /
-  str_replace — whatever your agent framework exposes); do NOT
-  ask me to paste manually.
+  ordering (PURPOSE → DIFFERENTIATORS → INVARIANTS → GOTCHAS).
+  Do NOT touch sections you decided to preserve. Use your editor
+  tool (Edit / Write / str_replace — whatever your agent framework
+  exposes); do NOT ask me to paste manually.
 
   After step 2, confirm with a one-line summary of which sections
   were rewritten and which were preserved, plus the final line

tests/revive.bats

@@ -916,20 +916,116 @@ EOF
 }
 
 @test "suggest prompt requests PURPOSE as Deliverable 1 (v0.1.13)" {
+  # After v0.1.14 DIFFERENTIATORS slots in as Deliverable 2 — keep this
+  # test narrow: PURPOSE must be Deliverable 1.
   run "$REVIVE" suggest
   [ "$status" -eq 0 ]
-  [[ "$output" == *"Deliverable 1 — PURPOSE"* ]]   || return 1
-  [[ "$output" == *"Deliverable 2 — INVARIANTS"* ]] || return 1
-  [[ "$output" == *"Deliverable 3 — GOTCHAS"* ]]   || return 1
+  [[ "$output" == *"Deliverable 1 — PURPOSE"* ]] || return 1
+}
+
+@test "suggest PURPOSE deliverable requires business goals (v0.1.14)" {
+  # Marketing one-liners are no longer "substantive" — PURPOSE must
+  # cover what + why (business goal) + essential constraint.
+  run "$REVIVE" suggest
+  [ "$status" -eq 0 ]
+  printf '%s\n' "$output" | grep -qF 'business goal or success criterion' || return 1
+  printf '%s\n' "$output" | grep -qF 'All three must be present'           || return 1
+  # Placeholder classification must explicitly cover marketing-tagline state
+  printf '%s\n' "$output" | grep -qF "what success"                         || return 1
+}
+
+# DIFFERENTIATORS section (v0.1.14)
+
+@test "init scaffolds DIFFERENTIATORS section alongside others" {
+  run "$REVIVE" init
+  [ "$status" -eq 0 ]
+  run cat .revive/static.md
+  [[ "$output" == *"DIFFERENTIATORS:"* ]]                   || return 1
+  [[ "$output" == *"what sets this project apart"* ]]       || return 1
+  # section ordering: PURPOSE → DIFFERENTIATORS → INVARIANTS → GOTCHAS
+  local purp_line diff_line inv_line got_line
+  purp_line=$(printf '%s\n' "$output" | grep -n '^PURPOSE:'         | cut -d: -f1)
+  diff_line=$(printf '%s\n' "$output" | grep -n '^DIFFERENTIATORS:' | cut -d: -f1)
+  inv_line=$(printf '%s\n' "$output" | grep -n '^INVARIANTS:'       | cut -d: -f1)
+  got_line=$(printf '%s\n' "$output" | grep -n '^GOTCHAS:'          | cut -d: -f1)
+  [ "$purp_line" -lt "$diff_line" ] || return 1
+  [ "$diff_line" -lt "$inv_line" ]  || return 1
+  [ "$inv_line" -lt "$got_line" ]   || return 1
+}
+
+@test "show skips placeholder DIFFERENTIATORS bullets" {
+  "$REVIVE" init
+  run "$REVIVE" show
+  # header stays for structure, placeholder bullet must not leak
+  [[ "$output" == *"DIFFERENTIATORS:"* ]]        || return 1
+  [[ "$output" != *"what sets this project"* ]]  || return 1
+}
+
+@test "show keeps substantive DIFFERENTIATORS bullets intact" {
+  mkdir -p .revive
+  cat > .revive/static.md <<'EOF'
+PURPOSE: Test project.
+DIFFERENTIATORS:
+  - Unlike cron — code-defined schedules that survive deploys.
+  - Unlike SaaS schedulers — zero new infrastructure.
+INVARIANTS:
+GOTCHAS:
+EOF
+  run "$REVIVE" show
+  [[ "$output" == *"Unlike cron"* ]]              || return 1
+  [[ "$output" == *"zero new infrastructure"* ]] || return 1
+}
+
+@test "init --force preserves substantive DIFFERENTIATORS across PURPOSE regen" {
+  mkdir -p .revive
+  cat > .revive/static.md <<'EOF'
+PURPOSE: old stale purpose
+DIFFERENTIATORS:
+  - Custom differentiator 1.
+  - Custom differentiator 2.
+INVARIANTS:
+  - user rule 1
+GOTCHAS:
+  - user gotcha 1
+EOF
+  printf '{"description":"fresh purpose"}\n' > package.json
+  run "$REVIVE" init --force
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DIFFERENTIATORS/INVARIANTS/GOTCHAS preserved"* ]] || return 1
+  run cat .revive/static.md
+  [[ "$output" == *"Custom differentiator 1."* ]] || return 1
+  [[ "$output" == *"Custom differentiator 2."* ]] || return 1
+  [[ "$output" == *"user rule 1"* ]]              || return 1
+  [[ "$output" == *"user gotcha 1"* ]]            || return 1
+  [[ "$output" == *"fresh purpose"* ]]            || return 1
+}
+
+@test "suggest prompt introduces DIFFERENTIATORS as Deliverable 2" {
+  run "$REVIVE" suggest
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Deliverable 1 — PURPOSE"* ]]          || return 1
+  [[ "$output" == *"Deliverable 2 — DIFFERENTIATORS"* ]]  || return 1
+  [[ "$output" == *"Deliverable 3 — INVARIANTS"* ]]       || return 1
+  [[ "$output" == *"Deliverable 4 — GOTCHAS"* ]]          || return 1
+}
+
+@test "suggest prompt lists DIFFERENTIATORS placeholder marker" {
+  # "what sets this project apart" wraps across two lines in the prompt;
+  # assert the left half which is line-complete.
+  run "$REVIVE" suggest
+  [ "$status" -eq 0 ]
+  printf '%s\n' "$output" | grep -qF 'what sets this project' || return 1
 }
 
 @test "suggest prompt tells agent to preserve substantive sections across the board" {
-  # Semantics: existing human-curated content in PURPOSE / INVARIANTS /
-  # GOTCHAS must survive a re-run. Only placeholder sections get rewritten.
+  # Semantics: existing human-curated content in any STATIC section must
+  # survive a re-run. Only placeholder sections get rewritten.
+  # (String "preserved verbatim" is line-wrapped in the prompt; check
+  # for the sentinel words on their own lines.)
   run "$REVIVE" suggest
   [ "$status" -eq 0 ]
   printf '%s\n' "$output" | grep -qF 'Treat existing human-' || return 1
-  printf '%s\n' "$output" | grep -qF 'preserved verbatim'    || return 1
+  printf '%s\n' "$output" | grep -qF 'verbatim'              || return 1
   printf '%s\n' "$output" | grep -qF 'placeholder state'     || return 1
 }