@event4u/agent-config 9.7.0 → 9.9.0

package/docs/hook-payload-capture.md

@@ -1,221 +0,0 @@
-# Hook payload capture guide
-
-**Purpose:** walk through the live-session payload capture for one platform
-in roughly 5 minutes, so the corresponding entry in
-[`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
-can move from `docs-verified` to `payload-verified`.
-
-**Scope:** Cursor · Cline · Windsurf · Gemini CLI. Augment Code and Claude
-Code already shipped as `docs-verified` in Phase 1 of the now-archived
-[`road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md).
-Cowork is upstream-blocked separately
-([`#40495`](https://github.com/anthropics/claude-code/issues/40495)) and
-not in scope here.
-
-**Why this is opportunistic:** the payload-verified upgrade is a nice-to-have.
-The shipping `docs-verified` extractors already match the vendor docs —
-captures are insurance against silent vendor-side schema drift. Pick one
-platform when convenient; do not run all four in one sitting unless you
-already have all four IDEs installed and licensed.
-
-## Pre-flight (one-time, ~30 seconds)
-
-```bash
-cd /path/to/agent-config
-
-# Confirm the dispatcher is wired in this project (idempotent — safe to rerun).
-# Replace <platform> with cursor / cline / windsurf / gemini as appropriate
-# when you reach that platform's section.
-npx @event4u/agent-config install --<platform>
-
-# Confirm the trampoline + project-scope hooks file landed.
-./agent-config hooks:status | grep -E "^[ ✓✅⚠️❌·] (cursor|cline|windsurf|gemini)"
-```
-
-`hooks:status` should report `installed` for the platform you just wired
-(or `missing` if the project-scope file did not land — in that case rerun
-the install with `--force`).
-
-## Common capture loop (steps reused on every platform)
-
-```bash
-# 1. Pick a per-platform capture dir (gitignored; never committed).
-export AGENT_HOOK_CAPTURE_DIR="$HOME/.agent-config-captures/<platform>"
-mkdir -p "$AGENT_HOOK_CAPTURE_DIR"
-
-# 2. Restart / reload the platform so it picks up the env var.
-#    Per-platform commands below.
-
-# 3. Run ONE short, boring session in the platform.
-#    Recommended prompt: "echo hello" or "what time is it".
-#    Goal is to capture the envelope shape, not interesting content.
-
-# 4. Confirm capture files exist.
-ls -1 "$AGENT_HOOK_CAPTURE_DIR" | head
-
-# 5. Redact (replaces user-content fields with <REDACTED>;
-#    envelope keys preserved).
-./scripts-run src/scripts/redact_hook_capture "$AGENT_HOOK_CAPTURE_DIR" --strict
-
-# 6. Pick the smallest representative file.
-ls -1Sr "$AGENT_HOOK_CAPTURE_DIR"/*.redacted.json | head -1
-
-# 7. cat it; copy the JSON; paste into the archived roadmap section
-#    (see § Where to paste below).
-```
-
-The redaction step is non-negotiable. The goal is to lock schemas, not to
-archive conversations.
-
-## Per-platform notes
-
-### Cursor (~5 min)
-
-- **Install:** `npx @event4u/agent-config install --cursor` (project) or
-  `--cursor-user-hooks` (covers every project you open).
-- **Restart:** quit Cursor (Cmd+Q on macOS), then relaunch from the
-  shell where you exported `AGENT_HOOK_CAPTURE_DIR` so the env var
-  propagates to the renderer process. Reopening a window from the
-  Dock will not inherit the env.
-- **Trigger event:** type a prompt in Cursor's agent panel and let it
-  finish. Expected captures: one `sessionStart`, one
-  `beforeSubmitPrompt`, one `afterAgentResponse` and/or `stop`,
-  zero or more `postToolUse`.
-- **File pattern:** `cursor__afterAgentResponse__<ts>__<pid>.json` is
-  the most useful one to paste.
-- **CLI vs IDE:** Cursor CLI fires only
-  `beforeShellExecution`/`afterShellExecution` — for the
-  per-turn payload you need the IDE.
-
-### Cline (~5 min)
-
-- **Install:** `npx @event4u/agent-config install --cline` (project) or
-  `--cline-user-hooks` (user-scope, covers every workspace).
-- **Restart:** in VS Code or JetBrains, run "Developer: Reload
-  Window" (Cmd+Shift+P) from a terminal where the env is exported.
-  Cline reads hooks at task start, so a fresh task is required —
-  closing and reopening the side panel is not enough.
-- **Trigger event:** start a new Cline task and let one turn complete.
-  Cline calls them "tasks" not "sessions"; the equivalent boundaries
-  are `TaskStart` → `UserPromptSubmit` → `PostToolUse`* →
-  `TaskComplete`.
-- **File pattern:** `cline__TaskComplete__<ts>__<pid>.json` if you let
-  the task finish; `cline__UserPromptSubmit__<ts>__<pid>.json` is also
-  acceptable (carries the `prompt` envelope).
-- **Windows caveat:** hooks are unsupported on Windows
-  ([`cline/cline#8073`](https://github.com/cline/cline/issues/8073));
-  capture from macOS or Linux.
-
-### Windsurf (~5 min)
-
-- **Install:** `npx @event4u/agent-config install --windsurf` (project) or
-  `--windsurf-user-hooks` (user-scope at `~/.codeium/windsurf/hooks.json`).
-- **Restart:** quit Cascade fully, then relaunch from the shell with
-  the env exported. The `pre_user_prompt` event fires on every turn —
-  no full restart needed once Cascade is up, but the *first* turn after
-  launch must be the captured one.
-- **Trigger event:** ask Cascade one short question and let it answer.
-  Expected captures: `pre_user_prompt`,
-  `post_cascade_response_with_transcript`. The
-  `_with_transcript` variant is the more useful one to paste because it
-  carries the full response inline.
-- **File pattern:** `windsurf__post_cascade_response_with_transcript__<ts>__<pid>.json`.
-- **Async caveat:** `post_cascade_response` fires asynchronously off
-  the critical path. The capture file might land a second or two after
-  the response renders — wait briefly before running the redact step.
-
-### Gemini CLI (~5 min)
-
-- **Install:** `npx @event4u/agent-config install --gemini` (project) or
-  `--gemini-user-hooks` (user-scope at `~/.gemini/settings.json`).
-- **Restart:** Gemini CLI is invoked per command — no daemon to
-  restart. Just open a new shell with `AGENT_HOOK_CAPTURE_DIR`
-  exported and run the next session there.
-- **Trigger event:** any short Gemini CLI session
-  (`gemini "what time is it"` or similar). Hooks fire on
-  `SessionStart` → `BeforeAgent` → `AfterTool`* → `AfterAgent` →
-  `SessionEnd`.
-- **File pattern:** `gemini__AfterAgent__<ts>__<pid>.json` carries the
-  per-turn close envelope and is the recommended paste target.
-- **Advisory hooks:** `SessionStart` and `SessionEnd` are advisory only
-  in Gemini CLI — do not be alarmed if those captures look thinner than
-  the others.
-
-## Where to paste the redacted payload
-
-The roadmap is now archived. Paste under the matching phase:
-
-[`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)
-
-- Cursor → § Phase 2 — Cursor
-- Cline → § Phase 3 — Cline
-- Windsurf → § Phase 4 — Windsurf
-- Gemini CLI → § Phase 5 — Gemini CLI
-
-In the chosen phase, paste the redacted JSON inside a fenced
-`json` block under a heading like `### <Platform> payload shape (captured 2026-MM-DD)`,
-then flip the `[ ] Optional upgrade — payload-verified` checkbox to
-`[x]`.
-
-Then update the matching row in
-[`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md):
-the `Verification` column moves from `docs-verified` to
-`payload-verified`.
-
-If the captured shape diverges from the docs-verified extractor
-branch, that is the trigger for a code patch — open a tiny new roadmap
-under `agents/roadmaps/` for the divergence work, do **not** edit the
-archived roadmap to track new code work
-(see [`no-roadmap-references`](../dist/agent-src/rules/no-roadmap-references.md)).
-
-## Final verify
-
-After pasting and flipping the checkbox:
-
-```bash
-# Lint gates must stay green.
-./scripts-run src/scripts/lint_hook_manifest
-./scripts-run src/scripts/check_references
-./scripts-run src/scripts/check_portability
-
-# Tests still green.
-node node_modules/.bin/vitest run tests/scripts/hooks/ -q
-
-# Optional: regenerate the dashboard if the archived roadmap's
-# checkbox change should bubble up. Iron Law from
-# `roadmap-progress-sync` says yes if it does.
-./agent-config roadmap:progress
-```
-
-Per
-[`commit-policy`](../dist/agent-src/rules/commit-policy.md):
-do **not** commit unless explicitly told to. The user owns the commit
-step.
-
-## Cleanup after capture
-
-```bash
-# Raw captures (not redacted) contain real prompt content.
-# Either delete the directory or leave it for repeat captures.
-rm -rf "$AGENT_HOOK_CAPTURE_DIR"
-
-# Or keep redacted ones only:
-# find "$AGENT_HOOK_CAPTURE_DIR" -type f ! -name '*.redacted.json' -delete
-
-# Unset the env var when done so subsequent sessions do not capture.
-unset AGENT_HOOK_CAPTURE_DIR
-```
-
-The capture directory is gitignored project-wide; raw captures are
-never accidentally committed. The redaction step is still mandatory
-before paste because the redacted output goes into a tracked file
-(the archived roadmap) and would otherwise leak.
-
-## Sources
-
-- Capture engine: [`scripts/hooks/dispatch_hook.py`](../src/scripts/hooks/dispatch_hook.py) — `_maybe_capture_payload`
-- Redactor: [`scripts/redact_hook_capture.py`](../src/scripts/redact_hook_capture.py)
-- Per-platform install logic: [`scripts/install.py`](../src/scripts/install.py) — search `ensure_<platform>_bridge` / `ensure_<platform>_user_hooks`
-- Platform matrix + payload schemas: [`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
-- Hook architecture: [`docs/contracts/hook-architecture-v1.md`](contracts/hook-architecture-v1.md)
-- Archived roadmap with per-phase paste sections: [`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)

package/docs/install-friction-report.md

@@ -1,66 +0,0 @@
----
-status: template — awaiting sessions (no real data yet)
-study: install-friction (B9)
-recruits_target: 3
----
-
-# Install-friction report (B9)
-
-> **Template — not yet run.** This file carries the Gate-C read for the wedge
-> install. It holds **no real data** until ≥ 3 external Laravel/TS developers
-> have completed the study per
-> [`agents/recruit-sessions/_install-friction-runbook.md`](../agents/recruit-sessions/_install-friction-runbook.md).
-> Do not cite the placeholder numbers below as findings.
-
-## What this measures
-
-Can an external developer — not on the maintainer team, no prior exposure —
-install the `production-validator` wedge and reach first value (a real verdict
-on their own code) in **< 60 s**, unaided, without abandoning? That is the
-Gate-C signal. Method: observed, timed, wedge-only (see the runbook).
-
-## Per-recruit results
-
-> One row per recruit. `TTFV` = time-to-first-value in seconds ("—" if
-> abandoned). `outcome` ∈ completed · completed-with-rescue · abandoned.
-> Real names never appear (R1/R2/R3); raw notes stay private with the recording.
-
-| recruit | stack | TTFV (s) | outcome | abandonment point | top friction |
-|---|---|---|---|---|---|
-| R1 | _tbd_ | _tbd_ | _tbd_ | _tbd_ | _tbd_ |
-| R2 | _tbd_ | _tbd_ | _tbd_ | _tbd_ | _tbd_ |
-| R3 | _tbd_ | _tbd_ | _tbd_ | _tbd_ | _tbd_ |
-
-## Aggregate
-
-| metric | value | Gate-C threshold |
-|---|---|---|
-| Median TTFV | _tbd_ s | ≤ 60 s |
-| Abandonment rate | _tbd_ % | ≤ 20 % |
-| Clean completions (no rescue) | _tbd_ / _n_ | — |
-
-## Top-3 friction points
-
-> Ranked by how many recruits hit each. Each cites the redacted verbatim moment
-> that named it (timestamp against the private recording).
-
-1. _tbd_ — hit by _N_/_n_ recruits. Quote: _tbd_. Fix: _tbd_.
-2. _tbd_
-3. _tbd_
-
-## Gate-C verdict
-
-```
-PASS  ⇔  median TTFV ≤ 60 s  AND  abandonment rate ≤ 20 %.
-FAIL  →  iterate on the wedge install before finalizing C2. Do not ship a failed wedge.
-```
-
-- **Verdict:** _tbd (PASS / FAIL)_ — filled once the aggregate is real.
-- On **FAIL**, the top-3 friction points above are the exact iteration targets;
-  re-run the study after the fix. A failed gate is a finding, not a stopper.
-
-## Provenance
-
-- Protocol: [`agents/recruit-sessions/_install-friction-runbook.md`](../agents/recruit-sessions/_install-friction-runbook.md).
-- Consent + redaction: [`agents/recruit-sessions/README.md`](../agents/recruit-sessions/README.md) § "Consent + redaction policy".
-- Recordings + raw per-recruit notes: private (not in-repo), per the redaction policy.