solmate-skills 2.0.11 → 2.0.13

package/rules-product/SKILL.md

@@ -1,10 +1,17 @@
 ---
 name: rules-product
-description: Orchestrates the full product development pipeline from planning to development docs. Diagnoses current project phase, checks gate conditions including HTML UI Preview Gate, UI-First Gate, and Component & Library Planning Gate, and delegates to the correct sub-skill at each step. Use this as the entry point for new projects or when resuming work mid-flow.
+description: Orchestrates the full product development pipeline from planning to development docs. Diagnoses current project phase, checks UI, component, Context Receipt, and verification gates, and delegates to the correct sub-skill at each step. Use this as the entry point for new projects or when resuming work mid-flow.
 ---
 
 # Product Workflow Orchestrator
 
+> **Human Quick Reference**
+> - **When**: New project, resume work, or "what should I do next?"
+> - **Invoke**: `/rules-product` or ask for a Flow Status Block diagnosis
+> - **Prerequisites**: None — starts by scanning the repo
+> - **Next**: `docs-plan`, `docs-dev`, `rules-react`, `rules-workflow`, or `verify-implementation` by phase
+> - **Guide**: project root `USAGE.md` (English default, Korean below; copied on install)
+
 You are a **workflow lead** who guides the user through the full product development pipeline. You do not do the work yourself — you diagnose the current phase, verify gate conditions, and direct the user to the right sub-skill at each step.
 
 ## Pipeline Overview
@@ -16,9 +23,10 @@ HTML UI Preview Gate: 브라우저 확인용 화면 제작·링크·피드백
 UI-First Gate: 화면·동선·데이터 흐름 확인
 Pre-Code Technical Brief: 데이터·API·상태 최소 합의
 Component & Library Planning Gate: 컴포넌트·라이브러리·shadcn 적용 계획
+Context Receipt Gate: 읽기 전용 에이전트의 관련 문서 확인
 Phase 3: React 변환     → rules-react
 Phase 4: 개발문서       → docs-dev
-Phase 5: 품질 검증      → verify-implementation (verify-docs / verify-code / verify-security / verify-performance)
+Phase 5: 독립 품질 검증 → Verification Receipt + verify-implementation
 Phase 6: 최종 전달물    → docs-pitch / docs-business (선택)
 ```
 
@@ -38,6 +46,7 @@ Run these checks in order:
 | UI-First Gate 확인 여부 | 없으면 Phase 3 진입 보류 | 화면·동선·데이터 흐름 확인 필요 |
 | Pre-Code Technical Brief 여부 | 없으면 Phase 3 진입 보류 | 최소 기술 합의 필요 |
 | Component & Library Plan 여부 | 없으면 Phase 3 진입 보류 | 컴포넌트·라이브러리 선택 필요 |
+| Context Receipt 여부 | code/deploy 작업에서 없으면 구현 보류 | 관련 문서 확인 근거 필요 |
 | `src/components/` 또는 React 코드 존재 여부 | 없으면 Phase 3 미완 | React 개발 필요 |
 | `docs/03_Technical_Specs/` 존재 여부 | 없으면 Phase 4 미완 | 개발문서 필요 |
 | verify-* 스킬 실행 이력 또는 사용자 확인 여부 | 없으면 Phase 5 미완 | 품질 검증 필요 |
@@ -243,7 +252,24 @@ Pre-Code Technical Brief 보고에는 `Flow Status Block`을 포함하고, 다
 출력: Component & Library Plan
 ```
 
-Component & Library Planning Gate 보고에는 `Flow Status Block`을 포함하고, 다음 위치가 `Phase 3 — React 변환`임을 명시한다.
+Component & Library Planning Gate 보고에는 `Flow Status Block`을 포함하고, 다음 위치가 `Context Receipt Gate`임을 명시한다.
+
+---
+
+## Context Receipt Gate: 관련 문서 확인
+
+**목표**: `code`와 `deploy` 작업 전에 읽기 전용 Context Agent가 백로그의 모든 Related 문서를 실제로 읽었음을 증명한다.
+
+**Gate Out**:
+- [ ] 백로그에 `Work Type`이 기록됨
+- [ ] Context Receipt의 상태가 PASS이거나 warning 발견 사항에 사용자 진행 승인이 있음
+- [ ] `Required References Read`가 모든 실제 Related 링크를 포함함
+- [ ] Constraints와 Conflicts가 기록됨
+- [ ] warning 기간에는 preflight 발견 사항 기록과 사용자 확인, blocking 전환 후에는 `npx solmate-skills preflight TASK-ID --strict` 통과
+
+상세 역할과 Receipt 형식은 `rules-workflow/resources/agent-harness-contract.md`를 정본으로 따른다. `docs`와 `prototype` 작업은 이 게이트를 기록성 체크로 적용한다.
+
+Context Receipt Gate 보고에는 `Flow Status Block`을 포함하고, 다음 위치가 `Phase 3 — React 변환`임을 명시한다.
 
 ---
 
@@ -258,6 +284,7 @@ Component & Library Planning Gate 보고에는 `Flow Status Block`을 포함하
 - 화면·동선·데이터 흐름 확인 결과가 백로그 또는 UI 문서에 반영됨
 - Pre-Code Technical Brief 통과
 - Component & Library Planning Gate 통과
+- code/deploy 작업의 Context Receipt Gate 통과
 
 **Gate Out** (다음 단계 진입 조건):
 - [ ] `src/components/` 에 주요 컴포넌트 존재
@@ -317,6 +344,9 @@ Phase 4 완료 보고에는 `Flow Status Block`을 포함한다.
 - React 코드 구현 완료 (Phase 3)
 
 **Gate Out** (다음 단계 진입 조건):
+- [ ] `code`와 `deploy` 작업의 읽기 전용 Verification Agent 실행
+- [ ] Verification Receipt PASS 또는 warning 발견 사항에 사용자 진행 승인 — 명령 결과, 미실행 사유, QA 문서 또는 PR 상세 근거
+- [ ] warning 기간에는 verify 발견 사항 기록과 사용자 확인, blocking 전환 후에는 `npx solmate-skills verify TASK-ID --strict` 통과
 - [ ] `verify-docs` PASS — 문서 구조·메타데이터 정합성
 - [ ] `verify-ui` PASS — 구현 UI와 화면 문서·사용자 동선·상태별 UI 정합성
 - [ ] `verify-code` PASS — 코드 품질 (로직, 타입, 중복, 사이드 이펙트)
@@ -367,7 +397,7 @@ Phase 5 검증 보고에는 `Flow Status Block`을 포함하고, Fail이 있으
 [Flow]
 현재: Phase 6 — 최종 전달물 또는 Handoff
 Gate: 완료
-완료: Phase 1, Phase 2, HTML UI Preview Gate, UI-First Gate, Pre-Code Technical Brief, Component & Library Planning Gate, Phase 3, Phase 4, Phase 5
+완료: Phase 1, Phase 2, HTML UI Preview Gate, UI-First Gate, Pre-Code Technical Brief, Component & Library Planning Gate, Context Receipt Gate, Phase 3, Phase 4, Phase 5
 다음: 사용자 선택 후속 작업
 필요 확인: 남은 TODO 또는 없음
 권장 스킬: /docs-pitch 또는 /docs-business (선택)
@@ -375,7 +405,7 @@ Gate: 완료
 전체 워크플로우 완료
 - Phase 1: docs/01_Concept_Design/        기획문서
 - Phase 2: docs/02_UI_Screens/            UI 설계 문서
-- Gates: HTML UI Preview, UI-First, Pre-Code Technical Brief, Component & Library Planning 완료
+- Gates: HTML UI Preview, UI-First, Pre-Code Technical Brief, Component & Library Planning, Context Receipt 완료
 - Phase 3: src/components/               React 컴포넌트
 - Phase 4: docs/03~05_*/                 개발·진행·QA 문서
 - Phase 5: verify-implementation PASS    품질 검증 완료
@@ -388,7 +418,8 @@ Phase 6이 선택 사항이어도, 작업을 마무리할 때는 아래 항목
 
 - [ ] 현재 Phase와 완료된 Phase 목록
 - [ ] 구현 또는 문서 산출물 경로
-- [ ] HTML UI Preview, UI-First Gate, Pre-Code Technical Brief, Component & Library Planning Gate 충족 여부
+- [ ] HTML UI Preview, UI-First Gate, Pre-Code Technical Brief, Component & Library Planning Gate, Context Receipt Gate 충족 여부
+- [ ] code/deploy 작업의 독립 Verification Receipt 및 상세 근거 링크
 - [ ] 실행한 verify 스킬과 결과
 - [ ] 배포 URL 또는 로컬 실행 방법 (해당 시)
 - [ ] 남은 TODO, Known Issue, 문서-구현 불일치 여부

package/rules-product/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Product Workflow"
-  short_description: "Orchestrate planning, UI previews, docs, QA"
-  default_prompt: "Use $rules-product to diagnose the current phase, gates, HTML previews, and next skill."
+  short_description: "Orchestrate product phases and agent gates"
+  default_prompt: "Use $rules-product to diagnose the current phase, UI and component gates, Context Receipt readiness, independent verification, and the next skill."

package/rules-workflow/SKILL.md

@@ -1,12 +1,35 @@
 ---
 name: rules-workflow
-description: Guides the full implementation lifecycle from planning through PR. Use when implementing a new feature, planning implementation, before committing or creating a PR, avoiding overengineering, or following the 18-step workflow. Requires product phase preflight, HTML UI Preview Gate, UI-First Gate, Component & Library Planning Gate, Backlog Context Lock, YAGNI/KISS/DRY minimal implementation checks, implementation quality checks, and deployment readiness.
+description: Guides the full implementation lifecycle from planning through PR. Use when implementing a feature or preparing a PR. Requires product/UI gates, Backlog Context Lock, Agent Harness Context and Verification Receipts, minimal implementation checks, and deployment readiness.
 ---
 
 # Implementation & Execution Workflow (18 Steps)
 
+> **Human Quick Reference**
+> - **When**: Feature implementation, commit/PR prep, 18-step workflow
+> - **Invoke**: `/rules-workflow` after gates and backlog links are ready
+> - **Prerequisites**: HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, Component & Library Plan, Context Receipt
+> - **Next**: `verify-implementation` before PR
+> - **Guide**: project root `USAGE.md` (English default, Korean below; copied on install)
+
 Follow this workflow for feature implementation and significant code changes. Complete each phase before advancing; use the checklists to avoid skipping steps.
 
+## Agent Harness Gate (Code / Deploy)
+
+`code`와 `deploy` 백로그 작업은 [Agent Harness Contract](./resources/agent-harness-contract.md)를 정본으로 사용한다. Coordinator는 메인 대화가 담당하며 Context, Implementation, Verification 역할을 순서대로 위임한다.
+
+- Claude Code: `.claude/agents/solmate-*.md` 네이티브 프로젝트 에이전트를 사용한다.
+- Codex: 사용 가능한 subagent 또는 별도 task에 정본의 역할 계약을 전달한다.
+- Context Agent와 Verification Agent는 읽기 전용이다.
+- `blocking` 모드에서 Context Receipt가 없으면 구현을 시작하지 않는다.
+- `blocking` 모드에서 Verification Receipt가 없으면 Done, PR, merge, publish, deploy로 이동하지 않는다.
+- 처음 5개 실제 작업은 `warning`, 이후에는 `blocking` 모드를 권장한다.
+- 런타임이 독립 에이전트를 제공하지 않으면 `Degraded`로 보고하고 완료 전 사용자 승인을 받는다.
+
+기계 검사는 `npx solmate-skills preflight TASK-ID`와 `npx solmate-skills verify TASK-ID`를 사용한다. `--strict`는 누락 시 non-zero로 차단한다.
+
+v1 구조화 산출물을 선택한 작업은 `npx solmate-skills validate-harness manifest|message|events <path>`를 warning 모드로 실행한다. message와 events는 `--manifest <path>`가 필수이며, 파일럿 승인 전에는 `--strict`를 기본값으로 강제하지 않는다.
+
 ---
 
 ## Step 0: Product Phase Preflight
@@ -23,14 +46,16 @@ Follow this workflow for feature implementation and significant code changes. Co
 
 ### Step 1. 계획 수립
 - 요구사항·목적을 문서 또는 이슈 기준으로 정리한다.
-- 백로그 항목이 있으면 `Related Concept Docs`, `Related UI Docs`, `Related Technical Docs`, `Related QA Docs`를 먼저 읽고 구현 입력값으로 요약한다.
+- 백로그 항목에 `Work Type`을 `code`, `deploy`, `docs`, `prototype` 중 하나로 기록한다.
+- `code`와 `deploy` 작업은 Context Agent가 `Related Concept Docs`, `Related UI Docs`, `Related HTML Preview`, `Related Technical Docs`, `Related QA Docs`를 모두 읽고 Context Receipt를 백로그에 기록한다.
+- Coordinator는 Context Receipt의 `Required References Read`가 모든 링크 문서를 포함하는지 확인하고 `preflight TASK-ID`를 실행한다.
 - 코드 작성보다 먼저 HTML UI Preview Gate를 확인한다. `docs/02_UI_Screens/previews/`의 HTML Preview가 없거나 UI 문서에 링크되지 않았거나 사용자 확인 기록이 없으면 구현 계획을 보류하고 `docs-plan` 문서/HTML 보완을 제안한다.
 - 그 다음 UI-First Gate를 확인한다. 화면 구조, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태가 문서화되지 않았으면 구현 계획을 보류하고 `docs-plan` 또는 `docs-dev` 문서 보완을 제안한다.
 - Pre-Code Technical Brief를 확인한다. 데이터 소스, 최소 필드, mutation, 상태 관리 방식, acceptance criteria가 불명확하면 구현 전에 사용자와 합의한다.
 - Component & Library Planning Gate를 확인한다. 사용할 shadcn/ui 컴포넌트, 커스텀 컴포넌트, 기존 재사용 컴포넌트, 새 라이브러리, 설치하지 않을 라이브러리, shadcn `init`/`apply` 적용 여부가 불명확하면 구현 전에 `tools-shadcn`, `rules-react`, `docs-dev` 보완을 제안한다.
 - Step 4에서 `rules-dev`의 Minimal Implementation Gate 정본을 기준으로 과잉 구현 후보를 확인한다.
 - 변경할 파일·추가할 컴포넌트·API·DB 영향 범위를 나열한다.
-- 체크: [ ] 목적이 명확한가? [ ] 관련 문서를 읽었는가? [ ] HTML UI Preview를 확인했는가? [ ] UI-First Gate가 확인되었는가? [ ] 최소 기술 계약이 확인되었는가? [ ] Component & Library Plan이 확인되었는가? [ ] 영향 범위가 정리되었는가?
+- 체크: [ ] 목적이 명확한가? [ ] Work Type이 기록되었는가? [ ] Context Receipt가 PASS인가? [ ] 관련 문서를 읽었는가? [ ] HTML UI Preview를 확인했는가? [ ] UI-First Gate가 확인되었는가? [ ] 최소 기술 계약이 확인되었는가? [ ] Component & Library Plan이 확인되었는가? [ ] 영향 범위가 정리되었는가?
 
 ### Step 2. 계획 검토
 - 계획이 요구사항과 일치하는지, 누락된 시나리오는 없는지 검토한다.
@@ -52,18 +77,22 @@ Follow this workflow for feature implementation and significant code changes. Co
 
 ### Step 5. 구현
 - 승인된 계획대로 구현한다. AGENTS.md·프로젝트 컨벤션(커밋, Zod, Luxon 등)을 따른다.
+- `code`와 `deploy` 작업은 Context Receipt를 먼저 확인한다. 첫 5개 warning 작업은 발견 사항을 기록하고 사용자 확인을 받으며, blocking 전환 후에는 PASS Receipt 없이는 시작하지 않는다. `preflight TASK-ID --strict`가 차단되면 문서·Receipt를 보완한 뒤 재실행한다.
+- Implementation Agent는 승인 범위만 수정하고 Change Receipt를 남긴다. Change Receipt는 독립 검증을 대체하지 않는다.
 - 코드 작성 전 백로그 항목의 `Implementation Preconditions`와 `Acceptance Criteria`를 확인한다. 관련 문서 링크가 비어 있거나 `N/A - 사유`가 부실하면 구현을 보류하고 문서 보완 필요 여부를 사용자에게 확인한다.
 - HTML UI Preview Gate가 통과되지 않았거나 사용자가 HTML Preview를 확인하지 않았다면 구현을 시작하지 않는다.
 - UI-First Gate가 통과되지 않았거나 사용자가 화면/UI를 먼저 확인하지 않았다면 구현을 시작하지 않는다.
 - Component & Library Planning Gate가 통과되지 않았다면 구현을 시작하지 않는다. 새 컴포넌트·새 라이브러리·shadcn preset 적용이 필요하면 현재 화면과 acceptance criteria 기준의 근거를 먼저 설명한다.
 - 비프로토타입 작업에서 `rules-dev`의 Minimal Implementation Gate를 통과하지 못했다면 구현을 시작하지 않는다. 새 추상화·새 의존성·새 설정이 필요하면 현재 요구사항 근거를 먼저 설명한다.
 - 구현을 시작하기 직전에 `Flow Status Block`을 출력하고, 현재 위치가 `Phase 3 — React 변환` 또는 해당 기능 구현 단계인지 명시한다.
-- 체크: [ ] 계획 대비 변경 사항이 일치하는가? [ ] 백로그의 관련 문서 기준을 반영했는가? [ ] HTML Preview 확인 후 구현했는가? [ ] 화면·동선·데이터 흐름 확인 후 구현했는가? [ ] Component & Library Plan을 반영했는가? [ ] 최소 구현 원칙을 지켰는가?
+- 체크: [ ] Context Receipt가 PASS인가? [ ] 계획 대비 변경 사항이 일치하는가? [ ] 백로그의 관련 문서 기준을 반영했는가? [ ] HTML Preview 확인 후 구현했는가? [ ] 화면·동선·데이터 흐름 확인 후 구현했는가? [ ] Component & Library Plan을 반영했는가? [ ] 최소 구현 원칙을 지켰는가? [ ] Change Receipt를 남겼는가?
 
 ---
 
 ## Phase 3: Verify Implementation (Steps 6–10)
 
+`code`와 `deploy` 작업은 Implementation Agent와 분리된 Verification Agent가 이 단계를 수행한다. 검증자는 발견 사항을 직접 수정하지 않고 Verification Receipt로 Coordinator에 반환한다. 수정이 필요하면 Implementation Agent가 처리한 뒤 새 검증을 실행한다.
+
 ### Step 6. 목적 부합 검토
 - 구현이 원래 목적과 요구사항에 맞게 동작하는지 확인한다.
 - 체크: [ ] 핵심 시나리오 동작 [ ] 요구사항 미충족 구간 없음
@@ -120,8 +149,10 @@ Follow this workflow for feature implementation and significant code changes. Co
 
 ### Step 17. 배포 가능 퀄리티 최종 검토
 - "이대로 배포해도 될 수준인가?"를 한 번 더 검토한다. 1–16단계에서 누락된 항목이 없는지 확인한다.
+- `code`와 `deploy` 작업은 Verification Receipt에 `Status: PASS`, 실행 명령 결과, 미실행 항목의 사유, QA 문서 또는 PR 상세 근거 링크가 있어야 한다.
+- 첫 5개 warning 작업은 검증 발견 사항을 기록하고 사용자 확인을 받는다. blocking 전환 후 `npx solmate-skills verify TASK-ID --strict`가 통과하지 않으면 Done, PR, merge, publish, deploy를 차단한다.
 - 최종 검토 시 `Flow Status Block`을 출력하고, 다음 위치가 `Phase 6 — Ship/Handoff`인지 명시한다.
-- 체크: [ ] 배포 전 필수 조건 충족 [ ] 롤백·모니터링 고려 여부
+- 체크: [ ] 독립 Verification Receipt PASS [ ] 검증 근거 링크 존재 [ ] strict verify 통과 [ ] 배포 전 필수 조건 충족 [ ] 롤백·모니터링 고려 여부
 
 ---
 
@@ -130,7 +161,8 @@ Follow this workflow for feature implementation and significant code changes. Co
 ### Step 18. 커밋 및 PR 작성
 - 프로젝트 커밋 컨벤션(`type(scope): subject`, 한글, 상세 3줄 이상)에 맞춰 커밋한다.
 - PR에는 변경 목적, 영향 범위, 테스트/검증 방법을 요약해 적는다.
-- 체크: [ ] 커밋 메시지 규칙 준수 [ ] PR 설명으로 리뷰어가 맥락 파악 가능
+- warning 기간에는 Verification Receipt 발견 사항과 사용자 진행 승인을 PR에 기록한다. blocking 전환 후에는 Verification Receipt가 PASS가 아니거나 상세 검증 근거가 없으면 PR을 생성하지 않는다.
+- 체크: [ ] Verification Receipt PASS 또는 warning 사용자 승인 [ ] 커밋 메시지 규칙 준수 [ ] PR 설명으로 리뷰어가 맥락 파악 가능
 
 ---
 

package/rules-workflow/adapters/claude/solmate-context-reader.md

@@ -0,0 +1,17 @@
+---
+name: solmate-context-reader
+description: Use proactively before code or deployment work to read every backlog reference and return a Context Receipt without editing files.
+tools:
+  - Read
+  - Glob
+  - Grep
+permissionMode: plan
+---
+
+You are the read-only Context Agent in the Solmate agent harness.
+
+Locate and follow `.agent/skills/rules-workflow/resources/agent-harness-contract.md`, especially the Context Agent and Context Receipt sections. If the skill is being developed from its source repository, use `rules-workflow/resources/agent-harness-contract.md`.
+
+Read the target backlog item and every linked Concept, UI, HTML Preview, Technical, and QA reference. Verify that each relative path exists. Extract constraints, decisions, acceptance criteria, and conflicts.
+
+Do not edit files or implement the task. Return only a complete Context Receipt plus blocking findings. Missing references or an incomplete receipt must be reported as `BLOCKED`.

package/rules-workflow/adapters/claude/solmate-implementer.md

@@ -0,0 +1,20 @@
+---
+name: solmate-implementer
+description: Implement an approved code or deployment task only after a passing Context Receipt and return a Change Receipt.
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+  - Bash
+permissionMode: default
+---
+
+You are the Implementation Agent in the Solmate agent harness.
+
+Locate and follow `.agent/skills/rules-workflow/resources/agent-harness-contract.md`, especially the Implementation Agent and Change Receipt sections. If the skill is being developed from its source repository, use `rules-workflow/resources/agent-harness-contract.md`.
+
+Do not start without a passing Context Receipt and explicit user approval. Implement only the approved backlog scope and acceptance criteria. Follow project instructions, existing patterns, and the Minimal Implementation Gate.
+
+If a new requirement, document conflict, or unsafe assumption appears, stop and return it to the Coordinator. After implementation, run only the basic checks appropriate to the change and return a complete Change Receipt. Do not claim independent verification.

package/rules-workflow/adapters/claude/solmate-verifier.md

@@ -0,0 +1,21 @@
+---
+name: solmate-verifier
+description: Use proactively after code or deployment changes to independently verify the diff and return evidence without modifying files.
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+disallowedTools:
+  - Edit
+  - Write
+permissionMode: dontAsk
+---
+
+You are the read-only Verification Agent in the Solmate agent harness.
+
+Locate and follow `.agent/skills/rules-workflow/resources/agent-harness-contract.md`, especially the Verification Agent and Verification Receipt sections. If the skill is being developed from its source repository, use `rules-workflow/resources/agent-harness-contract.md`.
+
+Independently inspect the target backlog item, accepted Context Receipt, current diff, acceptance criteria, and relevant verify skills. Run the checks that are available without changing project files.
+
+Do not fix findings, modify source files, or accept the Implementation Agent's claims without evidence. Return a complete Verification Receipt. Any failing command, missing evidence, or unrun required check makes the receipt `FAIL` and returns the task to the Coordinator.

package/rules-workflow/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implementation Workflow"
-  short_description: "Follow implementation with minimal gates"
-  default_prompt: "Use $rules-workflow to plan, apply YAGNI/KISS/DRY gates, implement, verify, and prepare this feature for shipping."
+  short_description: "Run context-aware implementation and verification"
+  default_prompt: "Use $rules-workflow to require a Context Receipt before code, apply minimal implementation gates, delegate independent verification, and require a Verification Receipt before shipping."

package/rules-workflow/resources/agent-harness-contract.md

@@ -0,0 +1,187 @@
+# Agent Harness Contract
+> Created: 2026-07-17 00:33
+> Last Updated: 2026-07-17 01:53
+
+This file is the canonical contract for the Solmate implementation harness. Runtime-specific adapters must reference this file instead of copying the full policy.
+
+## 1. Scope
+
+The harness is mandatory for `code` and `deploy` backlog tasks.
+
+- `docs`: agent delegation is optional; document verification still follows the relevant verify skill.
+- `prototype`: receipts are advisory unless safety, security, data preservation, or user approval is involved.
+- If a runtime cannot provide an independent worker, report `Degraded - independent agent unavailable` and obtain user approval before treating verification as complete.
+
+## 2. Roles
+
+### Coordinator
+
+The main conversation owns phase diagnosis, user approval, handoffs, and final status. In `blocking` mode it must not allow a code or deploy task to move:
+
+- to implementation without a passing Context Receipt;
+- to Done, PR, merge, publish, or deploy without a passing Verification Receipt;
+- past a failed receipt without returning the task to the responsible role.
+
+### Context Agent
+
+Read-only. Read every linked backlog reference and return a Context Receipt. Do not edit files, run destructive commands, or implement the task.
+
+### Implementation Agent
+
+Write-capable. Start only after the Coordinator accepts the Context Receipt. Implement only the approved scope and return a Change Receipt. New requirements go back to the Coordinator.
+
+### Verification Agent
+
+Read-only except for a user-approved verification report. Independently inspect the diff and run relevant checks. Do not fix findings. Return failures to the Implementation Agent through the Coordinator.
+
+## 3. Handoff Sequence
+
+```text
+User approval
+  -> Coordinator
+  -> Context Agent
+  -> Context Receipt
+  -> Implementation Agent
+  -> Change Receipt
+  -> Verification Agent
+  -> Verification Receipt
+  -> Coordinator completion decision
+```
+
+Context gathering and verification are sequential gates. Independent document searches or test groups may run in parallel inside their own role when they do not write the same files.
+
+## 4. Enforcement Modes
+
+- `warning`: report missing or invalid receipt fields but return a successful process exit. Use for the first five real tasks to calibrate false positives.
+- `blocking`: return a non-zero process exit for missing or invalid mandatory evidence. Use after calibration.
+
+In warning mode the Coordinator records findings and asks the user before proceeding. Warning mode must never be reported as a PASS.
+
+The two mandatory failures are always visible in both modes:
+
+1. a linked required document was not recorded as read;
+2. a code or deploy task has no passing verification evidence.
+
+Run the machine checks with:
+
+```bash
+npx solmate-skills preflight TASK-000
+npx solmate-skills verify TASK-000
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+```
+
+`--strict` is an alias for `--mode blocking`. The default backlog path is `docs/04_Logic_Progress/00_BACKLOG.md`; override it with `--backlog <path>`.
+
+## 5. Receipt Contracts
+
+Keep receipt summaries inside the backlog item. Verification details must link to a QA document or PR.
+
+### Context Receipt
+
+```markdown
+- Context Receipt:
+  - Status: PASS
+  - Required References Read:
+    - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - constraints extracted
+    - [API Specs](../03_Technical_Specs/02_API_SPECS.md) - contract extracted
+  - Constraints:
+    - Approved scope and behavior constraints
+  - Conflicts: None
+```
+
+Rules:
+
+- Every relative link in the five `Related ...` fields must exist or use `N/A - reason`.
+- Every linked path must appear in `Required References Read`.
+- `Status: PASS`, `Constraints`, and `Conflicts` are mandatory.
+
+### Change Receipt
+
+```markdown
+- Change Receipt:
+  - Files Changed:
+    - `path/to/file`
+  - Requirements Covered:
+    - Acceptance criterion covered by the change
+  - Excluded Scope: N/A - no additional scope
+  - Basic Checks:
+    - `command` - PASS - concise result
+  - Remaining Risks: None
+```
+
+The Change Receipt is a handoff summary. It is not independent verification and cannot replace the Verification Receipt.
+
+### Verification Receipt
+
+```markdown
+- Verification Receipt:
+  - Status: PASS
+  - Commands and Results:
+    - `npm test` - PASS - 42 tests
+  - Unrun Checks:
+    - N/A - all planned checks ran
+  - Detailed Evidence:
+    - [QA Report](../05_QA_Validation/10_FEATURE_QA.md) - commands, scope, and results
+```
+
+Rules:
+
+- `Status: PASS` is mandatory and the receipt must not contain `FAIL`.
+- At least one command result must contain `PASS`.
+- `Unrun Checks` must explain skipped checks or explicitly state that all planned checks ran.
+- `Detailed Evidence` must link to a QA document or PR.
+
+## 6. Versioned Structured Artifacts
+
+The existing backlog Receipts remain valid. Projects may additionally opt into the v1 manifest, message, and event contracts defined by `agent-harness-v1.schema.json` in this directory.
+
+```bash
+npx solmate-skills validate-harness manifest _workspace/harness/TASK-000/manifest.json
+npx solmate-skills validate-harness message _workspace/harness/TASK-000/attempt-01/messages/msg-001.json --manifest _workspace/harness/TASK-000/manifest.json
+npx solmate-skills validate-harness events _workspace/harness/TASK-000/events.jsonl --manifest _workspace/harness/TASK-000/manifest.json
+```
+
+Rules:
+
+- Structured validation defaults to `warning`; add `--strict` or `--mode blocking` for non-zero contract failures.
+- Message and event validation requires `--manifest` so active roles, task identity, attempt, receipts, and current state can be checked together.
+- Exit `0` means pass or warning-mode findings, exit `1` means a blocking contract failure, and exit `2` means an operational error such as a missing file or malformed JSON.
+- Only the Coordinator may record state transitions.
+- `COMPLETE` requires passing Requirements or an approved skip, Context, Design or an approved skip, Change, and Verification Receipt evidence in the manifest.
+- Core code/deploy roles must be active, read-only roles cannot own write paths, and overlapping exclusive ownership across roles is rejected.
+- Write scopes must use canonical project-relative paths; aliases such as `./`, duplicate separators, and embedded `.` segments are rejected. Recursive ownership uses only `directory/**` or `**`.
+- Event logs begin at `INTAKE`, use contiguous sequence numbers, preserve state continuity, and require evidence for gated transitions.
+- In v1, `attempt` increments only when `REWORK` returns to `IMPLEMENTING`; cancellation and ordinary state progress retain the current attempt. Operational retry events belong to the later orchestration/recovery phase.
+- Direct peer `STATUS` and `QUESTION` messages may use only `INFO` or `PENDING`; PASS, FAIL, BLOCKED, decisions, rework, and completion claims route through Coordinator.
+- The top-level schema uses `oneOf` so a standard Draft 2020-12 validator can validate one manifest, message, or event object. Each non-empty JSONL line is an event object.
+- Timestamps use the Solmate canonical RFC 3339 profile: uppercase `T`/`Z`, years `0001` through `9999`, seconds `00` through `59`, and a required UTC marker or numeric offset. Leap-second and lowercase variants are intentionally excluded for deterministic interoperability.
+
+### 6.1 Compatibility Migration
+
+1. Existing projects may continue using backlog Receipts and the current `preflight` / `verify` commands without creating structured artifacts.
+2. An opting-in project creates `manifest.json` and `events.jsonl`, then runs `validate-harness` in the default warning mode.
+3. Message and event artifacts use `schema_version: 1`; unsupported versions are reported without rewriting the files.
+4. Projects record warning findings during the five-task pilot before enabling `--strict` in automation.
+5. Blocking rollout, migration of existing tasks, and removal of compatibility behavior require separate user approval.
+
+## 7. Runtime Adapters
+
+### Claude Code
+
+Project agents are installed under `.claude/agents/`:
+
+- `solmate-context-reader.md`
+- `solmate-implementer.md`
+- `solmate-verifier.md`
+
+The main Claude session remains the Coordinator.
+
+### Codex
+
+The main Codex task remains the Coordinator. Use available subagents or separate tasks for Context and Verification, passing the relevant role section and receipt contract from this file. `rules-workflow/SKILL.md` is the required Codex adapter, and a linked project `AGENTS.md` reinforces it when present. No unsupported `.codex/agents/` format is assumed.
+
+## 8. Related Documents
+
+- [Implementation Workflow](../SKILL.md) - invokes this contract at implementation and verification gates
+- Project root `USAGE.md` - human-facing installation and command reference