@manhd_d/ai-harness 0.14.0 → 0.15.0

package/core/skills/harness-end-user-testing/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: harness-end-user-testing
+description: Exercise approved user journeys through the actual browser, device, CLI or API interface and record outcome evidence. Use when the user requests end-user testing or a change affects an externally observable flow; report unavailable tools/access as BLOCKED.
+---
+
+# Test as an end user
+
+## Input
+Approved AC/use cases and changed paths, app entry/start instructions, current revision/environment,
+existing runner or actual host tools, test-role/account references, authorized isolated fixtures and
+configured evidence destinations. Never ask for passwords in chat or record them in shared reports.
+
+## Procedure
+1. Load `.harness/core/workflows/end-user-acceptance.md` and reuse `harness-verification` for report
+   validation. Inspect requirements and affected interfaces. Choose proportional journeys with stable
+   AC IDs: happy path and applicable validation/error/empty/denied-role/state/persistence regressions.
+   Avoid imposing a CRM CRUD/login suite on static tools, backend-only services or unrelated changes.
+2. Verify that the running app, test accounts and tools are actually reachable. Reuse existing Playwright,
+   Cypress, device or CLI/API tests and project commands. If a web runner is missing, propose Playwright
+   or an authorized host browser tool and clarify only the consequential setup choice. A declared MCP
+   alias does not prove access. Missing essentials block only affected journeys.
+3. Exercise the real boundary: web browser navigation/click/fill/keyboard, device/simulator taps,
+   terminal commands/output/file state or API-client actor workflows. For web, use accessible roles,
+   labels and user-visible controls; avoid internal component state or calling JS handlers as a
+   substitute for interaction. API setup can create isolated fixtures but cannot count as UI coverage.
+4. Compare outcomes with reviewed AC. Check visible results and applicable persisted state after
+   refresh/navigation/reopen, denied actions and negative input. Inspect affected console/network
+   failures; they are diagnostic context, not a replacement for business assertions. Avoid fixed sleeps;
+   use bounded waits/assertions and reviewed retry limits. Reproduce defects before scoped repairs.
+5. Capture redacted machine observations, executed tool/command, timestamps/revision/environment,
+   real vs mocked dependencies, role, steps, expected/observed outcomes and fixture cleanup. Keep
+   screenshot/trace/video/report attachments separate from JSON assertion evidence and review them
+   for sensitive data. Screenshots alone, HTTP 200 or a successful build do not establish a journey PASS.
+6. Reuse schema-1 verification reports: user-facing requirements set verification_target to end-user and name the web/mobile/cli/api surface;
+   scenarios record journey surface/actor/entrypoint/interaction/dependencies/attachments. Mocked
+   or unknown dependency coverage can pass its scoped assertions but cannot verify full end-user AC.
+   Run `aih verify --report <file>`; independently inspect raw evidence and current source revision.
+7. Fix accepted defects through debugging/TDD/implementer, then rerun affected journeys and regression
+   checks. Bound repair/retest rounds according to existing host/project limits. Report remaining
+   FAILED/BLOCKED/NOT_RUN before handoff; do not weaken AC or ignore failing assertions to finish.
+
+## Output
+AC → actual interface steps → expected/observed/assertions → evidence/attachments → tested scope,
+PASSED/FAILED/BLOCKED/NOT_RUN, cleanup receipts, defect reproductions and concrete remaining needs.
+
+## Constraints
+No dependency installation, production/shared fixtures, paid provider calls or remote writes beyond
+existing authorization. Reuse host/runtime permission and source-write policies. No automatic merge,
+release or business-owner UAT approval. Playwright mobile viewport emulation is web evidence, not a
+native mobile device test. Test steps and receipts are producer-declared, not independent proof of agent
+compliance; independent Harness/model evaluation is a separate use of harness-ai-evaluation.
+
+## Handoff
+Give Implementer/Reviewer exact failed AC, reproducible interaction, tested revision/fixture, scoped
+result and evidence paths. Domain-owner acceptance remains separate from automated end-user checks.

package/core/skills/harness-review/SKILL.md

@@ -26,3 +26,7 @@ Use `.harness/core/workflows/continuous-development.md` to review baseline fresh
 stable requirement → spec → code → tests/evidence links and selective documentation diffs/proposals.
 Check required maintenance blockers and remaining-work handoff. Separate implementation complete,
 merged and released; neither a passing test nor this review supplies business approval.
+
+For required end-user acceptance, inspect actual interface interaction, real/mocked dependency scope,
+requirement surface, redacted attachments and source revision. API/unit/build evidence cannot prove a
+browser/device journey. Required BLOCKED/NOT_RUN journeys prevent an unconditional completion claim.

package/core/skills/harness-spec/SKILL.md

@@ -11,7 +11,9 @@ User request, authoritative source links, existing specs and repository boundari
 1. Read source context and identify missing or conflicting business decisions. Follow the installed
    clarification workflow: ask 1–3 consequential questions with A/B/C trade-offs, a grounded
    recommendation and free text. Reuse established answers and authorization.
-2. Draft proposal, design, tasks and capability delta specs in openspec/changes/<id>/.
+2. Use aih new-change <id> for Harness drafts. If an external OpenSpec propose flow created the change,
+   run aih change-sidecars <id> to add missing metadata/decisions/verification/artifact-impact templates
+   without overwriting existing files. Draft proposal, design, tasks and capability delta specs there.
 3. Use ADDED/MODIFIED/REMOVED requirement sections and WHEN/THEN acceptance scenarios.
 4. Include affected repositories, non-goals, security impact, migration and rollback.
 5. Plan vertical tasks with public test boundaries and trace them to requirements.

package/core/skills/harness-start/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: harness-start
+description: Start or resume Harness onboarding inside the current AI session; inspect existing context and ask only missing consequential questions.
+---
+
+## Input
+The current user request, AGENTS.md, project-owned .harness/ configuration and available host tools.
+The native Kiro wrapper exposes this skill as /harness-start. Other hosts can load this canonical skill.
+
+## Procedure
+1. Read AGENTS.md and the installed project-setup workflow. Identify the installed CLI invocation
+   already used by the user (npm/pip aih, npx, or offline node/aih.cmd); reuse it without downloading
+   or requiring another installation. Run `start --compact --host <current-host>` for a read-only orientation in any host, or read the same local configs
+   if shell access is unavailable. This returns a plan, not a second interview in a terminal.
+   If shared configuration is missing in a cloned snapshot, use `setup --apply --dry-run`, then
+   `setup --apply` with that same CLI. This scaffolds missing user files without changing the bundle.
+   Without shell access, read installed templates and create missing configs with host file tools;
+   preserve existing bytes, and report CLI integrity checks NOT_RUN. Do not reinstall or invent paths.
+2. Read local.md frontmatter first, then prose and start.json if present. Run `seed --check` to assess
+   freshness. On first use run `seed` for the source map. Inspect only needed sources and relevant
+   scoped AGENTS/conventions; cached summaries never replace applicable instructions.
+   Read .harness/decisions.json if present before asking. Reuse only confirmed project/applicable
+   module choices while their scope and sources remain valid; proposed/superseded answers do not
+   establish current behavior. A do_not_ask_again flag never prevents reconsidering changed evidence.
+3. Infer goal from the user's actual request. A bug report means change; do not ask them to choose
+   the category again. Reuse declared stack, accepted deviations, sources, outputs and host settings.
+   Ask at most 1–3 missing consequential questions at a time, with concrete options and a grounded
+   recommendation. Never require Maven for a non-Java skill or docs destinations for a tiny bugfix.
+4. During initial setup inspect build manifests, relevant conventions and authorized docs. Populate
+   local.md using the installed templates/local.md schema: stack/build values, sources inspected and
+   already approved deviations. Preserve all existing prose and decisions; migrate legacy prose
+   additively, without treating inferred exceptions as approved. Keep the summary compact and linked.
+   Declare shared tools/files/commands in environment.json; ignored machine.json overrides only
+   declared tool executables and file paths. For Maven settings use files.maven-settings.path.
+   For existing modules follow .harness/core/workflows/seed.md; for new work follow
+   .harness/core/workflows/greenfield-setup.md. Classify mode per affected module. Save observations
+   with sources, mark inferences/unknowns explicitly, and distinguish user-confirmed choices. Do not
+   force technology/CI/MCP interviews before they are relevant to the task.
+5. Inspect host MCP availability. For Kiro, `sync-integrations --host kiro --dry-run` can import server
+   aliases from local host config. Review discoveries and save declarations with the same command
+   without --dry-run. Inspect actual tools in the host; imported config does not establish access.
+6. Save a known task using `start --goal <idea|docs|change|resume> --task <text>` and --change only for
+   an existing resume checkpoint. Use structured tool arguments/proper shell quoting for user text.
+   Save accepted choices incrementally in their existing configs; no duplicate onboarding database.
+   Project/module decisions go in .harness/decisions.json; change-specific answers stay under the
+   OpenSpec change. Preserve superseded history and its replacement ID. Save after each meaningful
+   answer so interruption resumes from partial context; a completed hash cache is not required to
+   preserve a useful observation or confirmed answer.
+   Run doctor (and doctor --skill <name> before a selected skill). Resolve relevant missing fields,
+   then `seed --record` after reconciling the inspected sources. If interrupted, preserve partial facts;
+   do not mark uninspected sources as complete. The next invocation continues from saved facts.
+7. Show a short summary: task, stack/build, approved exceptions, sources, blockers and next action.
+   Continue the user's authorized task through solution-framing or continuous-development, loading
+   only relevant roles/skills. For spec proposals created by an external OpenSpec flow, run
+   `change-sidecars <id>` to add missing decisions/evidence/impact sidecars without overwriting.
+
+## Output
+Shared context in local.md/environment.json, host connection declarations in integrations.json,
+task in start.json, ignored machine paths if needed and reconciled hashes in knowledge.json.
+An actionable next step or concrete blockers, with no repeated questionnaire for known facts.
+
+## Constraints
+The host understands the project and asks questions; CLI validates and records local data. No model
+API key, provider call, automatic delegation, secret copying or upstream OpenSpec modification.
+Do not execute a saved task solely on SessionStart. Host/user authorization and core security apply.
+Never claim token savings, live hook loading or model compliance without actual measurements.

package/core/skills/harness-verification/SKILL.md

@@ -11,6 +11,8 @@ Approved requirements/AC, scoped code and contracts, existing project tests/comm
 ## Procedure
 1. Discover languages, frameworks, architecture, routes/auth, data dependencies, existing docs and test entry points. `aih verify --adaptive` supplies metadata hints only; inspect scoped source and record unknowns.
 2. Select needed unit, integration, API/contract, backend/browser/mobile E2E, authorization/security, regression or AI/RAG evaluation. Reuse existing frameworks. A static site needs no invented API; a mobile app needs no forced browser suite.
+For changed public journeys or an explicit end-user request, load harness-end-user-testing and the
+   installed end-user-acceptance workflow; use the actual interface and distinguish real/mocked scope.
 3. Derive scenarios from requirements: CRUD, approval/roles, state transitions, uploads, asynchronous events, transactions or external integrations only when applicable. Record preconditions, isolated fixtures, steps, expected business assertions, cleanup and evidence.
 4. Check actual tools, permissions and environment. Declare BLOCKED for missing infrastructure/access; NOT_RUN for skipped scope. Agree consequential gaps using existing clarification workflow.
 5. Execute through authorized host tools with bounded timeouts/retries. Assert transport plus business/schema/state/authorization semantics. Expected errors require exact HTTP/application assertions; timeout/network exceptions never pass by default.

package/core/workflows/adaptive-verification.md

@@ -6,3 +6,8 @@ Choose applicable verification methods from feature risk and existing tooling, r
 
 On resume, use `continuous-development.md` to compare the tested revision with the current baseline.
 Re-run affected checks after code/spec changes; a previous PASS does not verify a new revision.
+
+For changed public journeys or an explicit end-user testing request, apply
+`.harness/core/workflows/end-user-acceptance.md` and `harness-end-user-testing`: exercise the actual
+interface, distinguish real/mocked dependencies, and include user-facing outcome evidence or concrete
+BLOCKED/NOT_RUN reasons before completion. API/unit/build success cannot replace required browser/device flows.

package/core/workflows/agent-routing.md

@@ -27,3 +27,9 @@ canonical aliases and preferred skills without spawning workers or probing provi
    receipts and next owner. Reconcile checkpoint and current source/remote state before retries.
 
 Use continuous-development.md for full changes/resume. No CLI orchestration runtime or paid model calls.
+
+Before applying a role, read contract_load_order from aih agents: the canonical core/capability contract,
+then project-owned extensions in declared order. Extensions specialize domain facts; they cannot grant
+permissions or weaken core security. Missing extensions block that role; reconcile contradictory facts
+with the owner. Before a selected skill use aih doctor --skill <name> for declared requires; verify MCP
+access/tools in the actual host even when local prerequisites pass.

package/core/workflows/approvals.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "workflow",
+    "approvals"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "workflow": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "approvals": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "stage",
+          "role",
+          "by",
+          "at",
+          "source_ref"
+        ],
+        "properties": {
+          "stage": {
+            "type": "string"
+          },
+          "role": {
+            "enum": [
+              "spec-owner",
+              "product-owner",
+              "reviewer"
+            ]
+          },
+          "by": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096
+          },
+          "at": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "Z$"
+          },
+          "source_ref": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096
+          }
+        }
+      }
+    }
+  },
+  "description": "Producer declaration only. Drivers validate stage/role pairs, uniqueness and actual review authority/freshness separately."
+}

package/core/workflows/clarification.md

@@ -3,6 +3,8 @@
 Apply during setup, requirement discovery and any later change that exposes a new consequential gap.
 
 1. Read the user request, project facts, relevant code/specs and previously recorded decisions.
+   Read .harness/decisions.json for project-wide/applicable module choices, then the active change's
+   decisions.json. Confirm applicability; superseded/proposed records are not current decisions.
 2. Separate verified facts, consequential unknowns and reversible implementation details.
    Ask about business behavior, public API contracts, data changes, authorization or costly architecture.
    Use project conventions for routine choices; record assumptions rather than blocking every edit.
@@ -12,7 +14,10 @@ Apply during setup, requirement discovery and any later change that exposes a ne
    Use the host's question UI if available; plain text is a valid fallback.
 4. For critical decisions, an unanswered question is not approval. Pause only the affected slice;
    continue independent authorized work. Do not silently implement a suggested answer.
-5. Save shared setup answers in local.md/environment.json. Save change-specific questions, selected
+5. Save shared setup facts in local.md/environment.json and confirmed project/module choices in
+   .harness/decisions.json. Reuse them without asking again while scope and sources still apply.
+   Changed evidence may reopen an affected choice; do_not_ask_again is not permanent authority.
+   Save change-specific questions, selected
    answers and source references in decisions.json. Set reviewed=true only after examining the actual
    scope for consequential ambiguity; an empty decision list is valid when there are no such gaps.
    Status open means unresolved; resolved needs both answer and source. Preserve superseded decisions

package/core/workflows/continuous-development.md

@@ -99,3 +99,8 @@ implementation/merge/release status. On the next session, start again at baselin
 
 ## Meaningful-step recovery
 Use agent-routing.md for scoped perspectives. Keep the existing design/tasks/decisions/evidence current, then save a compact project-owned checkpoint after meaningful steps and before external side effects. aih checkpoint/resume supplies validation and local freshness hints, not execution. Record task/evidence IDs, baseline digests, completed/pending work, blockers, operation identity/status and next action; never copy chat or secrets. If interrupted, reconcile actual sources and unknown/prepared remote operations before retrying. Read real host usage/quota only when available; otherwise record unknown and retain user model settings. Use explicit actions/repository scope for an authorized autopilot; host/repo permission rules still apply.
+
+For changed public journeys or an explicit end-user testing request, apply
+`.harness/core/workflows/end-user-acceptance.md` and `harness-end-user-testing`: exercise the actual
+interface, distinguish real/mocked dependencies, and include user-facing outcome evidence or concrete
+BLOCKED/NOT_RUN reasons before completion. API/unit/build success cannot replace required browser/device flows.

package/core/workflows/end-user-acceptance.md

@@ -0,0 +1,36 @@
+# End-user acceptance
+
+Trigger when the user asks to test like an end user or the changed behavior has an applicable public
+journey. Use harness-end-user-testing with harness-verification. This workflow is available in Core;
+it requires actual host tools and app access, not a separately launched Harness runtime.
+
+1. Read agreed AC/source revisions, saved project context, existing tests and affected routes/screens.
+   Reuse prior answers. `aih verify --adaptive` supplies end_user_acceptance metadata hints and a host
+   prompt; the host derives concrete scenarios from actual requirements, not generic detector rules.
+2. Establish the app URL or executable/start command, local/test/staging environment, actor/test-account
+   references and isolated data. Inspect existing environment.json/integrations.json; keep credentials
+   in the host. Ask 1–3 missing consequential questions with alternatives and a grounded recommendation.
+3. Reuse existing runners. Web: available Playwright/Cypress or authorized browser tools; native mobile:
+   existing device/simulator runner; CLI: real terminal; API-only: public HTTP interface and business
+   state. Documents-only changes use source review; do not invent a web app or claim browser coverage.
+4. Run the agreed happy and relevant negative/role/state journeys through that interface. Web test must
+   actually navigate and use controls. Fixture setup/API assertions supplement, not replace, UI steps.
+   Assert visible results and persistence where specified. Record exactly which backend/services were
+   real, mocked, absent by design or unknown; third-party mocks narrow the proven scope.
+5. Save redacted JSON observations and optional screenshots/traces/videos into existing configured
+   evidence locations (fallback local project-owned verification/ only when no external canonical route
+   is required). Use schema-1 report with requirement verification_target=end-user plus the expected surface and scenario journey
+   declarations; digest-check attachments as well as JSON. Raw attachments can contain secrets: review
+   before retention/sharing; do not dump storage-state cookies or credential-bearing traces into Git.
+6. PASSED only for actually executed scenarios whose expected AC assertions and owned cleanup pass.
+   Mocked/unknown dependencies cannot establish full end-user verification. Missing browser/device,
+   app/account/service access is BLOCKED; unexecuted or deliberate skips remain NOT_RUN with reasons.
+   Unit/component/build/static checks are supplementary. No check-count/coverage threshold substitutes
+   for the journey. CLI validation checks consistency, not real tool execution or stakeholder approval.
+7. Route bugs to scoped implementation and rerun affected journeys after source changes. Preserve
+   unrelated user work and stop bounded retries on persistent blockers. Reviewer's handoff includes
+   AC coverage, real/mocked scope, defects, redacted evidence and actual next needs. Required missing
+   journeys prevent unconditional completion; business-owner UAT and independent model eval are separate.
+
+A small change needs only affected user journeys. Do not require every browser/platform on every task;
+choose them from target users and risk, and disclose what was not exercised.

package/core/workflows/greenfield-setup.md

@@ -0,0 +1,27 @@
+# Build context for a new project
+
+Enter from harness-start/project-setup when no relevant implementation exists. `setup --greenfield`
+selects this guidance; it does not establish project facts or install an adapter. Read current ideas,
+authorized docs, local.md and confirmed decisions before asking. A new module in an existing repo
+also needs the relevant existing-module seed and scoped conventions.
+
+1. Purpose: clarify only missing user outcomes, acceptance behavior and material constraints. Reuse
+   an existing BRD/PRD or the current conversation. Do not force stack choices before understanding
+   the requested product, or require every document template for a small tool.
+2. Design: when implementation needs it, propose the smallest stack/architecture satisfying known
+   constraints. Ask only consequential unresolved choices (data, integrations, deployment/network).
+   A framework choice does not imply microservices, corporate tooling or infrastructure.
+3. Conventions: adopt the relevant installed defaults unless an applicable approved project rule
+   overrides them. Record source/reason/scope for confirmed exceptions. Proposed conventions are
+   not user approval. Resolve API/error/data/test choices only when they affect the accepted scope.
+4. Tooling: discover the actual host, build/test commands and available integrations as needed.
+   Save shared commands/references separately from machine-only paths; never ask for credentials.
+   Defer irrelevant CI/MCP/IDE details rather than blocking useful requirements or implementation.
+
+Ask at most 1–3 questions per turn with options, trade-offs and an evidence-based recommendation.
+Save each established answer incrementally in existing configs and .harness/decisions.json; reuse
+confirmed answers while their scope/sources apply. Mark unknowns/proposals explicitly, preserve
+superseded decisions, and reopen only material affected choices when new evidence warrants it.
+Before seed --record, create/link actual inspected project sources (such as accepted requirements);
+no codebase or source means no claim of a reconciled source cache. Resume from partial saved answers.
+Start authorized work once relevant minimum context exists; additional planning follows task depth.

package/core/workflows/project-setup.md

@@ -4,9 +4,15 @@ Read AGENTS.md, local.md, actual build files and existing environment configurat
 For project/MVP/architecture decisions, apply `solution-framing.md` at the appropriate depth.
 For input/output/storage/source-write decisions, apply `artifact-contract.md`; ask only when
 needed for the task and reuse known project/session decisions.
+Use harness-start in the current session (Kiro: /harness-start), with seed freshness checks.
 Use `aih start` for terminal intake or a read-only host plan; reuse `.harness/start.json` and declared
 artifacts before asking. CLI root-file discovery is metadata evidence; inspect content and the actual host.
 Use `aih setup` for structured suggestions; it never interviews the user or writes answers.
+Use `aih setup --apply` only to scaffold missing user files from a cloned installed snapshot;
+preview with --dry-run. Existing configs and managed payload/lock are preserved. Missing setup
+does not justify reinstalling the bundle. machine.json/start.json are not fabricated by scaffolding.
+Follow seed.md for existing modules and greenfield-setup.md for new modules; inspect their relevant
+project-wide and module-scoped decisions in .harness/decisions.json before asking.
 Do not ask about facts already established in the repository or current conversation.
 
 1. Identify project scope, source documents, build/test commands and environment constraints.
@@ -19,11 +25,15 @@ Do not ask about facts already established in the repository or current conversa
 3. For Java, inspect Maven/Gradle wrappers before proposing PATH or a custom tool. A wrapper is
    a recommendation only when present and consistent with project policy; do not switch corporate
    tools or download a replacement without authorization.
-4. Record shared facts and decisions in `.harness/local.md`: scope/mode, authoritative source paths,
+4. Record shared facts in `.harness/local.md`: scope/mode, authoritative source paths,
    layout and dependency boundaries, reusable common APIs, naming/error/test conventions, commands
    and approved exceptions. Link existing documentation instead of duplicating it. Keep missing facts
    explicit; do not overwrite previous answers. Define exact tool IDs, argument arrays
    and required file paths in `.harness/environment.json`. Record evidence/source, not guessed versions.
+   Save project-wide/module decisions in `.harness/decisions.json` with scope/status/answer/reason/source.
+   Keep proposed choices separate from confirmed ones. When replacing a decision preserve the old
+   record as superseded and link its confirmed replacement. Reuse answers only while applicable;
+   changed scope or contradictory sources can warrant a focused question even with do_not_ask_again.
 5. For a machine-specific executable/file location, use `.harness/machine.json` or an environment
    reference. The machine file can only override declared paths. It does not override permissions,
    arguments, requirements or business decisions. Do not store passwords/tokens in either file.
@@ -44,7 +54,8 @@ If C is selected, ask for only the missing executable/settings locations. Do not
 
 Explain the user-owned files in `.harness/`: project selection in project.json, model/agent preferences in
 agents.json, task in start.json, sources/destinations in artifacts.json, connection aliases in
-integrations.json, shared commands in environment.json and domain facts in local.md. OpenSpec config
+integrations.json, shared commands in environment.json, domain facts in local.md and shared decisions
+in decisions.json. OpenSpec config
 lives in openspec/config.yaml; checkpoints/evidence live under openspec/changes/<id>/, not in `.harness/state/`.
 Keep managed core/adapters/capabilities/templates/lock separate from customization. Update preserves
 user files; use `aih backup` and copy the reported JSON outside the project before consequential changes.

package/core/workflows/seed.md

@@ -0,0 +1,25 @@
+# Understand an existing project
+
+Enter from harness-start/project-setup when affected modules already exist. CLI `seed` discovers
+paths/hashes; the host reads and understands them. Reuse current context and applicable confirmed
+project/module decisions; do not repeat a full repository scan each session.
+
+1. Topology: read root/scoped AGENTS, build manifests and declared convention/source guides.
+   Identify module boundaries and the affected stack. Do not infer architecture from adapter names.
+2. Architecture: inspect one or two representative modules relevant to the task, aiming at no more
+   than eight source files initially. Expand only to resolve a concrete boundary/behavior uncertainty.
+   Record source-linked observations; label inferences separately. Existing code is not approval for
+   an exception, especially when it conflicts with instructions or security.
+3. Tooling: discover only relevant skills/roles, current changes, declared commands and host tools.
+   MCP config names indicate declarations; confirm actual availability and scope in the host.
+4. Machine: reuse shared environment declarations. Ask only missing local executable/file locations
+   and save overrides in ignored machine.json. PATH/wrappers/custom settings are project choices;
+   do not universally require Maven or a settings flag.
+
+Keep local.md compact with evidence paths and unresolved facts. Save confirmed project-wide/module
+choices in .harness/decisions.json and change-specific choices under the active OpenSpec change.
+Keep superseded answers traceable. Source changes invalidate affected assumptions; inspect the
+changed source and any relevant scoped instructions, update only affected context, then seed --record.
+Save partial observations after each useful step; do not fabricate completion or a confidence score.
+Continue the authorized task when its relevant facts are sufficient; do not make exhaustive discovery
+a gate for a small fix. Semantic understanding and token/time savings require actual host measurement.

package/core/workflows/spec-to-code.md

@@ -2,14 +2,14 @@
 
 | Stage | Input | Output and gate |
 | --- | --- | --- |
-| Discover | Request, repository, linked sources | Scope/mode, affected repos and risks, convention sources, comparable code and reuse candidates; clarify consequential unknowns |
-| Specify | Agreed behavior | proposal, design, delta specs and vertical tasks |
-| Review spec | Acceptance scenarios and design | Owner agreement for consequential choices; explicit task authorization may already cover routine choices |
-| Implement | One task with a public test boundary and reuse plan | Failing meaningful test, minimal implementation, green test; established boundaries and rationale for new components |
-| Verify | Changed behavior | Relevant automated checks and honest skipped-check list |
-| Review | Diff plus spec and convention sources | Findings on correctness, security, compatibility, reuse, placement and unnecessary abstraction |
-| Deliver | Reviewed branch | PR with change ID, evidence, residual risks and rollback plan |
-| Archive | All associated PRs merged | Sync accepted specs and archive via OpenSpec in a separate reviewed change if needed |
+| `discover` | Request, repository, linked sources | Scope/mode, affected repos and risks, convention sources, comparable code and reuse candidates; clarify consequential unknowns |
+| `specify` | Agreed behavior | proposal, design, delta specs and vertical tasks |
+| `review-spec` | Acceptance scenarios and design | Owner agreement for consequential choices; explicit task authorization may already cover routine choices |
+| `implement` | One task with a public test boundary and reuse plan | Failing meaningful test, minimal implementation, green test; established boundaries and rationale for new components |
+| `verify` | Changed behavior | Relevant automated checks and honest skipped-check list |
+| `review` | Diff plus spec and convention sources | Findings on correctness, security, compatibility, reuse, placement and unnecessary abstraction |
+| `deliver` | Reviewed branch | PR with change ID, evidence, residual risks and rollback plan |
+| `archive` | All associated PRs merged | Sync accepted specs and archive via OpenSpec in a separate reviewed change if needed |
 
 Apply `artifact-contract.md` for declared inputs/outputs, canonical ownership and connections.
 Maintain affected docs/spec/UI in the same change; record artifact-impact.json when outputs are
@@ -42,3 +42,14 @@ For proportional checks and evidence integrity, use `.harness/core/workflows/ada
 
 For successive changes and resumed sessions, enter through `continuous-development.md` for baseline
 reconciliation, selective artifact maintenance, feedback triage and evidence-linked handoff.
+
+For changed public journeys or an explicit end-user testing request, apply
+`.harness/core/workflows/end-user-acceptance.md` and `harness-end-user-testing`: exercise the actual
+interface, distinguish real/mocked dependencies, and include user-facing outcome evidence or concrete
+BLOCKED/NOT_RUN reasons before completion. API/unit/build success cannot replace required browser/device flows.
+
+When an external OpenSpec propose flow creates a change, run aih change-sidecars <id> before the
+clarification/readiness stages to create missing metadata, decisions, verification and artifact-impact
+sidecars. Existing files remain unchanged; Harness does not patch the upstream OpenSpec CLI.
+
+Machine contract: spec-to-code.workflow.json. Use explicit `aih ready <id> --workflow spec-to-code --stage implement` to require a recorded review-spec approval; legacy implement/review calls retain their structural behavior. Approval records declare an external review, not authenticated identity or permission.

package/core/workflows/spec-to-code.workflow.json

@@ -0,0 +1,99 @@
+{
+  "schema_version": 1,
+  "id": "spec-to-code",
+  "stages": [
+    {
+      "id": "discover",
+      "owner": "core:planner",
+      "next": [
+        "specify"
+      ]
+    },
+    {
+      "id": "specify",
+      "owner": "core:planner",
+      "outputs": [
+        "proposal.md",
+        "design.md",
+        "tasks.md"
+      ],
+      "next": [
+        "review-spec"
+      ]
+    },
+    {
+      "id": "review-spec",
+      "owner": "human:spec-owner",
+      "entry_gate": {
+        "deterministic": [
+          "spec-structure"
+        ]
+      },
+      "approval": {
+        "role": "spec-owner"
+      },
+      "next": [
+        "implement"
+      ],
+      "on_reject": "specify"
+    },
+    {
+      "id": "implement",
+      "owner": "core:implementer",
+      "entry_gate": {
+        "deterministic": [
+          "spec-structure",
+          "decisions-resolved",
+          "tasks-present",
+          "artifact-impact"
+        ],
+        "approval_from": "review-spec"
+      },
+      "next": [
+        "verify"
+      ]
+    },
+    {
+      "id": "verify",
+      "owner": "core:test-engineer",
+      "entry_gate": {
+        "deterministic": [
+          "tasks-complete"
+        ]
+      },
+      "next": [
+        "review"
+      ],
+      "on_fail": "implement"
+    },
+    {
+      "id": "review",
+      "owner": "core:reviewer",
+      "entry_gate": {
+        "deterministic": [
+          "spec-structure",
+          "decisions-resolved",
+          "tasks-complete",
+          "verification-evidence",
+          "artifact-impact"
+        ]
+      },
+      "next": [
+        "deliver"
+      ],
+      "on_fail": "implement"
+    },
+    {
+      "id": "deliver",
+      "owner": "core:planner",
+      "next": [
+        "archive"
+      ]
+    },
+    {
+      "id": "archive",
+      "owner": "core:planner",
+      "next": []
+    }
+  ]
+}