@pareto4/pp-core 1.5.0

package/pp-core/references/prohibition-probe.md

@@ -0,0 +1,326 @@
+# Prohibition-Probe — Spec-Completeness Must-NOT Reference
+
+Shared reference for the spec/requirements phase. Companion to
+`@~/.claude/pp-core/references/edge-probe.md`: `edge-probe` reaches the
+**data/behavior-shape axis** (boundaries, adjacency, encoding, ordering) — the things a
+feature must *do*. This reference reaches the orthogonal **must-NOT axis** (product, values,
+safety, ethics) — the things a feature must *never silently become*. The edge-probe caught
+0/8 of these in controlled testing because it is the wrong instrument: a shape taxonomy
+cannot surface "the reminder must not shame the user." Walk each requirement through the
+two-stage recall→precision protocol below and resolve each surfaced prohibition to exactly
+one state.
+
+This doc is written in generic `requirements → checks → verifier` terms with no
+tool-specific vocabulary, so it is portable: copy it into any spec/requirements process.
+A short mapping table at the end binds it to common host structures.
+
+## Why front-of-pipeline
+
+A goal-backward verifier only checks assertions that exist; an assertion only exists for a
+requirement that was written down. The class of constraint this probe targets — the
+*"must-NOT"* the author assumed but never wrote — is invisible to the verifier in exactly
+the same way an omitted edge is, but with a sharper failure mode: a `✅ done` that means
+"the code matches the words in the spec" can still ship a feature that does what the author
+explicitly would *not* want. The manipulative-streak reminder, the loan model that proxies
+on zip code, the audit log that stores raw SSN — each one passes a literal spec while
+violating the intent. The fix is not a better verifier; it is **spec completeness**: surface
+the omitted prohibition into an explicit, checkable acceptance criterion *before* any code
+exists, after which the verifier reliably enforces it.
+
+The technique is adversarial elicitation, not deterministic computation. Unlike the edge
+taxonomy (a closed eight categories a classifier can apply), the recall stage is inherently
+model-driven: it asks an open question and reads prose. There is **no compiled
+`prohibition-probe.cjs` engine** — the recall stage is an LLM prose pass, and only the
+schema/projection layer is real code (ADR-550 Decision 7b). Building a deterministic
+recall adapter would be the scope-creep the maintainer flags.
+
+## Inputs
+
+A list of requirements, each a `{ id, text }` record where `text` is a testable statement.
+There is no shape override and no taxonomy classifier — the recall stage reads the prose
+directly and the precision stage filters its raw output. The probe runs **after** the
+edge-probe in the spec phase, over the same requirement list.
+
+## Two-stage protocol (recall → precision)
+
+The probe is a two-pass pipeline per requirement. Stage 1 maximizes recall (cast wide);
+Stage 2 restores precision (drop the noise). Running them in this order — wide then narrow —
+is what keeps the surfaced list both complete and short.
+
+**Stage 1 — Recall (adversarial probe).** Ask the single adversarial question of each
+requirement:
+
+> *What could this feature silently become that the author would NOT want, but the spec
+> does not forbid?*
+
+This question is model-robust (17/17 holistic surfacing including smaller models in the N18
+experiment). It deliberately over-produces: ~10 raw candidates per requirement, including
+routine engineering items. That over-production is intentional — recall first.
+
+**Stage 2 — Precision (one-pass classifier).** Filter the raw Stage-1 list in a single pass.
+The rule is a drop/keep split:
+
+- **DROP routine-engineering items** — anything that is a normal correctness or hygiene
+  concern rather than an intent constraint: "must not mutate its input", "must not throw on
+  empty list", "must return a primitive not an object", "must not leak a file handle". These
+  belong to the edge-probe or to ordinary code review, not here.
+- **KEEP values / safety / ethics items** — anything that, if violated, makes the feature do
+  something the author would object to on product, fairness, privacy, transparency, or
+  safety grounds: "must not use shaming framing", "must not proxy on protected attributes",
+  "must not store raw PII in plaintext".
+
+This collapses the raw ~10 to ~2–3 genuine prohibitions (GT 5/5, 0 false positives on the
+N18 eight-spec battery). A requirement that yields zero kept prohibitions emits an empty
+list — that is the correct precision outcome for a pure utility, not a failure.
+
+## Canon-referral (do not mint canon items)
+
+Some kept candidates are not bespoke at all — they are **canon** security/compliance
+constraints that a dedicated tool already owns. Do NOT mint a prohibition for them. Instead
+emit a one-line breadcrumb and stop:
+
+- OWASP / prototype-pollution / path-traversal / injection → breadcrumb to `/pp:secure-phase`
+  and `eslint` (security plugins), not a minted prohibition.
+- GDPR / data-retention / consent → breadcrumb to `/pp:secure-phase`.
+- Generic fairness/bias canon → breadcrumb to `/pp:secure-phase`.
+
+The breadcrumb reads like: *"prototype-pollution is canon — covered by /pp:secure-phase +
+eslint; not minted here."* This keeps the surfaced list to the ~2–3 **bespoke** items that
+no other tool would catch — the manipulative-framing prohibition, the product-specific
+fairness constraint — which is the whole value of the probe. Minting canon items both
+duplicates other tooling and drowns the bespoke signal (ADR-550 Decision 6).
+
+## Resolution states
+
+Each surfaced prohibition carries two orthogonal axes — a resolution **lifecycle** and, when
+resolved, a **verification** tier (ADR-550 Decision 7, the shared probe-core model; the
+lifecycle is identical to the edge-probe, the verification tiers differ):
+
+- **status** — `resolved | dismissed | unresolved` (IDENTICAL to the edge-probe):
+  - **resolved** — the prohibition is addressed; *how* it is addressed is the verification tier.
+  - **dismissed** — not a genuine prohibition for this feature, accompanied by a required,
+    non-empty reason string. "N/A — this utility has no user-facing surface, no values
+    constraint applies" is valid; silence is not. The reason string is the audit trail.
+  - **unresolved** — carried forward and flagged; the author chose not to resolve it yet.
+- **verification** (only when `status` is `resolved`; `null` otherwise) — `test | judgment`
+  (this REPLACES the edge-probe's `explicit | backstop`):
+  - **test** — the prohibition can be mechanically checked (a negative test, a lint rule, an
+    assertion that the audit log contains no raw SSN). A checkable assertion exists.
+  - **judgment** — the prohibition is real but cannot be reduced to a mechanical test (a
+    human/LLM judgment that the framing is not manipulative). It records intent and routes
+    to a judgment-based review rather than a green/red test.
+
+  At verify time these tiers are routed differently (ADR-550 D4):
+  - A **test**-tier prohibition is enforced + hard-gates via the deterministic
+    `check prohibition-enforcement` sub-command (#1259 + #1279, ADR-550 D5d): it locates the wired
+    mechanical check (a `node --test` negative test OR a lint/AST rule run as
+    `eslint --format json` and filtered by `ruleId`), **machine-proves it is fail-first** against a
+    known violation, runs it for a genuine **non-vacuous** pass, and emits the
+    `dispositionForProhibition()` verdict. A passing, fail-first-proven wired check disposes **green**
+    (satisfiable → can reach `passed`); a missing, un-provable, or genuinely-non-passing check
+    **hard-gates** (flagged, never green → `gaps_found`) in BOTH interactive and autonomous modes —
+    never a silent pass.
+
+    **Machine-proven fail-first (#1279).** `failFirst` is now **machine-proven, not caller-attested**:
+    before a clean pass greens, the producer independently runs the wired check against a KNOWN
+    VIOLATION and confirms it goes RED (any other outcome — passes-on-violation, can't-prove, throws,
+    times out, no violation source — hard-gates). The violation is sourced from a descriptor field:
+    - **`violationFixture`** — an author-supplied path to a KNOWN-BAD subject. For `lint-rule`: a file
+      whose content violates `rule`; the prover lints it and requires the rule id to appear in the
+      JSON report (the rule must have teeth). For `node-test`: a subject the negative test exercises,
+      expected to drive it RED.
+    - **`GSD_PROHIB_SUBJECT`** — the node-test subject-injection convention: the producer spawns the
+      negative test with `GSD_PROHIB_SUBJECT=<violationFixture>` in the child env; the test reads that
+      env var to locate its subject-under-test and is expected to go red against the violating subject.
+    - **lint-fixture authoring gotcha** — the violating fixture must actually trigger the rule. For the
+      `local/no-source-grep` dogfood anchor specifically, use the `path.join('lib','foo.cjs')` form
+      (a standalone quoted dir token); a single string literal like `'src/x.cjs'` does NOT trigger the
+      rule, so a mis-authored fixture makes the prover report "not proven" and hard-gate a legitimately
+      wired check. (`no-source-grep` has no filename guard — any `.cjs` with the pattern fires.)
+
+    > **PROPOSED, renamable conventions (zero live consumers).** Both `GSD_PROHIB_SUBJECT` and
+    > `violationFixture` are net-new surface with **no live in-tree consumer yet** — there is no
+    > in-tree `node --test` prohibition; node-test fail-first proof is exercised only by SYNTHETIC
+    > temp fixtures in the tests, and the real dogfood remains the LINT-rule `local/no-source-grep`.
+    > They are therefore **open to maintainer adjustment (rename, or replacing the env var with an
+    > argv) at PR review with zero migration cost.** See the ADR-550 2026-06-15 addendum (#1279).
+  - A **judgment**-tier prohibition routes to a never-silent / never-hard-halt soft gate
+    (autonomous emits an `unverified-prohibition — human review recommended` flag).
+
+Splitting these axes keeps the lifecycle enum free of a verification fact and lets the
+prohibition adapter declare `test | judgment` without forking the shared lifecycle enum that
+the edge-probe's `explicit | backstop` also uses.
+
+## Optional wired-check descriptor (deterministic locate + machine-proof, #1278 + #1346)
+
+A `resolved`/`test`-tier prohibition MAY carry an **optional `check` descriptor** that names
+the wired mechanical check, so verify-phase locates it deterministically instead of inventing
+`{kind, target, rule}` each run. The descriptor is captured at spec-phase (soft / optional —
+the author wires it when the negative test or lint rule already exists) and is represented as
+**four flat scalar keys** on the `must_haves.prohibitions` item — never a nested `check: {}`
+object:
+
+- `check_kind` — `node-test` | `lint-rule` (which producer mechanism runs the check).
+- `check_target` — the test file (`node-test`) or the file the rule runs against (`lint-rule`).
+- `check_rule` — the `ruleId` to filter on, **lint-rule only** (absent for `node-test`).
+- `check_violation_fixture` — path to a KNOWN-BAD subject the #1279 prover runs the check against to
+  machine-prove fail-first (rides BOTH kinds; for `node-test` it is injected via `GSD_PROHIB_SUBJECT`).
+
+The flat-scalar shape is load-bearing: the shared `parseMustHavesBlock` is a flat parser and a
+nested object would flatten/mangle the round-trip (ADR-550 2026-06-15 addendum; #644 "no parser
+rewrite" precedent). `projectProhibitions` emits these keys **only for a well-formed descriptor**
+(valid `check_kind` + non-empty `check_target`; `check_rule` only on the lint-rule path;
+`check_violation_fixture` only when non-empty), and verify-phase reads them back via
+`descriptorFromProjection` into the `CheckDescriptor` handed to `check prohibition-enforcement`. This
+closes **both** the locate (#1278) and the machine-proof-fixture (#1346) halves with **zero manual
+descriptor authoring**: a prohibition authored with all four scalars greens end-to-end through the
+projection alone.
+
+**Fail-closed + backward-compat.** A partial descriptor (`lint-rule` missing `check_rule`), an
+unknown `check_kind`, an **absent** descriptor, OR a descriptor with **no `check_violation_fixture`**
+falls through to the producer's fail-closed paths (`located: false`, or located-but-unprovable) —
+never a silent green. A prohibition with no descriptor parses and disposes byte-identically to today.
+`failFirst` is **not** sourced from the descriptor and is **demoted** (machine-proven fail-first
+DELIVERED in #1279 — no path greens on attestation alone, FF-08); the `dispositionForProhibition`
+policy is unchanged. Residual (tracked **#1346**): the node-test proof confirms the fixture exists and
+the check goes RED, but cannot generically prove the red was *caused by* the subject's content.
+
+## Output schema
+
+The probe emits, per kept prohibition, an item of the form:
+
+```
+{ requirement_id, category, status, verification, resolution, reason, statement,
+  check_kind?, check_target?, check_rule? }
+```
+
+where `statement` is the must-NOT sentence and `category` is the values/safety/ethics class
+(`values`, `fairness`, `privacy`, `transparency`, `safety`, …). The optional **flat-scalar
+`check_*` descriptor** (#1278) is present only on a resolved `test`-tier prohibition carrying a
+wired check: `check_kind` (`node-test` | `lint-rule`), `check_target`, and `check_rule` (lint-rule
+only). `projectProhibitions` emits these into `must_haves.prohibitions` and `descriptorFromProjection`
+reads them back into a `{ kind, target, rule? }` `CheckDescriptor`; they are flat scalars (never a
+nested `check:{}` object) so they round-trip through the unchanged `parseMustHavesBlock`. Plus a
+coverage summary:
+
+```
+coverage: { applicable, resolved, unresolved, byVerification: { test, judgment } }
+```
+
+`applicable` is the number of kept prohibitions, `resolved` = closed (`resolved` +
+`dismissed`) status items, `unresolved` is the remainder, and `byVerification` breaks the
+`resolved`-status items down by tier (`{ test, judgment }`). This JSON is the stable contract
+both the reference implementation and any third-party port emit.
+
+## Generic mapping (requirements → checks → verifier)
+
+| Host structure | "requirement" | a `resolved`/`test` prohibition becomes | a `resolved`/`judgment` prohibition becomes |
+|----------------|---------------|------------------------------------------|----------------------------------------------|
+| GSD SPEC | a SPEC Requirement | a SPEC acceptance criterion (marked prohibition) that `plan-phase` lifts into `must_haves.prohibitions` | a `must_haves.prohibitions` item routed to judgment review |
+| Gherkin feature | a Scenario | a negative `Then` assertion / tagged negative scenario | a tagged scenario routed to manual review |
+| OpenAPI operation | an operation | a contract test asserting the forbidden behavior never occurs | a documented constraint flagged for review |
+| Docstring contract | a documented behavior | a negative assertion in the contract test | a documented must-NOT for reviewers |
+
+The portable invariant: a `resolved`/`test` prohibition produces **a checkable negative the
+verifier iterates over** (GSD: a `must_haves.prohibitions` item with a test); a
+`resolved`/`judgment` prohibition produces a recorded intent routed to judgment review. An
+`unresolved` prohibition is an explicit assumption the downstream planner must surface, not
+silently drop.
+
+## Worked example (streak-reminder)
+
+A single requirement to send a daily habit reminder. The edge-probe sees a `stateful`
+requirement and asks about idempotency; the prohibition-probe asks the adversarial question
+and surfaces what the reminder must never *become*. Stage 1 over-produces ("must not spam",
+"must not throw on a deleted habit", "must not use shaming framing"); Stage 2 drops the
+routine-engineering items and keeps the one genuine values prohibition:
+
+```json prohibition-probe:01-streak-reminder/expected.json
+{
+  "items": [
+    {
+      "requirement_id": "R1",
+      "category": "values",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT use shaming, guilt, or loss-aversion streak framing (e.g. \"Don't lose your streak!\") — the reminder must encourage without penalty framing"
+    }
+  ],
+  "coverage": { "applicable": 1, "resolved": 1, "unresolved": 0, "byVerification": { "test": 0, "judgment": 1 } }
+}
+```
+
+The kept prohibition is `judgment`-tier: "manipulative framing" cannot be reduced to a
+mechanical test, so it records intent and routes to judgment review — but it is now an
+explicit acceptance criterion the spec must clear, not an unwritten assumption.
+
+## Worked example (clean-utility)
+
+A pure utility requirement — "deduplicate a list of integers" — has no user-facing surface,
+no values/safety/ethics dimension. Stage 1 still over-produces ("must not mutate the input",
+"must not change order"), but every candidate is routine engineering that Stage 2 drops (and
+the edge-probe already owns). The correct precision outcome is an empty prohibition list — a
+zero, not a false positive:
+
+```json prohibition-probe:02-clean-utility/expected.json
+{
+  "items": [],
+  "coverage": { "applicable": 0, "resolved": 0, "unresolved": 0, "byVerification": { "test": 0, "judgment": 0 } }
+}
+```
+
+This is the precision discipline that keeps the probe from crying wolf: a utility with no
+intent surface produces zero prohibitions, so a non-empty list always carries signal.
+
+## Worked example (multi-prohibition)
+
+A loan-decision requirement is the high-stakes case: it surfaces several distinct
+prohibitions across categories. Stage 1 produces a long list including canon items
+(prototype-pollution, generic GDPR retention) that canon-referral breadcrumbs out; Stage 2
+keeps the three bespoke values/safety items — a `fairness` constraint, a `privacy` constraint
+(`test`-tier, mechanically checkable against the audit log), and a `transparency` constraint:
+
+```json prohibition-probe:03-multi-prohibition/expected.json
+{
+  "items": [
+    {
+      "requirement_id": "R1",
+      "category": "fairness",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT use protected attributes (race, gender, age, national origin) or their proxies (zip code, name) in the loan decision or rate"
+    },
+    {
+      "requirement_id": "R1",
+      "category": "privacy",
+      "status": "resolved",
+      "verification": "test",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT store raw PII / financial secrets (SSN, full account or card numbers) in plaintext in the audit log"
+    },
+    {
+      "requirement_id": "R1",
+      "category": "transparency",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT mislead or omit the true rate/APR/terms in the explanation; an adverse decision must state the real principal reason (adverse-action)"
+    }
+  ],
+  "coverage": { "applicable": 3, "resolved": 3, "unresolved": 0, "byVerification": { "test": 1, "judgment": 2 } }
+}
+```
+
+The `privacy` row is `test`-tier — "no raw SSN in the audit log" is a mechanical assertion —
+while `fairness` and `transparency` are `judgment`-tier. The byVerification rollup
+`{ test: 1, judgment: 2 }` is the count-preserved breakdown of the three `resolved`-status
+items. Each worked-example block above is kept byte-for-byte (parsed-JSON) identical to its
+fixture under `pp-core/references/prohibition-probe-fixtures/` by
+`tests/prohibition-probe.docs-fixtures.test.cjs`, so the doc and the reference data cannot
+silently drift.

package/pp-core/references/project-skills-discovery.md

@@ -0,0 +1,19 @@
+# Project Skills Discovery
+
+Before execution, check for project-defined skills and apply their rules.
+
+**Discovery steps (shared across all GSD agents):**
+1. Check `.claude/skills/` or `.agents/skills/` directory — if neither exists, skip.
+2. List available skills (subdirectories).
+3. Read `SKILL.md` for each skill (lightweight index, typically ~130 lines).
+4. Load specific `rules/*.md` files only as needed during the current task.
+5. Do NOT load full `AGENTS.md` files — they are large (100KB+) and cost significant context.
+
+**Application** — how to apply the loaded rules depends on the calling agent:
+- Planners account for project skill patterns and conventions in the plan.
+- Executors follow skill rules relevant to the task being implemented.
+- Researchers ensure research output accounts for project skill patterns.
+- Verifiers apply skill rules when scanning for anti-patterns and verifying quality.
+- Debuggers follow skill rules relevant to the bug being investigated and the fix being applied.
+
+The caller's agent file should specify which application applies.

package/pp-core/references/questioning.md

@@ -0,0 +1,162 @@
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation — why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness — what it actually is:**
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+**Clarification — what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+**Success — how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+- Headers longer than 12 characters (hard limit — validation will reject them)
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+**Tip for users — modifying an option:**
+Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
+
+</using_askuserquestion>
+
+<freeform_rule>
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** — NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
+
+**Wrong:** User says "let me describe it" → AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
+
+</freeform_rule>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>

package/pp-core/references/research-documentation-lookup.md

@@ -0,0 +1,29 @@
+When you need library or framework documentation, check in this order:
+
+1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
+   - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
+   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+
+2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
+   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+
+   Step 1 — Resolve library ID:
+   ```bash
+   if command -v ctx7 &>/dev/null; then
+     ctx7 library <name> "<query>"
+   else
+     echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
+   fi
+   ```
+   Step 2 — Fetch documentation:
+   ```bash
+   if command -v ctx7 &>/dev/null; then
+     ctx7 docs <libraryId> "<query>"
+   else
+     echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
+   fi
+   ```
+
+Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
+works via Bash and produces equivalent output. Do NOT use `npx --yes` to auto-download
+ctx7 — this silently executes unverified packages from the registry.

package/pp-core/references/research-philosophy.md

@@ -0,0 +1,29 @@
+## Claude's Training as Hypothesis
+
+Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
+
+**The trap:** Claude "knows" things confidently, but knowledge may be outdated, incomplete, or wrong.
+
+**The discipline:**
+1. **Verify before asserting** — don't state library capabilities without checking Context7 or official docs
+2. **Date your knowledge** — "As of my training" is a warning flag
+3. **Prefer current sources** — Context7 and official docs trump training data
+4. **Flag uncertainty** — LOW confidence when only training data supports a claim
+
+## Honest Reporting
+
+Research value comes from accuracy, not completeness theater.
+
+**Report honestly:**
+- "I couldn't find X" is valuable (now we know to investigate differently)
+- "This is LOW confidence" is valuable (flags for validation)
+- "Sources contradict" is valuable (surfaces real ambiguity)
+
+**Avoid:** Padding findings, stating unverified claims as facts, hiding uncertainty behind confident language.
+
+## Research is Investigation, Not Confirmation
+
+**Bad research:** Start with hypothesis, find evidence to support it
+**Good research:** Gather evidence, form conclusions from evidence
+
+When researching "best library for X": find what the ecosystem actually uses, document tradeoffs honestly, let evidence drive recommendation.

package/pp-core/references/research-verification-protocol.md

@@ -0,0 +1,27 @@
+## Known Pitfalls
+
+### Configuration Scope Blindness
+**Trap:** Assuming global configuration means no project-scoping exists
+**Prevention:** Verify ALL configuration scopes (global, project, local, workspace)
+
+### Deprecated Features
+**Trap:** Finding old documentation and concluding feature doesn't exist
+**Prevention:** Check current official docs, review changelog, verify version numbers and dates
+
+### Negative Claims Without Evidence
+**Trap:** Making definitive "X is not possible" statements without official verification
+**Prevention:** For any negative claim — is it verified by official docs? Have you checked recent updates? Are you confusing "didn't find it" with "doesn't exist"?
+
+### Single Source Reliance
+**Trap:** Relying on a single source for critical claims
+**Prevention:** Require multiple sources: official docs (primary), release notes (currency), additional source (verification)
+
+## Pre-Submission Checklist
+
+- [ ] All research domains in this agent's scope investigated (e.g. stack, features, architecture, patterns, pitfalls — whichever apply)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources cross-referenced for critical claims
+- [ ] URLs provided for authoritative sources
+- [ ] Publication dates checked (prefer recent/current)
+- [ ] Confidence levels assigned honestly
+- [ ] "What might I have missed?" review completed