solmate-skills 2.0.12 → 2.0.13

package/docs/05_QA_Validation/01_TEST_SCENARIOS.md

@@ -0,0 +1,313 @@
+# Agent Harness Test Scenarios
+> Created: 2026-07-17 01:04
+> Last Updated: 2026-07-17 01:53
+
+## 1. Purpose
+
+This document defines design-stage acceptance and future implementation scenarios for the enhanced Solmate agent harness. A scenario is not considered passing until independent evidence identifies the command, fixture, result, and relevant requirement.
+
+## 2. Global Rubric Validation
+
+| Criterion | Status | Evidence / Design Response |
+|---|---|---|
+| Functionality | Pass at design stage | Requirements, architecture, state transitions, messages, errors, execution plan, and tests are defined; implementation remains pending |
+| Potential Impact | Pass at design stage | The design targets the recurring failures of unread context, improvised workflows, conflicting agents, and unsupported completion claims |
+| Novelty | Pass at design stage | Solmate combines role/topology design with machine-enforced document and independent-verification Receipts rather than relying on personas alone |
+| UX | Pass at design stage | Minimal topology is the default; optional specialists and warning rollout limit procedural and latency overhead |
+| Open-source | Pass at design stage | Runtime-neutral contracts, standard JSON/JSONL, and thin adapters allow reuse without a proprietary orchestration service |
+| Business Plan | Pass at design stage | Reliable Claude/Codex workflow behavior strengthens the package's value and reduces support cost from inconsistent agent execution |
+
+Implementation-stage status must replace these design-stage statements with executable evidence.
+
+## 3. Requirement Traceability Matrix
+
+| Requirement | Architecture Coverage | Primary Scenario | Design Status |
+|---|---|---|---|
+| FR-001 | Artifact Model, Receipt Integration | QA-REQ-001 | Covered |
+| FR-002 | Role Catalog, Activation Rules | QA-ROLE-001 | Covered |
+| FR-003 | Persona Contract, Permissions | QA-ROLE-002 | Covered |
+| FR-004 | Receipt Integration, Compatibility | QA-COMPAT-001 | Covered |
+| FR-005 | Optional Specialists, State Machine | QA-DESIGN-001 | Covered |
+| FR-006 | Message Protocol | QA-SCHEMA-001, QA-MSG-001, QA-MSG-002 | Covered |
+| FR-007 | State Machine, Error Handling | QA-STATE-001, QA-STATE-002 | Covered |
+| FR-008 | Permissions, QA Role | QA-QA-001, QA-QA-002 | Covered |
+| FR-009 | Error Handling | QA-ERR-001 through QA-ERR-006 | Covered |
+| FR-010 | Runtime Adapters | QA-ADAPTER-001 | Covered |
+| FR-011 | Execution Workspace | QA-RECOVERY-001, QA-RECOVERY-002 | Covered |
+| FR-012 | Requirements Traceability | QA-TRACE-001 | Covered |
+| FR-013 | Topology Selection | QA-TOPO-001 through QA-TOPO-003 | Covered |
+| FR-014 | Compatibility And Maintenance | QA-DRIFT-001 | Covered |
+| FR-015 | Warning Pilot | QA-PILOT-001 | Covered |
+
+### 3.1 Non-Functional Requirement Traceability
+
+| Requirement | Primary Scenario | Design Status |
+|---|---|---|
+| NFR-001 | QA-SEC-001, QA-ERR-006 | Covered |
+| NFR-002 | QA-STATE-001, QA-RECOVERY-002 | Covered |
+| NFR-003 | QA-ADAPTER-001 | Covered |
+| NFR-004 | QA-ROLE-001, QA-TOPO-001 | Covered |
+| NFR-005 | QA-COST-001, QA-PILOT-001 | Covered |
+| NFR-006 | QA-SCHEMA-001, QA-MSG-001, QA-STATE-002 | Covered |
+| NFR-007 | QA-COMPAT-001 | Covered |
+| NFR-008 | QA-QA-001, QA-QA-002 | Covered |
+| NFR-009 | QA-RECOVERY-001, QA-RECOVERY-002 | Covered |
+| NFR-010 | QA-LICENSE-001 | Covered |
+
+## 4. Requirements And Context Scenarios
+
+### QA-REQ-001 - Requirements Artifact Completeness
+
+- **Given**: A new feature request with product behavior and implementation expectations.
+- **When**: Requirements Analyst prepares the canonical analysis.
+- **Then**: The document contains user need, FR, NFR, included/excluded scope, acceptance criteria, assumptions, unresolved questions, risks, and related-document links.
+- **Failure**: Implementation begins from chat text without the required artifact or explicit small-task skip decision.
+- **Evidence**: Parsed document fields and Coordinator acceptance event.
+
+### QA-CONTEXT-001 - Linked Document Read Proof
+
+- **Given**: A code task links Concept, Technical, and QA documents.
+- **When**: Context Reader returns a Context Receipt.
+- **Then**: Every linked path exists and appears in `Required References Read`; constraints and conflicts are present.
+- **Failure**: Any required document is missing, unread, or silently omitted.
+- **Evidence**: Existing strict `preflight` command plus manifest references.
+
+### QA-CONTEXT-002 - Conflicting Documents
+
+- **Given**: Two linked documents define incompatible behavior.
+- **When**: Context Reader compares them.
+- **Then**: State becomes `BLOCKED_CONTEXT`; both sources are preserved and Coordinator routes a decision.
+- **Failure**: Context Reader chooses one silently or Implementer starts work.
+
+## 5. Role And Design Scenarios
+
+### QA-ROLE-001 - Minimal Task Avoids Optional Specialists
+
+- **Given**: A small, single-module change with complete requirements and no public contract or state-machine change.
+- **When**: Coordinator selects topology.
+- **Then**: Core linear path is used; Requirements Analyst, Architect, Logic Builder, Security Inspector, and Release Guardian are recorded as `Skipped - reason` where considered.
+- **Failure**: Full specialist team is spawned only because multiple roles are available.
+
+### QA-ROLE-002 - Persona Contract Completeness
+
+- **Given**: A runtime agent definition.
+- **When**: Persona validation runs.
+- **Then**: All persona fields are present, permissions match role responsibility, and denied tools are explicit for read-only roles.
+- **Failure**: A narrative persona has no non-goals, output contract, escalation, completion evidence, or write scope.
+
+### QA-DESIGN-001 - Architect And Logic Builder Activation
+
+- **Given**: A feature changes an API contract and introduces three business states with failure transitions.
+- **When**: Coordinator evaluates specialists.
+- **Then**: Architect and Logic Builder are both activated, with non-overlapping outputs and linked Design Receipt.
+- **Failure**: Implementer invents the API or state behavior during coding.
+
+## 6. Message And State Scenarios
+
+### QA-SCHEMA-001 - Versioned Artifact Schema Selection
+
+- **Given**: A v1 manifest, message, or individual event object.
+- **When**: A standard Draft 2020-12 validator or the Solmate CLI selects the artifact contract.
+- **Then**: Top-level `oneOf` selects exactly one artifact shape, `schema_version: 1` is required, and every non-empty JSONL line validates as an event before ordered-log checks run.
+- **Failure**: The top-level schema accepts an unconstrained object, an unsupported version passes, or malformed JSONL is treated as a contract warning instead of an operational error.
+
+### QA-MSG-001 - Valid Structured Handoff
+
+- **Given**: Architect completes an approved Architecture Decision Packet.
+- **When**: A `HANDOFF` message is emitted.
+- **Then**: Schema version, message/task IDs, attempt, timestamp, sender, recipient, status, summary, requirement/artifact/decision refs, blockers, next action, and retry count validate.
+- **Failure**: A free-form “done” message is accepted without an artifact.
+
+### QA-MSG-002 - Direct Peer Decision Is Rejected
+
+- **Given**: Frontend Implementer asks Backend Implementer to change an accepted API response.
+- **When**: Backend replies directly with a scope-changing decision.
+- **Then**: Direct peer messages are limited to `STATUS` or `QUESTION` with `INFO` or `PENDING`; PASS, FAIL, BLOCKED, decision, rework, and completion claims route through Coordinator.
+- **Failure**: The API and UI drift without an updated requirement or decision.
+
+### QA-STATE-001 - Legal Transition Sequence
+
+- **Given**: All required artifacts pass.
+- **When**: Coordinator advances the task.
+- **Then**: Every state follows a legal transition and records reason, actor, timestamp, and artifacts.
+- **Evidence**: Ordered `events.jsonl` fixture.
+
+### QA-STATE-002 - Completion Bypass Is Rejected
+
+- **Given**: A Change Receipt exists but independent verification has not passed.
+- **When**: A role requests `CHANGE_READY -> COMPLETE`.
+- **Then**: The transition is rejected as a contract error.
+- **Failure**: PR, merge, publish, or deploy is reported ready.
+
+## 7. Error And Recovery Scenarios
+
+### QA-ERR-001 - Context Error Does Not Retry
+
+- **Given**: A required technical document is missing.
+- **Then**: State becomes `BLOCKED_CONTEXT`; no automatic retry or implementation occurs.
+
+### QA-ERR-002 - Transient Tool Error Retries Once
+
+- **Given**: An otherwise valid non-destructive command fails from a temporary runtime interruption.
+- **Then**: One retry occurs in a new recorded attempt with unchanged scope.
+- **Failure**: Retry changes requirements, deletes prior evidence, or loops indefinitely.
+
+### QA-ERR-003 - Repeated Transient Failure Blocks Dependency
+
+- **Given**: The allowed retry fails again.
+- **Then**: State becomes `BLOCKED_DEPENDENCY` and reports attempts, evidence, and recovery condition.
+
+### QA-ERR-004 - Verification Failure Routes Rework
+
+- **Given**: QA finds a failed acceptance criterion.
+- **Then**: QA emits a finding; Coordinator sets `REWORK`; Implementer creates a new attempt and Change Receipt.
+- **Failure**: QA modifies source files or marks its own fix as verified.
+
+### QA-ERR-005 - Rework Loop Limit
+
+- **Given**: Two implementation rework attempts fail the same criterion.
+- **Then**: Coordinator pauses further changes and requests a user decision with the repeated failure pattern.
+- **Failure**: A third automatic loop starts.
+
+### QA-ERR-006 - Critical Artifact Failure Cannot Degrade Silently
+
+- **Given**: Architect, Implementer, or QA fails without producing a required critical artifact.
+- **Then**: Code/deploy task remains blocked; final output explicitly names the missing artifact.
+- **Failure**: Remaining partial results are used to report completion.
+
+### QA-RECOVERY-001 - Interrupted Task Resume
+
+- **Given**: The active agent stops after valid requirements and context events.
+- **When**: The task resumes.
+- **Then**: Runtime loads the latest valid manifest and events, creates or resumes the legal attempt, and does not repeat approved work unnecessarily.
+
+### QA-RECOVERY-002 - Attempt Preservation
+
+- **Given**: Attempt 1 fails and attempt 2 begins.
+- **Then**: Attempt 1 artifacts and failure evidence remain immutable and manifest points to attempt 2 as active.
+
+## 8. Independent QA And Boundary Scenarios
+
+### QA-QA-001 - QA Write Attempt Is Denied
+
+- **Given**: QA Inspector identifies a code defect.
+- **When**: It attempts to use Edit or Write on implementation files.
+- **Then**: Runtime permission or contract validation rejects the operation and records the violation.
+
+### QA-QA-002 - Implementer Cannot Self-Verify
+
+- **Given**: Implementer reports basic checks as passing.
+- **Then**: Change Receipt is accepted as a handoff but cannot satisfy Verification Receipt or completion.
+
+### QA-BOUNDARY-001 - Producer And Consumer Contract Comparison
+
+- **Given**: A producer returns a structured response and a consumer declares its expected type.
+- **Then**: QA reads both sides, compares shape, optionality, naming, and failure behavior, and links evidence.
+- **Failure**: QA checks only that both files exist or only that compilation passes.
+
+### QA-BOUNDARY-002 - State Definition And Mutation Comparison
+
+- **Given**: A Logic Contract defines legal transitions.
+- **Then**: QA compares every implementation mutation and UI branch against reachable states and identifies unauthorized or dead transitions.
+
+### QA-TRACE-001 - End-To-End Requirement Evidence
+
+- **Given**: A P0 functional requirement is marked complete.
+- **When**: Traceability validation runs.
+- **Then**: The requirement links to its approved Requirements Analysis, required Architecture or Logic artifact, Change Receipt or diff, and independent QA evidence.
+- **Failure**: A requirement is marked `Pass` from implementation claims alone, or a required design artifact is absent without `Skipped - reason`.
+
+## 9. Topology And Adapter Scenarios
+
+### QA-TOPO-001 - Read-Only Fan-Out/Fan-In
+
+- **Given**: Four independent document groups require analysis.
+- **Then**: Read-only agents run in parallel, write no shared source, and Coordinator integrates artifact references and conflicts.
+
+### QA-TOPO-002 - Parallel Write Ownership
+
+- **Given**: Frontend and Backend work can proceed in parallel.
+- **Then**: Exclusive paths are canonical project-relative paths; aliases and overlapping literal or recursive scopes are rejected, while shared contracts are frozen or owned serially.
+- **Failure**: Both agents modify the same shared file without coordination.
+
+### QA-TOPO-003 - Hierarchy Depth Limit
+
+- **Given**: A proposed topology delegates more than two levels deep.
+- **Then**: Coordinator flattens or rejects the topology unless the user approves a documented exception.
+
+### QA-ADAPTER-001 - Claude And Codex Contract Parity
+
+- **Given**: The same fixture task runs through both adapters.
+- **Then**: Role activation, canonical states, required artifact refs, failure classification, and Receipt fields are semantically equivalent.
+- **Allowed Difference**: Native tool names, peer-message support, concurrency, and resume capability.
+
+### QA-ADAPTER-002 - Degraded Independent Agent Capability
+
+- **Given**: A runtime cannot provide an independent QA execution context.
+- **Then**: State becomes `DEGRADED`; user approval is required before any completion claim and the limitation remains visible.
+
+## 10. Compatibility, Drift, And Security Scenarios
+
+### QA-COMPAT-001 - Existing Receipt Fixtures Remain Valid
+
+- **Given**: Current valid Context and Verification Receipt fixtures.
+- **When**: The enhanced validator runs in compatibility mode.
+- **Then**: Existing commands and exit codes remain valid; new fields are warning-only until migration.
+
+### QA-DRIFT-001 - Role And Adapter Drift Detection
+
+- **Given**: A role is renamed or a runtime adapter omits a mandatory persona field.
+- **Then**: Package verification identifies the stale reference, duplicate role, or missing adapter mapping.
+
+### QA-COST-001 - Agent And Model Cost Is Proportional
+
+- **Given**: Equivalent small, medium, and complex task fixtures.
+- **Then**: The small fixture uses the minimal role path; optional specialists and stronger model tiers appear only with a recorded task need.
+- **Failure**: Every task uses the full team or globally forces the most expensive model tier.
+
+### QA-LICENSE-001 - External Reference Attribution And Originality
+
+- **Given**: A new contract or persona is informed by an external open-source project.
+- **Then**: Source references and applicable license obligations are reviewed, while Solmate text and schemas are independently authored unless copied material is explicitly attributed and licensed.
+- **Failure**: Substantial external text is copied without notice, source, or license review.
+
+### QA-SEC-001 - Sensitive Workspace Content Rejected
+
+- **Given**: A message or evidence artifact contains a credential, secret token, or prohibited raw personal data.
+- **Then**: Persistence is rejected or redacted according to explicit policy and the task reports the blocked evidence.
+- **Failure**: Sensitive content is written to a commit-ready workspace.
+
+## 11. Pilot And Release Scenarios
+
+### QA-PILOT-001 - Five-Task Warning Calibration
+
+- **Given**: Five representative real code/deploy tasks.
+- **Then**: Each records selected topology, activated/skipped roles, missing fields, false positives, retries, rework, user overrides, runtime gaps, and escaped findings.
+- **Exit**: User reviews the pilot and explicitly approves or rejects blocking mode.
+
+### QA-RELEASE-001 - Package And Documentation Agreement
+
+- **Given**: A proposed npm release.
+- **Then**: Tests, package dry run, installed adapters, schema files, README, USAGE, version, changelog, rollback, and migration guidance agree.
+- **Failure**: Documentation claims behavior absent from the packaged files.
+
+## 12. Design Document Verification Checklist
+
+- [ ] All Markdown files use required Created and Last Updated metadata.
+- [ ] All document filenames use two-digit numbering and uppercase snake case where applicable.
+- [ ] Related Documents use valid relative links with relationship descriptions.
+- [ ] Architecture embeds the data-flow SVG from the required assets directory.
+- [ ] Every P0 FR has architecture coverage and a QA scenario.
+- [ ] Backlog code/deploy tasks contain all Related fields and pending Receipt contracts.
+- [ ] UI and HTML Preview fields use reasoned N/A rather than blank values.
+- [ ] Decision Log records alternatives and reconsideration conditions.
+- [ ] No implementation or release is represented as approved by these documents.
+- [ ] External reference concepts are independently expressed and not copied verbatim.
+
+## 13. Related Documents
+
+- **Concept_Design**: [Agent Harness Requirements Analysis](../01_Concept_Design/01_AGENT_HARNESS_REQUIREMENTS_ANALYSIS.md) - requirement IDs and approved scope
+- **Technical_Specs**: [Agent Harness Architecture](../03_Technical_Specs/01_AGENT_HARNESS_ARCHITECTURE.md) - roles, states, messages, errors, artifacts, and adapters under test
+- **Logic_Progress**: [Backlog](../04_Logic_Progress/00_BACKLOG.md) - task-level acceptance and Receipt status
+- **Logic_Progress**: [Execution Plan](../04_Logic_Progress/01_EXECUTION_PLAN.md) - staged implementation, pilot, and release exits
+- **Logic_Progress**: [Decision Log](../04_Logic_Progress/03_DECISION_LOG.md) - approved design decisions verified by these scenarios

package/docs/05_QA_Validation/02_AGENT_HARNESS_DESIGN_REVIEW.md

@@ -0,0 +1,100 @@
+# Agent Harness Design Review
+> Created: 2026-07-17 01:15
+> Last Updated: 2026-07-17 01:22
+
+## 1. Review Scope
+
+This report records structural and traceability verification of the enhanced Agent Harness design baseline. It does not verify future CLI, schema, adapter, orchestration, release, or runtime behavior.
+
+Reviewed artifacts:
+
+- Requirements Analysis
+- Architecture and data-flow SVG
+- Backlog
+- Execution Plan
+- Decision Log
+- Test Scenarios
+
+## 2. Verification Results
+
+| Check | Result | Evidence |
+|---|---|---|
+| Markdown metadata | Pass | Seven design Markdown files contain Created and Last Updated metadata |
+| File naming | Pass | Markdown filenames use two-digit uppercase snake case |
+| Relative document links | Pass | All local Markdown links resolve to existing files |
+| SVG validity | Pass | `xmllint --noout` accepts the data-flow SVG |
+| SVG visual rendering | Pass | A full 1600x900 Chrome render has no clipping or text/connector overlap after correction |
+| Backlog Context Lock shape | Pass for current docs task | All Related fields are present; UI and HTML Preview use reasoned N/A |
+| Requirement traceability | Pass | 15 FR and 10 NFR entries have QA trace rows |
+| Scenario references | Pass | 35 referenced QA scenario IDs have corresponding definitions |
+| Existing package tests | Pass | `npm test` reports `harness checks ok` |
+| Whitespace / patch integrity | Pass | `git diff --check` returns no error |
+| User design review | Pending | The user has not yet reviewed the completed artifacts |
+
+## 3. Commands And Results
+
+| Command / Method | Result | Summary |
+|---|---|---|
+| `git diff --check` | Pass | No whitespace errors |
+| Metadata and naming shell checks | Pass | Required metadata and filename conventions found |
+| Relative-link Node check | Pass | Six Markdown files checked before this report was added; all local targets resolved |
+| Requirement trace Node check | Pass | 25 unique FR/NFR IDs have QA trace rows |
+| Scenario-reference Node check | Pass | 35 scenario definitions cover every referenced scenario ID |
+| `xmllint --noout docs/03_Technical_Specs/assets/01_agent_harness_data_flow.svg` | Pass | SVG is well-formed XML |
+| Chrome headless 1600x900 SVG render and visual inspection | Pass | Full diagram framing, labels, and connectors are visible without overlap |
+| `node bin/cli.js preflight TASK-HARNESS-001 --strict --backlog docs/04_Logic_Progress/00_BACKLOG.md` | Advisory Pass | Docs work type is correctly treated as advisory |
+| `npm test` | Pass | Existing harness test suite remains green |
+
+## 4. Findings And Corrections
+
+### DR-001 - Missing Traceability Scenario
+
+- **Initial Finding**: The traceability matrix referenced `QA-TRACE-001`, but no matching scenario section existed.
+- **Correction**: Added the end-to-end requirement evidence scenario.
+- **Status**: Resolved and rechecked.
+
+### DR-002 - Non-Functional Requirements Were Not Explicitly Mapped
+
+- **Initial Finding**: NFR concerns appeared across scenarios, but no NFR traceability table proved complete coverage.
+- **Correction**: Added a 10-row NFR matrix and dedicated cost and external-reference originality scenarios.
+- **Status**: Resolved and rechecked.
+
+### DR-003 - Data-Flow Connector Overlapped A Role Boundary
+
+- **Initial Finding**: The Coordinator-to-document connector crossed the Release Guardian boundary in the first full SVG render.
+- **Correction**: Shifted the Release Guardian node and adjusted adjacent connector endpoints without changing the architecture.
+- **Status**: Resolved in a second 1600x900 render and visually rechecked.
+
+## 5. Global Rubric Validation
+
+| Criterion | Result | Evidence |
+|---|---|---|
+| Functionality | Pass at design stage | Workflow contracts and failure paths are specified and structurally verified |
+| Potential Impact | Pass at design stage | Design addresses context omission, improvised delegation, agent conflict, and unsupported completion |
+| Novelty | Pass at design stage | Team architecture is combined with machine-enforced document and independent-verification evidence |
+| UX | Pass at design stage | Minimal topology and conditional specialists avoid mandatory full-team overhead |
+| Open-source | Pass at design stage | Runtime-neutral contracts use standard formats and independently authored text |
+| Business Plan | Pass at design stage | More reliable installed behavior can reduce support burden and improve package trust |
+
+## 6. Residual Risks
+
+- Runtime capability details must be reverified against current official Claude Code and Codex behavior before adapter implementation.
+- Structured schemas and legal transitions are design-only until automated validators exist.
+- Read-only permissions and exclusive write ownership require runtime and fixture evidence.
+- Cost and agent-count benefits require the five-task warning pilot.
+- The user must review this baseline before Phase B code work can be proposed.
+
+## 7. Review Conclusion
+
+**Status: Pass for structural design review.**
+
+The design baseline is internally linked, traceable, and consistent with the approved direction. It is not an implementation approval and does not authorize code changes, blocking mode, merge, publish, or deployment.
+
+## 8. Related Documents
+
+- **Concept_Design**: [Agent Harness Requirements Analysis](../01_Concept_Design/01_AGENT_HARNESS_REQUIREMENTS_ANALYSIS.md) - reviewed requirement source
+- **Technical_Specs**: [Agent Harness Architecture](../03_Technical_Specs/01_AGENT_HARNESS_ARCHITECTURE.md) - reviewed technical contract
+- **Logic_Progress**: [Backlog](../04_Logic_Progress/00_BACKLOG.md) - current task and verification summary
+- **Logic_Progress**: [Execution Plan](../04_Logic_Progress/01_EXECUTION_PLAN.md) - future unapproved delivery phases
+- **Logic_Progress**: [Decision Log](../04_Logic_Progress/03_DECISION_LOG.md) - reviewed approved decisions
+- **QA_Validation**: [Agent Harness Test Scenarios](./01_TEST_SCENARIOS.md) - reviewed scenario and traceability catalog

package/docs/05_QA_Validation/03_AGENT_HARNESS_CONTRACT_QA.md

@@ -0,0 +1,96 @@
+# Agent Harness Contract Implementation QA
+> Created: 2026-07-17 02:39
+> Last Updated: 2026-07-17 02:44
+
+## 1. Scope
+
+This report verifies `TASK-HARNESS-002`: the opt-in v1 manifest, message, and event contracts; semantic validation; deterministic CLI exits; existing Receipt compatibility; package inclusion; and documentation synchronization.
+
+It does not verify specialist persona adapters, runtime orchestration, persistent recovery, the five-task warning pilot, blocking rollout, merge, publish, or deployment.
+
+## 2. Flow Status
+
+```text
+[Flow]
+Current: Phase 5 - Quality Verification
+Gate: Quality + Minimal Implementation + Independent Agent Harness Verification - PASS
+Completed: Approved requirements, Context Receipt, implementation, local checks, independent QA
+Next: Phase 6 - Commit and handoff
+Required confirmation: Separate approval for TASK-HARNESS-003, PR, merge, publish, or deploy
+```
+
+## 3. Verification Results
+
+| Area | Result | Evidence |
+|---|:---:|---|
+| Versioned schema | Pass | Draft 2020-12 schema contains disjoint manifest, message, and event contracts under top-level `oneOf` |
+| Structured parsing | Pass | JSON and JSONL parse errors are separated from contract failures |
+| State transitions | Pass | Legal, illegal, blocked-resume, rework, cancellation, sequence, attempt, and final-state fixtures |
+| Role and ownership | Pass | Core activation, skipped reason, read-only ownership, canonical paths, recursive overlap, and alias fixtures |
+| Message authority | Pass | Direct peer traffic is limited to `STATUS` / `QUESTION` with `INFO` / `PENDING`; Coordinator routing is enforced |
+| Evidence gates | Pass | Required Receipt and event evidence blocks incomplete `COMPLETE` transitions |
+| Input safety | Pass | Path traversal, URL, backslash, wildcard, non-string, null, prototype-named, and invalid timestamp fixtures |
+| Exit behavior | Pass | Warning contract failure `0`; blocking contract failure `1`; operational parse/file/input error `2` |
+| Compatibility | Pass | Existing `preflight`, `verify`, Receipt fixture text, and custom Claude agent preservation remain valid |
+| Dependency scope | Pass | No runtime or development dependency was added |
+| Independent QA | Pass | Final read-only QA Inspector reported no P0, P1, or P2 findings |
+
+## 4. Commands And Results
+
+| Command / Method | Result | Summary |
+|---|:---:|---|
+| `npm test` | Pass | `harness checks ok`; `harness artifact checks ok` |
+| `node --check` on changed/new JavaScript | Pass | CLI, validator, runner, and fixture syntax valid |
+| `node bin/cli.js preflight TASK-HARNESS-002 --strict` | Pass | Context and related-document evidence accepted |
+| Node 16 `bin/test.js` | Pass | Both suites pass on an older ARM-compatible runtime |
+| Acorn `--ecma2020` parse | Pass | New validator uses Node 14-compatible syntax |
+| Ajv Draft 2020 compile | Pass | External validator compiles the top-level v1 schema |
+| Ajv validation of `{}` | Expected reject | Top-level `oneOf` rejects an unconstrained artifact |
+| `npm pack --dry-run --json` | Pass | 454 files; validator, tests, schema, contract, and architecture included |
+| Document metadata and relative links | Pass | All current `docs/**/*.md` files validate |
+| Requirement and scenario trace | Pass | 25 requirements and 36 scenario IDs resolve |
+| Secret-pattern scan | Pass | No credential pattern found in changed implementation and documentation |
+| `git diff --check` | Pass | No whitespace or patch-integrity errors |
+
+## 5. Independent Findings And Corrections
+
+Independent read-only QA runs found and the Implementer corrected the following before the final PASS:
+
+1. Canonicalized exclusive ownership paths and rejected `./`, duplicate separators, parent traversal, and ambiguous recursive aliases.
+2. Rejected direct peer PASS, FAIL, BLOCKED, decision, rework, and completion status.
+3. Added top-level `oneOf` so the schema is useful to a standard Draft 2020-12 validator.
+4. Kept parseable invalid values as contract failures instead of internal operational exceptions.
+5. Made v1 attempt increments legal only for `REWORK -> IMPLEMENTING`.
+6. Replaced `Date.parse()` normalization with a schema-aligned Solmate canonical timestamp profile.
+7. Rejected inherited `constructor` and `__proto__` names under `additionalProperties: false`.
+8. Corrected the architecture description so `events.jsonl` contains state events and messages remain attempt artifacts.
+
+After each correction a new read-only QA Inspector reviewed the updated files. The final run returned **No findings** and **Verification Receipt Status: PASS** without editing files.
+
+## 6. Minimal Implementation Review
+
+- **YAGNI**: No persona runtime, orchestration server, database, queue, recovery engine, rollout automation, or release behavior was added.
+- **KISS**: One canonical JSON Schema file and one Node standard-library validator module implement the approved contract.
+- **DRY**: State, role, evidence, and schema definitions remain centralized; CLI and runtime adapters reference the contract.
+- **Safety**: Validation, independent QA, deterministic failures, path safety, evidence preservation, and compatibility checks were retained.
+
+## 7. Unrun Checks And Residual Risks
+
+- Actual Node 14 execution was unavailable because npm has no matching `node-bin-darwin-arm64@14.21.3`; Node 16 execution and ECMAScript 2020 static parsing passed.
+- Ajv CLI compiled the schema and exercised top-level rejection without `ajv-formats`; calendar and canonical timestamp semantics are additionally covered by the package validator tests.
+- Claude/Codex persona parity, runtime permission enforcement, orchestration recovery, warning-pilot metrics, and release behavior belong to later tasks.
+- Package version remains `2.0.12`; no version bump, PR, merge, publish, or deploy was authorized in this task.
+
+## 8. Conclusion
+
+**Status: PASS for TASK-HARNESS-002.**
+
+The v1 structured contract and machine validator satisfy the approved acceptance criteria while preserving current Receipt behavior. Later phases remain separately gated.
+
+## 9. Related Documents
+
+- **Concept_Design**: [Agent Harness Requirements Analysis](../01_Concept_Design/01_AGENT_HARNESS_REQUIREMENTS_ANALYSIS.md) - approved requirements and compatibility constraints
+- **Technical_Specs**: [Agent Harness Architecture](../03_Technical_Specs/01_AGENT_HARNESS_ARCHITECTURE.md) - implemented schema and semantic contract
+- **Logic_Progress**: [Backlog](../04_Logic_Progress/00_BACKLOG.md) - completed task Receipts
+- **Logic_Progress**: [Execution Plan](../04_Logic_Progress/01_EXECUTION_PLAN.md) - Phase B completion and later phases
+- **QA_Validation**: [Agent Harness Test Scenarios](./01_TEST_SCENARIOS.md) - traceability and planned scenario catalog

package/manage-collaboration/SKILL.md

@@ -33,6 +33,8 @@ The AI MUST check for and follow these documents if they exist in the repository
 Apply the "Subagent Strategy" to keep the main context clean:
 - **Delegation**: Offload research/analysis to Browser/Thinking tools.
 - **Aggregation**: Return only summarized, high-value insights to the main chat.
+- **Canonical Contract**: For code and deploy tasks, use `rules-workflow/resources/agent-harness-contract.md` for Coordinator, Context, Implementation, Verification roles and handoffs.
+- **Independence**: Context and Verification agents are read-only. Verification findings return to the Implementation Agent instead of being fixed by the verifier.
 
 ### 3.2. 자가개선 루프 (Self-Improvement)
 - Maintain `tasks/lessons.md` to capture patterns and avoid repeating mistakes.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "solmate-skills",
-  "version": "2.0.12",
-  "description": "AI workflow skills for UI-first planning, YAGNI/KISS/DRY gates, docs, QA, and Solmate projects",
+  "version": "2.0.13",
+  "description": "AI agent harness and workflow skills for context-aware planning, implementation, verification, docs, and QA",
   "main": "bin/cli.js",
   "bin": {
     "solmate-skills": "bin/cli.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node bin/test.js"
   },
   "keywords": [
     "ai-skills",
@@ -22,7 +22,9 @@
     "qa",
     "solmate",
     "skills",
-    "automation"
+    "automation",
+    "agent-harness",
+    "multi-agent"
   ],
   "author": "",
   "license": "ISC",

package/rules-docs/SKILL.md

@@ -89,12 +89,26 @@ docs/02_UI_Screens/previews/
 - `Related HTML Preview`
 - `Related Technical Docs`
 - `Related QA Docs`
+- `Work Type`
 - `Implementation Preconditions`
+- `Context Receipt`
+- `Change Receipt`
+- `Verification Receipt`
 - `Acceptance Criteria`
 - `Document Sync Check`
 
 각 Related 필드는 상대 경로 링크와 관계 설명을 포함해야 한다. 관련 문서나 HTML Preview가 없으면 빈칸으로 두지 않고 `N/A - 사유`를 명시한다. 단, 구현 판단에 필요한 Concept, UI, HTML Preview, Technical Spec, QA 기준이 아직 문서화되지 않은 경우에는 백로그만으로 구현을 시작할 수 없으며, 먼저 문서 작성 또는 보완 여부를 사용자에게 확인한다.
 
+`Work Type`은 `code`, `deploy`, `docs`, `prototype` 중 하나를 사용한다. `code`와 `deploy` 작업은 다음 Agent Harness 조건을 추가로 지킨다.
+
+- Context Agent가 모든 Related 링크를 읽고 `Context Receipt`에 기록한다.
+- warning 기간에는 Context Receipt 발견 사항과 사용자 확인을 기록한다. blocking 전환 후에는 PASS Context Receipt 없이는 구현을 시작하지 않는다.
+- Implementation Agent는 `Change Receipt`를 남기지만 이를 독립 검증으로 간주하지 않는다.
+- 읽기 전용 Verification Agent가 `Verification Receipt`를 작성한다.
+- warning 기간에는 Verification Receipt 발견 사항과 사용자 확인을 기록한다. blocking 전환 후에는 PASS Verification Receipt와 QA 문서 또는 PR 상세 근거 링크 없이는 Done 처리하지 않는다.
+
+Receipt 형식과 런타임별 역할은 `rules-workflow/resources/agent-harness-contract.md`를 정본으로 따른다.
+
 ### 메타데이터 (필수)
 
 모든 문서 최상단:
@@ -133,7 +147,7 @@ docs/02_UI_Screens/previews/
 
 **Logic_Progress**: Concept_Design + UI_Screens + Technical_Specs (DB, API) + QA_Validation
 
-**Backlog Items**: 각 항목 단위로 Concept_Design + UI_Screens + HTML Preview + Technical_Specs + QA_Validation 링크를 포함한다. 구현자는 항목 착수 전 링크된 문서와 HTML Preview를 확인하고 `Implementation Preconditions`를 확인해야 한다.
+**Backlog Items**: 각 항목 단위로 Concept_Design + UI_Screens + HTML Preview + Technical_Specs + QA_Validation 링크를 포함한다. `code`와 `deploy` 작업은 구현자가 아니라 읽기 전용 Context Agent가 먼저 링크된 문서를 확인하고 Context Receipt를 제출해야 한다.
 
 **QA_Validation**: 모든 상위 레이어 참조