docs: add parallel agents and git workflow guidance#142
Merged
Conversation
…ord-mcp The "claim tasks without collision" line covered task-level claims but left the git-level story unspecified, so users assumed file-level locking that the cartridge does not actually provide. Add a "Parallel agents and git" subsection to both READMEs that names the real guarantee (task-id mutex, not file lock) and documents the supported workflow: branch-per-claim, optional per-peer worktree, master-gated integration via coord_approve, and drift as an advisory signal. Also note what is explicitly out of scope (file-range locks, auto-rebase, conflict resolution) so the supervision model's serialisation point is unambiguous.
🔍 Hypatia Security ScanFindings: 30 issues detected
View findings[
{
"reason": "Stale AI session file -- delete",
"type": "stale",
"file": "GEMINI.md",
"action": "delete",
"rule_module": "root_hygiene",
"severity": "medium"
},
{
"reason": "Issue in quality.yml",
"type": "missing_workflow",
"file": "quality.yml",
"action": "create",
"rule_module": "workflow_audit",
"severity": "high"
},
{
"reason": "Issue in security-policy.yml",
"type": "missing_workflow",
"file": "security-policy.yml",
"action": "create",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
"type": "unpinned_action",
"file": "governance.yml",
"action": "pin_sha",
"rule_module": "workflow_audit",
"severity": "high"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
}
]Powered by Hypatia Neurosymbolic CI/CD Intelligence |
Close the two gaps identified by the multi-agent-coord MCP survey without modifying the verified Zig/Idris backend. * Bridge-layer path-claims (mcp-bridge/lib/path-claims.js). coord_claim_task accepts an optional `paths` array; the bridge maintains an in-memory map of active path-claims keyed by task and annotates the response with `path_overlap` warnings using segment-aware prefix matching. Advisory by design — warnings never block a claim. TTL-swept lazily, refreshed by coord_progress, released by coord_report_outcome. * Tool surface updated in mcp-bridge/lib/tools.js with the new input parameter and output fields; cartridge.json mirrors the addition so the bridge/cartridge coherence test stays green. * `just coord-worktree <task>` + matching `coord-worktree` shell helper: attempts the claim first, then provisions ../<repo>-worktrees/<task> on branch agent/<peer>/<task>. Refuses to touch the working tree when the backend denies the claim. Idempotent on re-runs. * path_claims_test.js covers overlap semantics (segment prefix, not character prefix), normalisation, TTL sweep, refresh/release, and same- holder dedupe. * Both READMEs flip the previously-"planned" caveats to describe shipped behaviour and keep the honest "does not do" list around hard locks, auto-rebase, and conflict resolution.
🔍 Hypatia Security ScanFindings: 30 issues detected
View findings[
{
"reason": "Stale AI session file -- delete",
"type": "stale",
"file": "GEMINI.md",
"action": "delete",
"rule_module": "root_hygiene",
"severity": "medium"
},
{
"reason": "Issue in quality.yml",
"type": "missing_workflow",
"file": "quality.yml",
"action": "create",
"rule_module": "workflow_audit",
"severity": "high"
},
{
"reason": "Issue in security-policy.yml",
"type": "missing_workflow",
"file": "security-policy.yml",
"action": "create",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
"type": "unpinned_action",
"file": "governance.yml",
"action": "pin_sha",
"rule_module": "workflow_audit",
"severity": "high"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
},
{
"reason": "TypeScript file detected -- banned language",
"type": "banned_language_file",
"file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
"action": "flag",
"rule_module": "cicd_rules",
"severity": "critical"
}
]Powered by Hypatia Neurosymbolic CI/CD Intelligence |
Owner
Author
|
Closing — already merged.
GitHub showed this as conflicting only because the squash produced a new SHA, so the branch's original commits looked like they still needed to apply on top of a tree that already contains them. Generated by Claude Code |
5 tasks
hyperpolymath
added a commit
that referenced
this pull request
May 24, 2026
…integration (#143) ## Summary Post-merge cleanup on top of #142. Three commits, all on top of the squash-merged #142 content: 1. **`6f861a1` — refactor.** Tighten `path-claims.js` (cache segment-splits, single-regex `//` normalise, extract `DEFAULT_TTL_S`); split `dispatcher.dispatchLocalCoord` into explicit `pathClaimsBefore`/`pathClaimsAfter` hooks; DRY the shell helpers (`_coord_claim_quiet` shared between `coord-claim` and `coord-worktree`). Adds a `PR Workflow` section to `.claude/CLAUDE.md` documenting the squash-merge + follow-up-commit hazard that produced #142's ghost-conflict. 2. **`9bb7df5` — bench.** `mcp-bridge/tests/path_claims_bench.js` + `just bench-bridge` recipe. Reference numbers on dev host: 240k ops/s at 10 active claims, 3.9k ops/s at 1000 claims, `pathsOverlap` ~170 ns/op. 3. **`f1e646a` — CI.** New `bench-bridge` job in `e2e.yml`: runs the bench, uploads artifact, posts a **sticky** PR comment (marker-tag find-or-update) so bench deltas show up inline across pushes. Per-job `pull-requests: write` override keeps workflow-level perms at `read-all`. Comment failure is non-fatal (`continue-on-error`) — token hiccups never gate the bench. ## Behavioural changes None. All 26 bridge tests stay green. Backend (Idris2/Zig) untouched. ## Test plan - [x] `node --test mcp-bridge/tests/dispatch_test.js mcp-bridge/tests/path_claims_test.js` → 26/26 pass locally - [x] `node mcp-bridge/tests/path_claims_bench.js` → completes in ~3s, stable output - [x] `python3 -c "import yaml; yaml.safe_load(open('.github/workflows/e2e.yml'))"` → valid YAML - [ ] First PR push triggers `bench-bridge` job; sticky comment appears with numbers - [ ] Second push to same PR updates the sticky comment in place (no spam) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- _Generated by [Claude Code](https://claude.ai/code/session_018MBrAtPrwfgn2WG4BAerZW)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds comprehensive documentation to both README.adoc and README.md explaining the supported patterns for parallel agent work with
local-coord-mcpand git. Clarifies that task-level collision avoidance does not provide git-level file locking, and documents the recommended workflow for coordinating multiple journeymen agents.Changes
agent/<peer-id>/<task-id>)coord_approveas serialization pointcoord_scan_suggestionsRSR Quality Checklist
Required
.envfiles includedAs Applicable
Testing
N/A — documentation-only change. No code execution or automated tests required.
https://claude.ai/code/session_018MBrAtPrwfgn2WG4BAerZW