Skip to content

chore(claude): retire pair-flow remnants superseded by planwright - #33

Merged
inkatze merged 6 commits into
mainfrom
chore/retire-pair-flow-remnants
Jun 25, 2026
Merged

chore(claude): retire pair-flow remnants superseded by planwright#33
inkatze merged 6 commits into
mainfrom
chore/retire-pair-flow-remnants

Conversation

@inkatze

@inkatze inkatze commented Jun 24, 2026

Copy link
Copy Markdown
Owner

Summary

planwright now ships the spec-driven pipeline as a Claude Code plugin (installed via the marketplace flow in `roles/osx/tasks/osx.yml`). This removes the local pair-flow pieces planwright supersedes, while keeping the dotfiles-local surfaces planwright has no equivalent for.

Changes

  • delete `scripts/spec-validate.sh` — planwright ships its own validator
  • trim `scripts/skill-contracts.sh` to the surviving review commands (`panel-*`, `peer-review`); the migrated pipeline skills moved to planwright (with their own CI)
  • drop the dead `stale-lock-threshold` from `pair-flow.yml` — planwright owns the orchestrator lock now (zero surviving readers)
  • reframe the Spec-Driven Autonomy Pipeline section of `roles/osx/files/CLAUDE.md` to point at the planwright plugin + its overlay/doctrine model; tag `/self-review` + `/polish` as planwright skills
  • move the deferred orchestrate-retirement task to Completed in `specs/pair-flow/tasks.md` (gate fired: planwright merged in feat(claude): integrate planwright framework, retire migrated pair-flow commands #30/chore(claude): install planwright via plugin marketplace #32 + proven end-to-end)

Kept (planwright has no equivalent)

`pair-flow-config.sh` (`repo-class`), `pair-flow.yml` (`panel-backends`), the inbox/heartbeat substrate, and the `panel-`/`peer-review`/`copilot-`/`code-review` commands.

Validation

`skill-contracts.sh`, `yamllint`, `ansible-lint`, and `syntax-check` all pass; no active config/script/doc references the deleted validator.


Self-review audit

Standalone /self-review pass against origin/main. Diff: 6 files (prose + config + one script trim + one deletion).

Lens coverage

Lens Findings Notes
Correctness, logic, edge cases none skill-contracts.sh trim passes (all invariants hold); spec-validate.sh deletion has zero live readers; dropped stale-lock-threshold is unread by pair-flow-config.sh
Security n/a no auth/secrets/crypto/permissions touched; doc + checker-trim + validator-deletion only
Error handling and failure modes none skill-contracts.sh retains set -euo pipefail and the error-count/exit-1 path
Performance n/a doc/config/script-trim diff; no hot paths
Concurrency / state n/a no concurrent state in diff
Naming, readability, structure none script trim is a net simplification; nothing worsened
Documentation 1 inbox substrate path pointed at repo-root scripts/ (where MCP sync scripts live) instead of the real roles/osx/files/claude/scripts/
Tests / verification none the contract test (skill-contracts.sh) passes against the surviving files; planwright owns the migrated-skill tests
Cross-file consistency none no stale refs to the deleted validator in CLAUDE.md/settings.json/osx.yml/commands/*.md; tasks.md Deferred→Completed move matches the actual changes

Auto-applicable

Finding Disposition
none

Agent-resolvable

Finding Disposition
none Bucket available (single Active spec specs/pair-flow/ with a sibling kickoff-brief.md); no test-backed findings surfaced

Needs sign-off

Finding File Fix Commit
inbox/heartbeat substrate path was scripts/inbox-*.sh, which resolves to repo root; the scripts live under roles/osx/files/claude/scripts/ roles/osx/files/CLAUDE.md:284 repoint to roles/osx/files/claude/scripts/inbox-*.sh (matches the tracked-source convention this doc uses for worktree-bootstrap.sh) 5f4b024

Needs human judgment

Finding Options
none

Declined

Finding Rationale
none

Pending sign-off checklist

  • 5f4b024 — fix inbox substrate path in roles/osx/files/CLAUDE.md (repo-root scripts/roles/osx/files/claude/scripts/)

Pass summary

  • Mode: standalone
  • Base: origin/main (fetched at pre-flight)
  • Tooling run this pass: yamllint roles/osx/files/claude/pair-flow.yml (pass), skill-contracts.sh (pass — all invariants hold), bash -n skill-contracts.sh (pass). shellcheck unavailable on this host → degraded grounding for the shell lens; mitigated by the trim being a deletion-only change with a clean bash -n.
  • Reverts / surfaced failures: none

inkatze added 4 commits June 24, 2026 12:30
planwright now ships the spec-driven pipeline as a plugin, so remove the
local pieces it supersedes:

- delete scripts/spec-validate.sh (planwright ships its own validator)
- trim scripts/skill-contracts.sh to the surviving review commands
  (panel-*, peer-review); the migrated pipeline skills moved to planwright
- drop the dead stale-lock-threshold from pair-flow.yml (planwright owns
  the orchestrator lock now)
- reframe the Spec-Driven Autonomy Pipeline section of CLAUDE.md to point
  at the planwright plugin and its overlay/doctrine model
- move the deferred orchestrate-retirement task to Completed in
  specs/pair-flow/tasks.md (gate fired: planwright merged + proven)

pair-flow-config.sh (repo-class), pair-flow.yml (panel-backends), the inbox
substrate, and the panel-*/peer-review/copilot-*/code-review commands stay;
planwright has no equivalent.
- pair-flow.yml: reword so the osx.yml pointer attaches to the planwright
  plugin install, not to config-get.sh (which osx.yml does not reference)
- CLAUDE.md: rewrite the /polish bullet to planwright's actual loop (drains
  all action buckets on-branch, no dotfiles repo-class gating), resolving the
  contradiction with the Autonomy-gate paragraph
- specs/README.md: the pair-flow index row no longer claims it 'defines' the
  pipeline skills (they moved to the planwright plugin in #30)

specs/pair-flow/{design,tasks,kickoff} stale refs left intact: that bundle is
preserved as origin spec + history.
scripts/inbox-*.sh pointed at repo root (where MCP sync scripts live);
the inbox/heartbeat scripts actually live under
roles/osx/files/claude/scripts/. Matches the tracked-source convention
this doc already uses for worktree-bootstrap.sh.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR retires remaining local “pair-flow” pipeline remnants that have been superseded by the planwright Claude Code plugin, while keeping the dotfiles-local review and inbox surfaces.

Changes:

  • Remove the local spec validator and the obsolete stale-lock-threshold config.
  • Trim the local contract checker to focus on surviving dotfiles-local review commands.
  • Update specs and CLAUDE documentation to reflect planwright as the source of the pipeline skills and validator.

Lens Check (exhaustive)

  • Correctness and logic bugs: 1 finding, skill-contracts.sh no longer checks panel-review.md despite claiming to cover panel-*.
  • Security and secret handling: none, only docs and local scripts, no secret surfaces changed.
  • Error handling and failure modes: none, no new failure paths introduced.
  • Edge cases: none, changes are deletions and doc reframes.
  • Idempotency: none, no Ansible task behavior changed here.
  • Naming, readability, and code structure: 1 nit, terminology drift (“skills” vs “commands”) in skill-contracts.sh header.
  • Documentation: 2 findings, incorrect file paths and stale config key mentioned in specs/pair-flow/tasks.md.
  • Tests / verification: none, no new behavior added, existing pre-commit contract guard is the relevant check.
  • Cross-file consistency: covered by the documentation findings above (config key removed but still described as present).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
specs/README.md Reframes the pair-flow/ spec as origin/history and points pipeline skills to planwright.
specs/pair-flow/tasks.md Moves orchestrate retirement to Completed and updates narrative for planwright ownership.
specs/_observations/opportunities.md Adds a tooling-hardening observation (shellcheck absence).
roles/osx/files/claude/scripts/spec-validate.sh Deletes the local spec validator (planwright owns validation now).
roles/osx/files/claude/scripts/skill-contracts.sh Trims contract checks to remaining dotfiles-local review commands.
roles/osx/files/claude/pair-flow.yml Removes stale-lock threshold and reframes file scope to review and inbox surfaces.
roles/osx/files/CLAUDE.md Updates workflow and pipeline docs to reflect planwright plugin and remaining dotfiles-local pieces.

Comment thread specs/pair-flow/tasks.md
Comment thread specs/pair-flow/tasks.md Outdated
Comment thread roles/osx/files/claude/scripts/skill-contracts.sh Outdated
Comment thread roles/osx/files/claude/scripts/skill-contracts.sh

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Comment thread specs/pair-flow/tasks.md
Comment thread roles/osx/files/claude/pair-flow.yml
@inkatze
inkatze merged commit 8379d32 into main Jun 25, 2026
8 of 10 checks passed
@inkatze
inkatze deleted the chore/retire-pair-flow-remnants branch June 25, 2026 19:40
inkatze added a commit that referenced this pull request Jul 13, 2026
- skill-contracts.sh: the three-bucket check was decorative in 2 of 3
  files it's supposed to guard. Reproduced directly: mutating
  panel-pairing.md/peer-review.md back to "four buckets" still passed,
  because an unrelated "three-pass"/"three tables" sentence elsewhere
  in the same file independently satisfied the shared alternation
  regex. Same failure mode the v1-retrospective already documented
  once for this exact checker. Rewritten to anchor on each file's own
  specific declarative sentence plus an explicit Agent-resolvable
  absence guard, using if-blocks instead of a set -e-unsafe
  `cond && ! grep && err` chain (which silently exited the script on
  the passing case during my own validation of the fix).
- decouple-review-tooling.md: fixed a status line that claimed
  "resolved" while the body still narrated the deleted files in
  present tense, and a numbering reference that didn't map to the
  doc's actual numbered lists.
- tasks.md: fixed a citation typo (D-9.1, which doesn't exist as a
  design decision, for REQ-D9.1) and an incomplete REQ-C1.x list
  (missing C1.1/C1.3) in the retirement bullet I added.
- opportunities.md: fixed a misattributed quote (the "convergence
  layer" phrase is decouple-review-tooling.md's, not obs #3's) and an
  overstated claim that obs #3's "commands not skills" point is still
  open (it was already resolved in PR #33, before this branch).

Declined with rationale: test-spec.md's and scheduled-runner.md's
stale references to pair-flow-config.sh were left untouched, matching
the verified precedent that the /orchestrate retirement also left
these two files alone despite equivalent staleness at the time.
inkatze added a commit that referenced this pull request Jul 14, 2026
…, repo-class) (#35)

* chore(tmux,claude): remove cross-session inbox substrate + tmux dashboard

The tmux status-bar segment and prefix+i popup didn't pan out, so the
whole substrate comes out rather than leaving the write-side hooks
running with no reader: the six inbox-*.sh scripts, the tmux-side
status wrapper, settings.json hook wiring, the inbox Ansible task, and
pair-flow.yml's heartbeat-interval config. notify-event.sh (macOS
notifications) is untouched since it's called independently.

* chore(claude): retire notify-event.sh (Stop/permission/idle noise)

Became noise, so it goes the same way as the inbox substrate: script
deleted, hooks.Stop/hooks.Notification set to [] in settings.json. The
tnotify-send/tnotify-watch fish infra stays; it's generic terminal-
notification plumbing also used directly by worktree-bootstrap.sh.

* chore(claude): retire repo-class / pair-flow-config.sh and the Agent-resolvable bucket

repo-class (solo vs multi-reviewer) existed to gate whether Agent-resolvable
findings could auto-apply without asking. Walking every consumer showed none
of them actually varies safe behavior on it: /panel-pairing, /peer-review, and
planwright's /polish all already draft a PR and never mark it ready without
human sign-off regardless of repo-class, and /peer-review's "solo" branch was
vacuous (it only runs when a peer already reviewed). Deletes
pair-flow-config.sh, pair-flow.yml, and their Ansible task; collapses Finding
Categorization from four buckets back to three (Auto-applicable / Needs
sign-off / Needs human judgment) across CLAUDE.md, panel-review.md,
panel-pairing.md, peer-review.md, code-review.md, and skill-contracts.sh.
panel-backends now resolves from the profile-table default that already
existed as a fallback, no config file needed.

* fix(claude): self-review findings on the repo-class retirement branch

- skill-contracts.sh: the three-bucket check was decorative in 2 of 3
  files it's supposed to guard. Reproduced directly: mutating
  panel-pairing.md/peer-review.md back to "four buckets" still passed,
  because an unrelated "three-pass"/"three tables" sentence elsewhere
  in the same file independently satisfied the shared alternation
  regex. Same failure mode the v1-retrospective already documented
  once for this exact checker. Rewritten to anchor on each file's own
  specific declarative sentence plus an explicit Agent-resolvable
  absence guard, using if-blocks instead of a set -e-unsafe
  `cond && ! grep && err` chain (which silently exited the script on
  the passing case during my own validation of the fix).
- decouple-review-tooling.md: fixed a status line that claimed
  "resolved" while the body still narrated the deleted files in
  present tense, and a numbering reference that didn't map to the
  doc's actual numbered lists.
- tasks.md: fixed a citation typo (D-9.1, which doesn't exist as a
  design decision, for REQ-D9.1) and an incomplete REQ-C1.x list
  (missing C1.1/C1.3) in the retirement bullet I added.
- opportunities.md: fixed a misattributed quote (the "convergence
  layer" phrase is decouple-review-tooling.md's, not obs #3's) and an
  overstated claim that obs #3's "commands not skills" point is still
  open (it was already resolved in PR #33, before this branch).

Declined with rationale: test-spec.md's and scheduled-runner.md's
stale references to pair-flow-config.sh were left untouched, matching
the verified precedent that the /orchestrate retirement also left
these two files alone despite equivalent staleness at the time.

* chore(osx): clean up orphaned pair-flow.yml symlink and inbox dir

Two hard-disqualifier-zone findings from the self-review pass (delete
ops reaching other hosts), reviewed and approved in conversation rather
than deferred to the PR checklist. Any host that ran the pre-retirement
osx.yml has a dangling ~/.claude/pair-flow.yml symlink (target deleted)
and an orphaned ~/.claude/inbox/ directory (inbox-sweep.sh, the only
thing that ever cleaned it, is also deleted). Both are state: absent,
safe no-ops on a fresh machine. Verified against fixtures: removes an
existing dangling symlink + populated directory, and is idempotent
when already absent.

* fix(claude): panel-pairing findings, reviewed and approved

/panel-pairing iteration 1 (backend: codex) surfaced 2 real findings
that lacked a tool citation, so they routed to Needs sign-off rather
than Auto-applicable per the skill's own rule; both approved in
conversation rather than left on the checklist.

- tasks.md / decouple-review-tooling.md overclaimed that
  pair-flow.local.yml "was removed" -- it wasn't. It's untracked and
  was never Ansible-managed (a pre-existing, deliberate policy); I
  only manually deleted it on this one machine earlier. Reworded to
  say it's orphaned wherever it existed, not deleted.
- skill-contracts.sh's new bucket_files/bucket_phrases parallel arrays
  had no length-parity guard. Confirmed a mismatch already fails
  loudly under set -u (not silent), but with an unhelpful "unbound
  variable" instead of a clear diagnostic. Added an explicit check;
  validated against real files (still passes) and a simulated
  mismatch (now fails with a specific message).

Two other codex findings were declined after validation: the
settings.json Stop/Notification "[]" wipe concern doesn't apply (no
other writer touches those hook categories, and "[]" to remove a hook
is this repo's own documented convention); codex's "correction" to my
set -e comment is itself incomplete (doesn't hold for the exact
function-wrapped case the comment was describing, re-confirmed
empirically).

* chore(claude): address copilot-pairing thread on CLAUDE.md:171

Copilot flagged that /copilot-pairing was listed among skills that
"categorize each finding into one of three buckets and present them
as separate tables," but copilot-pairing.md never references the
bucket taxonomy anywhere -- confirmed via direct grep, both on this
branch and on origin/main (pre-existing since before this PR, but the
sentence itself is already in this diff's touched lines, so in scope).
It has its own classification scheme entirely (valid /
already-handled / false positive / adjacent finding). Removed it from
the list; kept /copilot-review's adjacent-findings output, which does
genuinely use the three-bucket tables (confirmed in copilot-review.md).

* chore(claude): fix v1-retrospective citation path in skill-contracts.sh

Copilot flagged that the comment I added cites
research/v1-retrospective.md:89, which doesn't resolve from repo root
(lefthook's cwd). Every other reference to this file in the repo uses
the full path specs/pair-flow/research/v1-retrospective.md; mine was
the only outlier. Fixed to match.

* chore(specs): fix stale tasks.md header (Last reviewed date, private wording)

Copilot flagged this via /copilot-pairing on PR #35, twice in a row
(loop detection fired on the second occurrence since I'd already
replied "tracking elsewhere" to the first). Pulling it into scope per
explicit direction rather than continuing to loop against an already
correct dismissal. Bumped Last reviewed to today; planwright went
public 2026-06-23 per the already-open opportunities.md entry this
also closes out. Left tasks.md:55's Deferred-section "private" mention
alone -- not flagged by Copilot, describes a historical fact, out of
scope for this pass.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants