solmate-skills 2.0.12 → 2.0.13

package/docs/01_Concept_Design/01_AGENT_HARNESS_REQUIREMENTS_ANALYSIS.md

@@ -0,0 +1,162 @@
+# Agent Harness Requirements Analysis
+> Created: 2026-07-17 01:04
+> Last Updated: 2026-07-17 01:31
+
+## 1. Purpose
+
+This document translates the approved user request into traceable requirements for the next Solmate agent harness iteration. It is the canonical requirements input for architecture, implementation planning, and QA.
+
+The requested outcome is not merely a larger agent catalog. The harness must make specialist collaboration reliable across Claude Code and Codex while preserving Solmate's existing document-reference and independent-verification gates.
+
+## 2. User Need
+
+The user identified the following needs after reviewing `revfactory/harness` and its generated examples:
+
+- establish explicit workflows instead of relying on an agent to improvise the execution order;
+- define operational personas such as Architect, Logic Builder, and QA Inspector;
+- establish an inter-agent communication protocol;
+- handle agent, tool, contract, and verification failures explicitly;
+- create a user-requirements analysis artifact before design and implementation;
+- retain Solmate's stronger machine-enforced document and verification evidence;
+- support both Claude Code and Codex without assuming one runtime's private tool names in the canonical contract.
+
+## 3. Problem Statement
+
+The current harness solves two high-risk failures well:
+
+1. implementation can be gated on proof that linked documents were read;
+2. completion can be gated on independent verification evidence.
+
+It does not yet define:
+
+- how a request becomes a stable requirements artifact;
+- when an Architect or Logic Builder is necessary;
+- which team topology fits a task;
+- how agents exchange structured status, findings, decisions, and artifact references;
+- how retryable failures differ from contract or approval failures;
+- how intermediate state survives agent or session termination;
+- how role permissions and file ownership prevent conflicting edits;
+- how requirements are traced through design, changes, and QA evidence.
+
+## 4. Target Users And Work Types
+
+| User / Work Type | Primary Need | Harness Behavior |
+|---|---|---|
+| Project owner | Retain decision authority | Coordinator routes unresolved scope and risk decisions to the user |
+| New feature work | Convert intent into testable requirements | Requirements Analysis is required before architecture or code |
+| Small code change | Avoid procedural overhead | Use the minimal core path without optional specialists |
+| Complex feature | Separate product, architecture, logic, implementation, and QA concerns | Activate specialists through an Expert Pool decision |
+| Code / deploy work | Prevent unverified completion | Context and Verification Receipts remain mandatory |
+| Docs / prototype work | Keep the process lightweight | Specialist delegation is advisory unless safety or approval is involved |
+| Claude Code | Use native project-agent capabilities | Claude adapter maps the canonical roles to supported project agents |
+| Codex | Use available subagents or tasks | Codex adapter maps the same contract without inventing unsupported files |
+
+## 5. Functional Requirements
+
+| ID | Requirement | Priority | Acceptance Summary |
+|---|---|---:|---|
+| FR-001 | Produce a canonical User Requirements Analysis before new-feature design or implementation | P0 | Functional, non-functional, scope, assumptions, questions, and acceptance criteria are present |
+| FR-002 | Maintain a minimal core team and activate optional specialists only when justified | P0 | Small tasks do not automatically spawn Architect, Logic Builder, or Release Guardian |
+| FR-003 | Define every persona with mission, non-goals, inputs, outputs, permissions, escalation, and completion criteria | P0 | Role files can be checked for all mandatory persona fields |
+| FR-004 | Preserve the existing Context Receipt gate and linked-document read proof | P0 | Existing preflight behavior remains compatible |
+| FR-005 | Add architecture and business-logic design gates for tasks whose complexity requires them | P0 | Coordinator records why each optional gate is invoked or skipped |
+| FR-006 | Define a runtime-neutral structured inter-agent message envelope | P0 | Every handoff can identify task, attempt, sender, recipient, status, artifacts, blockers, and next action |
+| FR-007 | Define workflow states and legal transitions, including blocked, rework, degraded, cancelled, and complete | P0 | Illegal completion and bypass transitions are rejected |
+| FR-008 | Keep QA Inspector independent and non-writing | P0 | QA cannot modify implementation files and must return findings through the Coordinator |
+| FR-009 | Distinguish retryable operational errors from context, contract, decision, and verification failures | P0 | Each error class has an explicit retry, escalation, and completion policy |
+| FR-010 | Support Claude Code and Codex through adapters that reference one canonical contract | P0 | Runtime differences do not duplicate the business policy |
+| FR-011 | Preserve intermediate artifacts and attempts for audit and recovery | P1 | Previous attempts are not overwritten; task manifests identify the active attempt |
+| FR-012 | Trace requirements through architecture, logic, implementation, and QA evidence | P0 | Each completed requirement has linked design, change, and verification evidence |
+| FR-013 | Support Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, and Supervisor patterns selectively | P1 | Coordinator records the selected topology and reason; hierarchy depth is bounded |
+| FR-014 | Detect role, skill, and contract drift during harness maintenance | P1 | Validation reports missing, duplicate, or stale adapters and role references |
+| FR-015 | Calibrate enforcement through warning tasks before blocking rollout | P0 | Five real tasks record false positives and unresolved gaps before strict mode |
+
+## 6. Non-Functional Requirements
+
+| ID | Category | Requirement |
+|---|---|---|
+| NFR-001 | Safety | Authentication, authorization, security, accessibility, data preservation, and verification may not be removed for simplicity |
+| NFR-002 | Auditability | Decisions, handoffs, attempts, failures, and evidence must remain inspectable after the active session ends |
+| NFR-003 | Portability | Canonical contracts may not depend on Claude-only or Codex-only tool names |
+| NFR-004 | Simplicity | The minimal linear workflow is the default; multi-agent topologies require a recorded benefit |
+| NFR-005 | Cost Control | Model choice and agent count are task-sensitive rather than globally fixed to the most expensive option |
+| NFR-006 | Determinism | Machine-checkable fields use versioned structured schemas and explicit state transitions |
+| NFR-007 | Compatibility | Existing backlog receipts and `preflight` / `verify` commands remain valid during migration |
+| NFR-008 | Independence | Verification evidence must come from a role that did not implement the change |
+| NFR-009 | Recoverability | A stopped agent or interrupted session can resume from persisted artifacts without silently restarting the task |
+| NFR-010 | Open Source | Concepts may be inspired by external projects, but Solmate contracts are independently written and attributable where necessary |
+
+## 7. Approved Scope
+
+### Included
+
+- requirements-analysis contract and template;
+- core and optional role catalog;
+- persona schema and permission matrix;
+- topology-selection rules;
+- runtime-neutral handoff message schema;
+- task state machine and error classification;
+- artifact ownership and persistence rules;
+- incremental QA and independent final verification;
+- Claude Code and Codex adapter boundaries;
+- validation, pilot, and blocking-rollout plan.
+
+### Excluded From This Design Stage
+
+- implementation changes to skills, CLI, or installers;
+- creation of a general-purpose multi-agent runtime service;
+- direct dependency on experimental runtime APIs;
+- automatic model purchasing or account configuration;
+- a visual end-user interface;
+- replacing project-specific domain skills with generic personas.
+
+## 8. Acceptance Criteria
+
+- [ ] Every P0 functional requirement maps to an architecture section and QA scenario.
+- [ ] The minimal path remains usable with Coordinator, Context Reader, Implementer, and QA Inspector.
+- [ ] Requirements Analyst, Architect, Logic Builder, and Release Guardian have explicit activation conditions.
+- [ ] Direct peer communication cannot approve scope, decisions, completion, or release.
+- [ ] Code and deploy tasks cannot complete from partial critical artifacts.
+- [ ] QA Inspector cannot edit implementation files or self-resolve its own findings.
+- [ ] Retryable and non-retryable errors have distinct transitions.
+- [ ] Claude Code and Codex use the same role and receipt semantics.
+- [ ] Existing Context, Change, and Verification Receipts remain part of the enhanced workflow.
+- [ ] The design does not require a UI document or HTML Preview because no user-facing screen is introduced.
+
+## 9. Risks And Constraints
+
+| Risk | Constraint / Response |
+|---|---|
+| Excessive agents increase cost and coordination latency | Use Expert Pool activation and a four-role minimal path |
+| Free-form messages become untraceable decisions | Require a structured envelope and Coordinator-owned decision recording |
+| Agents write overlapping files | Declare write ownership before implementation and serialize shared-file changes |
+| QA loses independence by fixing findings | Keep QA read-only and route rework to Implementer |
+| Runtime tools evolve | Keep runtime adapters thin and canonical policy tool-neutral |
+| New gates create checklist fatigue | Make architecture and logic gates conditional; retain strict gates only for critical evidence |
+| External source text creates licensing ambiguity | Reimplement concepts in original language and retain source references without copying substantial text |
+
+## 10. Decision Status
+
+The user approved the following direction on 2026-07-17:
+
+- fixed core team plus optional specialists;
+- canonical project documents plus an execution-only workspace;
+- Coordinator-centered decisions with limited direct peer communication;
+- separate Architect and Logic Builder responsibilities;
+- independent, non-writing QA Inspector;
+- explicit blocked, rework, degraded, and completion states;
+- one canonical contract with Claude Code and Codex adapters.
+
+No unresolved product decision blocks the technical design. The user reviewed and approved the design baseline and `TASK-HARNESS-002` implementation on 2026-07-17. Later persona, orchestration, blocking rollout, merge, publish, and deploy phases remain separately gated.
+
+## 11. External References
+
+- [revfactory/harness](https://github.com/revfactory/harness) - team topology, persona, file-handoff, and QA ideas used as comparative design input
+- [revfactory/harness-100](https://github.com/revfactory/harness-100) - generated fullstack and product-management examples used to identify useful patterns and unsafe defaults
+
+## 12. Related Documents
+
+- **Technical_Specs**: [Agent Harness Architecture](../03_Technical_Specs/01_AGENT_HARNESS_ARCHITECTURE.md) - technical realization of these requirements
+- **Logic_Progress**: [Decision Log](../04_Logic_Progress/03_DECISION_LOG.md) - approved architecture decisions and alternatives
+- **Logic_Progress**: [Execution Plan](../04_Logic_Progress/01_EXECUTION_PLAN.md) - approved design-to-implementation sequence
+- **QA_Validation**: [Agent Harness Test Scenarios](../05_QA_Validation/01_TEST_SCENARIOS.md) - traceable validation criteria

package/docs/03_Technical_Specs/01_AGENT_HARNESS_ARCHITECTURE.md

@@ -0,0 +1,376 @@
+# Agent Harness Architecture
+> Created: 2026-07-17 01:04
+> Last Updated: 2026-07-17 01:53
+
+## 1. Architecture Goal
+
+The enhanced harness coordinates specialized agents without surrendering user authority, document traceability, implementation scope, or independent verification. It extends the current receipt sequence rather than replacing it.
+
+The architecture is deliberately split into two layers:
+
+1. **Canonical policy layer**: runtime-neutral roles, states, messages, artifacts, gates, and failure rules.
+2. **Runtime adapter layer**: Claude Code and Codex mappings to the capabilities actually available in each runtime.
+
+## 2. Design Principles
+
+1. **User authority is non-delegable**: agents may analyze and recommend; unresolved scope, risk, and release decisions return to the user through the Coordinator.
+2. **Documents are canonical; messages are transport**: a chat message may announce a result but cannot replace the linked artifact or Receipt.
+3. **Minimal topology first**: use a linear four-role path unless a specialist or parallel topology provides a specific benefit.
+4. **Persona does not grant permission**: role identity, tool permission, and file ownership are separately declared.
+5. **Producer and verifier remain separate**: QA Inspector reports findings and never fixes the implementation it verifies.
+6. **Failures are states, not prose**: the Coordinator records a typed state and legal next action.
+7. **No silent degradation**: missing critical context, design, code, or verification cannot be hidden by a partial final report.
+8. **Adapters are thin**: runtime-specific tool names never become canonical workflow rules.
+
+## 3. System Context And Data Flow
+
+![Agent harness data flow](./assets/01_agent_harness_data_flow.svg)
+
+The Coordinator owns the task state. Specialists produce versioned artifacts. The task manifest and event log preserve transport state, while approved project documents remain the source of truth.
+
+## 4. Role Catalog
+
+### 4.1 Core Roles
+
+| Role | Activation | Primary Responsibility | Write Authority |
+|---|---|---|---|
+| Coordinator | Always | User communication, topology selection, state transitions, approvals, handoffs, completion decision | Backlog, decision and receipt summaries only |
+| Context Reader | Code and deploy; advisory elsewhere | Read all linked references, detect conflicts, return Context Receipt | None |
+| Implementer | After required design and Context gates pass | Change only approved files and return Change Receipt | Declared implementation ownership |
+| QA Inspector | After a Change Receipt; incrementally for complex work | Independently inspect boundaries, execute checks, return findings and Verification Receipt | None, except a separately approved QA report written by Coordinator |
+
+### 4.2 Optional Specialists
+
+| Role | Activation Condition | Required Output | Non-Goal |
+|---|---|---|---|
+| Requirements Analyst | New feature, ambiguous request, multiple stakeholders, or missing acceptance criteria | User Requirements Analysis | Does not choose unresolved product scope |
+| Architect | Cross-module boundary, new API/DB contract, dependency or deployment decision | Architecture Decision Packet | Does not implement the selected design |
+| Logic Builder | Non-trivial business rules, state transitions, retry policy, calculation, or authorization logic | Logic Contract | Does not own UI styling or infrastructure |
+| Frontend Implementer | UI-specific owned files | Frontend Change Receipt contribution | Does not change backend contracts unilaterally |
+| Backend Implementer | API, persistence, authentication, or business-service owned files | Backend Change Receipt contribution | Does not change UI expectations unilaterally |
+| Security Inspector | Authentication, authorization, secrets, uploads, PII, or high-risk boundary | Security findings and evidence | Does not replace QA Inspector |
+| Release Guardian | Publish, deployment, migration, or rollback risk | Release Readiness Receipt | Does not approve its own unresolved risk |
+
+### 4.3 Activation Rules
+
+- A small single-module change uses the core path only.
+- Requirements Analyst is mandatory when acceptance criteria cannot be derived from approved documents.
+- Architect is mandatory when a public contract, persistence model, module boundary, dependency, or deployment topology changes.
+- Logic Builder is mandatory when more than one state transition, failure branch, invariant, or domain calculation must be coordinated.
+- Security Inspector is mandatory for authentication, authorization, secret handling, protected uploads, personal data, or external trust boundaries.
+- Release Guardian is mandatory before npm publish, deployment, destructive migration, or rollback-sensitive operations.
+- The Coordinator records `Activated` or `Skipped - reason` for every optional role considered.
+
+## 5. Persona Contract
+
+Every runtime agent definition must contain the following fields. Friendly prose may supplement these fields but cannot replace them.
+
+| Field | Purpose |
+|---|---|
+| `role_id` | Stable machine identifier |
+| `mission` | One responsibility stated as an outcome |
+| `activation` | Conditions under which the role is invoked |
+| `non_goals` | Explicitly excluded decisions and work |
+| `required_inputs` | Artifact and Receipt prerequisites |
+| `required_outputs` | Schema and canonical destination |
+| `allowed_tools` | Minimum tool capability set |
+| `denied_tools` | Tools prohibited even if the runtime offers them |
+| `write_scope` | Files or directories exclusively owned by the role |
+| `communication` | Allowed message types and recipients |
+| `escalation` | Conditions that return control to Coordinator or user |
+| `completion_criteria` | Evidence required before reporting success |
+| `failure_policy` | Retry and non-retry behavior |
+| `model_policy` | Task-sensitive capability tier, never a globally fixed model |
+
+## 6. Workflow Topology Selection
+
+| Pattern | Use When | Solmate Constraint |
+|---|---|---|
+| Linear Pipeline | Default; each output is required by the next stage | Minimal path and default topology |
+| Expert Pool | A specialist is conditionally required | Preferred way to activate Architect, Logic Builder, Security, or Release roles |
+| Fan-out/Fan-in | Independent read-only searches or test groups can run in parallel | Coordinator integrates results; no overlapping writes |
+| Producer-Reviewer | Implementation must be independently assessed | Implementer and QA Inspector remain separate |
+| Supervisor | Work volume requires dynamic allocation | Coordinator remains the only approval and state authority |
+| Hierarchical Delegation | A large task naturally splits into independently owned domains | Maximum depth two; avoid when a flat team is sufficient |
+
+The Coordinator records the selected pattern, benefit, agent count, write ownership, and fallback before delegation. Two or more agents alone are not sufficient justification for a team topology.
+
+## 7. Canonical Workflow State Machine
+
+### 7.1 Primary States
+
+```text
+INTAKE
+  -> REQUIREMENTS_READY
+  -> CONTEXT_LOCKED
+  -> DESIGN_READY
+  -> IMPLEMENTING
+  -> CHANGE_READY
+  -> VERIFYING
+  -> COMPLETE
+```
+
+`DESIGN_READY` may record Architect and Logic Builder as `Skipped - reason` for a simple task. It does not imply that every task creates extra design documents.
+
+### 7.2 Exception States
+
+| State | Meaning | Legal Next State |
+|---|---|---|
+| `BLOCKED_CONTEXT` | Required document missing, unread, stale, or conflicting | `CONTEXT_LOCKED` after correction |
+| `BLOCKED_DECISION` | User-owned scope, risk, or architecture decision unresolved | Previous state after user decision |
+| `BLOCKED_DEPENDENCY` | External service, credential, permission, or environment unavailable | Previous state after dependency recovery |
+| `REWORK` | Implementation or evidence failed an accepted criterion | `IMPLEMENTING` with a new attempt |
+| `DEGRADED` | Required independent runtime capability unavailable | User-approved continuation or `CANCELLED` |
+| `CANCELLED` | User or Coordinator terminates the task | Terminal |
+
+### 7.3 Transition Rules
+
+- Only Coordinator changes the canonical task state.
+- Every transition records `from`, `to`, `reason`, `actor`, `timestamp`, and `artifact_refs`.
+- `IMPLEMENTING` requires accepted requirements, passing Context Receipt, and any required design outputs.
+- `VERIFYING` requires a Change Receipt and a frozen diff or commit reference.
+- `COMPLETE` requires a passing Verification Receipt and no unresolved P0/P1 finding.
+- PR, merge, publish, and deploy remain downstream gates and may add Release Guardian requirements.
+- An illegal transition is a contract failure and is never retried automatically.
+
+## 8. Artifact Model
+
+### 8.1 Canonical Project Documents
+
+| Artifact | Canonical Location | Owner |
+|---|---|---|
+| User Requirements Analysis | `docs/01_Concept_Design/NN_<FEATURE>_REQUIREMENTS_ANALYSIS.md` | Requirements Analyst, approved by user/Coordinator |
+| UI and flow evidence | `docs/02_UI_Screens/` and `previews/` | UI workflow |
+| Architecture Decision Packet | `docs/03_Technical_Specs/NN_<FEATURE>_ARCHITECTURE.md` | Architect |
+| Logic Contract | `docs/04_Logic_Progress/NN_<FEATURE>_LOGIC.md` | Logic Builder |
+| Backlog and receipt summary | `docs/04_Logic_Progress/00_BACKLOG.md` | Coordinator |
+| QA plan and detailed evidence | `docs/05_QA_Validation/` | QA process, recorded by Coordinator |
+
+### 8.2 Execution Workspace
+
+```text
+_workspace/harness/<task-id>/
+├── manifest.json
+├── events.jsonl
+├── attempt-01/
+│   ├── messages/
+│   ├── artifacts/
+│   └── evidence/
+└── attempt-02/
+    └── ...
+```
+
+Rules:
+
+- `_workspace/` is execution evidence, not the approved product specification.
+- Attempts are append-only; a retry creates a new attempt directory.
+- `manifest.json` identifies schema version, current state, active attempt, topology, role activation, write ownership, and canonical document links.
+- `events.jsonl` records ordered state-transition events. Structured messages remain under the active attempt's `messages/` directory.
+- Secrets, credentials, raw personal data, and unrestricted production logs are prohibited.
+- The project decides whether `_workspace/` is committed, archived, or ignored; canonical evidence links must remain valid either way.
+
+### 8.3 Version 1 Machine Contract
+
+The canonical machine schema is `rules-workflow/resources/agent-harness-v1.schema.json`. It contains the manifest, message, and event JSON Schemas plus the legal transition, critical evidence, core-role, read-only-role, and required Receipt tables used by the validator.
+
+The v1 manifest fields are:
+
+- `schema_version`, `artifact_type`, `task_id`, `work_type`, `current_state`, and `active_attempt`;
+- `topology` with pattern, reason, active agent count, and fallback;
+- `roles` with `ACTIVE` or `SKIPPED` activation and a required reason;
+- exclusive `write_ownership` scopes;
+- `canonical_documents` and state-relevant `receipts`.
+
+The v1 event fields are `schema_version`, `artifact_type`, `event_id`, `task_id`, `attempt`, `sequence`, `timestamp`, `actor`, `from`, `to`, `reason`, `artifact_refs`, `evidence_refs`, and conditional `resume_state`. Message and event validation is paired with the manifest so inactive roles, task/attempt drift, incomplete Receipt evidence, and final-state drift cannot silently pass.
+
+The first implementation uses Node standard-library JSON/JSONL parsing and no third-party dependency. Existing backlog Receipt parsing remains unchanged and structured artifacts are opt-in during warning migration.
+
+The top-level Draft 2020-12 schema selects exactly one manifest, message, or event with `oneOf`; an `events.jsonl` file validates each non-empty line as an event and then applies ordered-log semantics. Project paths are canonical and relative. Embedded `.` aliases, duplicate separators, parent traversal, URLs, backslashes, and ambiguous wildcards are rejected. Exclusive recursive ownership uses `directory/**` or `**` only.
+
+Timestamps use a deterministic Solmate canonical profile over RFC 3339: uppercase `T` and `Z`, years `0001` through `9999`, seconds `00` through `59`, and a required UTC marker or numeric offset. Lowercase variants and leap-second notation are intentionally excluded from generated execution evidence.
+
+In the v1 state-event contract, `attempt` increments only on `REWORK -> IMPLEMENTING`. Cancellation and ordinary progress retain the current attempt. `TASK-HARNESS-004` must define the persisted event shape for transient operational retries before that recovery path is enabled.
+
+## 9. Inter-Agent Message Protocol
+
+### 9.1 Message Envelope
+
+```json
+{
+  "schema_version": 1,
+  "artifact_type": "agent_message",
+  "message_id": "msg-01J...",
+  "task_id": "TASK-HARNESS-002",
+  "attempt": 1,
+  "timestamp": "2026-07-17T01:04:00+09:00",
+  "from": "architect",
+  "to": ["coordinator"],
+  "type": "HANDOFF",
+  "status": "PASS",
+  "summary": "Architecture decision packet is ready.",
+  "requirement_refs": ["FR-005", "FR-012"],
+  "artifact_refs": ["docs/03_Technical_Specs/01_AGENT_HARNESS_ARCHITECTURE.md"],
+  "decision_refs": ["DEC-002"],
+  "evidence_refs": [],
+  "blockers": [],
+  "next_action": "Coordinator may activate Logic Builder.",
+  "retry_count": 0
+}
+```
+
+### 9.2 Message Types
+
+| Type | Purpose | Decision Authority |
+|---|---|---|
+| `REQUEST` | Assign approved work | Coordinator |
+| `STATUS` | Report progress without changing scope | Any active role |
+| `QUESTION` | Request clarification | Any active role |
+| `DECISION_REQUIRED` | Escalate an unresolved decision | Coordinator routes to user or decision owner |
+| `HANDOFF` | Transfer a completed artifact | Producing role; Coordinator accepts or rejects |
+| `FINDING` | Report a defect, conflict, or risk | Inspector roles |
+| `REWORK_REQUEST` | Request a new implementation attempt | Coordinator after accepting a finding |
+| `RESULT` | Return final role evidence | Producing role |
+
+### 9.3 Routing Rules
+
+- Agents may communicate directly for status, evidence location, or bounded technical clarification.
+- Direct peer `STATUS` and `QUESTION` messages use only `INFO` or `PENDING`; PASS, FAIL, BLOCKED, rework, and completion status route through Coordinator.
+- Scope changes, acceptance changes, architecture decisions, risk acceptance, state transitions, PASS decisions, and releases must route through Coordinator.
+- Direct messages that alter a contract are invalid until recorded as a Coordinator decision and linked artifact update.
+- Large content is never copied into a message; the message contains a summary and artifact reference.
+- Every finding names the violated requirement or contract when one exists.
+
+## 10. Error Handling
+
+| Error Class | Examples | Retry | State / Action |
+|---|---|---:|---|
+| Context error | Missing reference, unread document, conflicting specification | 0 | `BLOCKED_CONTEXT`; repair or user decision |
+| Decision error | Unapproved scope, ambiguous product behavior, risk acceptance | 0 | `BLOCKED_DECISION`; ask user |
+| Contract error | Invalid schema, illegal transition, unauthorized write | 0 | Reject message or artifact; return to responsible role |
+| Transient operational error | Temporary network, rate limit, tool process interruption | 1 | Retry same scope in a new recorded attempt |
+| Agent timeout / stop | Agent exits without valid handoff | 1 | Resume or replace role using persisted inputs |
+| Implementation failure | Build, test, or accepted behavior fails | Up to 2 rework loops | `REWORK`; Implementer produces a new Change Receipt |
+| Verification failure | QA finding or required check fails | No QA self-fix | `REWORK`; Coordinator sends finding to Implementer |
+| Critical artifact loss | Requirements, Context, design, code, or verification unavailable | 0 | Block; code/deploy cannot continue with a silent omission |
+| Independent verifier unavailable | Runtime cannot provide independent execution | 0 automatic | `DEGRADED`; explicit user approval required |
+| Conflicting specialist outputs | Two valid but incompatible recommendations | 0 | Preserve both, record trade-off, route decision |
+
+Retry rules:
+
+- Retrying never broadens scope or changes acceptance criteria.
+- A retry increments the attempt and retains the failed evidence.
+- Repeated transient failure becomes `BLOCKED_DEPENDENCY`.
+- After two rework loops, Coordinator reports the repeated failure pattern and requests a user decision before further changes.
+- Partial output may inform diagnosis but cannot satisfy a missing critical gate.
+
+## 11. Permissions And Ownership
+
+| Role | Read | Write | Execute Checks | Approve Scope | Approve Completion |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Coordinator | Yes | Governance docs | Yes | User-confirmed only | Yes, with required evidence |
+| Requirements Analyst | Yes | Requirements draft only | No | No | No |
+| Context Reader | Yes | No | Non-mutating inspection only | No | No |
+| Architect | Yes | Architecture draft only | Non-mutating analysis | No | No |
+| Logic Builder | Yes | Logic draft only | Non-mutating analysis | No | No |
+| Implementer | Yes | Declared implementation scope | Basic checks | No | No |
+| QA Inspector | Yes | No | Verification commands | No | No |
+| Release Guardian | Yes | Release evidence only | Packaging/deploy checks | No | No |
+
+Before parallel write work begins, Coordinator records exclusive ownership. Shared files are assigned to one role or updated serially. An agent may not revert or overwrite another role's work to resolve a conflict.
+
+## 12. Receipt Integration
+
+The existing Receipts retain their meaning:
+
+- **Context Receipt** proves linked references were read and conflicts surfaced.
+- **Change Receipt** states changed files, covered requirements, exclusions, checks, and risks.
+- **Verification Receipt** independently proves accepted criteria and required checks.
+
+The enhanced flow adds:
+
+- **Requirements Receipt**: approved requirements document, unresolved questions, and scope state;
+- **Design Receipt**: role activation, architecture/logic artifact links, decisions, and skipped-gate reasons;
+- **Error Receipt**: failure class, attempt, evidence, retry decision, and legal next action;
+- **Release Readiness Receipt**: version, package contents, migration, rollback, monitoring, and publish/deploy evidence.
+
+Receipt summaries belong in the backlog. Detailed evidence belongs in canonical documents, QA reports, PRs, or the execution workspace according to retention policy.
+
+## 13. Runtime Adapters
+
+### 13.1 Claude Code Adapter
+
+- Install namespaced project agents under `.claude/agents/`.
+- Map supported native team or subagent operations to `spawn`, `send`, `wait`, and `close` adapter capabilities.
+- Tool and permission declarations enforce the persona contract where supported.
+- The adapter must not assume experimental team features are available; it reports capability and selects a supported topology.
+
+### 13.2 Codex Adapter
+
+- Keep the main task as Coordinator.
+- Use available subagents for bounded Context, specialist, implementation, or QA work.
+- Pass canonical role, artifact, ownership, and message contracts explicitly.
+- Do not invent a `.codex/agents/` project format unless official runtime support exists.
+
+### 13.3 Capability Negotiation
+
+At task start, an adapter reports:
+
+```json
+{
+  "runtime": "claude-code-or-codex",
+  "parallel_agents": true,
+  "peer_messages": false,
+  "read_only_role_enforcement": true,
+  "persistent_agent_resume": false,
+  "max_concurrency": 4
+}
+```
+
+Coordinator selects the topology from declared capability. Missing peer messaging does not block the workflow because canonical handoffs are artifact- and Coordinator-based.
+
+## 14. Requirements Traceability
+
+Each task maintains a traceability record:
+
+| Requirement | Requirements Artifact | Design Artifact | Change Evidence | Verification Evidence | Status |
+|---|---|---|---|---|---|
+| `FR-*` / `NFR-*` | Link | Link or `Skipped - reason` | Change Receipt / diff | QA report / command | Pending / Pass / Fail / Deferred |
+
+Rules:
+
+- `Deferred` requires a reason and approved future owner; it cannot be used for a P0 requirement in the current scope.
+- A requirement is `Pass` only when independent evidence exists.
+- Requirements added during implementation return the task to `BLOCKED_DECISION` and update the requirements artifact before code resumes.
+
+## 15. Compatibility And Migration
+
+- Existing backlog tasks remain valid until they opt into the enhanced fields.
+- Existing `Context Receipt`, `Change Receipt`, `Verification Receipt`, `preflight`, and `verify` behavior remains compatible.
+- New structured manifests begin in warning mode.
+- The first five real code/deploy tasks collect false-positive and missing-capability evidence.
+- Blocking mode activates only after the pilot review and user approval.
+- Structured validation is available through `validate-harness manifest|message|events`; message and event validation requires the matching manifest.
+- Contract failures return exit `1` only in blocking mode, while malformed JSON, missing files, and invalid command input return exit `2` in all modes.
+
+## 16. YAGNI / KISS / DRY Check
+
+- One canonical architecture contract is referenced by runtime adapters.
+- Optional agents are activated by need rather than installed as a mandatory full team.
+- No new orchestration server, database, queue, or third-party dependency is required for the first implementation.
+- JSON and JSONL use standard parsers; no custom wire format is introduced.
+- Direct peer communication remains optional because artifact handoffs work in both target runtimes.
+- Safety, evidence, accessibility, security, data preservation, and testability are not simplified away.
+
+## 17. External References
+
+- [revfactory/harness](https://github.com/revfactory/harness) - comparative source for team architecture patterns, persona structure, orchestration, and incremental QA
+- [revfactory/harness-100](https://github.com/revfactory/harness-100) - comparative source for fullstack and product-management team examples
+- [Apache License 2.0](https://github.com/revfactory/harness/blob/main/LICENSE) - source material is referenced conceptually; this specification is independently authored rather than copied verbatim
+
+## 18. Related Documents
+
+- **Concept_Design**: [Agent Harness Requirements Analysis](../01_Concept_Design/01_AGENT_HARNESS_REQUIREMENTS_ANALYSIS.md) - source requirements and approved scope
+- **Logic_Progress**: [Backlog](../04_Logic_Progress/00_BACKLOG.md) - design and future implementation tasks
+- **Logic_Progress**: [Execution Plan](../04_Logic_Progress/01_EXECUTION_PLAN.md) - staged implementation and rollout
+- **Logic_Progress**: [Decision Log](../04_Logic_Progress/03_DECISION_LOG.md) - approved architecture choices and alternatives
+- **QA_Validation**: [Agent Harness Test Scenarios](../05_QA_Validation/01_TEST_SCENARIOS.md) - requirement and failure-path validation

package/docs/03_Technical_Specs/assets/01_agent_harness_data_flow.svg

@@ -0,0 +1,94 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
+  <title id="title">Solmate agent harness data flow</title>
+  <desc id="desc">User decisions flow through a coordinator to requirements, context, optional design specialists, implementation, independent QA, and release gates. Canonical documents and an execution workspace preserve artifacts and evidence.</desc>
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L10,5 L0,10 z" fill="#374151"/>
+    </marker>
+    <style>
+      .title { font: 700 30px system-ui, sans-serif; fill: #111827; }
+      .subtitle { font: 400 16px system-ui, sans-serif; fill: #4b5563; }
+      .label { font: 700 18px system-ui, sans-serif; fill: #111827; }
+      .small { font: 400 14px system-ui, sans-serif; fill: #374151; }
+      .box { stroke-width: 2; rx: 6; }
+      .line { stroke: #374151; stroke-width: 2.5; fill: none; marker-end: url(#arrow); }
+      .dashed { stroke: #6b7280; stroke-width: 2; stroke-dasharray: 8 7; fill: none; marker-end: url(#arrow); }
+    </style>
+  </defs>
+
+  <rect width="1600" height="900" fill="#f9fafb"/>
+  <text x="80" y="65" class="title">Solmate Agent Harness</text>
+  <text x="80" y="94" class="subtitle">Canonical documents carry decisions; structured messages carry status and artifact references.</text>
+
+  <rect x="70" y="160" width="180" height="96" class="box" fill="#fef3c7" stroke="#b45309"/>
+  <text x="160" y="198" text-anchor="middle" class="label">User</text>
+  <text x="160" y="224" text-anchor="middle" class="small">scope and risk authority</text>
+
+  <rect x="315" y="145" width="220" height="126" class="box" fill="#dbeafe" stroke="#1d4ed8"/>
+  <text x="425" y="188" text-anchor="middle" class="label">Coordinator</text>
+  <text x="425" y="216" text-anchor="middle" class="small">state, topology, approvals</text>
+  <text x="425" y="240" text-anchor="middle" class="small">handoff acceptance</text>
+
+  <rect x="615" y="135" width="240" height="146" class="box" fill="#dcfce7" stroke="#15803d"/>
+  <text x="735" y="178" text-anchor="middle" class="label">Requirements Analyst</text>
+  <text x="735" y="206" text-anchor="middle" class="small">FR, NFR, AC, scope</text>
+  <text x="735" y="230" text-anchor="middle" class="small">questions and assumptions</text>
+  <text x="735" y="254" text-anchor="middle" class="small">conditional specialist</text>
+
+  <rect x="935" y="145" width="220" height="126" class="box" fill="#e0e7ff" stroke="#4338ca"/>
+  <text x="1045" y="188" text-anchor="middle" class="label">Context Reader</text>
+  <text x="1045" y="216" text-anchor="middle" class="small">linked documents</text>
+  <text x="1045" y="240" text-anchor="middle" class="small">Context Receipt</text>
+
+  <rect x="1240" y="120" width="270" height="176" class="box" fill="#f3e8ff" stroke="#7e22ce"/>
+  <text x="1375" y="163" text-anchor="middle" class="label">Expert Pool</text>
+  <text x="1375" y="195" text-anchor="middle" class="small">Architect</text>
+  <text x="1375" y="220" text-anchor="middle" class="small">Logic Builder</text>
+  <text x="1375" y="245" text-anchor="middle" class="small">Security Inspector</text>
+  <text x="1375" y="270" text-anchor="middle" class="small">activated only when justified</text>
+
+  <rect x="760" y="390" width="260" height="145" class="box" fill="#cffafe" stroke="#0e7490"/>
+  <text x="890" y="434" text-anchor="middle" class="label">Implementer</text>
+  <text x="890" y="462" text-anchor="middle" class="small">exclusive write scope</text>
+  <text x="890" y="486" text-anchor="middle" class="small">Change Receipt</text>
+  <text x="890" y="510" text-anchor="middle" class="small">new attempt on rework</text>
+
+  <rect x="1110" y="390" width="260" height="145" class="box" fill="#fee2e2" stroke="#b91c1c"/>
+  <text x="1240" y="434" text-anchor="middle" class="label">QA Inspector</text>
+  <text x="1240" y="462" text-anchor="middle" class="small">read-only independent checks</text>
+  <text x="1240" y="486" text-anchor="middle" class="small">boundary comparison</text>
+  <text x="1240" y="510" text-anchor="middle" class="small">Verification Receipt</text>
+
+  <rect x="470" y="390" width="250" height="145" class="box" fill="#fce7f3" stroke="#be185d"/>
+  <text x="595" y="434" text-anchor="middle" class="label">Release Guardian</text>
+  <text x="595" y="462" text-anchor="middle" class="small">package and deploy checks</text>
+  <text x="595" y="486" text-anchor="middle" class="small">rollback and monitoring</text>
+  <text x="595" y="510" text-anchor="middle" class="small">conditional specialist</text>
+
+  <path d="M250 208 H315" class="line"/>
+  <path d="M535 208 H615" class="line"/>
+  <path d="M855 208 H935" class="line"/>
+  <path d="M1155 208 H1240" class="line"/>
+  <path d="M1375 296 V345 H890 V390" class="line"/>
+  <path d="M1045 271 V330 H890 V390" class="line"/>
+  <path d="M1020 462 H1110" class="line"/>
+  <path d="M1110 500 H1045 V570 H890 V535" class="dashed"/>
+  <text x="1040" y="592" text-anchor="middle" class="small">FAIL / REWORK through Coordinator</text>
+  <path d="M1240 535 V625 H425 V271" class="line"/>
+  <path d="M760 500 H720" class="dashed"/>
+  <path d="M595 390 V325 H425 V271" class="dashed"/>
+
+  <rect x="160" y="690" width="560" height="140" class="box" fill="#ffffff" stroke="#374151"/>
+  <text x="440" y="732" text-anchor="middle" class="label">Canonical Project Documents</text>
+  <text x="440" y="764" text-anchor="middle" class="small">Requirements, Architecture, Logic, Backlog, QA</text>
+  <text x="440" y="791" text-anchor="middle" class="small">approved decisions and long-lived evidence</text>
+
+  <rect x="880" y="690" width="560" height="140" class="box" fill="#ffffff" stroke="#374151"/>
+  <text x="1160" y="732" text-anchor="middle" class="label">Execution Workspace</text>
+  <text x="1160" y="764" text-anchor="middle" class="small">manifest.json, events.jsonl, attempts, messages</text>
+  <text x="1160" y="791" text-anchor="middle" class="small">runtime transport, recovery, and audit trail</text>
+
+  <path d="M425 271 V655 H440 V690" class="dashed"/>
+  <path d="M890 535 V645 H1160 V690" class="dashed"/>
+  <path d="M1240 535 V635 H1160 V690" class="dashed"/>
+</svg>