Skip to content

fix: harden forge-coordination skill against DCP compression - #56

Open
jflowers wants to merge 1 commit into
unbound-force:mainfrom
jflowers:opsx/harden-forge-skill-compression
Open

fix: harden forge-coordination skill against DCP compression#56
jflowers wants to merge 1 commit into
unbound-force:mainfrom
jflowers:opsx/harden-forge-skill-compression

Conversation

@jflowers

@jflowers jflowers commented Aug 2, 2026

Copy link
Copy Markdown
Contributor

Summary

Restructures the forge-coordination skill to survive DCP context compression. Critical access-control constraints were expressed as parenthetical asides and buried bullet items — exactly the constructs that context compression drops first.

Addresses four specific fragilities identified in #48:

  1. (coordinator only) parenthetical on comms_release_all() — promoted to ## Coordinator-Only Operations section header
  2. exclusive=true as optional bullet — made the documented default in comms_reserve call signature
  3. Conflict resolution in a separate section — inlined at the "Reserve files" step in the Worker Protocol
  4. Mixed coordinator/worker rules in a flat list — split into role-scoped sections with MUST/MUST NOT rules at section top

Closes #48

How to Test

# Build compiles with updated embedded skill
make build

# All tests pass (190+ tests, race detection)
make test

# Both skill copies are byte-identical
diff internal/agentkit/content/skills/forge-coordination/SKILL.md \
     .opencode/skills/forge-coordination/SKILL.md

# Verify the restructured document
cat internal/agentkit/content/skills/forge-coordination/SKILL.md

Verify the following structural properties in the output:

  • ## Coordinator-Only Operations section exists with MUST NOT rules before protocol steps
  • ## Worker-Only Operations section exists with MUST/MUST NOT rules before protocol steps
  • comms_release_all() appears only under Coordinator-Only Operations
  • Workers MUST NOT call comms_release_all() is explicit in Worker-Only Operations
  • Conflict resolution steps are inlined after step 3 (Reserve files) in Worker Protocol
  • comms_reserve(paths=[...], exclusive=true, reason="...") is the documented call

How to Demo

Review the restructured skill document side-by-side with the original (via git diff). The key observation is that safety constraints have moved from low-salience positions (parentheticals, buried bullets, separate sections) to high-salience positions (section headers, first-position MUST rules, inline at point of use).

Key Files Changed

Skill files (implementation):

  • .opencode/skills/forge-coordination/SKILL.md — restructured with role-scoped sections
  • internal/agentkit/content/skills/forge-coordination/SKILL.md — identical copy (embedded in binary)

OpenSpec artifacts (planning):

  • openspec/changes/harden-forge-skill-compression/proposal.md — motivation, impact, constitution alignment
  • openspec/changes/harden-forge-skill-compression/design.md — 5 design decisions with rationale
  • openspec/changes/harden-forge-skill-compression/specs/forge-coordination-hardening.md — delta spec with GIVEN/WHEN/THEN scenarios
  • openspec/changes/harden-forge-skill-compression/tasks.md — implementation checklist (all complete)

Known Issues

The following findings from the review council were acknowledged but not resolved (out of scope for this change):

  • LOW: forge-global skill uses weaker phrasing for comms_release_all access control
  • LOW: /handoff command calls comms_release_all() without role guard
  • LOW: Worker agent checklist omits explicit comms_release step

This PR was generated by /uf.finale (AI-assisted).

Restructure the forge-coordination skill to survive context
compression by promoting safety-critical constraints to
high-salience positions:

- Replace flat "File Reservation Rules" section with role-scoped
  "Coordinator-Only Operations" and "Worker-Only Operations" sections
- Inline conflict resolution at the "Reserve files" step instead of
  separate section
- Make exclusive=true the documented default for comms_reserve
- Place MUST/MUST NOT rules at section top, before protocol steps
- Add explicit "Workers MUST NOT call comms_release_all()" constraint

Both skill copies (agentkit embed + opencode runtime) updated
identically. Includes OpenSpec artifacts (proposal, design, spec,
tasks).

Closes unbound-force#48

Assisted-by: claude-opus
Generated with AI assistance (claude-opus)
@jflowers
jflowers requested a review from a team as a code owner August 2, 2026 19:21
@jflowers
jflowers requested a review from yvonnedevlinrh August 2, 2026 20:50
@jflowers jflowers self-assigned this Aug 2, 2026
@jflowers jflowers moved this to In Review 👀 in Unbound Force Planning Aug 2, 2026
@yvonnedevlinrh yvonnedevlinrh self-assigned this Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Review 👀

Development

Successfully merging this pull request may close these issues.

bug: forge-coordination skill scoping restrictions expressed as parentheticals — lost under compression

2 participants