Mk Sprint Contract

mk:sprint-contract — File-Based Sprint Contract Protocol

Negotiation protocol between generator and evaluator. Produces a signed contract file at tasks/contracts/{date}-{slug}-sprint-{N}.md BEFORE the generator writes any source code. Enforced by gate-enforcement.sh (Phase 4 extension).

For single-task plan validation (cook flow), use mk:validate-plan instead. mk:sprint-contract is for product-level specs feeding into mk:autobuild only.

When to Use

Activate when:

• User runs the sprint-contract skill <action> [task-slug]
• Harness (Phase 5) needs to negotiate a sprint before invoking the generator
• Generator agent needs to read a signed contract before starting implementation
• A previously signed contract needs amendment due to mid-build scope discovery

Skip when:

• MEOWKIT_AUTOBUILD_MODE=LEAN (adaptive density bypass for the complex/capable tier)
• The plan is --fast mode (overhead exceeds value)
• The task is the fix skill simple (Gate 1 already bypassed; contract bypass too)

Subcommands

Workflow (Inline — monolithic, < 150 lines)

propose (generator)

1. Read active product spec from newest tasks/plans/*/plan.md
2. Load rubric preset via mk:rubric/scripts/load-rubric.sh --preset {preset}
3. Determine sprint N: max of existing tasks/contracts/*-{slug}-sprint-*.md + 1, default 1
4. Copy assets/contract-template.md → tasks/contracts/{YYMMDD-HHMM}-{slug}-sprint-{N}.md
5. Populate: 5–15 ACs in Given/When/Then form, each bound to one preset rubric, each with a Verification line. Every preset rubric should have ≥1 AC binding
6. Set frontmatter: status: negotiating, rounds: 0, created: {YYMMDD-HHMM}
7. Run validate-contract.sh; fix and re-validate until clean
8. Print: "Contract proposed at {path}. Awaiting evaluator review."

review (evaluator)

1. Read newest negotiating contract for the active task
2. Per AC check: Testable? (probable via browser/curl/CLI) Rubric-aligned? (binding matches content) Scope clear? (no ambiguity)
3. For each weak AC, append Round {N+1} (reviewer): AC-{NN} {clarification} to Negotiation Log
4. If clean, write Round {N+1} (reviewer): accepted and proceed to sign
5. If clarifications added, increment rounds and signal generator to amend
6. HARD CAP: 2 negotiation rounds. Round 3 escalates to human via stop and ask the user in chat

amend (generator)

1. Address every clarification from the previous round in the relevant ACs (replace, don't delete)
2. Append Round {N+1} (proposer): {summary of changes} to the log
3. Re-run validate-contract.sh
4. Signal evaluator to review again

sign (both agents in sequence)

The signature workflow uses two commits per agent to avoid the chicken-and-egg of "the SHA must be inside the file but the file's commit hasn't happened yet."

1. Generator (commit 1): git add tasks/contracts/{path}.md && git commit -m "contract: generator commits sprint {N} for {slug}". The contract file is committed with generator_signed: pending.
2. Generator (commit 2 — capture SHA): gen_sha=$(git rev-parse HEAD). Edit the frontmatter: generator_signed: $gen_sha. Then git add + git commit -m "contract: generator signs sprint {N} for {slug} (sha=$gen_sha)". The captured SHA references the COMMIT THAT EXISTED WHEN THE GENERATOR APPROVED — its own first commit.
3. Evaluator (commit 1): verify the contract is unchanged from commit 2 above. Then git add + git commit -m "contract: evaluator commits sprint {N} for {slug}".
4. Evaluator (commit 2 — capture SHA): eval_sha=$(git rev-parse HEAD). Edit the frontmatter: evaluator_signed: $eval_sha, status: signed. Then git add + git commit -m "contract: evaluator signs sprint {N} for {slug} (sha=$eval_sha)".
5. The git log IS the audit trail — every signature commit is verifiable via git log --oneline tasks/contracts/{path}.md.
6. After both sign, gate-enforcement.sh allows source edits for this sprint.

Validator enforcement: check-contract-signed.sh rejects placeholder values (null, pending, todo, empty, quoted variants of these). Only a real git rev-parse HEAD SHA passes.

validate

.cursor/skills/sprint-contract/scripts/validate-contract.sh tasks/contracts/{path}.md

sprint-goal (Agile mode — gated by agile-sprint-commitment.md 1)

Sprint-LEVEL goal management. Writes to tasks/contracts/sprint-state-{date}-sprint-{N}.md — distinct from per-story sprint-CONTRACT files.

Concurrent-write safety: sprint-goal set MUST acquire flock on the sprint-state file before any read-modify-write. YAML frontmatter append is non-atomic across shells; lock is the only mitigation. Release on completion or error.

Validator scope: the existing validate-contract.sh is for sprint-CONTRACT files only. Sprint-STATE files have NO validator; YAML is parsed inline by consuming skills (this skill, mk:agent-detector Step 0b, mk:jira-agile).

Why this lives here: tasks/contracts/ already belongs to this skill; co-locating sprint-goal avoids creating a sibling skill that duplicates path discipline.

Mid-build amendment (post-sign)

The amendment flow MUST null both signature fields BEFORE adding the amendment block. Otherwise stale SHAs from the prior signing round would falsely pass check-contract-signed.sh.

1. Generator opens amendment:
   • Edit the frontmatter: status: amended, generator_signed: null, evaluator_signed: null
   • Append ### Amendment N — {YYMMDD-HHMM} under ## Amendments describing the change
   • DO NOT edit the original signed criteria — append the revised version as a new AC or override note
   • git commit -m "contract: amendment N for sprint {N} ({slug})"
2. Both agents re-sign following the same two-commit pattern from sign action above. New SHAs replace the nulled fields.
3. gate-enforcement.sh enforcement: between step 1 and step 2 (sigs are null but status is amended), source edits are BLOCKED. The check-contract-signed.sh script rejects amended-status contracts that have null/placeholder sigs. This is the intended discipline — you can't push source code while an amendment is in-flight.

Original signed criteria stay visible — amendments are append-only history.

Adaptive Density Skip

When MEOWKIT_AUTOBUILD_MODE=LEAN:

• The contract negotiation is skipped entirely (per Phase 5 adaptive density policy for the complex/capable tier — capable models self-derive criteria from the product spec)
• gate-enforcement.sh honors the env var and allows source edits without contract verification
• LEAN bypasses are logged to .meowkit/telemetry/lean-bypass.log for audit
• LEAN mode is a PROJECT-level setting, not per-file override

Gotchas

• Don't mutate signed criteria. Revisions go in the Amendments section, not by editing original ACs in place
• Don't exceed 2 negotiation rounds. Escalate to human on round 3 — agents that can't converge in 2 rounds won't converge in 5
• Don't skip the rubric tie-in. Each AC must reference one rubric in the active preset, otherwise the evaluator has no anchor for grading
• Don't write source code without checking the contract. gate-enforcement.sh will block; the developer agent's "Contract Discipline" section codifies this behavioral requirement too
• Don't sign without git commits. The git log is the audit trail — generator_signed and evaluator_signed fields hold real SHAs, not "yes" placeholders

References

Related Rules

• AGENTS.md (Gates) — Gate 1 contract-signing requirement this skill enforces before source edits are allowed

Start

For interactive use, run the sprint-contract skill propose <task-slug> to begin negotiation. For harness-driven use (Phase 5), the harness skill invokes propose → review → amend → sign automatically as a substep between Phase 2 (test red) and Phase 3 (build green).