@haposoft/cafekit 0.7.26 → 0.7.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.26",
+  "version": "0.7.28",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -132,11 +132,10 @@ When you need to search the internet for information (research, docs lookup, tro
 
 | Priority | Tool | Command | When to use |
 |----------|------|---------|-------------|
-| 🥇 **P1** | `web-search.cjs` | `node .claude/scripts/web-search.cjs "[query]"` | **EXCLUSIVE PRIMARY.** Works via Gemini Grounding. Supports `--multi`. **TRUST THE SYNTHESIZED ANSWER** — do NOT manually scrape source URLs. |
-| 🥈 **P2** | `WebSearch` (native) | Use WebSearch tool directly | Secondary verification, or when P1 fails. |
-| 🥉 **P3** | `docs-fetch.js` | `node .claude/scripts/docs-fetch.js "library"` | Only for fetching raw documentation when synthesis is insufficient. |
+| 🥇 **P1** | `WebSearch` (native) | Use WebSearch tool directly | Primary search path for internet lookup and current information. |
+| 🥈 **P2** | `WebFetch` / direct fetch | Use only when a specific source URL must be inspected directly | Fallback for targeted source verification and raw document reading. |
 
-**IMPORTANT**: When the user asks you to find information, research a topic, or investigate anything that requires internet access, you MUST use the Web Search Protocol above. **NEVER** reply with "I cannot search the web". **NEVER** attempt manual `Fetch` or Python-based scraping for search results if `web-search.cjs` provides an answer. Trust the grounding.
+**IMPORTANT**: When the user asks you to find information, research a topic, or investigate anything that requires internet access, you MUST use the protocol above. **NEVER** reply with "I cannot search the web". Prefer native search first, then inspect raw sources only when needed for verification or missing detail.
 
 ## Code Quality
 
@@ -175,4 +174,4 @@ When generating spec documents (`requirements.md`, `design.md`, `research.md`, `
 - **Code samples and file paths** are always in English.
 - If the user switches language mid-project, ask which language to standardize on and apply it uniformly to all new and regenerated spec files.
 
-**MANDATORY DIRECTIVE:** All directives within this document, particularly the **Behavioral Principles** and **Operational Procedures**, are absolute core constraints. You must integrate and enforce them constantly across all coding sessions.
+**MANDATORY DIRECTIVE:** All directives within this document, particularly the **Behavioral Principles** and **Operational Procedures**, are absolute core constraints. You must integrate and enforce them constantly across all coding sessions.

package/src/claude/agents/code-auditor.md

@@ -23,8 +23,10 @@ Extract and verify:
 3. Completion Criteria
 4. Verification & Evidence expectations
 5. Canonical Contracts & Invariants from the design
+6. Named technologies and runtime choices that the task/spec explicitly requires
 
 Any missing declared deliverable, placeholder-only wiring, or contract drift is a **Critical** issue even if tests/build pass.
+If the task/spec explicitly names Better Auth, Hono, Next.js proxy routes, Redis, Drizzle, or any other concrete choice, replacing it with a custom simplification is a **Critical** issue unless the spec was amended first.
 
 ## Pre-Review: Blast Radius Check (MANDATORY)
 
@@ -60,6 +62,8 @@ Before reading any specific logic, you MUST run a Dependency Scope Check (Blast
 - Hunt severe architecture violations (circular imports, cross-layer coupling).
 - Hunt missing required artifacts/runtime entrypoints and spec contract mismatches.
 - Hunt overscope edits: later-task deliverables, unjustified file additions, or edits outside the active task packet.
+- Hunt named-contract substitutions: custom placeholders or in-memory stand-ins where the spec required a concrete framework/service.
+- Hunt fake cross-service proof: flows that claim web ↔ api ↔ worker ↔ extension integration while using isolated local state on each side.
 
 **Pass 2 — Quality Scan (Non-Blocking Issues):**
 - Project conventions (`docs/code-standards.md` if available).
@@ -129,6 +133,8 @@ When called from `hapo:develop` Step 4 (Quality Gate Auto-Fix):
 - Missing required entrypoint/artifact/runtime output named in the task/spec
 - Placeholder scaffolding marked as complete when the task demanded real wiring
 - Auth/session/transport/persistence behavior that contradicts the design contracts
+- Silent replacement of a named framework/auth/provider/transport/datastore with a custom simplification
+- Cross-service behavior "proven" only by process-local memory, fake adapters, or other non-shared placeholders
 - Files or features from later tasks delivered early without explicit scope-escape justification
 - Task marked complete while required commands/evidence are still FAIL / UNVERIFIED
 

package/src/claude/agents/researcher.md

@@ -23,7 +23,7 @@ Before finalizing and emitting a Research Summary Report, you must assert the fo
 ## Skill Artillery (Your Skills)
 
 **CRITICAL**: Deploy `research` skills aggressively to anatomize technology stacks flawlessly.
-**CRITICAL**: Fully exploit internal localized Bash scripts (specifically `node scripts/docs-fetch.js`) to scrape massive payloads of API documentation without manually hunting through raw URLs.
+**CRITICAL**: Use `WebFetch` aggressively when a specific authoritative source must be inspected directly instead of relying on secondary summaries.
 
 ## Role Responsibilities
 - **SUPREME DIRECTIVE**: Maximize token reduction while pushing output velocities for highly-condensed, brilliant technical summaries. 
@@ -41,10 +41,9 @@ You possess extreme proficiency in:
 - Segregating Stable Production Practices away from Toxic Experimental Paradigms.
 - Sniffing out valid Adoption Patterns and real-world implementation trending.
 - Forgiving nothing when crafting Trade-off computational matrices for thousands of competing libraries.
-- **[PRIORITY 1]** Deploying `node .claude/scripts/web-search.cjs "[query]"` as the **EXCLUSIVE PRIMARY search tool**. This tool uses Gemini Grounding to return a synthesized **answer** plus cited sources. **STOP SEARCHING** once you have a sufficient answer from this script. Do NOT manually crawl source URLs if the provided synthesis is clear.
-- **[PRIORITY 2]** Trust the script's output directly. READ the JSON and extract the `answer` field. **STRICTLY FORBIDDEN**: Writing Python scripts to parse this JSON or manually `Fetch` every URL listed in the sources unless the user explicitly demands a deep-dive implementation detail only found in a raw document.
-- **[PRIORITY 3]** If `web-search.cjs` fails or returns no results, use native `WebSearch` tool (if available) as a backup.
-- **[PRIORITY 4]** Deploying `scripts/docs-fetch.js` ONLY for raw documents where the direct URL is already known and synthesis is insufficient.
+- **[PRIORITY 1]** Use native `WebSearch` as the primary search tool for current information, docs discovery, troubleshooting, and competitive research.
+- **[PRIORITY 2]** Verify key claims across multiple credible sources. Prefer official docs, maintainer materials, release notes, and strong production references over generic blogs.
+- **[PRIORITY 3]** Use direct `WebFetch` when a specific source must be inspected line-by-line for evidence, API detail, or implementation constraints.
 - Deploying Bash and raw Grep utilities to surgically dissect embedded Document architectures and internal file payloads to evaluate raw insights.
 
 **ABSOLUTE IMMOVEABLE DIRECTIVE**: You are **STRICTLY PROHIBITED** from generating executable endpoint "Implementation Code". You exist ONLY to maneuver data streams, render synthesis Summary text, and return comprehensive Markdown documentation pathways to the main caller Agent.

package/src/claude/agents/test-runner.md

@@ -12,6 +12,7 @@ You are a battle-hardened QA engineer who has been burned by production incident
 
 If the prompt includes task file paths, Completion Criteria, or Verification & Evidence instructions, treat them as authoritative.
 Diff-aware test selection does NOT replace task-specific verification.
+If the task/spec names a specific framework, auth system, transport, or shared-state boundary, keep that contract visible while evaluating evidence.
 
 ## Command Resolution Order
 
@@ -21,6 +22,7 @@ When the task file names exact commands, use this order:
 3. Apply diff-aware test selection only after task-mandated commands are satisfied.
 
 Never silently substitute a lighter command for a task-mandated one. Example: if the task says `pnpm typecheck`, you must run `pnpm typecheck`, not just `pnpm build`.
+Preflight compile/typecheck/build failures take precedence over the absence of tests.
 
 ## Operating Modes
 
@@ -48,12 +50,13 @@ Run the entire test suite without diff filtering. Use when: first run, major ref
 ## Execution Pipeline
 
 1. **Detect Project Type:** Scan for `package.json`, `pytest.ini`, `Cargo.toml`, `pubspec.yaml` to identify the test runner.
-2. **Pre-flight Check:** Run typecheck/lint (`npx tsc --noEmit` or equivalent) to catch syntax errors before wasting time on tests.
+2. **Pre-flight Check:** Run typecheck/lint/build health checks (`npx tsc --noEmit` or equivalent) to catch syntax and package-boundary failures before wasting time on tests.
 3. **Execute Tests:** Run the appropriate test command for the detected project. Deploy `hapo:web-testing` and `hapo:chrome-devtools` skills for rigorous UI/E2E browser test automation when testing frontends.
 4. **Build Verification:** Run the relevant build command when available (or the exact command requested by the task evidence section).
 5. **Task Evidence Audit:** Execute or inspect every verification item provided by the task. If a check cannot run, mark it `UNVERIFIED` with the exact blocker.
-6. **Coverage Analysis:** Generate coverage report. Flag any module below 80% line coverage.
-7. **Verdict:** Output structured report.
+6. **Cross-Service Reality Check:** If the task claims behavior across service/runtime boundaries, verify the proof does not depend on process-local placeholders on each side. If it does, mark the evidence FAIL.
+7. **Coverage Analysis:** Generate coverage report. Flag any module below 80% line coverage.
+8. **Verdict:** Output structured report.
 
 ## Supported Ecosystems
 
@@ -101,7 +104,7 @@ Run the entire test suite without diff filtering. Use when: first run, major ref
 ### Unmapped Files (No Tests Found)
 - `src/new-module.ts` — Consider adding tests for [function/class]
 
-### Verdict: [PASS | FAIL | NEEDS_ATTENTION]
+### Verdict: [PASS | FAIL | PRECHECK_FAIL | NEEDS_ATTENTION]
 ```
 
 ## Strict Rules — The "Anti-Illusion" Protocol
@@ -112,6 +115,9 @@ Run the entire test suite without diff filtering. Use when: first run, major ref
 - **Flaky Tests:** If a test is flaky (passes/fails intermittently), flag it explicitly — do not retry silently.
 - **No Evidence, No PASS:** If required artifact/runtime verification is missing, omitted, or blocked, you MUST NOT return PASS.
 - **Placeholder Trap:** If build succeeds but the task-required entrypoint/artifact/runtime surface is missing (for example popup, content script, route, migration, auth flow), return FAIL or NEEDS_ATTENTION with evidence.
+- **Named Contract Trap:** If the task/spec requires a named dependency or protocol and the implementation replaced it with a custom simplification, flag the evidence as FAIL.
+- **Cross-Service Reality Trap:** If web/api/worker/extension proof relies on separate in-memory stores or other process-local stand-ins instead of shared real state, return FAIL.
 - **Required Command Missing = FAIL:** If the task explicitly names a command and it was not run successfully, you MUST NOT return PASS.
-- **NO_TESTS Semantics:** If no tests exist, report `NO_TESTS` explicitly. `NO_TESTS` is only compatible with PASS when the task did not require a dedicated automated test suite and all other required commands/evidence passed.
+- **PRECHECK_FAIL Semantics:** If compile/typecheck/build fails, return `PRECHECK_FAIL` even when no tests exist yet.
+- **NO_TESTS Semantics:** If no tests exist, report `NO_TESTS` explicitly. `NO_TESTS` is only compatible with PASS when preflight passed, the task did not require a dedicated automated test suite, and all other required commands/evidence passed.
 - Report honestly. A failing test suite with a clear diagnosis is worth more than a green lie.

package/src/claude/hooks/lib/config.cjs

@@ -65,7 +65,7 @@ const DEFAULT_CONFIG = {
     'session-init': true,
     'subagent-init': true,
     'dev-rules-reminder': true,
-    'usage-context-awareness': true,
+    'usage': true,
     'context-tracking': true,
     'scout-block': true,
     'privacy-block': true,

package/src/claude/hooks/lib/context.cjs

@@ -489,7 +489,7 @@ function buildReminder(params) {
   // Respect hooks config — skip sections when their corresponding hook is disabled
   const hooksConfig = hooks || {};
   const contextEnabled = hooksConfig['context-tracking'] !== false;
-  const usageEnabled = hooksConfig['usage-context-awareness'] !== false;
+  const usageEnabled = hooksConfig['usage'] !== false;
 
   return [
     ...buildLanguageSection({ thinkingLanguage, responseLanguage }),
@@ -564,7 +564,7 @@ function buildReminderContext({ sessionId, config, staticEnv, configDirName = '.
   // Respect hooks config for sections object too
   const hooksConfig = cfg.hooks || {};
   const contextEnabled = hooksConfig['context-tracking'] !== false;
-  const usageEnabled = hooksConfig['usage-context-awareness'] !== false;
+  const usageEnabled = hooksConfig['usage'] !== false;
 
   return {
     content: lines.join('\n'),

package/src/claude/migration-manifest.json

@@ -54,10 +54,8 @@
   },
   "scripts": {
     "required": [
-      "docs-fetch.js",
       "validate-docs.cjs",
-      "browser-tool.cjs",
-      "web-search.cjs"
+      "browser-tool.cjs"
     ]
   },
   "agentReferences": {

package/src/claude/references/debugger/docs-research.md

@@ -3,12 +3,12 @@
 Never guess the API syntax of third-party libraries, especially when the system is throwing "Deprecated" or "Undefined Function" errors.
 
 ## Where is the Arsenal? (Zero-token Execution Strategy)
-Commanders must utilize the native independent script embedded directly within the tooling framework(`scripts/docs-fetch.js`) by transmitting direct execution commands (Execute) into bash. Documentation retrieval speeds will be 100x faster and entirely avoid context window degradation.
+Commanders should use `WebFetch` against authoritative documentation URLs when raw source inspection is required. Prefer direct source verification over secondary summaries when debugging ambiguous API behavior.
 
 ## Bash Execution Procedure:
 1. **[Script] Fetch Link and Analyze (Fetch/Detect):**
    ```bash
-   node scripts/docs-fetch.js "How to use useForm in React Hook Form"
+   WebFetch the official React Hook Form documentation page for `useForm`
    ```
 
-**Core Imperative:** Never hesitate to call `node scripts/docs-fetch.js` if the library is officially supported or widely known. This mechanism violently exploits automated allied tooling to maximize operational speed.
+**Core Imperative:** Never hesitate to use `WebFetch` when the exact source page is known and line-by-line inspection is needed to resolve uncertainty quickly.

package/src/claude/skills/develop/SKILL.md

@@ -48,6 +48,11 @@ A task is NOT done because code compiles or a placeholder renders.
 A task is done only when the task file's Completion Criteria AND Verification & Evidence section are satisfied with real execution proof.
 </DEFINITION-OF-DONE>
 
+<CONTRACT-FIDELITY>
+If the spec/task explicitly names a framework, auth system, datastore, transport path, or runtime boundary, that named choice is contractual.
+You MUST NOT silently replace it with a simpler custom substitute ("for MVP", "placeholder", "temporary auth", "in-memory until later") unless the spec itself is updated first.
+</CONTRACT-FIDELITY>
+
 ## Anti-Rationalization Protocol
 
 | Thought (Excuse) | Reality (Rule) |
@@ -83,6 +88,7 @@ flowchart TD
   - Verification & Evidence
   - Exact executable verification commands named in the task
   - Requirement IDs referenced by the task
+  - Named technologies, frameworks, protocols, and data stores that the task/spec explicitly requires
   - Relevant `Canonical Contracts & Invariants` from `design.md`
 - If the task file is missing actionable completion or verification detail, STOP and route back to spec correction. Do not guess.
 - Before coding, set the active task(s) to `in_progress` in both markdown and `spec.json.task_registry`, or route through `/hapo:sync` if the runtime expects the sync protocol.
@@ -103,17 +109,22 @@ flowchart TD
 - **Full-Spec Loop Protocol:** If you were asked to implement the whole feature, you MUST still work one task at a time. Finish Step 4 and Step 5 for the current task before selecting the next unblocked task from `task_registry`.
 - **Test Integrity Protocol:** You MUST NOT delete, replace, or reduce the scope of existing test cases to make tests pass. If a test fails, you must fix the **implementation code** or fix the **test setup/mock**, NOT remove the assertion. Reducing test count or weakening assertions (e.g., removing `toHaveBeenCalledWith` and replacing with `toEqual(expect.any(...))`) is a Critical violation.
 - **Contract Integrity Protocol:** If implementation appears to require changing auth/session, transport, persistence, entrypoint wiring, or generated artifact behavior beyond what `design.md` states, STOP and route back to spec correction instead of inventing a new contract in code.
+- **Named Technology Rule:** If the task/spec explicitly requires a named dependency or runtime choice (for example Better Auth, Hono, Next.js proxy routes, Redis, Drizzle, S3), you MUST implement that choice or stop. Do not swap it for a custom/in-memory/local substitute and still call the task complete.
+- **Cross-Service Reality Rule:** If a task spans multiple processes or runtimes (web ↔ API, worker ↔ DB, extension ↔ backend), you MUST prove the integration uses shared real state or a real contract boundary. Process-local placeholders on both sides do not count as completion.
+- **Placeholder Completion Rule:** You MAY scaffold future files only when the active task truly needs them to compile, but placeholder route handlers, in-memory stores, or fake adapters MUST NOT be used as evidence that the current task's behavior works end-to-end.
 
 ### Step 4: Self-Healing (Quality Gate Auto-Fix)
 The moment you finish coding, DO NOT proceed further. Switch to `references/quality-gate.md` and run the automatic review loop.
 **Mantra:** All feedback from code-auditor must be addressed thoroughly: Score >= 9.5 & Zero Critical issues.
 
 - Passing Step 4 requires ALL of the following:
-  1. Automated verification passes, including every exact command named in the task's `Verification & Evidence` section
+  1. Automated verification passes, including preflight compile/typecheck/build health and every exact command named in the task's `Verification & Evidence` section
   2. Code review passes
   3. Task evidence passes (artifacts/runtime surfaces/negative-path checks from the task file are proven)
+- `PRECHECK_FAIL` outranks `NO_TESTS`. If compile/typecheck/build fails, the task is FAIL even when no test suite exists yet.
 - `NO_TESTS` is NOT equivalent to PASS. If the task explicitly requires a test command or automated test proof, `NO_TESTS` is a FAIL or BLOCKED outcome until the requirement is satisfied or the spec is corrected.
 - If build/test passes but task evidence is missing, the task is still FAIL.
+- If the implementation silently replaced a named contract choice or relies on cross-service process-local stand-ins, the task is still FAIL.
 - Only escalate to the user after 3 consecutive failed review rounds.
 
 ### Step 5: State Sync + Task-Level Docs Sync
@@ -124,7 +135,8 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
   - `spec.json.task_registry[path].status = "done"`
   - `completed_at` + `last_updated_at`
   - synchronized top-level `updated_at`
-  - a human-readable verification receipt inside the task's `Verification & Evidence` section showing which commands ran and what proof was observed
+  - a human-readable verification receipt inside the task's `Verification & Evidence` section showing which commands ran, their outcomes, and what proof was observed
+- Verification receipts with `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation intentionally simplified a named contract MUST NOT be synchronized as `done`.
 - After syncing the active task, run a **Task Closeout Docs Checkpoint**
 - Task Closeout Docs Checkpoint:
   - Evaluate `Docs impact: none | minor | major` based on real behavior changes from the just-completed task

package/src/claude/skills/develop/references/quality-gate.md

@@ -10,9 +10,12 @@ Green tests are NOT enough. The gate requires three proofs:
 ## Automation Semantics
 
 - If the task names exact commands in `Verification & Evidence`, those exact commands are mandatory and must run before any fallback repo defaults.
+- Preflight compile/typecheck/build health is mandatory. If compile/typecheck/build fails before tests are meaningful, the gate result is `PRECHECK_FAIL`, not `NO_TESTS`.
 - `NO_TESTS` is never an automatic PASS.
 - `NO_TESTS` is acceptable only when the task does **not** require a dedicated test suite command and every other required automated command/evidence item passes.
 - If the task explicitly requires tests and the repo has no such test command or suite, the task is FAIL or BLOCKED, not done.
+- Named frameworks, auth systems, transports, datastores, and runtime boundaries in the task/spec are contractual. Silent substitutions are review failures, not acceptable implementation trade-offs.
+- Multi-process or multi-runtime flows must prove shared real state or a real boundary contract. Matching in-memory placeholders on both sides do not count as working integration.
 
 ## Parallel Quality Cycle
 
@@ -33,11 +36,11 @@ START_LOOP:
   PARALLEL GATE: Spawn BOTH agents simultaneously
   ---------------------------------------------------------------
   → Task(subagent_type="test-runner",
-        prompt="Run task-aware verification for the recently implemented code. Read the active task file(s) and execute the exact verification commands named there first, in order. After that, run any additional repo-level typecheck/test/build checks needed for confidence. Inspect named artifacts/runtime outputs. Return PASS only if automated checks and task evidence both pass. Mark anything unexecuted as UNVERIFIED. Treat NO_TESTS as non-passing unless the task did not require a dedicated test suite.",
+        prompt="Run task-aware verification for the recently implemented code. Read the active task file(s) and execute the exact verification commands named there first, in order. Preflight compile/typecheck/build failures must be reported as PRECHECK_FAIL and take precedence over NO_TESTS. After that, run any additional repo-level typecheck/test/build checks needed for confidence. Inspect named artifacts/runtime outputs. For multi-service tasks, verify the flow does not rely on process-local stand-ins masquerading as shared state. Return PASS only if automated checks and task evidence both pass. Mark anything unexecuted as UNVERIFIED. Treat NO_TESTS as non-passing unless the task did not require a dedicated test suite.",
         description="Test [feature]")
 
   → Task(subagent_type="code-auditor",
-        prompt="Review all recently written code against the active task file(s), referenced requirements, and design contracts. Missing deliverables, placeholder-only wiring, missing runtime entrypoints, overscope edits outside the task packet, or contract drift are Critical even if build/tests pass. Check security, logic, architecture, YAGNI/KISS/DRY. Return score (X/10), critical count, warning list, and evidence gaps.",
+        prompt="Review all recently written code against the active task file(s), referenced requirements, and design contracts. Missing deliverables, placeholder-only wiring, missing runtime entrypoints, overscope edits outside the task packet, silent replacement of named technologies/contracts, or fake cross-service proof via process-local state are Critical even if build/tests pass. Check security, logic, architecture, YAGNI/KISS/DRY. Return score (X/10), critical count, warning list, and evidence gaps.",
         description="Review [feature]")
 
   Wait for BOTH to return results.
@@ -46,7 +49,7 @@ START_LOOP:
   COMBINE RESULTS
   ---------------------------------------------------------------
 
-  CASE 1 — Automated FAIL OR required command missing OR Evidence FAIL / UNVERIFIED OR NO_TESTS when tests were required:
+  CASE 1 — PRECHECK_FAIL OR Automated FAIL OR required command missing OR Evidence FAIL / UNVERIFIED OR NO_TESTS when tests were required:
     - Increment retry_count++
     - If retry_count >= 3:
         → COLLAPSE! AskUserQuestion: "Quality gate cannot prove this task is complete! User intervention required!"
@@ -86,6 +89,8 @@ REVIEW_ONLY:
 - **Principles:** YAGNI violations, KISS violations, DRY violations (excessive code duplication).
 - **Evidence / Done-Criteria Drift:** Missing required artifacts, placeholder-only wiring, missing entrypoints, unproven completion criteria, or runtime contract mismatches.
 - **Overscope Delivery Drift:** Implementing later-task deliverables or editing out-of-scope files without direct justification for the active task.
+- **Contract Substitution Drift:** Replacing a named framework/auth/transport/datastore/runtime boundary with a custom simplification without a spec amendment.
+- **Cross-Service Reality Failure:** Claiming end-to-end behavior across web/api/worker/extension boundaries while state only exists in local process memory or placeholder adapters.
 
 ## Terminal Log Format
 
@@ -93,5 +98,6 @@ Must log the Quality Gate result to the terminal for user visibility:
 
 - **Quick Pass:** `✓ Step 4 Quality Gate: Test PASS + Evidence PASS + Review 9.5/10 - Auto-Approved`
 - **Hard-Won Pass:** `✓ Step 4 Quality Gate: Failed 2 rounds → Test PASS + Evidence PASS + Review 9.6/10`
+- **Preflight Fail:** `[x] Step 4 Quality Gate: PRECHECK_FAIL → compile/typecheck/build failed before tests mattered`
 - **Fix Needed:** `[~] Step 4 Quality Gate: Tests/evidence failed → returned to god-developer`
 - **Awaiting Rescue:** `[!] Step 4 Quality Gate: Failed 3 rounds! Awaiting user intervention...`

package/src/claude/skills/research/SKILL.md

@@ -23,11 +23,11 @@ Call the `TaskCreate` tool to spin up the `researcher` subagent.
 **Instructions to pass to Researcher:**
 ```text
 Conduct comprehensive research on: [topic]
-Constraint 1: ALWAYS use `node .claude/scripts/web-search.cjs "[query]"` as the EXCLUSIVE primary search method. This tool uses Gemini Grounding and returns a synthesized answer + cited sources. Do NOT manually crawl source URLs if the script provides a sufficient answer.
-Constraint 2: TRUST THE SYNTHESIS. The output contains the research results. Read the JSON and use the `answer` field directly. Do NOT write Python scripts to re-parse it or manually `Fetch` sources unless deep implementation details are missing.
-Constraint 3: Use native WebSearch or manual Fetch ONLY if the script fails or returns no results.
+Constraint 1: ALWAYS use native `WebSearch` as the primary search method.
+Constraint 2: Validate key claims with multiple credible sources. Prioritize official docs, maintainers, release notes, and strong production references.
+Constraint 3: Use direct `WebFetch` only when search results are insufficient or raw source inspection is required.
 Constraint 4: Limit total search calls to a maximum of 5 distinct queries.
-Constraint 5: Stop excessive "chain-searching". Use the grounding answer as the definitive summary.
+Constraint 5: Stop excessive "chain-searching". Synthesize decisively once the evidence is sufficient.
 Output Format: Must strictly follow the 'Standard Research Report' layout.
 ```
 

package/src/claude/skills/sync/references/sync-protocols.md

@@ -16,6 +16,8 @@ When requested to update a phase or change task configuration, `spec.json` must
 *   **Status Update:** If a task changes to `blocked`, the matching `task_registry[path].status` must become `"blocked"`, `task_registry[path].blocker` must record the reason, and `spec.json.status` / `spec.json.blocker` must reflect the top-level block if work is globally blocked.
 *   **Timestamp Rule:** Update `task_registry[path].started_at`, `completed_at`, and `last_updated_at` consistently with the new state. Also refresh `spec.json.updated_at`.
 *   **Done-State Rule:** Never set `task_registry[path].status = "done"` unless the matching markdown task file already contains a verification receipt in `## Verification & Evidence`, or the caller explicitly provides proof that can be written there first.
+*   **Receipt Integrity Rule:** A valid verification receipt must include the exact commands run, their outcomes, and artifact/runtime proof. Receipts containing `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit "placeholder / simplified for MVP / production later" contract deviations are not eligible for `done`.
+*   **Contract Fidelity Rule:** If the task file notes or evidence show that a named framework/auth/runtime choice from the spec was silently replaced, sync MUST refuse `done` until the spec is amended or the implementation is corrected.
 *   **Task Docs Rule:** After a task is moved to `done`, emit a short alert that a task-level docs checkpoint is due for this verified task.
 
 ## 2. Updating `tasks/task-**.md`
@@ -26,11 +28,12 @@ The structure of `tasks/task.md` relies heavily on exact keyword markers. Follow
 When `/hapo:sync <feature> <task-id> done`:
 1. Find: `**Status:** pending` (or `in_progress` / `blocked`).
 2. Inspect `## Verification & Evidence` first. If it has no explicit proof lines (commands run, artifact proof, runtime proof, or blockers cleared), STOP and refuse to mark the task done.
-3. Replace with: `**Status:** done`.
-4. Locate block: `## Implementation Steps`.
-5. Convert `- [ ]` into `- [x]` strictly within that section.
-6. Update relevant checkboxes in `## Completion Criteria` and `## Verification & Evidence` only when the caller provides or the file already contains real proof.
-7. Surface a note such as: `Docs checkpoint due: task Rn-mm just completed`.
+3. Refuse completion if the receipt contains any non-passing marker such as `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation substituted a named contract with a placeholder/custom simplification.
+4. Replace with: `**Status:** done`.
+5. Locate block: `## Implementation Steps`.
+6. Convert `- [ ]` into `- [x]` strictly within that section.
+7. Update relevant checkboxes in `## Completion Criteria` and `## Verification & Evidence` only when the caller provides or the file already contains real proof.
+8. Surface a note such as: `Docs checkpoint due: task Rn-mm just completed`.
 
 ### B. Blocking a Task
 When `/hapo:sync <feature> <task-id> blocked "API error"`:
@@ -57,5 +60,6 @@ When `/hapo:sync audit <feature>` is activated:
    - Markdown says `done` but registry not done → registry wins only if evidence already exists; otherwise downgrade markdown or flag conflict
    - Registry says `done` but markdown still pending → update markdown only if evidence exists
    - Either side says `done` but `## Verification & Evidence` has no concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
+   - Either side says `done` but the receipt contains `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit contract-substitution notes → downgrade to `in_progress` or flag conflict
 5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.
 6. **Task Docs Alert:** If audit reveals tasks newly marked `done`, include whether task-level docs sync appears still due or already accounted for in the current run summary.

package/src/claude/scripts/docs-fetch.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-/**
- * Native Docs Fetcher
- * Aggregates extraction of `llms.txt` patterns from context7.com (Unified logic).
- * Usage: node docs-fetch.js "How to use Next.js App router"
- */
-
-const https = require('https');
-
-function fetchUrl(url) {
-  return new Promise((resolve) => {
-    https.get(url, { headers: { 'User-Agent': 'Docs-Fetcher' } }, (res) => {
-      let data = '';
-      res.on('data', chunk => data += chunk);
-      res.on('end', () => resolve({ status: res.statusCode, data }));
-    }).on('error', () => resolve({ status: 500, data: null }));
-  });
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  if (args.length === 0) {
-    console.error('[Docs Fetcher] Error: Explicit query parameter required. (Example: node docs-fetch.js "next.js router")');
-    process.exit(1);
-  }
-
-  const query = args.join(' ').toLowerCase();
-
-  // Smart Detection (Keyword mapping index)
-  const knownLibs = {
-    'next.js': 'vercel/next.js',
-    'nextjs': 'vercel/next.js',
-    'react': 'facebook/react',
-    'shadcn': 'shadcn-ui/ui',
-    'shadcn/ui': 'shadcn-ui/ui',
-    'astro': 'withastro/astro',
-    'remix': 'remix-run/remix'
-  };
-
-  let targetRepo = '';
-  for (const [key, repo] of Object.entries(knownLibs)) {
-    if (query.includes(key)) {
-      targetRepo = repo;
-      break;
-    }
-  }
-
-  // Heuristic string fallback matching for "docs for abc" sequences
-  if (!targetRepo) {
-    const fallbackMatch = query.match(/for ([a-z0-9-]+)/);
-    if (fallbackMatch) targetRepo = `websites/${fallbackMatch[1]}`;
-    else targetRepo = `websites/${query.split(' ')[0]}`; // Fallback primitive string assumption
-  }
-
-  const url = `https://context7.com/${targetRepo}/llms.txt`;
-  console.log(`[Docs Fetcher] Interrogating Knowledge Archival Node at: ${url}`);
-
-  const fallbackUrl = `https://raw.githubusercontent.com/${targetRepo}/main/README.md`;
-
-  const result = await fetchUrl(url);
-
-  if (result.status === 200 && result.data) {
-    console.log('\n--- SUCCESSFUL PAYLOAD EXTRACTED ---');
-    // Buffer restriction truncation
-    console.log(result.data.substring(0, 3000));
-    console.log('\n(Output truncated cleanly to minimize LLM Context Overload)');
-  } else {
-    console.warn(`[!] Architectural layout llms.txt missing at: ${url}`);
-    console.log(`[+] Executing GitHub default branch failover (README.md mapping): ${fallbackUrl}`);
-    const fbResult = await fetchUrl(fallbackUrl);
-    if (fbResult.status === 200 && fbResult.data) {
-      console.log('\n--- PAYLOAD EXTRACTED (README.md) ---');
-      console.log(fbResult.data.substring(0, 3000));
-    } else {
-      console.error('\n[FATAL] Documentation retrieval failure. No corresponding books identified within known databanks. Agent must fall back to utilizing standard WebSearch mapping via DuckDuckGo execution streams!');
-      process.exit(1);
-    }
-  }
-}
-
-main();

package/src/claude/scripts/web-search.cjs

@@ -1,211 +0,0 @@
-#!/usr/bin/env node
-/**
- * Web Search via Gemini API + Google Search Grounding
- * Fallback search tool for models without native WebSearch capability.
- *
- * Usage:
- *   node web-search.cjs "your search query here"
- *   node web-search.cjs --multi "query1" "query2" "query3"
- *
- * Requires: GEMINI_API_KEY in .claude/.env or environment
- *
- * Output: JSON-structured search results with sources and citations.
- */
-
-const https = require('https');
-const path = require('path');
-const fs = require('fs');
-
-// ---------------------------------------------------------------------------
-// ENV Resolution: .claude/.env → process.env
-// ---------------------------------------------------------------------------
-function loadEnv() {
-  const envPaths = [
-    path.join(process.cwd(), '.claude', '.env'),
-    path.join(process.cwd(), '..', '.claude', '.env'),
-  ];
-
-  for (const envPath of envPaths) {
-    try {
-      if (fs.existsSync(envPath)) {
-        const content = fs.readFileSync(envPath, 'utf8');
-        content.split(/\r?\n/).forEach(line => {
-          const match = line.match(/^([^=]+)=(.*)$/);
-          if (match) {
-            const key = match[1].trim();
-            const val = match[2].trim().replace(/^["']|["']$/g, '');
-            // Only set if not already present in environment
-            if (process.env[key] === undefined) {
-              process.env[key] = val;
-            }
-          }
-        });
-        return; // Loaded successfully, no need to check other paths
-      }
-    } catch { /* skip */ }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Gemini API Call with Google Search Grounding
-// ---------------------------------------------------------------------------
-function callGemini(apiKey, query, model) {
-  return new Promise((resolve, reject) => {
-    const payload = JSON.stringify({
-      contents: [{ parts: [{ text: query }] }],
-      tools: [{ googleSearch: {} }],
-      generationConfig: {
-        temperature: 0.1,
-        maxOutputTokens: 4096,
-      }
-    });
-
-    const options = {
-      hostname: 'generativelanguage.googleapis.com',
-      path: `/v1beta/models/${model}:generateContent?key=${apiKey}`,
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Content-Length': Buffer.byteLength(payload),
-      },
-    };
-
-    const req = https.request(options, (res) => {
-      let data = '';
-      res.on('data', chunk => data += chunk);
-      res.on('end', () => {
-        try {
-          const json = JSON.parse(data);
-          if (json.error) {
-            reject(new Error(`Gemini API Error: ${json.error.message}`));
-            return;
-          }
-          resolve(json);
-        } catch (e) {
-          reject(new Error(`Failed to parse Gemini response: ${e.message}`));
-        }
-      });
-    });
-
-    req.on('error', reject);
-    req.write(payload);
-    req.end();
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Resolve Vertex AI grounding redirect URLs to real URLs
-// ---------------------------------------------------------------------------
-function resolveRedirectUrl(url) {
-  return new Promise((resolve) => {
-    if (!url || !url.includes('grounding-api-redirect')) {
-      resolve(url);
-      return;
-    }
-
-    const protocol = url.startsWith('https') ? https : require('http');
-    const req = protocol.request(url, { method: 'HEAD', timeout: 5000 }, (res) => {
-      // Follow redirect chain - Location header has the real URL
-      resolve(res.headers.location || url);
-    });
-    req.on('error', () => resolve(url));
-    req.on('timeout', () => { req.destroy(); resolve(url); });
-    req.end();
-  });
-}
-
-async function resolveAllUrls(sources) {
-  return Promise.all(sources.map(async (src) => {
-    const realUrl = await resolveRedirectUrl(src.url);
-    return { ...src, url: realUrl };
-  }));
-}
-
-// ---------------------------------------------------------------------------
-// Parse Grounding Metadata → Structured Output
-// ---------------------------------------------------------------------------
-async function parseResponse(geminiResponse, query) {
-  const candidate = geminiResponse.candidates?.[0];
-  if (!candidate) return { query, error: 'No candidates returned' };
-
-  const text = candidate.content?.parts?.map(p => p.text).join('\n') || '';
-  const meta = candidate.groundingMetadata || {};
-
-  // Extract source URLs from groundingChunks
-  let sources = (meta.groundingChunks || []).map(chunk => ({
-    title: chunk.web?.title || 'Unknown',
-    url: chunk.web?.uri || '',
-  }));
-
-  // Resolve redirect URLs to real URLs
-  sources = await resolveAllUrls(sources);
-
-  // Deduplicate by resolved URL
-  const seen = new Set();
-  sources = sources.filter(s => {
-    if (seen.has(s.url)) return false;
-    seen.add(s.url);
-    return true;
-  });
-
-  // Extract search queries used by the model
-  const searchQueries = meta.webSearchQueries || [];
-
-  return {
-    query,
-    answer: text,
-    searchQueriesUsed: searchQueries,
-    sources,
-    sourceCount: sources.length,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-async function main() {
-  const args = process.argv.slice(2);
-  const isMulti = args[0] === '--multi';
-  const queries = isMulti ? args.slice(1) : [args.join(' ')];
-
-  if (queries.length === 0 || (queries.length === 1 && !queries[0])) {
-    console.error(JSON.stringify({
-      error: 'Usage: node web-search.cjs "your query" | node web-search.cjs --multi "q1" "q2"'
-    }));
-    process.exit(1);
-  }
-
-  loadEnv();
-  const apiKey = process.env.GEMINI_API_KEY;
-  if (!apiKey) {
-    console.error(JSON.stringify({
-      error: 'GEMINI_API_KEY not found. Set it in .claude/.env or environment variable.'
-    }));
-    process.exit(1);
-  }
-
-  // Determine which model to use. User might configure MODEL or VISUAL_MODEL in their .env
-  let model = process.env.SEARCH_MODEL || process.env.MODEL || process.env.VISUAL_MODEL || 'gemini-2.5-flash';
-
-  // Google Search Grounding ONLY supports Gemini models (not Claude, not Gemma)
-  if (!model.toLowerCase().includes('gemini') && !model.toLowerCase().includes('learnlm')) {
-    model = 'gemini-2.5-flash'; // Fallback to safe search model
-  }
-
-  const results = [];
-
-  for (const query of queries) {
-    try {
-      const raw = await callGemini(apiKey, query, model);
-      results.push(await parseResponse(raw, query));
-    } catch (err) {
-      results.push({ query, error: err.message });
-    }
-  }
-
-  // Output as JSON for agent consumption
-  const output = isMulti ? results : results[0];
-  console.log(JSON.stringify(output, null, 2));
-}
-
-main();