chore(papercuts): prune environment noise + tighten the skill (#389)

.agents/PAPERCUTS.md

@@ -1,23 +1,18 @@
 # Papercuts
 
-Small, non-blocking friction encountered while working in this repository. Log it in the moment; review and fix entries in a separate, user-requested cleanup pass.
+Small, non-blocking friction in the repository itself — the kind that will
+waste the next contributor's time too. Log it in the moment; review and fix
+entries in a separate, user-requested cleanup pass.
 
-This is not a completed-work log or a bug tracker. Never include secrets, credentials, personal data, or raw customer payloads.
+This is not a completed-work log, a bug tracker, or a place for the agent's own
+sandbox/shell/network hiccups. Never include secrets, credentials, personal
+data, or sensitive paths.
 
 ## Open
 
-- [ ] `2026-07-11T21:38:29Z` — `codex` — While visually testing the BadSEO design lab, a stale local process still held the configured port 8787, so Vite silently moved the app to 8788. Make the active preview URL more visible in the normal workflow or provide a reliable task-local server cleanup step.
-- [ ] `2026-07-10T21:32:49Z` — `codex` — While starting the BadSEO TanStack/Cloudflare dev server in a sandbox, the Cloudflare Vite plugin failed with `listen EPERM` while probing its inspector port, even though the app port was otherwise valid. Document the need for elevated local port binding or provide an inspector-disabled validation command.
-- [ ] `2026-07-10T21:28:46Z` — `codex` — While validating the standalone BadSEO package after merging its TanStack migration, `pnpm --dir badseo run typecheck` appeared to work through the root toolchain but `pnpm --dir badseo run build` could not find Vite because `badseo/node_modules` was absent. Document or enforce the required package-local install before validation.
-- [ ] `2026-07-10T22:32:40Z` — `codex` — While running the badseo audit from the workspace, sandboxed TSX failed with `listen EPERM` when creating its IPC socket under the temporary directory. Rerunning the same audit with local IPC permission succeeded; provide a sandbox-compatible TSX invocation for validation scripts.
-- [ ] `2026-07-10T22:23:50Z` — `codex` — While pushing the consent-banner refinement to PR #380, the SSH push hung without output and a separate remote verification hung as well; retrying the same push succeeded immediately. Surface an actionable SSH timeout or connection error instead of waiting indefinitely.
-- [ ] `2026-07-10T21:36:27Z` — `codex` — While using the repository's `webapp-testing` skill, its required Python Playwright import was unavailable in both system and bundled Python. The bundled Node Playwright runtime completed the check; document or provide that fallback, including Cloudflare Vite's default port 8787 rather than Vite's usual 5173.
-- [ ] `2026-07-10T21:32:10Z` — `codex` — While formatting the standalone `badseo` workspace, `pnpm exec prettier` failed because Prettier is only available from the repository root. Document the root-only formatter command or expose a workspace-local formatting script.
-- [ ] `2026-07-11T15:13:43Z` — `codex` — While inspecting a BadSEO merge with login-shell commands, zsh printed `(eval):5: parse error near \`end'` before otherwise successful Git output. Running the same commands with login-shell initialization disabled avoided the noise; identify and fix the malformed shell startup hook.
-- [ ] `2026-07-11T15:15:13Z` — `codex` — While resolving a merge from the sandboxed BadSEO subdirectory, `git add` could not create the parent worktree's `index.lock` despite the merge itself being allowed. Staging required the approved elevated Git path; align the workspace write boundary with the actual Git worktree root.
-- [ ] `2026-07-10T21:09:27Z` — `codex` — While building the TanStack/Cloudflare badseo app, Wrangler reported an EPERM writing its debug log under the user preferences directory even though the build succeeded. Set `WRANGLER_LOG_PATH` to a writable temporary path in sandboxed build commands or make the logging failure non-fatal and quiet.
-- [ ] `2026-07-10T17:53:20Z` — `codex` — While validating `.greptile/`, both `pnpm exec prettier --check` and the existing `pnpm format:check` attempted to reconcile `node_modules` and aborted because no TTY was available. Calling `node_modules/.bin/prettier` performed the non-installing check successfully; the agent/CI path needs a stable way to run package scripts without an interactive modules purge.
-- [ ] `2026-07-10T18:12:35Z` — `codex` — While validating referenced files in zsh, using `path` as a loop variable overwrote zsh's special `path` array and made commands such as `git`, `jq`, and `sed` appear missing later in the same shell. Use a neutral name such as `file_path` in shell loops.
+- [ ] `2026-07-14T01:28:30Z` — `claude` — Regenerating the lockfile (adding or moving a dep) makes `pnpm install` re-run the `minimumReleaseAge` gate on transitive peers already pinned at that exact version (`mysql2`, `sql-escaper`, `@aws-sdk/credential-providers`), failing the install even though nothing about them changed. `pnpm install --config.minimumReleaseAge=0` — then confirm the lockfile diff stays version-neutral — unblocks it; worth documenting that regen step so the gate doesn't re-block already-pinned versions.
+- [ ] `2026-07-10T21:28:46Z` — `codex` — `pnpm --dir badseo run typecheck` works through the root toolchain but `pnpm --dir badseo run build` can't find Vite because `badseo/node_modules` is absent. Document or enforce the package-local install before validating the `badseo/` subpackage.
+- [ ] `2026-07-10T21:32:10Z` — `codex` — Formatting the `badseo/` workspace with `pnpm exec prettier` fails because Prettier is only available from the repository root. Document the root-only formatter command or expose a workspace-local formatting script.
 
 ## Resolved
 

.agents/skills/papercuts/SKILL.md

@@ -1,22 +1,47 @@
 ---
 name: papercuts
-description: Log small, non-blocking repository and agent-workflow friction to .agents/PAPERCUTS.md, or review, deduplicate, and resolve existing entries. Use proactively when a tool call has to be retried, setup or documentation is confusing, a command is flaky, a cache is stale, an error is misleading, or a non-obvious gotcha wastes time. Also use when the user asks to review, fix, or clean up papercuts.
+description: Log genuine, recurring repository friction to .agents/PAPERCUTS.md — confusing setup, a flaky repo command or script, a misleading in-repo error, stale generated files, or a non-obvious gotcha that will cost the next contributor time. Also use to review, deduplicate, and resolve existing entries. Gate hard before logging: only friction the repository itself can fix counts. Never log the agent's own sandbox/permission errors, shell-scripting mistakes, transient flakiness, or third-party tool quirks the repo can't change.
 ---
 
 # Papercuts
 
-Capture small friction in the moment without derailing the current task. Aggregated entries show where the repository needs sanding down.
+Capture small friction in the moment without derailing the current task.
+Aggregated entries show where the repository needs sanding down — so the bar is
+that a _different_ contributor would hit the same thing, and the _repository_
+can do something about it.
 
-## Decide whether it is a papercut
+## The two-question test
 
-A papercut is small, non-blocking friction in the repository, tooling, documentation, or agent workflow that is easy to push through but likely to waste time again.
+Log it only if **both** are true:
 
-Do not log:
+1. **Reproducible for anyone.** A different person, on a fresh checkout, working
+   in this repo would hit the same friction. It is not specific to your sandbox,
+   shell config, machine, network, or a one-time hiccup.
+2. **Fixable in the repo.** A change to the repo's code, config, scripts, or
+   docs would prevent or reduce it.
 
-- A product or code correctness bug that should be fixed now or tracked as real work.
-- What the agent accomplished; that belongs in the task summary.
+If either answer is "no," push through it and move on — do not log it.
+
+## Do NOT log
+
+- **Your environment's failures.** Sandbox `EPERM` / `listen` / IPC-socket
+  errors, blocked network or `fetch failed`, permission denials, missing system
+  tools. That is the runner, not the repo.
+- **Your own shell mistakes.** Reserved or special variable names (`status`,
+  `path`), unquoted globs, a broken login-shell hook. Fix the command — there is
+  nothing in the repo to sand down.
+- **Transient flakiness.** A command that succeeded on retry with no repo-side
+  cause (a network blip, a hung push, a slow mirror).
+- **Local state you corrupted.** A partial `node_modules` after branch-switching,
+  a stale dev-server port, a dirty cache. Re-run the install or cleanup.
+- **Third-party or beta-tool limitations the repo can't change** — unless the
+  fix is a repo-side workaround worth writing down (then log _that_ workaround).
+- Product or code correctness bugs (fix now or track as real work), and what you
+  accomplished (that belongs in the task summary).
 - Secrets, credentials, personal data, raw customer payloads, or sensitive paths.
-- A one-off typo with no plausible recurrence.
+
+When something fails, first ask "is this the repo, or is this me/my environment?"
+Only the former is a papercut.
 
 ## Log proactively
 
@@ -24,24 +49,31 @@ Do not log:
 2. Append one unchecked item under `## Open` using this format:
 
    ```markdown
-   - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — While <doing X>, <friction happened>. <Workaround, likely cause, or smallest useful improvement>.
+   - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>.
    ```
 
-3. Keep it to one or two sentences: what you were doing, what got in the way, and optionally the likely fix.
-4. Continue the original task. Do not opportunistically expand a papercut into unrelated work.
+3. Keep it to one or two sentences: what got in the way, and the likely repo-side
+   fix. Lead with the friction, not with what you were doing.
+4. Continue the original task. Do not expand a papercut into unrelated work.
 
-Use UTC timestamps. Use a short agent label such as `codex`, `claude`, or `human` and include a PR or task identifier only when it helps future triage.
+Use UTC timestamps and a short agent label (`codex`, `claude`, `human`). Add a
+PR or task identifier only when it helps future triage.
 
 ## Review or resolve
 
-Only mine a whole session or perform a broad papercut review when the user explicitly asks. Proactive behavior is limited to logging friction as it occurs.
+Only mine a whole session or do a broad review when the user explicitly asks.
 
 When asked to review the file:
 
-1. Deduplicate and group related entries.
-2. Verify each open papercut still exists.
-3. Fix the smallest safe, high-leverage entries first.
-4. Move fixed items to `## Resolved`, check them, and append the resolving date or commit.
-5. Route real bugs to normal issue/fix work. Route recurring review-policy gaps through `maintain-greptile-rules` instead of turning them into papercuts.
+1. Re-run the two-question test on every open entry; delete any that fail it
+   (environment/shell/flake noise that slipped in).
+2. Deduplicate and group related entries.
+3. Verify each surviving papercut still reproduces.
+4. Fix the smallest safe, high-leverage entries first.
+5. Move fixed items to `## Resolved`, check them, and append the resolving date
+   or commit. Route real bugs to normal issue/fix work; route recurring
+   review-policy gaps through `maintain-greptile-rules`.
 
-Preserve useful history; do not delete resolved entries merely to make the file shorter.
+Preserve useful history for genuinely-resolved papercuts; do not delete them
+merely to make the file shorter. (Noise that never belonged — see step 1 — is
+different: remove it.)

.claude/skills/papercuts/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: papercuts
+description: Log genuine, recurring repository friction to .agents/PAPERCUTS.md — confusing setup, a flaky repo command or script, a misleading in-repo error, stale generated files, or a non-obvious gotcha that will cost the next contributor time. Also use to review, deduplicate, and resolve existing entries. Gate hard before logging: only friction the repository itself can fix counts. Never log the agent's own sandbox/permission errors, shell-scripting mistakes, transient flakiness, or third-party tool quirks the repo can't change.
+---
+
+# Papercuts
+
+Capture small friction in the moment without derailing the current task.
+Aggregated entries show where the repository needs sanding down — so the bar is
+that a _different_ contributor would hit the same thing, and the _repository_
+can do something about it.
+
+## The two-question test
+
+Log it only if **both** are true:
+
+1. **Reproducible for anyone.** A different person, on a fresh checkout, working
+   in this repo would hit the same friction. It is not specific to your sandbox,
+   shell config, machine, network, or a one-time hiccup.
+2. **Fixable in the repo.** A change to the repo's code, config, scripts, or
+   docs would prevent or reduce it.
+
+If either answer is "no," push through it and move on — do not log it.
+
+## Do NOT log
+
+- **Your environment's failures.** Sandbox `EPERM` / `listen` / IPC-socket
+  errors, blocked network or `fetch failed`, permission denials, missing system
+  tools. That is the runner, not the repo.
+- **Your own shell mistakes.** Reserved or special variable names (`status`,
+  `path`), unquoted globs, a broken login-shell hook. Fix the command — there is
+  nothing in the repo to sand down.
+- **Transient flakiness.** A command that succeeded on retry with no repo-side
+  cause (a network blip, a hung push, a slow mirror).
+- **Local state you corrupted.** A partial `node_modules` after branch-switching,
+  a stale dev-server port, a dirty cache. Re-run the install or cleanup.
+- **Third-party or beta-tool limitations the repo can't change** — unless the
+  fix is a repo-side workaround worth writing down (then log _that_ workaround).
+- Product or code correctness bugs (fix now or track as real work), and what you
+  accomplished (that belongs in the task summary).
+- Secrets, credentials, personal data, raw customer payloads, or sensitive paths.
+
+When something fails, first ask "is this the repo, or is this me/my environment?"
+Only the former is a papercut.
+
+## Log proactively
+
+1. Search `.agents/PAPERCUTS.md` for an equivalent entry and avoid duplicates.
+2. Append one unchecked item under `## Open` using this format:
+
+   ```markdown
+   - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>.
+   ```
+
+3. Keep it to one or two sentences: what got in the way, and the likely repo-side
+   fix. Lead with the friction, not with what you were doing.
+4. Continue the original task. Do not expand a papercut into unrelated work.
+
+Use UTC timestamps and a short agent label (`codex`, `claude`, `human`). Add a
+PR or task identifier only when it helps future triage.
+
+## Review or resolve
+
+Only mine a whole session or do a broad review when the user explicitly asks.
+
+When asked to review the file:
+
+1. Re-run the two-question test on every open entry; delete any that fail it
+   (environment/shell/flake noise that slipped in).
+2. Deduplicate and group related entries.
+3. Verify each surviving papercut still reproduces.
+4. Fix the smallest safe, high-leverage entries first.
+5. Move fixed items to `## Resolved`, check them, and append the resolving date
+   or commit. Route real bugs to normal issue/fix work; route recurring
+   review-policy gaps through `maintain-greptile-rules`.
+
+Preserve useful history for genuinely-resolved papercuts; do not delete them
+merely to make the file shorter. (Noise that never belonged — see step 1 — is
+different: remove it.)