solmate-skills 2.0.12 → 2.0.13

package/AGENTS.md

@@ -99,6 +99,15 @@
 - **프로토타입 예외**: 프로토타입·스파이크·탐색 단계에서는 차단 조건이 아니라 기록성 체크로 적용한다.
 - **안전 예외**: 검증, 인증·인가, 에러 처리, 접근성, 보안, 데이터 보존, 테스트 가능성은 단순화를 이유로 제거하지 않는다.
 
+### 3.3. Agent Harness Gate (Context / Implementation / Verification)
+- **정본 위치**: 역할·권한·인계·Receipt 상세 형식은 `rules-workflow/resources/agent-harness-contract.md`를 따른다.
+- **적용 범위**: `Work Type`이 `code` 또는 `deploy`인 백로그 작업에 필수로 적용한다. `docs`, `prototype`은 기록성 체크로 적용한다.
+- **구현 전 차단**: `blocking` 모드에서는 읽기 전용 Context Agent가 모든 Related 문서를 읽고 PASS Context Receipt를 남기지 않으면 구현을 시작할 수 없다.
+- **완료 전 차단**: `blocking` 모드에서는 읽기 전용 Verification Agent가 명령 결과와 QA 문서 또는 PR 근거를 포함한 PASS Verification Receipt를 남기지 않으면 Done, PR, merge, publish, deploy로 이동할 수 없다.
+- **역할 분리**: Implementation Agent가 작성한 Change Receipt는 독립 검증이 아니다. Verification Agent는 발견 사항을 직접 수정하지 않고 Coordinator를 통해 Implementation Agent로 반환한다.
+- **Claude와 Codex**: Claude Code는 `.claude/agents/solmate-*.md`를 사용한다. Codex는 `rules-workflow` 정본을 사용 가능한 subagent 또는 별도 task에 전달한다.
+- **강제 수준**: 처음 5개 실제 작업은 `warning` 결과를 기록하고 사용자 확인 후 진행한다. 이후 `npx solmate-skills preflight TASK-ID --strict`와 `npx solmate-skills verify TASK-ID --strict`를 차단 게이트로 사용한다.
+
 ## 4. Skills & AI Capabilities
 AI 에이전트는 본 프로젝트에 설치된 다음 **26개 스킬**을 활용하여 작업을 수행하며, 모든 작업 결과물은 이 스킬들의 검증 가이드를 통과해야 한다.
 

package/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Repo Is
 
-`solmate-skills` is an npm package that ships curated AI skill files (SKILL.md) to downstream projects. It is **not** an application — it is a skill library and CLI tool. Each top-level directory (except `bin/`) is a skill that gets copied into `.agent/skills/<skill-name>` of a target project.
+`solmate-skills` is an npm package that ships curated AI skill files (SKILL.md) to downstream projects. It is **not** an application — it is a skill library and CLI tool. Each installable top-level directory contains `SKILL.md` and is copied into `.agent/skills/<skill-name>` of a target project.
 
 ## CLI Commands
 
@@ -17,13 +17,20 @@ npx solmate-skills install <skill-name>
 
 # Install all skills
 npx solmate-skills@latest install all
+
+# Refresh native Claude project agents
+npx solmate-skills@latest install agents
+
+# Check backlog context and verification receipts
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
 ```
 
-There are no build, test, or lint scripts in this repo (`"test": "echo \"Error: no test specified\" && exit 1"`).
+Run `npm test` to validate the harness receipt parser and blocking behavior. There is no build or lint script.
 
 ## Installing Skills via Symlink (Dev)
 
-`init-skills.sh` creates symlinks from a target project's `.agent/skills/` to this repo, and links `AGENTS.md` and `USAGE.md` to the project root. Run it from inside the target project:
+`init-skills.sh` creates symlinks from a target project's `.agent/skills/` to this repo, links `AGENTS.md` and `USAGE.md` to the project root, and links the namespaced Claude project agents under `.claude/agents/`. Run it from inside the target project:
 
 ```bash
 bash /Users/namhyeongseog/Documents/solmate-skills/init-skills.sh
@@ -33,6 +40,7 @@ bash /Users/namhyeongseog/Documents/solmate-skills/init-skills.sh
 
 ```
 bin/cli.js          — CLI entrypoint; discovers skills as top-level dirs, copies them to .agent/skills/
+bin/harness-check.js — Backlog Context/Verification Receipt parser and blocking checks
 AGENTS.md           — Global AI collaboration rules (linked into target projects)
 init-skills.sh      — Symlink installer for local development
 <skill-name>/
@@ -40,6 +48,7 @@ init-skills.sh      — Symlink installer for local development
   templates/        — (optional) document templates
   resources/        — (optional) reference files
   examples/         — (optional) example outputs
+  adapters/         — (optional) runtime-specific thin adapters; canonical policy remains in resources/
 ```
 
 Skills discovered by `bin/cli.js` = any top-level directory not in `IGNORED_FOLDERS` (`bin`, `node_modules`, `.git`, `.github`, `.gemini`, `.agent`).
@@ -61,6 +70,7 @@ Skills discovered by `bin/cli.js` = any top-level directory not in `IGNORED_FOLD
 - **Conventional Commits in Korean**: `type(scope): 한글 요약` (e.g. `feat(login): 소셜 로그인 API 연동`).
 - **5-Layer doc structure**: `docs/01_Concept_Design/`, `02_UI_Screens/`, `03_Technical_Specs/`, `04_Logic_Progress/`, `05_QA_Validation/`.
 - **Backlogs and roadmaps** belong exclusively in `docs/04_Logic_Progress/`.
+- **Agent Harness Gate**: code/deploy work requires a passing Context Receipt before implementation and an independent Verification Receipt before completion or release.
 
 ## Skill Categories
 

package/README.md

@@ -1,8 +1,8 @@
 # solmate-skills
 
-Reusable AI-agent skills for disciplined product work.
+Reusable AI-agent harness and workflow skills for disciplined product work.
 
-`solmate-skills` packages the Solmate workflow as installable skills: plan the product, create browser-viewable UI previews, lock backlog tasks to their source documents, plan components and libraries before coding, implement with YAGNI/KISS/DRY approval gates, and verify the result before release.
+`solmate-skills` packages the Solmate workflow as installable skills: plan the product, create browser-viewable UI previews, lock backlog tasks to their source documents, prove that required context was read, plan components and libraries before coding, implement with YAGNI/KISS/DRY approval gates, and independently verify the result before release.
 
 Use it when you want an AI coding agent to follow a shared workflow instead of improvising project structure, documentation, implementation order, and QA.
 
@@ -22,9 +22,12 @@ npx solmate-skills@latest install rules-product
 
 # Install proactive hook suggestions for Claude Code projects
 npx solmate-skills@latest install hooks
+
+# Refresh native Claude agents for the shared harness
+npx solmate-skills@latest install agents
 ```
 
-The installer copies each selected skill folder into `.agent/skills/<skill-name>` in your current project and copies [USAGE.md](./USAGE.md) to the project root.
+The installer copies each selected skill folder into `.agent/skills/<skill-name>` in your current project and copies [USAGE.md](./USAGE.md) to the project root. Installing `rules-workflow` or `all` also installs the namespaced Claude project agents under `.claude/agents/`; Codex uses the same canonical contract through `rules-workflow`, reinforced by `AGENTS.md` when that file is linked into the project.
 
 **Detailed usage:** see `USAGE.md` at the project root (English default, Korean below) for the situation-to-skill cheat sheet, orchestrator map, full skill catalog (26 skills), gate details, and recommended prompts.
 
@@ -37,8 +40,83 @@ The installer copies each selected skill folder into `.agent/skills/<skill-name>
 - **Component & Library Planning Gate**: React work must name the shadcn/ui components, custom components, reused components, libraries to add, libraries to avoid, and preset action before coding.
 - **YAGNI/KISS/DRY Gate**: `rules-dev` is the canonical source for avoiding future-only features, preferring the simplest existing/native path, and removing only true duplicate knowledge.
 - **Implementation workflow**: `/rules-workflow` keeps coding work tied to approved documents, preconditions, and acceptance criteria.
+- **Agent harness**: a read-only Context Agent proves required documents were read, an Implementation Agent returns a scoped change summary, and a read-only Verification Agent provides independent evidence before completion.
+- **Machine-checkable receipts**: `preflight TASK-ID` checks linked document coverage and `verify TASK-ID` checks command results plus QA/PR evidence; `--strict` turns findings into blocking exit codes.
+- **Versioned harness artifacts**: `validate-harness` checks v1 task manifests, structured messages, ordered state events, role activation, evidence gates, and exclusive write ownership.
 - **Release verification**: `/verify-implementation` runs the verification family for docs, UI, code, security, performance, DB schema, and skill package readiness.
 
+## What's New in 2.0.13: Agent Harness Contracts
+
+`solmate-skills@2.0.13` strengthens the existing Solmate workflow with a shared Claude/Codex agent harness. It addresses two recurring failure modes in long AI-assisted projects:
+
+1. An implementation starts from a backlog item without reading the linked concept, UI, technical, and QA documents.
+2. An agent marks work complete based only on its own summary, without independent verification evidence.
+
+The harness makes both boundaries explicit and machine-checkable while preserving the existing skill installation and backlog format.
+
+### How the harness works
+
+```text
+Coordinator
+  -> read-only Context Agent -> Context Receipt
+  -> Implementation Agent    -> Change Receipt
+  -> read-only QA Inspector   -> Verification Receipt
+  -> Done / PR / merge / publish / deploy
+```
+
+- **Context Receipt** records every required backlog reference that was read, the extracted constraints, and any conflict found before implementation.
+- **Change Receipt** records changed files, covered requirements, excluded scope, checks, and remaining risks. It is a handoff, not independent proof.
+- **Verification Receipt** records commands, results, unrun checks, detailed QA evidence, and the independent PASS/FAIL decision.
+- Code and deploy tasks are blocked from implementation without Context evidence and from completion without Verification evidence. Documentation and prototype work remain advisory.
+
+The canonical contract lives at [`rules-workflow/resources/agent-harness-contract.md`](./rules-workflow/resources/agent-harness-contract.md).
+
+### Backlog Receipt checks
+
+Existing projects can keep their current `00_BACKLOG.md` workflow and add the checks incrementally:
+
+```bash
+# Confirm required linked documents were read before coding
+npx solmate-skills preflight TASK-000
+
+# Confirm independent command and QA/PR evidence before completion
+npx solmate-skills verify TASK-000
+
+# Turn findings into blocking exit codes for CI or release gates
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+```
+
+### Versioned manifest, message, and event checks
+
+Projects that need structured multi-agent coordination can opt into the v1 contract without rewriting existing backlog Receipts:
+
+```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
+```
+
+[`agent-harness-v1.schema.json`](./rules-workflow/resources/agent-harness-v1.schema.json) defines the manifest, message, and state-event shapes. The validator additionally checks task identity, legal state transitions, active roles, message authority, required evidence, canonical file paths, and exclusive write ownership.
+
+| Mode / result | Exit code | Behavior |
+|:---|:---:|:---|
+| Default warning mode, valid | `0` | Reports PASS |
+| Default warning mode, contract finding | `0` | Reports findings without blocking migration |
+| `--strict`, contract finding | `1` | Blocks the workflow or CI step |
+| Invalid command input, unreadable file, malformed JSON/JSONL | `2` | Reports an operational error |
+
+### Compatibility and current scope
+
+- Existing `preflight`, `verify`, and backlog Receipt fixtures continue to work without structured artifact files.
+- The structured v1 contract is opt-in and warning-first; projects can move to `--strict` after a real-task pilot.
+- The implementation uses the Node standard library and adds no runtime dependency.
+- Claude Code can install the current namespaced `solmate-*` project agents with `install agents`; Codex follows the same canonical contract through its available delegation mechanism.
+- Specialist personas, runtime orchestration, persistent recovery, pilot automation, and blocking rollout remain separate follow-up work.
+- This release ships the contract and validation foundation; specialist personas and runtime orchestration remain separately gated follow-up work.
+
 ## What's New in 2.0.12
 
 `solmate-skills@2.0.12` adds a bilingual usage guide and copies it into every target project on install.
@@ -86,7 +164,7 @@ Recent workflow guardrails:
 
 ## Install Details
 
-`install all` installs only skill folders that contain `SKILL.md`. Use `install hooks` separately when you want prompt/file-change suggestions that nudge the agent toward `/rules-product`, `/rules-workflow`, and the relevant `verify-*` skills.
+`install all` installs only skill folders that contain `SKILL.md` and adds the namespaced Claude agent adapters. Use `install hooks` separately when you want prompt/file-change suggestions. Use `install agents` to refresh `rules-workflow`, its canonical contract, and the native Claude adapters in an existing project.
 
 ---
 
@@ -137,6 +215,14 @@ Reinstall from the project root, then diagnose — do not restart from Phase 1 b
 ```bash
 npx solmate-skills@latest install all
 npx solmate-skills@latest install hooks
+npx solmate-skills@latest install agents
+```
+
+For a `code` or `deploy` backlog item:
+
+```bash
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
 ```
 
 Example prompts: [USAGE.md §9 Recommended Prompts](./USAGE.md#9-recommended-prompts) (EN) · [§9 권장 프롬프트](./USAGE.md#9-권장-프롬프트-모음) (KO)
@@ -145,7 +231,7 @@ Example prompts: [USAGE.md §9 Recommended Prompts](./USAGE.md#9-recommended-pro
 
 ## Skills at a Glance
 
-26 installable skills plus `hooks`. Category summary:
+26 installable skills plus `hooks` and `agents` utilities. Category summary:
 
 | Category | Skills |
 |:---|:---|

package/USAGE.md

@@ -3,12 +3,12 @@
 <a id="solmate-skills-usage-guide"></a>
 
 Created Date: 2026-06-25 03:00  
-Last Updated Date: 2026-06-29 15:20
+Last Updated Date: 2026-07-17 00:33
 
 **Language:** English (default) · [Korean version below](#solmate-skills-usage-guide-korean)
 
 This is a **human-readable** guide for choosing and invoking skills.  
-Agent execution rules live in each `SKILL.md` and the installed `AGENTS.md`.
+Agent execution rules live in each `SKILL.md` and the project `AGENTS.md` when it is linked or installed.
 
 ---
 
@@ -29,9 +29,10 @@ Run /verify-implementation on the current changes
 ```bash
 npx solmate-skills@latest install all      # .agent/skills/<skill-name>/ + ./USAGE.md
 npx solmate-skills@latest install hooks    # Claude Code suggestions (optional) + ./USAGE.md
+npx solmate-skills@latest install agents   # Refresh rules-workflow + native Claude project agents
 ```
 
-Every `install` command (single skill, `all`, or `hooks`) copies `USAGE.md` to the **project root**.
+Every `install` command (single skill, `all`, `hooks`, or `agents`) copies `USAGE.md` to the **project root**. Installing `rules-workflow` or `all` also installs the namespaced Claude agents automatically.
 
 ### Local development (symlink)
 
@@ -42,7 +43,7 @@ When hacking on the `solmate-skills` repo itself:
 bash /path/to/solmate-skills/init-skills.sh
 ```
 
-This symlinks `.agent/skills/` to the repo and links `AGENTS.md` and `USAGE.md` at the project root.
+This symlinks `.agent/skills/` to the repo, links `AGENTS.md` and `USAGE.md` at the project root, and links the namespaced Claude agents under `.claude/agents/`.
 
 ---
 
@@ -107,6 +108,39 @@ This symlinks `.agent/skills/` to the repo and links `AGENTS.md` and `USAGE.md`
 | `rules-workflow` | Plan → implement → cleanup → PR (18 steps) | Feature work, commit/PR prep |
 | `verify-implementation` | Run verify-* by changed files, unified report | Pre-PR / pre-release |
 
+### Agent harness sequence
+
+For backlog tasks with `Work Type: code` or `Work Type: deploy`:
+
+```text
+Coordinator
+  -> read-only Context Agent -> Context Receipt
+  -> Implementation Agent    -> Change Receipt
+  -> read-only Verifier       -> Verification Receipt
+  -> Coordinator completion decision
+```
+
+- Claude Code uses `.claude/agents/solmate-context-reader.md`, `solmate-implementer.md`, and `solmate-verifier.md`.
+- Codex uses available subagents or separate tasks with the same canonical contract from `rules-workflow/resources/agent-harness-contract.md`.
+- The verifier reports findings but does not modify source files.
+- Receipt summaries stay in the backlog; detailed verification links to a QA document or GitHub PR.
+- Use warning mode for the first five real tasks, then switch to blocking checks:
+
+```bash
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+```
+
+Optional v1 structured artifacts use the same warning-to-blocking migration:
+
+```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
+```
+
+Add `--strict` for blocking validation. Contract failures then exit `1`; malformed JSON, missing files, and invalid command input exit `2`. Existing backlog-only projects do not need to create these files.
+
 ### Individual verify-* vs master
 
 | Situation | Use |
@@ -129,9 +163,10 @@ Phase 2  UI design docs      → docs-plan (02_UI_Screens)
          UI-First Gate        → screens, flows, data, states
          Pre-Code Technical Brief → API, state, acceptance criteria
          Component & Library Planning Gate → shadcn, custom, reuse, libraries
+         Context Receipt Gate  → linked docs read by a read-only agent
 Phase 3  React implementation → rules-react (+ tools-shadcn)
 Phase 4  Dev docs              → docs-dev (03–05)
-Phase 5  Quality verification  → verify-implementation
+Phase 5  Independent verification → Verification Receipt + verify-implementation
 Phase 6  Deliverables (opt.)   → docs-pitch / docs-business
 ```
 
@@ -171,9 +206,9 @@ Each entry: **When** / **Prerequisites** / **Invoke** / **Outputs** / **Next**
 #### `rules-workflow`
 
 - **When:** Feature implementation, planning, commit/PR (18 steps)
-- **Prerequisites:** HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, Component & Library Plan (non-prototype)
+- **Prerequisites:** HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, Component & Library Plan, Context Receipt (code/deploy)
 - **Invoke:** `/rules-workflow` — implement this backlog item
-- **Outputs:** Plan review, implementation, self-check, PR readiness
+- **Outputs:** Context Receipt, plan review, Change Receipt, independent Verification Receipt, PR readiness
 - **Next:** `verify-implementation`
 
 #### `rules-dev`
@@ -428,11 +463,21 @@ Required fields per item in `docs/04_Logic_Progress/00_BACKLOG.md`:
 
 - `Related Concept Docs`, `Related UI Docs`, `Related HTML Preview`
 - `Related Technical Docs`, `Related QA Docs`
-- `Implementation Preconditions`, `Component & Library Plan`
+- `Work Type`, `Implementation Preconditions`, `Component & Library Plan`
+- `Context Receipt`, `Change Receipt`, `Verification Receipt`
 - `Acceptance Criteria`, `Document Sync Check`
 
 Use `N/A - reason` when a doc does not exist. Pause implementation if a missing doc blocks a safe decision.
 
+### Agent Harness Gate
+
+- Canonical contract: `rules-workflow/resources/agent-harness-contract.md`
+- `code` and `deploy`: Context Receipt before implementation; Verification Receipt before Done, PR, merge, publish, or deploy
+- `docs` and `prototype`: advisory receipts
+- Context and Verification agents are read-only
+- Verification details must link to an existing `docs/05_QA_Validation/` document or GitHub PR
+- Default CLI mode is `warning`; `--strict` returns a blocking non-zero exit
+
 ### YAGNI/KISS/DRY Gate
 
 - **Canonical:** `rules-dev` § Minimal Implementation Gate
@@ -447,6 +492,7 @@ Use `N/A - reason` when a doc does not exist. Pause implementation if a missing
 ### [ ] TASK-000: Implement feature name
 
 - Status: ToDo
+- Work Type: code
 - Related Concept Docs:
   - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - feature purpose and user value
 - Related UI Docs:
@@ -464,6 +510,13 @@ Use `N/A - reason` when a doc does not exist. Pause implementation if a missing
   - [ ] Confirm user path and screen-by-screen data flow
   - [ ] Confirm loading, empty, and error states
   - [ ] Confirm implementation scope does not conflict with documented intent
+- Context Receipt:
+  - Status: PENDING
+  - Required References Read:
+    - PENDING - repeat every linked Related document after reading it
+  - Constraints:
+    - PENDING - extracted implementation constraints
+  - Conflicts: PENDING - use `None` only after checking
 - Component & Library Plan:
   - shadcn/ui components: button, card, form, or `N/A - reason`
   - Custom components: feature-specific components or `N/A - reason`
@@ -475,6 +528,23 @@ Use `N/A - reason` when a doc does not exist. Pause implementation if a missing
   - [ ] Feature follows the confirmed screen structure and user path
   - [ ] Feature behavior matches linked Concept/UI/Technical docs
   - [ ] QA criteria are testable and satisfied
+- Change Receipt:
+  - Files Changed:
+    - PENDING
+  - Requirements Covered:
+    - PENDING
+  - Excluded Scope: PENDING
+  - Basic Checks:
+    - PENDING
+  - Remaining Risks: PENDING
+- Verification Receipt:
+  - Status: PENDING
+  - Commands and Results:
+    - PENDING - `command` - PASS/FAIL - exact scope and result
+  - Unrun Checks:
+    - PENDING - skipped checks and reasons
+  - Detailed Evidence:
+    - PENDING - link an existing QA document or GitHub PR
 - Document Sync Check:
   - [ ] No mismatch between implementation and linked documents
   - [ ] Update related documents if implementation changes the agreed behavior
@@ -540,7 +610,7 @@ Run /verify-implementation on current changes. Include a Flow Status Block in th
 **언어:** [English (default)](#solmate-skills-usage-guide) · 한국어 (아래)
 
 사람이 읽기 위한 스킬 사용법 가이드입니다.  
-에이전트 실행 규칙의 정본은 각 `SKILL.md`와 프로젝트에 설치된 `AGENTS.md`입니다.
+에이전트 실행 규칙의 정본은 각 `SKILL.md`와 프로젝트에 링크 또는 설치된 `AGENTS.md`입니다.
 
 ---
 
@@ -561,9 +631,10 @@ Run /verify-implementation on current changes. Include a Flow Status Block in th
 ```bash
 npx solmate-skills@latest install all      # .agent/skills/<skill-name>/ + ./USAGE.md
 npx solmate-skills@latest install hooks    # Claude Code 자동 제안 (별도) + ./USAGE.md
+npx solmate-skills@latest install agents   # rules-workflow + Claude 프로젝트 에이전트 갱신
 ```
 
-모든 `install` 명령(단일 스킬, `all`, `hooks`)은 `USAGE.md`를 **프로젝트 루트**에 복사합니다.
+모든 `install` 명령(단일 스킬, `all`, `hooks`, `agents`)은 `USAGE.md`를 **프로젝트 루트**에 복사합니다. `rules-workflow` 또는 `all` 설치 시 Claude 에이전트도 자동 설치됩니다.
 
 ### 로컬 개발 (symlink)
 
@@ -574,7 +645,7 @@ npx solmate-skills@latest install hooks    # Claude Code 자동 제안 (별도)
 bash /path/to/solmate-skills/init-skills.sh
 ```
 
-`.agent/skills/`가 저장소로 symlink되고, `AGENTS.md`와 `USAGE.md`가 루트에 링크됩니다.
+`.agent/skills/`가 저장소로 symlink되고, `AGENTS.md`와 `USAGE.md`가 루트에 링크되며, `.claude/agents/`에 Solmate 에이전트가 연결됩니다.
 
 ---
 
@@ -620,6 +691,39 @@ bash /path/to/solmate-skills/init-skills.sh
 | `rules-workflow` | 승인된 문서 기준으로 계획→구현→정리→PR (18단계) | 기능 구현·커밋·PR 직전 |
 | `verify-implementation` | 변경 파일에 맞춰 verify-* 순차 실행·통합 보고 | PR·배포 전 최종 점검 |
 
+### 에이전트 하네스 순서
+
+`Work Type`이 `code` 또는 `deploy`인 백로그 작업은 다음 순서로 진행합니다.
+
+```text
+Coordinator
+  -> 읽기 전용 Context Agent -> Context Receipt
+  -> Implementation Agent    -> Change Receipt
+  -> 읽기 전용 Verifier      -> Verification Receipt
+  -> Coordinator 완료 판단
+```
+
+- Claude Code는 `.claude/agents/solmate-*.md`를 사용합니다.
+- Codex는 `rules-workflow/resources/agent-harness-contract.md`의 같은 계약을 subagent 또는 별도 task에 전달합니다.
+- 검증자는 문제를 직접 수정하지 않고 Implementation Agent로 돌려보냅니다.
+- Receipt 요약은 백로그에, 상세 검증 근거는 QA 문서 또는 GitHub PR에 남깁니다.
+- 처음 5개 실제 작업은 warning으로 확인한 뒤 blocking으로 전환합니다.
+
+```bash
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+```
+
+선택형 v1 구조화 산출물도 같은 warning-to-blocking 마이그레이션을 사용합니다.
+
+```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
+```
+
+차단 검증에는 `--strict`를 추가합니다. 계약 위반은 종료 코드 `1`, JSON 파싱·파일·명령 입력 오류는 종료 코드 `2`입니다. 기존 백로그 Receipt만 사용하는 프로젝트는 이 파일을 만들 필요가 없습니다.
+
 ### verify-* 개별 vs 통합
 
 | 상황 | 사용 |
@@ -642,9 +746,10 @@ Phase 2  UI 설계 문서     → docs-plan (02_UI_Screens)
          UI-First Gate          → 화면·동선·데이터 흐름·상태 확인
          Pre-Code Technical Brief → API·상태·acceptance criteria 합의
          Component & Library Planning Gate → shadcn·커스텀·재사용·라이브러리 계획
+         Context Receipt Gate → 읽기 전용 에이전트의 관련 문서 확인
 Phase 3  React 구현       → rules-react (+ tools-shadcn)
 Phase 4  개발문서         → docs-dev (03~05)
-Phase 5  품질 검증        → verify-implementation
+Phase 5  독립 품질 검증   → Verification Receipt + verify-implementation
 Phase 6  전달물 (선택)    → docs-pitch / docs-business
 ```
 
@@ -738,6 +843,7 @@ Gate: UI-First Gate 진행 중
 - **UI-First Gate:** 화면·동선·CTA·데이터 흐름·로딩/빈/오류 상태
 - **Component & Library Planning Gate:** shadcn·커스텀·재사용·라이브러리·preset
 - **Backlog Context Lock:** Related Docs, Preconditions, Component Plan, Acceptance, Sync Check
+- **Agent Harness Gate:** code/deploy 작업은 Context Receipt와 독립 Verification Receipt 필수
 - **YAGNI/KISS/DRY Gate:** `rules-dev` 정본; 프로토타입은 기록성 체크
 
 백로그 템플릿: [영문 §7 Backlog item template](#backlog-item-template) (필드명은 영문 유지)