Skip to content

fix(corpflow): State the build/test and worktree contracts in CORPFLOW.md - #22

Merged
ikorich merged 1 commit into
masterfrom
fix/corpflow-seam-contract
Aug 15, 2026
Merged

ikorich merged 1 commit into
masterfrom
fix/corpflow-seam-contract

Conversation

@ikorich

@ikorich ikorich commented Aug 15, 2026

Copy link
Copy Markdown
Member

Motivation

CORPFLOW.md is the only file in this plugin that knows corpflow exists — the single thing a sibling agent reads on entry to learn the stage contract. A four-platform, eleven-stage stress test surfaced four gaps in it. Each produced observable cross-agent divergence; one was an outright contradiction of corpflow's own rules.

Changes

Gap Before After
Build/test absent; android's copy pointed at raw Gradle, which agents/developer.md forbids ## Build and test (BINDING) — use the plugin's build-test command, --no-test for build-only, and the two correct outcomes when the gate still denies
Worktree absent; "nothing outside .context/ is yours to create" — wrong for DV ## Worktree isolation (DV) — mismatch means stop and report; never create/move worktrees; re-confirm the pin before each write batch
Evidence manifest unnamed screenshots.md is the record of authority; do not read/write facts.screenshots
Return summary role implicit returning is what settles the stage; out-of-band reporting does not

Additive only — no restructuring. Section order is now Evidence → Build and test → Worktree → Artifacts.

What went wrong without these

  • Two streams denied by the test-execution gate both invented --build-only (not a real flag on any plugin's command, so it classifies as a full test run and is denied again), and both fell back to direct toolchain calls.
  • Two agents in identical worktree situations resolved the tree check differently — one blocked correctly, one relocated its tree and staled every guard keyed to metadata.workspace_path.
  • One stream discovered the capped, last-writer-wins evidence ledger unaided and invented its own key to avoid erasing a sibling's rows.
  • One completed stage with its artifact on disk sat at in_progress because it reported out of band.

Test plan

Documentation-only; no executable behaviour. Verified:

  • All six sibling CORPFLOW.md files patched identically; plugin name correctly substituted into each build-test reference (/apple-developer:build-test, /frontend-developer:build-test, …).
  • android's contradicting sentence removed — grep -c 'use scoped .Bash(gradle' → 0 — and replaced with a pointer to the build-test command, retaining scoped Bash(adb:*) for evidence capture.
  • Section order and heading structure confirmed intact; file grew 253 → 302 lines with no existing section altered except the ## Artifacts scope sentence and android's evidence line.

Notes

The ## Artifacts line was corrected rather than deleted: .context/ remains the artifact home, and DV additionally owns its assigned platform tree inside its worktree.

CORPFLOW.md is the only corpflow-facing file in this plugin, so it is where a
sibling agent learns the stage contract. A four-platform run surfaced four gaps,
each causing observable cross-agent divergence.

Build and test was absent entirely, and android's copy contradicted corpflow by
directing the agent at raw Gradle. Two streams denied by the test-execution gate
invented --build-only, which is not a real flag, and fell back to toolchain calls
that agents/developer.md forbids. The file now names the build-test command,
--no-test for build-only, and the two correct outcomes when the gate still denies.

Worktree isolation was absent. The file said nothing outside .context/ was the
agent's to create, which is wrong for DV, and said nothing about the assigned-tree
check. Two agents resolved it differently; one relocated its tree and staled every
guard keyed to metadata.workspace_path. The file now states that a mismatch means
stop and report, that agents neither create nor move worktrees, and that the pin
is re-confirmed before each write batch.

The authoritative screenshot manifest was unnamed, so a stream invented its own
ledger key to avoid erasing a sibling's rows.

The return summary's role as the completion signal was implicit, so a finished
stage that reported out of band sat at in_progress with its artifact on disk.
@ikorich
ikorich merged commit b9ddfd2 into master Aug 15, 2026
2 checks passed
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.

1 participant