@manhd_d/ai-harness 0.7.0 → 0.9.0

package/capabilities/product/skills/harness-product-acceptance-criteria/SKILL.md

@@ -23,3 +23,20 @@ description: Write verifiable acceptance criteria in Given/When/Then for each st
 ## Constraints
 - Never claim that acceptance tests have run; these are specifications, not execution evidence.
 - Avoid arbitrary time, availability and performance thresholds.
+
+## Template
+Read `.harness/capabilities/product/templates/acceptance-criteria.md`; `aih new-doc acceptance-criteria` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: Given an employee outside the organization, when searching its customer, then access is denied without leaking existence.
+
+## Quality checklist
+- Happy, negative and boundary cases are observable.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-backlog-prioritization/SKILL.md

@@ -23,3 +23,20 @@ description: Rank proposed requirements transparently using explicit scoring ass
 ## Constraints
 - AI ranking is advisory; only the authorized PO/PM sets accepted priorities.
 - Do not equate an estimate with a delivery commitment.
+
+## Template
+Read `.harness/capabilities/product/templates/backlog.md`; `aih new-doc backlog` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: Rank secure create/search before optional import using agreed value/dependencies; effort stays unknown without team input.
+
+## Quality checklist
+- Priority rationale uses evidence instead of fabricated effort scores.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-brd-generation/SKILL.md

@@ -23,3 +23,20 @@ description: Produce a Business Requirements Document with actors, business rule
 ## Constraints
 - Never self-approve a BRD or invent evidence.
 - Avoid treating template placeholders as finished decisions.
+
+## Template
+Read `.harness/capabilities/product/templates/brd.md`; `aih new-doc brd` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: BRD links the customer-search goal to BR-001; cost/benefit values remain unknown without financial evidence.
+
+## Quality checklist
+- Business outcomes and stakeholder decisions are traceable.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-business-analysis/SKILL.md

@@ -24,3 +24,20 @@ description: Elicit actors, existing versus future processes, business rules, re
 ## Constraints
 - No unapproved product scope expansion; no fabricated regulation or SLA.
 - Do not reveal internal source material or imply stakeholder acceptance without a decision record.
+
+## Template
+Read `.harness/capabilities/product/templates/business-rules.md`; `aih new-doc business-rules` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: BR-001 requires organization-scoped search; AS-IS behavior and proposed TO-BE duplicate handling remain distinct.
+
+## Quality checklist
+- Business rules and AS-IS/TO-BE preserve source authority.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-document-review/SKILL.md

@@ -24,3 +24,20 @@ description: Review generated BRD/PRD/stories for traceability, completeness, co
 ## Constraints
 - Do not invent reviewer signatures, user research, tests or approvals.
 - Do not treat missing information as implicit consent.
+
+## Template
+Read `.harness/capabilities/product/templates/review-report.md`; `aih new-doc review-report` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: Flag conflicting duplicate policies with exact source references; do not turn the reviewed draft into owner approval.
+
+## Quality checklist
+- Findings include source, impact and decision owner.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-idea-discovery/SKILL.md

@@ -25,3 +25,20 @@ description: Collaboratively refine a developer's rough software idea into an ev
 - A solo developer may be the approval owner; never invent other stakeholders.
 - No fabricated user interviews, market sizes, competitor prices, dates, sources, or approvals.
 - An idea can remain a draft indefinitely; do not force implementation.
+
+## Template
+Read `.harness/capabilities/product/templates/idea.md`; `aih new-doc idea` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: Original idea is preserved; clarify prototype versus usable MVP and choose the smallest end-to-end journey with the user.
+
+## Quality checklist
+- Original words, assumptions, actual answers and non-goals stay visible.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-knowledge-analysis/SKILL.md

@@ -26,3 +26,20 @@ description: Catalog product ideas and authorized Confluence, PDF, meeting-note
 - Do not pretend to have opened a link if no connected connector or file access exists.
 - Do not store access tokens, private customer records or restricted source contents in a public repository.
 - Record missing or inaccessible sources explicitly; never invent citations.
+
+## Template
+Read `.harness/capabilities/product/templates/source-register.md`; `aih new-doc source-register` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: SRC-001 points to the approved SRS revision; a contradictory unapproved page is recorded as a gap, not merged as fact.
+
+## Quality checklist
+- Source authority/version and missing access are explicit.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-mvp-definition/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: harness-product-mvp-definition
+description: Define a usable MVP with in/out scope, acceptance, minimum safeguards and explicit owner decisions.
+---
+
+# harness-product-mvp-definition
+
+## Input
+Original idea or approved requirements, users, constraints, business rules, known alternatives and decision sources.
+
+## Procedure
+1. Identify one target actor, problem and observable user outcome; distinguish prototype, MVP and later release goals.
+2. Map the end-to-end journey, including required authorization, data integrity and recoverable failure behavior.
+3. Compare a few viable scope cuts by value, feasibility, dependency and evidence. Resolve material scope choices with the actual owner; do not accept your own recommendation.
+4. List in/out scope, AC IDs, required NFRs, validation method, success signals and unknown baselines/targets.
+5. Trace each included capability to the journey; defer optional analytics or bulk tools without deferring necessary security.
+6. Check against existing PRD/BA sources, record the agreed version and pass gaps to BA or Architecture.
+
+## Output
+Project-owned docs/product/mvp.md or an MVP section linked from PRD, with scope owner and review status.
+
+## Template
+Read `.harness/capabilities/product/templates/mvp.md` from the installed snapshot.
+Use `aih new-doc mvp` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+Customer-search MVP: an authorized employee creates and finds customers within permitted organization scope. Bulk import is deferred; tenant access checks and duplicate policy are required. Usage target stays unknown until owner confirmation.
+
+## Quality checklist
+- A complete user outcome, not an arbitrary count of features
+- Each scope item links AC and minimum quality constraints
+- Explicit exclusions, decision source and unresolved owner questions
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/product/skills/harness-product-prd-generation/SKILL.md

@@ -24,3 +24,20 @@ description: Produce a Product Requirements Document with user value, measurable
 ## Constraints
 - Estimates, success targets and roadmap dates are proposals until stakeholders approve them.
 - Do not silently change BRD scope or promise unverified capabilities.
+
+## Template
+Read `.harness/capabilities/product/templates/prd.md`; `aih new-doc prd` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: PRD includes authorized create/search and defers import; it links MVP/AC and leaves numeric adoption targets pending.
+
+## Quality checklist
+- MVP journey, exclusions and minimum quality are explicit.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-product-outcomes/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: harness-product-product-outcomes
+description: Define product success measures and experiments without inventing baselines or analytics evidence.
+---
+
+# harness-product-product-outcomes
+
+## Input
+Reviewed problem/MVP, personas, source evidence, available instrumentation and authorized research.
+
+## Procedure
+1. Identify user value and one primary outcome; keep activity/output measures separate from actual success.
+2. List assumptions, known baselines, evidence strength and measurement access; unknown values stay unknown.
+3. Propose metrics, definitions, event/source, owner and evaluation period; numeric targets need stakeholder evidence or approval.
+4. Choose a bounded experiment or feedback loop; account for privacy, cost and negative outcomes.
+5. Connect results to continue/pivot/stop proposals and backlog updates; only the owner decides scope changes.
+
+## Output
+Project-owned docs/product/outcomes.md linked to MVP and PRD.
+
+## Template
+Read `.harness/capabilities/product/templates/outcomes.md` from the installed snapshot.
+Use `aih new-doc outcomes` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+For customer lookup, propose task completion and observed latency as measures. Without real telemetry, label both baseline and target pending instead of claiming a 30% improvement.
+
+## Quality checklist
+- Metric has definition/source/owner and review period
+- Hypothesis and actual measurement are distinct
+- Experiment does not silently expand collection or release scope
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/product/skills/harness-product-product-research/SKILL.md

@@ -25,3 +25,20 @@ description: Research comparable products, user needs and implementation feasibi
 - Do not scrape inaccessible services, bypass document permissions or claim browsing occurred when it did not.
 - No fabricated references, metrics, reviews or user interviews.
 - Research is advisory, not an approval or an instruction to change the codebase.
+
+## Template
+Read `.harness/capabilities/product/templates/research.md`; `aih new-doc research` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: With no browsing access, competitor claims are UNKNOWN and research questions are proposed rather than citations invented.
+
+## Quality checklist
+- Retrieved facts, inferences and forecasts have provenance.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-srs-generation/SKILL.md

@@ -26,3 +26,20 @@ description: Produce a testable Software Requirements Specification linked to ap
 - Do not invent protocol guarantees, SLAs, security requirements or existing integrations.
 - Keep product intent separate from chosen technical implementation.
 - Never change code or claim stakeholder approval solely because a document was generated.
+
+## Template
+Read `.harness/capabilities/product/templates/srs.md`; `aih new-doc srs` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: FR-001 defines search behavior; NFR-001 target is pending until agreed and is passed to Architecture for a scenario/test plan.
+
+## Quality checklist
+- FR/NFR contracts, exception paths and trace IDs remain consistent.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-traceability/SKILL.md

@@ -22,3 +22,20 @@ description: Maintain bidirectional links from document sources through BRD/PRD/
 ## Constraints
 - Links are evidence pointers, not authorization to modify external systems.
 - Never rewrite approved artifacts automatically based on Confluence updates.
+
+## Template
+Read `.harness/capabilities/product/templates/traceability.md`; `aih new-doc traceability` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: SRC-001 → FR-001 → US-001 → AC-US-001-01 → ADR-001/OpenSpec task/test links form a checkable chain.
+
+## Quality checklist
+- Stable IDs, source versions and downstream gaps are maintained.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-use-case-generation/SKILL.md

@@ -24,3 +24,20 @@ description: Translate requirement and story IDs into consistent main, alternati
 - Never imply a draft flow is accepted without sign-off.
 - Avoid duplicating product scope in a competing document; reference established IDs.
 - No assumptions about system behavior presented as approved facts.
+
+## Template
+Read `.harness/capabilities/product/templates/use-cases.md`; `aih new-doc use-cases` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: UC-001 contains main lookup, no-result, permission denial and provider timeout paths linked to FR/AC.
+
+## Quality checklist
+- Actor, precondition, result and alternate/error flows are explicit.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-user-stories/SKILL.md

@@ -23,3 +23,20 @@ description: Turn approved requirements into atomic epics and user stories with
 ## Constraints
 - Do not fabricate persona needs or change scope via user-story rewriting.
 - A story marked Ready requires actual acceptance criteria and PO review.
+
+## Template
+Read `.harness/capabilities/product/templates/backlog.md`; `aih new-doc backlog` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: US-001: authorized employee finds a customer; links FR-001 and AC-US-001-01, with access-denial criteria.
+
+## Quality checklist
+- Story has user value, dependency and observable acceptance.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/templates/mvp.md

@@ -0,0 +1,25 @@
+# MVP scope
+
+Status: draft / pending review
+Owner: TODO
+Sources and revisions: TODO
+Scope / related requirement and decision IDs: TODO
+Last verified against code: TODO (or not applicable with reason)
+
+## User and outcome
+Target actor, problem, value-bearing end-to-end journey and validation evidence.
+## Scope cuts
+| Capability | In / out | Value / dependency | Requirement / AC | Decision source |
+| --- | --- | --- | --- | --- |
+| TODO | TODO | TODO | TODO | TODO |
+## Minimum viable quality
+Authorization, data integrity, failure recovery and relevant NFRs that cannot be deferred.
+## Acceptance and learning
+Observable journey completion, success signals, measurement owner, known baseline/target or unknown.
+## Open decisions
+Options/trade-offs, recommended cut with evidence and actual owner answer; unanswered choices remain pending.
+
+
+## Review and handoff
+Record actual owner decisions, unresolved consequential questions, verification performed/skipped,
+next role, source/output paths and affected OpenSpec change. Draft text is not an accepted decision.

package/capabilities/product/templates/outcomes.md

@@ -0,0 +1,23 @@
+# Product outcomes
+
+Status: draft / pending review
+Owner: TODO
+Sources and revisions: TODO
+Scope / related requirement and decision IDs: TODO
+Last verified against code: TODO (or not applicable with reason)
+
+## Value hypothesis
+User problem and expected benefit; link MVP/PRD instead of duplicating scope.
+## Measurement plan
+| Outcome / metric | Definition / source | Baseline | Proposed target / authority | Owner / period |
+| --- | --- | --- | --- | --- |
+| TODO | TODO | unknown | pending | TODO |
+## Experiment and guardrails
+Hypothesis, smallest experiment, cost/privacy limits, negative effects and decision checkpoint.
+## Evidence and next action
+Separate observed results from forecasts; propose continue/pivot/stop without self-approving scope changes.
+
+
+## Review and handoff
+Record actual owner decisions, unresolved consequential questions, verification performed/skipped,
+next role, source/output paths and affected OpenSpec change. Draft text is not an accepted decision.

package/capabilities/product/workflows/document-driven.md

@@ -11,3 +11,7 @@ Use when a project already supplies authorized BA/PO materials (Confluence, BRD,
 7. **Source changes:** compare actual source revisions and propose a reviewed requirements/code impact diff rather than overwriting user-owned artifacts.
 
 Canonical enterprise source stays in the enterprise system; consumer repo stores pointers, versioned derived docs and project-local engineering artifacts. RAG is optional permission-scoped retrieval, not a replacement for a system of record. The `aih` CLI does not ingest data or run agents.
+
+For new/material journeys, continue with `product-to-solution.md` after resolving the relevant scope.
+Use reviewed MVP/outcomes and optional Architecture/Delivery to assess solution/dependencies before
+OpenSpec implementation. Existing approved sources remain canonical; small clear changes stay compact.

package/capabilities/product/workflows/idea-driven.md

@@ -11,3 +11,7 @@ Use this when the developer starts with an idea, including a solo project. Produ
 7. **Changes:** when the idea changes, perform impact analysis and propose minimal document diffs; never silently overwrite approved requirements.
 
 Deliverables are **consumer-owned** `docs/discovery/`, `docs/product/` and `openspec/` files. For Confluence publishing, preserve URLs/page versions and request explicit write permission; the Harness CLI does not connect or publish to Confluence.
+
+For new/material journeys, continue with `product-to-solution.md` after resolving the relevant scope.
+Use reviewed MVP/outcomes and optional Architecture/Delivery to assess solution/dependencies before
+OpenSpec implementation. Existing approved sources remain canonical; small clear changes stay compact.

package/capabilities/product/workflows/product-to-solution.md

@@ -0,0 +1,15 @@
+# BA → PO → Solution → Delivery
+
+Use for a new product or material feature. For a small clear fix, use the Core compact path.
+1. BA preserves idea/approved document revisions, identifies users, business rules and contradictions;
+   load existing business-analysis/use-case/AC skills. Source/output register is authoritative.
+2. PO uses mvp-definition and product-outcomes to propose a complete journey, in/out scope, minimum
+   quality and success evidence. Resolve consequential unknowns with actual owner; no self-approval.
+3. Pass reviewed FR/US/AC/NFR and decision status to installed Architecture discovery-to-design.
+   If Architecture is not selected, Core spec uses the same constraints and records relevant choices.
+4. Pass accepted solution boundaries, AC, dependencies and actual estimates to optional Delivery planning;
+   absent Delivery, record a proportional task order in the OpenSpec change.
+5. UI/UX can iterate with SA/PO; adapters implement accepted technical decisions. Verify and review
+   against requirements/ADRs. Evidence and scope changes loop back to the owning role.
+6. Carry source revisions, IDs, output paths, decisions, unresolved questions, actual checks and next
+   owner in every handoff. A role label never creates a worker or approves a stakeholder decision.

package/cli/agents.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, stat, readJson, isObject, SLUG, SOURCE, HarnessError } from './files.js';
+
+export const AGENT_CONFIG = '.harness/agents.json';
+export const DEFAULT_AGENTS = 'config/agents.default.json';
+export const PRESETS = ['recommended', 'economy', 'custom'];
+export const REASONING = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const ROLE = /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/;
+const text = value => typeof value === 'string' && value.trim() === value && value.length > 0
+  && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value);
+const requireThat = (condition, label) => { if (!condition) throw new HarnessError('Invalid agent configuration: ' + label); };
+function fields(value, allowed, required, label) {
+  requireThat(isObject(value) && Object.keys(value).every(key => allowed.includes(key))
+    && required.every(key => Object.hasOwn(value, key)), label + ' fields');
+}
+function reference(value, label) {
+  requireThat(text(value), label + ' must be nonempty single-line text (max 256 characters)');
+  if (value.startsWith('@')) requireThat(SLUG.test(value.slice(1)), label + ' alias syntax');
+  else requireThat(!/\s/.test(value), label + ' model ID must not contain whitespace');
+}
+function provider(value, label) { requireThat(typeof value === 'string' && SLUG.test(value), label + ' provider ID'); }
+function reasoning(value, label) { requireThat(REASONING.includes(value), label + ' reasoning level'); }
+
+export function resolveModel(config, referenceValue, visited = []) {
+  if (!referenceValue.startsWith('@')) return { model: referenceValue, provider: config.provider };
+  const alias = referenceValue.slice(1);
+  requireThat(Object.hasOwn(config.models, alias), 'unknown alias @' + alias);
+  requireThat(!visited.includes(alias), 'cyclic alias @' + alias);
+  const descriptor = config.models[alias];
+  const next = typeof descriptor === 'string' ? descriptor : descriptor.model;
+  const resolved = resolveModel(config, next, [...visited, alias]);
+  return { ...resolved, provider: typeof descriptor === 'object' ? descriptor.provider ?? resolved.provider : resolved.provider };
+}
+
+export function validateAgentConfig(config) {
+  fields(config, ['schema_version', 'provider', 'defaultModel', 'defaultReasoning', 'models', 'agents', 'execution', 'hosts'],
+    ['schema_version', 'provider', 'defaultModel', 'defaultReasoning', 'models', 'agents', 'execution'], 'root');
+  requireThat(config.schema_version === 1, 'unsupported schema_version');
+  provider(config.provider, 'default'); reference(config.defaultModel, 'defaultModel');
+  reasoning(config.defaultReasoning, 'default');
+  requireThat(isObject(config.models) && Object.keys(config.models).length <= 64, 'models map (max 64 aliases)');
+  for (const [alias, descriptor] of Object.entries(config.models)) {
+    requireThat(SLUG.test(alias), 'alias ID');
+    if (typeof descriptor === 'string') reference(descriptor, 'models.' + alias);
+    else {
+      fields(descriptor, ['model', 'provider'], ['model'], 'models.' + alias);
+      reference(descriptor.model, 'models.' + alias);
+      if (descriptor.provider !== undefined) provider(descriptor.provider, 'models.' + alias);
+    }
+  }
+  resolveModel(config, config.defaultModel);
+  for (const alias of Object.keys(config.models)) resolveModel(config, '@' + alias);
+  requireThat(isObject(config.agents) && Object.keys(config.agents).length <= 128, 'agents map (max 128 roles)');
+  for (const [id, agent] of Object.entries(config.agents)) {
+    requireThat(ROLE.test(id), 'role ID must use namespace:role');
+    fields(agent, ['model', 'provider', 'reasoning', 'enabled'], [], id);
+    if (agent.model !== undefined) { reference(agent.model, id); resolveModel(config, agent.model); }
+    if (agent.provider !== undefined) provider(agent.provider, id);
+    if (agent.reasoning !== undefined) reasoning(agent.reasoning, id);
+    requireThat(agent.enabled === undefined || typeof agent.enabled === 'boolean', id + ' enabled');
+  }
+  const execution = config.execution;
+  fields(execution, ['mode', 'maxConcurrentAgents', 'maxRounds', 'autoEscalateToPremium'],
+    ['mode', 'maxConcurrentAgents', 'maxRounds', 'autoEscalateToPremium'], 'execution');
+  requireThat(['single-agent', 'hybrid', 'multi-agent'].includes(execution.mode), 'execution mode');
+  requireThat(Number.isSafeInteger(execution.maxConcurrentAgents) && execution.maxConcurrentAgents >= 1
+    && execution.maxConcurrentAgents <= 32, 'maxConcurrentAgents must be an integer from 1 to 32');
+  requireThat(execution.mode !== 'single-agent' || execution.maxConcurrentAgents === 1, 'single-agent requires maxConcurrentAgents=1');
+  requireThat(Number.isSafeInteger(execution.maxRounds) && execution.maxRounds >= 1 && execution.maxRounds <= 20,
+    'maxRounds must be an integer from 1 to 20');
+  requireThat(execution.autoEscalateToPremium === false, 'autoEscalateToPremium must be false; select premium explicitly');
+  const hosts = config.hosts ?? {};
+  requireThat(isObject(hosts) && Object.keys(hosts).length <= 16, 'hosts map (max 16 profiles)');
+  for (const [id, profile] of Object.entries(hosts)) {
+    requireThat(SLUG.test(id), 'host ID'); fields(profile, ['models', 'reasoning'], [], 'host ' + id);
+    for (const key of ['models', 'reasoning']) {
+      const map = profile[key] ?? {};
+      requireThat(isObject(map) && Object.keys(map).length <= 128, 'host ' + id + ' ' + key + ' map');
+      for (const [from, to] of Object.entries(map)) {
+        requireThat(key === 'models' ? text(from) && from.includes('/') : REASONING.includes(from), 'host mapping key');
+        requireThat(text(to) && !to.startsWith('@'), 'host mapping target must be explicit native text');
+      }
+    }
+  }
+  return config;
+}
+
+function readConfiguration(root, relative) {
+  const filename = safe(root, relative), info = stat(filename);
+  if (!info) return null;
+  requireThat(info.isFile() && info.size <= 1024 * 1024, relative + ' must be a file up to 1 MiB');
+  let config;
+  try { config = JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { throw new HarnessError('Invalid JSON in ' + relative); }
+  return validateAgentConfig(config);
+}
+export function loadAgentConfig(root) { return readConfiguration(root, AGENT_CONFIG); }
+
+export function agentDefaults(source = SOURCE, preset = 'recommended') {
+  requireThat(PRESETS.includes(preset), 'unknown preset; use recommended, economy or custom');
+  // Older alternate bundles remain usable; the packaged CLI supplies the new canonical seed.
+  const config = structuredClone(readConfiguration(source, DEFAULT_AGENTS) ?? readConfiguration(SOURCE, DEFAULT_AGENTS));
+  requireThat(config !== null, 'missing canonical default');
+  if (preset === 'economy') {
+    config.defaultModel = '@economy'; config.defaultReasoning = 'low';
+    config.execution.mode = 'single-agent'; config.execution.maxConcurrentAgents = 1;
+    for (const agent of Object.values(config.agents)) { agent.model = '@economy'; agent.reasoning = 'low'; }
+  }
+  return validateAgentConfig(config);
+}
+
+export function registeredRoles(source, capabilities = []) {
+  const roles = {};
+  const folder = path.dirname(safe(source, 'core/agents/.role-index'));
+  for (const name of fs.readdirSync(folder).filter(name => name.endsWith('.md')).sort()) {
+    roles['core:' + name.slice(0, -3)] = 'core/agents/' + name;
+  }
+  for (const id of capabilities) {
+    const metadata = readJson(safe(source, `capabilities/${id}/capability.json`));
+    for (const file of metadata.agents ?? []) {
+      const role = id + ':' + path.basename(file, '.md');
+      roles[role] = `capabilities/${id}/${file}`;
+    }
+  }
+  return roles;
+}
+
+export function resolveAgent(config, id) {
+  const agent = Object.hasOwn(config.agents, id) ? config.agents[id] : {};
+  const resolved = resolveModel(config, agent.model ?? config.defaultModel);
+  return { id, ...resolved, provider: agent.provider ?? resolved.provider,
+    reasoning: agent.reasoning ?? config.defaultReasoning, enabled: agent.enabled !== false,
+    source: Object.hasOwn(config.agents, id) ? 'role' : 'project-default' };
+}
+
+export function agentPlan(root, host) {
+  if (host !== undefined) requireThat(typeof host === 'string' && SLUG.test(host), 'host ID');
+  const config = loadAgentConfig(root);
+  const presets = [{ label: 'A', value: 'recommended', description: 'Sol, hybrid, at most two concurrent agents when supported.' },
+    { label: 'B', value: 'economy', description: 'Economy model, single-agent roles.' },
+    { label: 'C', value: 'custom', description: 'Edit provider/model/reasoning and role/host mappings explicitly.' }];
+  const note = 'Read-only declaration. No provider/model probing, native config writes, agent spawning, concurrency/token enforcement or usage tracking. Verify model access, effort and delegation in the actual host before execution.';
+  if (!config) return { status: 'not-configured', configured: false, presets, roles: [], note };
+  const lock = readJson(safe(root, '.harness/lock.json'));
+  const registry = registeredRoles(path.join(root, '.harness'), lock.capabilities ?? []);
+  const ids = [...new Set([...Object.keys(registry), ...Object.keys(config.agents)])].sort();
+  const profile = config.hosts?.[host] ?? {};
+  const roles = ids.map(id => {
+    const requested = resolveAgent(config, id);
+    const active = requested.enabled && Object.hasOwn(registry, id);
+    const mapping = profile.models?.[requested.provider + '/' + requested.model];
+    const incompatible = !mapping && ((host === 'claude-code' &&
+      (!['anthropic', 'bedrock', 'vertex'].includes(requested.provider) || requested.model.startsWith('gpt-'))) ||
+      (host === 'gemini-cli' && (!['google', 'vertex'].includes(requested.provider) || requested.model.startsWith('gpt-'))));
+    return { ...requested, active, contract: registry[id] ? '.harness/' + registry[id] : null,
+      host_model: mapping ?? requested.model, host_reasoning: profile.reasoning?.[requested.reasoning] ?? requested.reasoning,
+      mapping: mapping ? 'explicit-user-host-mapping' : 'requested',
+      availability: active && incompatible ? 'incompatible-provider' : 'unverified',
+      runtime_verified: false };
+  });
+  return { status: roles.some(role => role.active && role.availability === 'incompatible-provider') ? 'host-incompatible' : 'requires-host-verification',
+    configured: true, host: host ?? null, presets, execution: config.execution, roles,
+    missing_mappings: Object.keys(registry).filter(id => !Object.hasOwn(config.agents, id)), note };
+}