Add pair-flow spec bundle - #28

Encodes the decisions from the 2026-05-22 review pass:

- D-19/D-20: two-file config model (~/.claude/pair-flow.yml tracked
  defaults + ~/.claude/pair-flow.local.yml agent-maintained), with
  discovery flow that never silently writes. Replaces the spec-config.yml
  proposal that would have leaked personal workflow into shared repos.
- D-21: PRs are always drafts; no auto-merge at any tier. Removes the
  v3 auto-merge from Deferred and moves to Out of scope as permanent.
- D-22/D-23: dashboard visual language (red/orange/blue/yellow/green/grey)
  with sort order, plus inbox heartbeat (30s tick, 2-minute stale sweep,
  24h legacy fallback).
- D-24 through D-30: bundle sizing, CI retry, path-guard scope, brief
  invalidation scope, validator reuse, PR-merge detection, telemetry
  layout.

Adds Task 3.5 for the pair-flow config helper. Resolves nine of the ten
open questions; only codex availability on personal/alt remains, gated
on Task 1's investigation.

Resolves the second round of clarifications surfaced after the initial
spec was committed:

- D-31: Spec status lifecycle (Draft -> Active -> Done) with explicit
  ownership of each transition.
- D-32: Branch naming convention for orchestrator-created branches.
- D-33: No bypass mode for /spec-kickoff; manual work remains available.
- D-34: Inbox keyed per Claude Code session UUID, presented per worktree.
- D-35 through D-48: kickoff walkthrough on partial invalidation,
  orchestrator behavior on unkickoffed specs, cross-spec concurrency,
  measurement plan convention, in-session skill composition,
  Last-reviewed auto-update, incremental brief writing, spec-looks-wrong
  escalation, gh auth failure handling, worktree ownership split,
  validator status-aware enforcement, brief retention, uncommitted
  changes on /resume, and no separate audit log.

Adds Task 3.6 for the validator port + extension (a precondition for
/spec-draft and /spec-kickoff). Extends /spec-kickoff and /orchestrate
tasks with status-flipping responsibilities. Documents the spec-status
and measurement-plan conventions in specs/README.md.

The codex availability question (last remaining open question after the
first clarification pass) is also resolved: codex is available on both
work and personal profiles.

…pe, rewrite threshold)

- D-49: Kickoff briefs are committed to git as part of the spec bundle,
  not gitignored. They're decisions, not secrets.
- D-50: Validator v1 enforces structural fields only (stable ID,
  Done-when, Dependencies, Citations). Measurement plan and Last
  reviewed are recommended but not blocking.
- D-51: Wholesale-brief invalidation fires when both requirements.md
  and design.md change in the same commit, or when >50% of REQ-IDs
  or D-IDs change in a single commit. Otherwise section-scoped.

Adds REQ-A2.11 and REQ-A2.12 to anchor the requirements.

Final consistency pass surfaced two gaps and two adjacent fixes:

- D-52: One task per /orchestrate invocation; intra-spec parallelism
  comes from multiple invocations (manual via parallel tmux panes, or
  the scheduled runner picking up successive ready tasks). Matches the
  user's existing "different workstreams in parallel" workflow.
- D-53: /execute-task weighs performance, security, and system-wide
  implications during research and records tradeoffs in the kickoff
  brief's risk register. CI is the hard gate; performance regressions
  that pass CI are still user-observable and excluded from
  Agent-resolvable by D-3.
- D-17 fix: reconcile lock path with D-37 (per-spec, not repo-wide) and
  pin lock-release timing (released before /execute-task runs, not held
  for its full duration).
- D-37 wording: clarify that "same-spec concurrency blocked" applies
  only to state-changing moves, not to concurrent task execution.

REQ-B1.5 expanded with explicit "industry standards, popular projects"
language and the performance/security/system-wide weighing instruction.
REQ-D2.2 added with the parallelism contract.

Diagnosis: /panel-* shipped 2026-05-15, mid 30-day window. /copilot-* count
(42) all pre-release; /panel-* count (14) all post-release; zero copilot
invocations after panel landed. Not underuse, just availability.

Recommendation: keep panel as default. Confirms D-6 (codex-only default,
drop "provisional") and D-12 (panel-pairing demoted to escalation, /polish
as default convergence). One LAN-Ollama auto-mode classifier denial logged
as follow-up.

Structural validator for spec bundles. Checks four-file presence, Status:
declaration, and per-task fields (stable ID, Done when, Dependencies,
Citations). Status-aware: Draft warns (exit 0), Active errors (exit 1).
Also flags prose-only REQs (the tecpan/specs/org counter-example pattern).

Self-tests pass on the three target fixtures:
- tecpan/specs/settings (Active): 0 errors, 0 warnings
- tecpan/specs/org (no status, prose REQs, bare tasks): 0 errors, 27 warnings
- specs/pair-flow (Draft, this bundle): 0 errors, 0 warnings

The REQ-G7.1 Gherkin scenarios verified via synthetic fixture: same gap
warns on Draft (exit 0), errors on Active (exit 1). Materializes through
the existing roles/osx/tasks/osx.yml scripts/ directory symlink; no
per-file symlink task added.

Adds roles/osx/files/claude/pair-flow.yml (tracked defaults: codex-only panel
backend, 1h stale-lock threshold, 30s inbox heartbeat) plus a per-file
symlink task in osx.yml materializing it to ~/.claude/pair-flow.yml.

Adds roles/osx/files/claude/scripts/pair-flow-config.sh with five
subcommands: repo, defaults, repo-class, confirm-repo-class <value>, show.
Per D-20 the helper never silently writes — repo-class on an unknown repo
exits 2 with `needs-confirmation:<inferred>`; only confirm-repo-class
persists. Inference reads gh pr list and filters known bot logins
(*[bot], copilot-*, dependabot*, renovate*, github-actions*) plus
PR-author self-reviews so a solo repo with copilot review history is
not misclassified as multi-reviewer.

Smoke-tested end-to-end on this dotfiles repo. spec-validate.sh still
emits zero errors and zero warnings on specs/pair-flow.

Adds roles/osx/files/claude/scripts/path-guard.sh wired from settings.json
as a PreToolUse hook with matcher Read|Edit|Write (Bash and NotebookEdit
out of scope per D-26). The hook denies via the PreToolUse JSON envelope
with permissionDecision=deny and a structured reason so the model gets
useful context, not a stderr blob.

Blocks: Read/Edit on missing file or directory path; Write on missing
parent directory. Allows everything else. Smoke-tested seven cases via
direct stdin; the hook returns the correct deny envelope or silent allow
in each. End-to-end behavior needs a fresh session because PreToolUse
hooks load at session start; the materialized settings.json is updated
for the next session to pick up.

The 82/month file-path-mistake baseline (April-May 2026 friction analysis)
will be re-measured in the next 30-day window per Task 2's Measurement
plan.

Adds roles/osx/files/claude/commands/spec-kickoff.md, the didactic
walkthrough that produces signed-off kickoff briefs. Seven sections
(Goal+glossary, Requirements, Design, Verification, Task graph, Risk
register, Sign-off) walked per a read → restate → surface implicit
terms → Socratic checks → D-42 inconsistency gate → wait-for-sign-off
→ incremental-append pattern (D-41). Retrofit mode patches tasks.md
at the Task-graph step with per-patch red-line. Partial-invalidation
re-walk uses D-27 section scope plus D-51 wholesale-rewrite triggers.
Sign-off flips all four spec files Draft → Active via Edit and bumps
Last reviewed: (REQ-A2.9, D-40); validator failure post-flip reverts
and halts. Repo-class discovery via pair-flow-config.sh with the
needs-confirmation semantics from REQ-D9.1 / D-20; never silently
writes.

Pre-flight stages traced cleanly against specs/pair-flow/: validator
0/0, repo-class solo, no prior brief. The interactive bootstrap-test
per REQ-A2.7 is the user's move and the D-7 quality gate.

Cross-session awareness layer (REQ-F). Six inbox-*.sh scripts in
roles/osx/files/claude/scripts/ (materialized via the existing
directory symlink): write/heartbeat/sweep/session-start/status/
dashboard. Hooks wired in settings.json: SessionStart spawns the
heartbeat in the background, Stop transitions to idle, Notification
(permission_prompt | idle_prompt) transitions to awaiting-input
alongside the existing notify-event.sh chain. tmux.conf gains a
`prefix + i` popup binding for the dashboard plus a second dracula
custom plugin for the status-bar triplet (⚠N ●N ◆N).

Display-only v1 (no row-jump) and triplet status segment per user
pick on PR #28. macOS notifications reuse notify-event.sh's
tnotify-send chain rather than duplicating it. Heartbeat self-exits
when its claude PID dies (walks up to 6 ancestors looking for
claude/claude-code) or when the inbox file is removed, so no Stop
cleanup hook is required and orphan processes do not accumulate.
The sweeper combines the spec's 2-min heartbeat threshold (D-23)
with a same-host PID-liveness backstop for kill -9 leaks.

Sync mechanism (iCloud vs Syncthing) stays Awaiting input; entries
are single-writer atomic-rename sub-1KB JSON so either works.

Smoke-tested end-to-end: hook init + tick + transition + sweep all
behave; dashboard renders 6 mixed states with correct colours, sort
weights, column truncation; status segment computes correct counts;
heartbeat self-exits within 30s of its inbox file being removed.
v1 verification's two-concurrent-sessions + kill-9 + macOS-notify
checks are deferred to the user (require fresh-session hook load).

Add the four-bucket Finding Categorization to user-global CLAUDE.md
(Auto-applicable / Agent-resolvable / Needs sign-off / Needs human
judgment). The new Agent-resolvable bucket carries the REQ-C1.2 five-
condition predicate (failing regression test, test passes after fix,
full project CI passes, kickoff alignment, no hard disqualifier), with
a repo-class behavior split (solo auto-applies, multi-reviewer surfaces
for review with evidence) routed through ~/.claude/scripts/pair-flow-
config.sh repo-class.

/polish and /panel-pairing gain a pre-flight step that resolves repo-
class and locates the active kickoff brief, a 4-bucket categorize/
loop-fate path, and a new step (d-AR) Agent-resolvable application
flow (write failing test → confirm failure mode matches finding → fix
→ test passes → wider CI → verify kickoff alignment → record
evidence). Iteration summaries now log repo-class, brief path, all
four bucket counts, and per-item Agent-resolvable evidence. Auto-
execution invariants extended.

/peer-review updated to four tables with an Agent-resolvable thread
table and matching option semantics. /code-review's descriptive
reference updated to four-bucket. /copilot-pairing left untouched; it
inherits by reference from CLAUDE.md.

specs/pair-flow/tasks.md: Task 8 moved to Completed.

Add an "Invocation mode" section to polish.md that splits behavior on
the literal --nested flag in $ARGUMENTS. Standalone (default) pushes
and opens or updates a draft PR after a normal exit; nested mode (used
by /execute-task in the pair-flow design) hands back to the parent for
PR creation.

The new "Standalone-mode PR creation" section mirrors /self-review's
shape: push, check for an existing PR via gh pr view and reuse it,
otherwise template / convention discovery then gh pr create --draft
with a body listing the Polish notes (per-iteration Auto-applicable
and Agent-resolvable items, test paths and kickoff-brief citations,
plus any unresolved Needs sign-off / Needs human judgment items).

Auto-execution invariants split into in-loop (no push, no PR ever)
and post-loop (standalone may push and open a draft PR, nested may
not). Force-push, amend, squash, and rebase remain forbidden at all
times. Safety stops suppress PR creation in both modes.

specs/pair-flow/tasks.md: Task 9 moved to Completed.

…date hook

Document the canonical tasks.md state sections (Completed, In progress,
Awaiting input, Deferred, Out of scope) and the In progress annotation
format in specs/README.md. Phase values: implementing, polish iter N,
PR #M draft. Bullet shape for Completed pinned.

Add roles/osx/files/claude/scripts/tasks-pr-sync.sh wired from settings
.json under hooks.PostToolUse with matcher "Bash". The script filters
`gh pr (create|merge)` from the tool call, parses the D-32 branch
(pair-flow/<spec>/task-<ids>, including bundles and dotted IDs),
extracts the PR number from tool_response.stdout via URL match, then
`#N` literal, then argv, then `gh pr view` fallback, and rewrites
specs/<spec>/tasks.md.

On open: move task block(s) Forward plan → In progress, insert the
two annotation lines right after the H3; strip existing Status /
Last-activity bullets first so the hook is idempotent. On merge:
replace the block with a one-line Completed bullet referencing the
PR. Bundle order preserved. Silent on no-op cases; python failures
log to stderr and leave tasks.md untouched.

Smoke-tested seven scenarios via synthetic stdin against ephemeral
fixtures (single-task open, gh pr merge with realistic #N stdout,
bundle open with correct order, non-pair-flow branch no-op, non-Bash
tool no-op, idempotent re-open). Out-of-session merge reconciliation
remains Task 12's scheduled-runner job.

…observation convention

Apply kickoff-brief amendments: D-6 profile-aware panel backends (codex
on work, gemini on personal/alt), D-17 stale-lock threshold reduced from
1h to 15m, D-24 effort-based fallback for low-data repos.

Add skill-contracts.sh contract-consistency checker wired as a lefthook
pre-commit job. Checks cross-file invariants (D-32 branch naming,
four-bucket presentation, --nested flag, pair-flow-config.sh, D-21
always-draft, D-33 Active gate, D-36 kickoff gate) across skill files.

Add observation convention to /execute-task and /polish (Risk 6 Layers
1/1b: passive record of opportunities for future /spec-draft seeds).

Add execute-task.md and peer-review.md to the pair-flow-config.sh
check list in skill-contracts.sh. Both make load-bearing calls to
pair-flow-config.sh repo-class in their pre-flight.

…ple, Task 15

- Add interaction style sections to /spec-draft and /spec-kickoff:
  progress indicator, progressive disclosure, visual aids, selectors
  over open-ended questions, smart defaults, running summary
- Add composability-by-default design principle to user-global CLAUDE.md
- Add Task 15 (work project e2e validation) to pair-flow tasks
- Add standalone project extraction to Deferred with gate conditions

Add explicit handoff presentation rules to /polish post-loop flow.
Items sharing a decision axis (e.g., test coverage gaps) cluster into
one question instead of individual confirmations. Reduces human
interaction count without losing granularity.

…ions

Same fix as polish: when the autonomous loop hands off residual items,
cluster shared-axis findings and use batched decisions instead of
defaulting to one-by-one confirmation.

/orchestrate said "navigate to the worktree" but didn't specify how,
so /execute-task ran in the wrong directory. Now explicitly uses
EnterWorktree/ExitWorktree. Also documents /loop wrapping for
multi-task autopilot.

Gated on the standalone extraction goal — current sources
(specs/README.md, validator, /spec-draft) are sufficient for personal
use, and a meta-spec would add a sync burden without immediate value.

Two integration surfaces identified (discovery rigor fan-out across
review skills, /execute-task conditional fan-out for multi-file
mechanical work). Gated on Anthropic publishing the API.

A stale local main in a long-lived worktree inflates the diff with
already-merged commits. Fetch first and diff against the remote-tracking
base; fall back to local main only when no remote is configured.

Per the chosen resolution: keep the rich direct notify-event.sh permission/idle
hooks in settings.json (they carry the actual permission message) and stop
inbox-write.sh from emitting its own generic 'awaiting input' notification on
the same transition. inbox-write still records the awaiting-input state for the
dashboard, and still owns the draft-pr-ready notification (which has no direct
hook). Removes the duplicate macOS notification on permission_prompt/idle_prompt.
Verified: awaiting-input updates state with no notification; draft-pr-ready
still fires 'done'.