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 COMPLEX/Opus 4.6 tier)
• The plan is --fast mode (overhead exceeds value)
• The task is the fix skill simple (Gate 1 already bypassed; contract bypass too)

Subcommands

Subcommand	Owner	Effect
propose	generator (developer agent)	Drafts a contract from the product spec + rubric preset; status: draft → negotiating
review	evaluator	Critiques the proposed contract for testability + scope clarity; produces clarification requests
amend	generator	Iterates on the contract per evaluator feedback; status stays negotiating; rounds += 1
sign	both	Both agents commit to the contract via git commit messages; status: negotiating → signed
validate	anyone	Runs validate-contract.sh to check schema conformance
sprint-goal	user	Writes/reads/aligns sprint-LEVEL goal in tasks/contracts/sprint-state-{date}-sprint-{N}.md (Agile mode)

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

.agents/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.

Action	Form	Effect
set	mk:sprint-contract sprint-goal set "<text>" --sprint N	Writes sprint_goal: (≤120 chars) to tasks/contracts/sprint-state-{YYMMDD}-sprint-{N}.md. Creates the file from assets/sprint-state-template.md if absent
show	mk:sprint-contract sprint-goal show --sprint N	Prints current sprint_goal: from the newest sprint-state file matching --sprint N
align	mk:sprint-contract sprint-goal align --plan <path>	Renders alignment between plan goal (frontmatter goal: or first H1) and sprint goal. Advisory — never blocks

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 COMPLEX/Opus 4.6 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

File	Purpose
assets/contract-template.md	Canonical per-story sprint-contract schema with placeholder ACs
assets/sprint-state-template.md	Sprint-LEVEL state contract template (used by sprint-goal set; tracks goal + committed_tickets + amendments + closure summary)
scripts/validate-contract.sh	Schema + AC-form validator (POSIX-aware Bash 3.2+)
scripts/check-contract-signed.sh	Gate helper called by gate-enforcement.sh to block source edits before sign
references/bdd-to-ac-mapping.md	How Gherkin scenarios map to acceptance criteria
../../hooks/gate-enforcement.sh	Hook that enforces the contract gate on Edit/Write of source files
../../agents/developer.md	Generator agent — owns propose and amend actions
../../agents/evaluator.md	Evaluator agent — owns review action; also Phase 3 active-verification consumer
..the rubric skill/	Rubric library — provides composed presets the contract binds to
..the evaluate skill/	Evaluator skill — reads signed contract via step-01-load-rubrics.md

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).