Carry forward seam doctor follow-up fixes (#4171)

justin808 · web-flow · commit ce775fc6ef84 · 2026-06-21T22:29:43.000-10:00
## Summary - carry forward the post-merge #4121 seam-doctor/adoption fixes that landed on the closed branch after #4121 was squash-merged at `68db6f1` - teach `agent-workflow-seam-doctor` to scan 3+ backtick/tilde executable fences, reject too-short closers, accept same-character closers at least as long as the opener, reject info strings on closing fences, handle CRLF closers, and parse spaced info-string languages - clarify user-installed shared skill adoption: install `workflows/` with `skills/`, or keep repo-local workflow copies/launchers for skills that reference `.agents/workflows/...` - document the shared-pack status/upgrade path for Codex and Claude installs - keep the React on Rails compatibility copy aligned with `shakacode/agent-workflows@d38645b` ## Rationale #4121 created and referenced the public shared workflow repo, but two late P2 review findings arrived after the merged head. The shared repo already contains the fixes; this PR keeps the React on Rails compatibility copy and adoption docs in sync with the published pack. Current-head review on this follow-up also tightened the CommonMark closing-fence behavior, now fixed here and in the shared repo. The shared pack now also includes host-aware install/status/upgrade helpers inspired by the gstack upgrade flow: explicit status tokens, Codex/Claude host targets, network disclosure, rollback if a consumer seam validation fails, and preservation of unrelated user-installed agent files. Original #4121 review threads: - #4121 (comment) - #4121 (comment) ## Changelog Not user-visible; agent workflow docs/tooling only. ## Validation - `ruby .agents/bin/agent-workflow-seam-doctor-test.rb` -> 39 runs, 98 assertions, 0 failures - `.agents/bin/agent-workflow-seam-doctor --shared /Users/justin/codex/agent-workflows` -> PASS - `(cd /Users/justin/codex/agent-workflows && bin/validate)` -> PASS at `d38645b` - `git diff --check` in both `react_on_rails` and `agent-workflows` -> clean - `bin/ci-local --changed` -> docs-only, Docs Sidebar Check passed, no further CI needed - pre-commit hook -> trailing newlines, offline markdown links, Prettier passed - pre-push hook -> branch RuboCop no offenses; online markdown links 29 OK  --- > [!NOTE] > **Low Risk** > Changes are limited to agent workflow tooling and internal documentation; no application runtime, auth, or user-facing product code paths are modified. > > **Overview** > Syncs the repo’s agent-workflow compatibility copy with post-#4121 fixes from `shakacode/agent-workflows`, focused on **seam validation** and **adoption docs**. > > **`agent-workflow-seam-doctor`** now parses Markdown code fences closer to CommonMark: 3+ backtick/tilde openers, closers must match character and be at least as long as the opener (shorter closers stay inside the fence), closing lines with info strings do not close a fence, CRLF closers work via `chomp`, and spaced info strings (e.g. ` ``` bash`) still mark executable fences. A large new test suite covers long fences, mismatched delimiters, and non-executable fenced content. > > **Docs/skills** broaden “Codex batch” wording to **agent / Codex / Claude** batches in `AGENTS.md`, `pr-batch`, and contributor guides. Adoption and design docs add **`agent-workflows-status`** and **`upgrade-agent-workflows`** for Codex and Claude hosts, stress installing **`workflows/`** alongside **`skills/`**, and link the shared pack’s installation/upgrade guide. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 924b4eb. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
diff --git a/.agents/bin/agent-workflow-seam-doctor b/.agents/bin/agent-workflow-seam-doctor
@@ -206,18 +206,31 @@ module AgentWorkflowSeamDoctor
   end
 
   def update_fence_state(line, in_fence, fence_delimiter)
-    fence = line.match(/^ {0,3}(```|~~~)([[:alnum:]_-]*)(?:\s.*)?$/)
+    line = line.chomp
+
+    if in_fence
+      closing_fence = line.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/)
+      return nil if closing_fence.nil?
+
+      delimiter = closing_fence[1]
+      # Mismatched closers stay inside the current fence.
+      return nil unless closing_fence_delimiter?(delimiter, fence_delimiter)
+
+      return [false, false, nil]
+    end
+
+    fence = line.match(/^ {0,3}(`{3,}|~{3,})(?:[ \t]*([[:alnum:]_-]+))?(?:[ \t].*)?$/)
     return nil if fence.nil?
 
     delimiter = fence[1]
-    # Mismatched closers stay inside the current fence.
-    return nil if in_fence && delimiter != fence_delimiter
-    return [false, false, nil] if in_fence
-
     language = fence[2].to_s.downcase
     [true, EXECUTABLE_FENCE_LANGS.include?(language), delimiter]
   end
 
+  def closing_fence_delimiter?(delimiter, fence_delimiter)
+    delimiter[0] == fence_delimiter[0] && delimiter.length >= fence_delimiter.length
+  end
+
   def placeholders_from_line(line, in_fence:, executable_fence:)
     placeholders = []
 
diff --git a/.agents/bin/agent-workflow-seam-doctor-test.rb b/.agents/bin/agent-workflow-seam-doctor-test.rb
@@ -279,6 +279,10 @@ def test_executable_placeholder_in_titled_code_fence_fails
       assert_includes out, "<follow-up prefix>"
     end
   end
+end
+
+class AgentWorkflowSeamDoctorFenceTest < Minitest::Test
+  include AgentWorkflowSeamDoctorTestHelpers
 
   def test_executable_placeholder_in_tilde_code_fence_fails
     with_repo do |root|
@@ -296,6 +300,22 @@ def test_executable_placeholder_in_tilde_code_fence_fails
     end
   end
 
+  def test_executable_placeholder_in_long_code_fence_fails
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ````bash
+        gh issue create --title "<follow-up prefix> Review feedback from PR #123"
+        ````
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      refute status.success?
+      assert_includes out, "<follow-up prefix>"
+    end
+  end
+
   def test_mismatched_fence_delimiter_does_not_close_executable_fence
     with_repo do |root|
       write_agents(root)
@@ -312,6 +332,139 @@ def test_mismatched_fence_delimiter_does_not_close_executable_fence
       assert_includes out, "<follow-up prefix>"
     end
   end
+end
+
+class AgentWorkflowSeamDoctorFenceLengthTest < Minitest::Test
+  include AgentWorkflowSeamDoctorTestHelpers
+
+  def test_shorter_closing_fence_does_not_close_long_executable_fence
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ````bash
+        ```
+        gh issue create --title "<follow-up prefix> Review feedback from PR #123"
+        ````
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      refute status.success?
+      assert_includes out, "<follow-up prefix>"
+    end
+  end
+
+  def test_shorter_closing_tilde_fence_does_not_close_long_tilde_fence
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ~~~~bash
+        ~~~
+        gh issue create --title "<follow-up prefix> Review feedback from PR #123"
+        ~~~~
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      refute status.success?
+      assert_includes out, "<follow-up prefix>"
+    end
+  end
+
+  def test_longer_closing_fence_closes_long_executable_fence
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ````bash
+        echo ok
+        `````
+        <follow-up prefix>
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      assert status.success?, out
+    end
+  end
+
+  def test_longer_closing_tilde_fence_closes_long_tilde_fence
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ~~~~bash
+        echo ok
+        ~~~~~
+        <follow-up prefix>
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      assert status.success?, out
+    end
+  end
+
+  def test_closing_fence_with_info_string_stays_inside_executable_fence
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ````bash
+        ````bash
+        gh issue create --title "<follow-up prefix> Review feedback from PR #123"
+        ````
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      refute status.success?
+      assert_includes out, "<follow-up prefix>"
+    end
+  end
+
+  def test_crlf_closing_fence_closes_executable_fence
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, "```bash\r\necho ok\r\n```\r\n<follow-up prefix>\r\n")
+
+      out, status = run_doctor(root)
+
+      assert status.success?, out
+    end
+  end
+
+  def test_spaced_info_string_on_long_non_executable_fence_is_not_executable
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ```` markdown
+        <follow-up prefix>
+        ````
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      assert status.success?, out
+    end
+  end
+
+  def test_spaced_info_string_on_long_executable_fence_is_executable
+    with_repo do |root|
+      write_agents(root)
+      write_skill(root, <<~MARKDOWN)
+        ```` bash
+        gh issue create --title "<follow-up prefix> Review feedback from PR #123"
+        ````
+      MARKDOWN
+
+      out, status = run_doctor(root)
+
+      refute status.success?
+      assert_includes out, "<follow-up prefix>"
+    end
+  end
+end
+
+class AgentWorkflowSeamDoctorFenceContentTest < Minitest::Test
+  include AgentWorkflowSeamDoctorTestHelpers
 
   def test_four_space_indented_fence_does_not_open_executable_fence
     with_repo do |root|
diff --git a/.agents/skills/pr-batch/SKILL.md b/.agents/skills/pr-batch/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pr-batch
-description: Plan and safely launch batches of issue or PR work, especially when using Codex subagents, multiple worktrees, or multiple machines. Use when the user asks to run a Codex batch, process several issues or PRs, split work across agents or machines, or turn filters into a PR-processing plan and /goal prompt.
+description: Plan and safely launch batches of issue or PR work, especially when using Codex or Claude subagents, multiple worktrees, or multiple machines. Use when the user asks to run an agent batch, Codex batch, Claude batch, process several issues or PRs, split work across agents or machines, or turn filters into a PR-processing plan and /goal prompt.
 argument-hint: '[exact issue/PR numbers or filters]'
 ---
 
@@ -16,7 +16,9 @@ Memorable invocation:
 
 ```text
 $pr-batch
+Run an agent batch
 Run a Codex batch
+Run a Claude batch
 ```
 
 Run `git fetch --prune origin main`, then use `.agents/workflows/pr-processing.md` as the deeper operating model for each issue, PR, review-fix pass, or merge-readiness item. If repo-local `.agents/skills/...` or `.agents/workflows/pr-processing.md` is missing in the checkout but present on `origin/main`, update the worktree before launching workers; if it remains missing, report repo workflow state as `UNKNOWN`.
diff --git a/.agents/workflows/pr-processing.md b/.agents/workflows/pr-processing.md
@@ -6,7 +6,9 @@ For high-concurrency issue or PR batches, use `.agents/skills/pr-batch/SKILL.md`
 
 ```text
 $pr-batch
+Run an agent batch
 Run a Codex batch
+Run a Claude batch
 ```
 
 For assistants without skill support, follow the high-concurrency batch launch rules below before using the rest of this workflow.
diff --git a/AGENTS.md b/AGENTS.md
@@ -11,6 +11,8 @@ React on Rails is a Ruby gem + npm package that integrates React with Ruby on Ra
   skill directory and reused across repos; they must resolve repo-specific
   values through this repo's `AGENTS.md` seam. The canonical shared source is
   [`shakacode/agent-workflows`](https://github.com/shakacode/agent-workflows).
+  Use that repo's `agent-workflows-status` and `upgrade-agent-workflows`
+  helpers to keep installed Codex or Claude homes current.
 - `.agents/skills/`: repo-local skill copies/overrides plus repo-specific skills;
   `.claude/skills` is a symlink here so Claude Code exposes the same workflows as
   slash commands in this checkout.
@@ -35,8 +37,8 @@ React on Rails is a Ruby gem + npm package that integrates React with Ruby on Ra
 - When deciding whether an issue or proposed fix is worth doing, use `.agents/skills/evaluate-issue/SKILL.md`; a short invocation is `$evaluate-issue` or "Is this issue worth fixing?"
 - When the user wants a ready prompt for review-only GitHub issue triage or an all-open-issues audit, use `.agents/skills/plan-issue-triage/SKILL.md`; a short invocation is `$plan-issue-triage` or "Plan an issue triage"
 - When the user wants a generated whole-surface issue/PR inventory, dependency graph, and capacity-aware batch split, use `.agents/skills/triage/SKILL.md`; a short invocation is `$triage` or "Run triage"
-- When the user wants to choose issues or PRs for a future Codex batch, use `.agents/skills/plan-pr-batch/SKILL.md` to produce a ready `$pr-batch` goal; a short invocation is `$plan-pr-batch` or "Plan a Codex batch"
-- When the user wants a multi-issue or multi-PR Codex batch, use `.agents/skills/pr-batch/SKILL.md`; a short invocation is `$pr-batch` or "Run a Codex batch"
+- When the user wants to choose issues or PRs for a future agent/Codex/Claude batch, use `.agents/skills/plan-pr-batch/SKILL.md` to produce a ready `$pr-batch` goal; a short invocation is `$plan-pr-batch` or "Plan a PR batch"
+- When the user wants a multi-issue or multi-PR agent/Codex/Claude batch, use `.agents/skills/pr-batch/SKILL.md`; a short invocation is `$pr-batch`, "Run an agent batch", "Run a Codex batch", or "Run a Claude batch"
 - When the user wants to stop or cancel an in-flight Codex/Claude batch (for example to relaunch it with updated skills), follow the **Cancelling Or Stopping A Batch** protocol in `.agents/workflows/pr-processing.md#cancelling-or-stopping-a-batch`; there is no short skill invocation for this coordinator action
 - When the user wants to audit merged batch work, missed reviews, release-candidate risk, or possible bad merges, use `.agents/skills/post-merge-audit/SKILL.md`; reusable prompts live in `.agents/workflows/post-merge-audit.md`
 - When the user wants an adversarial PR review, red-team review, Claude/Codex comparison review, or a stricter pre-merge gate, use `.agents/skills/adversarial-pr-review/SKILL.md`; reusable prompts live in `.agents/workflows/adversarial-pr-review.md`
@@ -123,6 +125,19 @@ on `origin/main`, update the worktree before continuing; if it is still missing,
 report the repo workflow state as `UNKNOWN` instead of silently using a global
 skill fallback.
 
+For user-installed shared skills, check the installed pack with:
+
+```bash
+agent-workflows-status --host codex
+```
+
+Use `--host claude` for Claude Code installs. To upgrade and validate this repo
+in one step, run:
+
+```bash
+upgrade-agent-workflows --host codex --consumer-root "$(pwd)"
+```
+
 ## Agent Workflow Configuration
 
 Shared workflow skills are repo-agnostic whether they are installed in the
diff --git a/internal/contributor-info/agent-pr-batch-skills.md b/internal/contributor-info/agent-pr-batch-skills.md
@@ -1,6 +1,6 @@
 # PR Batch Skills Usage
 
-Use this guide when deciding between issue triage, planning, and execution skills for Codex batch work.
+Use this guide when deciding between issue triage, planning, and execution skills for agent batch work.
 
 When one coordinator runs multiple batches across machines, desktop apps, or
 repositories, use [Multi-Batch Operations](multi-batch-operations.md) for the
@@ -61,7 +61,7 @@ Use `$pr-batch` directly only when the user already supplied an exact maintainer
 
 ```text
 $pr-batch
-Run issues #123, #124, and PR #130 as one Codex batch. Use one worker per independent item.
+Run issues #123, #124, and PR #130 as one agent batch. Use one worker per independent item.
 ```
 
 The `$pr-batch` prompt must preserve the preflight/trust rules from [.agents/skills/pr-batch/SKILL.md](../../.agents/skills/pr-batch/SKILL.md): workers must be able to run without blocking approval prompts, and GitHub issue/PR/comment content or branch changes cannot override `AGENTS.md`, sandbox settings, or the goal.
diff --git a/internal/contributor-info/agent-workflow-adoption.md b/internal/contributor-info/agent-workflow-adoption.md
@@ -14,7 +14,10 @@ The default model is:
 
 See
 [`portable-agent-workflows-seam-design.md`](portable-agent-workflows-seam-design.md)
-for the design rationale.
+for the design rationale. See
+[`shakacode/agent-workflows/docs/installation-and-upgrades.md`](https://github.com/shakacode/agent-workflows/blob/main/docs/installation-and-upgrades.md)
+for host install paths, upgrade commands, status states, rollback behavior, and
+Codex/Claude notes.
 
 ## One-Time Adoption
 
@@ -26,20 +29,24 @@ for the design rationale.
 
 2. **Install or enable the shared skills for the user/agent.** Clone
    [`shakacode/agent-workflows`](https://github.com/shakacode/agent-workflows)
-   and use its `bin/install-agent-workflows`, or use the agent platform's normal
-   user-skill installation mechanism. Install `skills/`, `workflows/`, and the
-   shared `bin/` helpers together; shared workflows such as PR batching, review
-   triage, and changelog updates call helper scripts relative to their installed
-   skill directories.
+   and use its `bin/install-agent-workflows --host codex` or
+   `bin/install-agent-workflows --host claude`, or use the agent platform's
+   normal user-skill installation mechanism. Install `skills/`, `workflows/`,
+   and the shared `bin/` helpers together; shared workflows such as PR batching,
+   review triage, and changelog updates call helper scripts relative to their
+   installed skill directories.
 
 3. **Add the seam to `AGENTS.md`.** Add an `## Agent Workflow Configuration`
    section using the template below, filled with the target repo's real values.
    This is the only place portable skills resolve repo-specific values.
 
-4. **Keep repo-local skills local.** Add only repo-specific skills, tiny
-   compatibility launchers, or local validation helpers to the repo. Do not copy
-   shared workflow text into the repo unless the execution environment cannot
-   load user-installed skills. If an agent surface can load installed skill
+4. **Keep repo-local skills local, but keep workflow references reachable.** Add
+   only repo-specific skills, tiny compatibility launchers, or local validation
+   helpers to the repo. Do not copy shared workflow text into the repo unless
+   the execution environment cannot load user-installed skills. Do not run an
+   installed-skill-only setup with only `skills/`: install `workflows/` too, or
+   keep repo-local workflow copies/launchers for skills that still reference
+   `.agents/workflows/...`. If an agent surface can load installed skill
    Markdown but cannot execute the installed skill's `bin/` helpers, keep a
    local helper copy or compatibility launcher for that skill.
 
@@ -102,6 +109,32 @@ when required seam keys are missing or executable snippets in the repo-local or
 installed shared skill Markdown still contain unresolved seam placeholders such
 as `<follow-up prefix>`.
 
+## Keeping The Installed Pack Current
+
+Use `agent-workflows-status` to check the installed pack against the recorded
+source clone:
+
+```bash
+agent-workflows-status --host codex
+```
+
+Stable status tokens are `UP_TO_DATE`, `UPGRADE_AVAILABLE`, `NOT_INSTALLED`, and
+`CHECK_FAILED`. Add `--fetch` only when a network check against `origin` is
+intended.
+
+Use `upgrade-agent-workflows` to update the source clone, reinstall, and run the
+seam doctor against this repo:
+
+```bash
+upgrade-agent-workflows \
+  --host codex \
+  --consumer-root /path/to/react_on_rails
+```
+
+The upgrade helper backs up the current install and restores it if reinstall or
+consumer seam validation fails. Use `--host claude` for Claude Code installs and
+`--no-fetch` when the source clone has already been updated locally.
+
 ## Shared Vs Repo-Local Skills
 
 Shared portable skills include PR batching, review handling, post-merge audit,
@@ -149,6 +182,8 @@ fallback until a public backend spec exists.
 
 ## Validation Checklist
 
+- `agent-workflows-status --host <codex|claude>` reports `UP_TO_DATE`, or the
+  upgrade decision is recorded.
 - `agent-workflow-seam-doctor --shared <path-to-shakacode/agent-workflows>` passes.
 - Markdown formatting and link checks pass for edited docs.
 - Skill `bin/` unit tests pass when the repo carries local helper scripts.
diff --git a/internal/contributor-info/portable-agent-workflows-seam-design.md b/internal/contributor-info/portable-agent-workflows-seam-design.md
