@manhd_d/ai-harness 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## Unreleased — Workflow contracts and npm-independent pip distribution
+
+- Add schema-1 spec-to-code/Product idea-to-prd JSON contracts, offline graph/role/gate validation and Markdown drift checks; clarify contract/driver/evidence ownership.
+- Add workflow validate, named readiness stages and opt-in recorded approvals; preserve legacy implement/review behavior and describe identity/semantic limitations.
+- Add a separate Claude headless conformance driver with per-case progress, optional deterministic assertions, independent judge and 3–5 trial pass rates; live hosts/human audit remain NOT_RUN until actually recorded.
+- Add zero-dependency Python launcher and PEP 517 wheel/sdist packaging from the npm shared allowlist; pip/offline install needs Node 22+ but no npm/npx.
+- Add offline wheel parity/install/update smoke, dynamic shared version checks and dual-channel release from the same reviewed tag; PyPI Trusted Publisher setup required before publication.
+- Unify six-host harness-start guidance and make README host-neutral.
+
+## Unreleased — Missing-only setup and scoped project decisions
+
+- Add setup --apply/--dry-run using the installed snapshot; preserve user answers, managed payload/lock and machine data, with validation before writes.
+- Add optional schema-1 project/module decisions, confirmed/proposed/superseded states and validated replacement history; expose decisions and reuse guidance without permanent approval claims.
+- Include shared decisions in same-project backup/freshness, omit them from transfer, and reject malformed environment config before installation writes.
+- Add compact start orientation, existing/new-project workflows, interruption/source-change scenarios and packaged clone checks. Keep one-command install → /harness-start; no new runtime dependency or distribution bump.
+- Publish a live-host validation protocol; actual Kiro activation/model behavior and token savings remain NOT_RUN until measured.
+
+## Unreleased — Session onboarding and knowledge freshness
+
+- Add Kiro init/update --host kiro, canonical native wrappers and locked SessionStart v1; first chat: /harness-start.
+- Keep Kiro questions in the current session, reuse saved facts/tasks and preserve partial setup.
+- Add structured local.md with legacy preservation, seed plan/record/check and separate source/context hashes.
+- Add skill requires diagnostics, role extensions/load order, missing-only external propose sidecars and MCP alias-only discovery.
+- Document first/later sessions, offline/upgrade and backup/transfer boundaries; live loading/token savings remain unmeasured. No distribution bump or provider calls.
+
+## Unreleased — End-user acceptance
+
+- Add Core end-user-testing skill/workflow and test-engineer/review routing to exercise real browser/device/CLI/API journeys.
+- Adaptive plans disclose surface/tool hints and missing context; preserve existing runners and actual host permissions.
+- Add optional schema-1 end-user targets/surface/journey and bounded binary attachments; mocks, unknown dependencies and wrong-interface evidence cannot verify full end-user AC.
+- Reject browser/mobile/CLI transport-only PASS; connect React/Next.js and React Native 1.4.0, evidence docs and unscored behavior cases.
+- No browser/LLM runner, installed dependency, model calls or distribution bump; actual execution remains in the authorized host.
+
+## Unreleased — Guided start and portable configuration
+
+- Add start: short terminal intake, saved task/source/output choices, read-only non-TTY plan and host handoff.
+- Add bounded configuration backup/restore, dry-run conflicts, explicit replacement and before-backup; transfer only module/model preferences with old repo autonomy removed.
+- Keep canonical user config paths, ignore local backups, preserve settings through update, and document config vs full-project recovery in all README entry points.
+- Validate archive/config/path safety before writes; add rollback/transfer/intake tests, package coverage and unscored host scenarios. No model/network calls or distribution bump.
+
 ## Unreleased — Kiro and clearer tool setup
 
 - Add Kiro to all README languages and a documented IDE/CLI/Web setup guide with optional native skill pointers.
@@ -139,6 +179,23 @@
 - Check release metadata consistency and establish single-release-PR version discipline; retain v0.6.0 until a dedicated release PR.
 
 
+## [0.15.0](https://github.com/manh0303/ai-harness/compare/v0.14.0...v0.15.0) (2026-10-14)
+
+
+### Features
+
+* add actual end-user acceptance and journey evidence ([ee99fd6](https://github.com/manh0303/ai-harness/commit/ee99fd6825d46efb20e80ccb36cdec9e7b214b05))
+* add in-session Kiro onboarding and knowledge freshness ([8f2e68b](https://github.com/manh0303/ai-harness/commit/8f2e68b0b2200437096cc69ce5e8acae5b85002b))
+* add workflow contracts and offline pip distribution ([6cde81a](https://github.com/manh0303/ai-harness/commit/6cde81a0cc1c41922cce82458fbe88cca7913edd))
+* scaffold missing setup and persist scoped project decisions ([38877c8](https://github.com/manh0303/ai-harness/commit/38877c896e94a35a6d5407d2ab662538088cfd7b))
+
+## [0.14.0](https://github.com/manh0303/ai-harness/compare/v0.13.0...v0.14.0) (2026-10-14)
+
+
+### Features
+
+* add guided start and portable user configuration ([2f18d23](https://github.com/manh0303/ai-harness/commit/2f18d23d92811858a3b722b349f423694bfcf3e2))
+
 ## [0.13.0](https://github.com/manh0303/ai-harness/compare/v0.12.0...v0.13.0) (2026-10-13)
 
 

package/README.md

@@ -10,20 +10,35 @@ Works with any project through Core workflows. Optional stack support: Spring Bo
 
 ## Quick start
 
-Install/sign in to an AI tool below. Requires Node.js 22+. Run in your **project root** terminal:
+Requires **Node.js 22+** and your AI coding tool. Run in your **project root**:
 
 ```bash
-npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness init --host codex
 ```
 
-`npx` does not install a global `aih` command. Check the installation with
-`npx --yes @manhd_d/ai-harness check`; then open the same project in your AI tool.
+Set `--host` to `codex`, `claude-code`, `cursor`, `copilot`, `gemini-cli` or `kiro`.
+In your first AI session, invoke **harness-start** if the host exposes it, or send:
 
-Then ask your AI tool:
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
 
-> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain the affected docs.
+The agent inspects the project, asks only missing questions and saves context. Kiro exposes
+`/harness-start`; native discovery varies by client. [Host guides](docs/tool-setup/README.md).
+`npx` does not create a global command; use `npx --yes @manhd_d/ai-harness check` to check integrity.
 
-Use `init --detect` for supported stack detection. Existing project instructions and custom skills are preserved; `check` checks Harness integrity. Your host executes application tests and controls tools, delegation and permissions.
+**pip / restricted networks** (included in the next reviewed release; PyPI publication requires maintainer setup):
+
+```bash
+python -m pip install manhd-ai-harness
+aih init --host codex
+```
+
+Requires Python 3.9+ **and Node.js 22+**. The wheel bundles the same JavaScript CLI and assets;
+it never calls npm or `npx`. Offline: `python -m pip install --no-index --no-deps /path/to/package.whl`.
+[Offline install & update](docs/python-installation.md) · [Settings & backup](docs/configuration-backup.md).
+
+Use `init --detect` for stack detection. Your host runs tests and controls tools, delegation and permissions.
+Harness owns workflow contracts and evidence formats; hosts or separate drivers execute them.
+[Workflow contracts](docs/workflow-contract.md) · [Conformance runner](docs/conformance-runner.md).
 
 ## Where it runs
 

package/adapters/react-native/adapter.yaml

@@ -27,5 +27,5 @@
   ],
   "verification": "checks/verification.yaml",
   "evaluation": "evals/cases.json",
-  "module_version": "1.3.0"
+  "module_version": "1.4.0"
 }

package/adapters/react-native/skills/harness-react-native-behavior-testing/SKILL.md

@@ -47,3 +47,12 @@ from Node.js component tests. Keep existing tooling and Core permission/review g
 ## Handoff
 Pass AC/test/source paths, actual failures/results, device/toolchain needs and affected platforms to
 Implementer/Reviewer. The Harness emits instructions/checklists; the authorized host runs actual tests.
+
+## End-user acceptance
+
+When affected AC requires the public UI/device journey, load Core harness-end-user-testing and
+`.harness/core/workflows/end-user-acceptance.md`. Run actual controls in the existing browser/device
+runner, assert visible and persisted outcomes, and capture redacted evidence. Use schema-1 reports
+with verification_target=end-user and the expected surface; mocks/unknown dependencies do not verify
+full acceptance. Missing browser/device/account/environment is BLOCKED. Reuse the existing framework;
+Playwright is a web option, not a forced dependency or native-device proof.

package/adapters/react-nextjs/adapter.yaml

@@ -27,5 +27,5 @@
   ],
   "verification": "checks/verification.yaml",
   "evaluation": "evals/cases.json",
-  "module_version": "1.3.0"
+  "module_version": "1.4.0"
 }

package/adapters/react-nextjs/skills/harness-react-nextjs-behavior-testing/SKILL.md

@@ -47,3 +47,12 @@ call production services or claim browser/SSR/security verification from unit te
 Pass observed failures/results, AC IDs, relevant test/source paths and blocked environment needs to
 Implementer/Reviewer. Use `.agents/skills/harness-react-nextjs-server-boundaries/SKILL.md` for direct
 authorization/cache verification when relevant; the CLI does not run these tests.
+
+## End-user acceptance
+
+When affected AC requires the public UI/device journey, load Core harness-end-user-testing and
+`.harness/core/workflows/end-user-acceptance.md`. Run actual controls in the existing browser/device
+runner, assert visible and persisted outcomes, and capture redacted evidence. Use schema-1 reports
+with verification_target=end-user and the expected surface; mocks/unknown dependencies do not verify
+full acceptance. Missing browser/device/account/environment is BLOCKED. Reuse the existing framework;
+Playwright is a web option, not a forced dependency or native-device proof.

package/bin/aih.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 import { main } from '../cli/main.js';
 
-process.exitCode = main();
+process.exitCode = await main();

package/capabilities/product/capability.json

@@ -57,7 +57,7 @@
     "templates/outcomes.md",
     "templates/techspec.md"
   ],
-  "module_version": "1.6.0",
+  "module_version": "1.7.0",
   "verification": "checks/verification.json",
   "evaluation": "evals/cases.json",
   "template_aliases": {

package/capabilities/product/workflows/idea-to-prd.md

@@ -18,3 +18,18 @@ Store project-owned generated drafts under `docs/product/`: product-brief, sourc
 
 ## Integration boundary
 After approval, UI/UX consumes PRD + requirement IDs + stories/AC; OpenSpec consumes approved stories and rules. This workflow does not invoke LLM, Jira, Confluence, Figma or git actions by itself.
+
+## Contract stages
+
+| Stage ID | Owner |
+| --- | --- |
+| `intake` | product:business-analyst |
+| `business-discovery` | product:business-analyst |
+| `brd-gate` | product:business-analyst |
+| `prd` | product:product-manager |
+| `backlog` | product:product-owner |
+| `traceability` | product:business-analyst |
+| `independent-qa` | product:requirements-reviewer |
+| `human-approval` | human:product-owner |
+
+Machine contract: idea-to-prd.workflow.json. `ready --workflow idea-to-prd` uses the installed Product contract and per-change approvals; output checks require the declared docs/product files. Configure a different driver contract for externally stored artifacts. Sign-off remains external evidence, not identity verification.

package/capabilities/product/workflows/idea-to-prd.workflow.json

@@ -0,0 +1,82 @@
+{
+  "schema_version": 1,
+  "id": "idea-to-prd",
+  "stages": [
+    {
+      "id": "intake",
+      "owner": "product:business-analyst",
+      "next": [
+        "business-discovery"
+      ]
+    },
+    {
+      "id": "business-discovery",
+      "owner": "product:business-analyst",
+      "next": [
+        "brd-gate"
+      ]
+    },
+    {
+      "id": "brd-gate",
+      "owner": "product:business-analyst",
+      "next": [
+        "prd"
+      ],
+      "approval": {
+        "role": "product-owner"
+      },
+      "on_reject": "business-discovery"
+    },
+    {
+      "id": "prd",
+      "owner": "product:product-manager",
+      "next": [
+        "backlog"
+      ],
+      "entry_gate": {
+        "approval_from": "brd-gate"
+      }
+    },
+    {
+      "id": "backlog",
+      "owner": "product:product-owner",
+      "next": [
+        "traceability"
+      ]
+    },
+    {
+      "id": "traceability",
+      "owner": "product:business-analyst",
+      "next": [
+        "independent-qa"
+      ]
+    },
+    {
+      "id": "independent-qa",
+      "owner": "product:requirements-reviewer",
+      "next": [
+        "human-approval"
+      ],
+      "outputs": [
+        "docs/product/brd.md",
+        "docs/product/prd.md",
+        "docs/product/acceptance-criteria.md",
+        "docs/product/traceability.md"
+      ]
+    },
+    {
+      "id": "human-approval",
+      "owner": "human:product-owner",
+      "next": [],
+      "entry_gate": {
+        "deterministic": [
+          "outputs-present"
+        ]
+      },
+      "approval": {
+        "role": "product-owner"
+      },
+      "on_reject": "prd"
+    }
+  ]
+}

package/cli/adapters.js

@@ -145,7 +145,7 @@ export function evaluate(root, reportPath, scope = 'adapters') {
   const bytes = encode(dataset), hash = digest(bytes);
   if (!reportPath) return { status: 'planned', scope, dataset, report: { schema_version: 1,
     metadata: { model: '', harness_commit: '', dataset_sha256: hash, bundle_sha256: lock.bundle_sha256, reviewer: '', run_id: '', parameters: '' },
-    results: dataset.cases.map(c => ({ id: c.id, scores: c.criteria.map(() => null), evidence: '' })) },
+    results: dataset.cases.map(c => ({ id: c.id, scores: c.criteria.map(() => null), ...(c.assertions ? { assertions: c.assertions.map(() => null) } : {}), evidence: '' })) },
     note: 'Unscored template; run a real model separately and record reviewer evidence. No model is invoked.' };
   const report = readJson(path.resolve(reportPath));
   requireThat(report?.metadata?.bundle_sha256 === lock.bundle_sha256, 'Evaluation report belongs to a different installed bundle');

package/cli/agents.js

@@ -54,7 +54,11 @@ export function validateAgentConfig(config) {
   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);
+    fields(agent, ['model', 'provider', 'reasoning', 'enabled', 'extensions'], [], id);
+    if (agent.extensions !== undefined) {
+      requireThat(Array.isArray(agent.extensions) && agent.extensions.length <= 16 && new Set(agent.extensions).size === agent.extensions.length, id + ' extensions');
+      for (const file of agent.extensions) requireThat(typeof file === 'string' && /^[A-Za-z0-9._/-]+[.]md$/.test(file) && !file.startsWith('/') && !file.split('/').some(p => !p || p === '.' || p === '..') && !/^\.harness\/(?:core|adapters|capabilities|templates)\//.test(file), id + ' extension path must be project-owned Markdown');
+    }
     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);
@@ -110,7 +114,11 @@ function readConfiguration(root, relative) {
   catch { throw new HarnessError('Invalid JSON in ' + relative); }
   return validateAgentConfig(config);
 }
-export function loadAgentConfig(root) { return readConfiguration(root, AGENT_CONFIG); }
+export function loadAgentConfig(root) {
+  const config = readConfiguration(root, AGENT_CONFIG);
+  for (const agent of Object.values(config?.agents ?? {})) for (const file of agent.extensions ?? []) safe(root, file);
+  return config;
+}
 
 export function agentDefaults(source = SOURCE, preset = 'recommended', host) {
   requireThat(PRESETS.includes(preset), 'unknown preset; use recommended, economy or custom');
@@ -146,7 +154,7 @@ 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,
+    extensions: agent.extensions ?? [], reasoning: agent.reasoning ?? config.defaultReasoning, enabled: agent.enabled !== false,
     source: Object.hasOwn(config.agents, id) ? 'role' : 'project-default' };
 }
 
@@ -172,13 +180,14 @@ export function agentPlan(root, host) {
     const parts = registry[id]?.split('/');
     const canonical = parts ? (parts[0] === 'core' ? 'core:' : parts[1] + ':') + path.basename(registry[id], '.md') : id;
     const skills = registry[id] ? preferredSkills(fs.readFileSync(safe(path.join(root, '.harness'), registry[id]), 'utf8')) : { required: [], optional: [] };
-    return { ...requested, active, canonical_id: canonical, skills, contract: registry[id] ? '.harness/' + registry[id] : null,
+    const extensionFiles = requested.extensions.map(file => { const info = stat(safe(root,file)); requireThat(!info || info.size <= 65536, 'extension exceeds 64 KiB'); return { path: file, status: info ? 'present' : 'missing' }; });
+    return { ...requested, extension_files: extensionFiles, contract_load_order: [registry[id] ? '.harness/' + registry[id] : null, ...requested.extensions].filter(Boolean), active, canonical_id: canonical, skills, 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',
+  return { status: roles.some(role => role.active && role.extension_files.some(f => f.status === 'missing')) ? 'blocked' : 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 };
 }

package/cli/capabilities.js

@@ -1,3 +1,4 @@
+import { skillRequirements } from './skill-requirements.js';
 import fs from 'node:fs';
 import { manifest, readJson, safe, SLUG, HarnessError, payload } from './files.js';
 import { validateContract } from './module-contract.js';
@@ -17,7 +18,7 @@ function skillMetadata(body, name) {
   for (const heading of ['## Input', '## Procedure', '## Output', '## Constraints']) {
     if (!body.includes(heading)) fail(`Missing ${heading} in skill: ${name}`);
   }
-  return { name, description };
+  return { name, description, requires: skillRequirements(body) };
 }
 
 export function loadCapability(source, id) {

package/cli/end-user.js

@@ -0,0 +1,30 @@
+// Tool selection is a host decision. This plan never runs or installs browser/device tooling.
+export function endUserPlan({ adapters, frameworks, hasStaticPage, hasApi, hasCli }) {
+  const surfaces = [];
+  if (hasStaticPage || adapters.some(id => ['react-nextjs', 'astro'].includes(id))) surfaces.push('web');
+  if (adapters.includes('react-native')) surfaces.push('mobile');
+  if (hasApi || adapters.includes('java-spring')) surfaces.push('api');
+  if (hasCli) surfaces.push('cli');
+  const tools = surfaces.map(surface => ({ surface, availability: 'unverified',
+    candidates: surface === 'web' ? frameworks.filter(x => ['@playwright/test', 'playwright', 'cypress'].includes(x)).length
+      ? frameworks.filter(x => ['@playwright/test', 'playwright', 'cypress'].includes(x)) : ['authorized host browser tool', 'Playwright if a new runner is agreed']
+      : surface === 'mobile' ? frameworks.filter(x => ['detox', 'maestro'].includes(x)).length
+        ? frameworks.filter(x => ['detox', 'maestro'].includes(x)) : ['existing device/simulator tooling; clarify missing runner']
+      : surface === 'cli' ? ['authorized host terminal and existing CLI tests'] : ['existing HTTP/API test client'],
+  }));
+  return { executed: false, status: 'planned', surface_hints: surfaces, tools,
+    workflow: '.harness/core/workflows/end-user-acceptance.md', skill: 'harness-end-user-testing', role: 'core:test-engineer',
+    required_context: ['Reviewed AC and affected user journeys/roles; inspect input sources before asking.',
+      'Actual app URL/start command or public CLI/API entry; reachable test environment and test-account references.',
+      'Existing runner or available host tools, isolated fixtures and permitted mutations/cleanup.',
+      'Real vs mocked dependencies, tested revision and configured evidence/output destination.'],
+    completion_gate: ['Exercise the actual user-facing interface for applicable AC, including relevant failure/role/state paths.',
+      'Record observed user outcomes with requirement-linked JSON assertions and redacted screenshot/trace/video receipts where applicable.',
+      'For full acceptance use verification_target=end-user and a matching real/not-applicable dependency journey; mocks/unknown dependencies cannot verify that target.',
+      'Unavailable browser/device/account/service is BLOCKED; a deliberate skip is NOT_RUN; never replace UI proof with API/build/unit proof.',
+      'Browser/device/CLI/API automation does not establish business-owner UAT approval or actual model compliance.'],
+    host_prompt: 'Read AGENTS.md, the end-user-acceptance workflow and harness-end-user-testing. Inspect approved requirements, app entry points, existing test configuration and actual host tools. '
+      + 'Reuse established answers; ask only missing consequential environment/account/fixture decisions. Run affected user journeys through the real interface, assert visible and persisted outcomes, '
+      + 'classify real/mocked dependencies and save redacted evidence using the existing verification report. Mark required missing access BLOCKED; report gaps before completion.',
+    note: 'Surface hints are metadata only. Requirements choose actual journeys; no generic login/CRUD/browser suite is forced on every project.' };
+}

package/cli/environment.js

@@ -5,6 +5,7 @@ import { agentPlan } from './agents.js';
 import { readConfig } from './project-config.js';
 export { readConfig } from './project-config.js';
 import { artifactReport } from './artifacts.js';
+import { projectDecisionReport } from './project-decisions.js';
 
 export const ENVIRONMENT = '.harness/environment.json';
 export const MACHINE = '.harness/machine.json';
@@ -155,6 +156,7 @@ export function setupPlan(root, adapters, env = process.env, host) {
   });
   questions.push(...artifacts.questions);
   return { status: environment.problems.length ? 'blocked' : 'planned', environment, artifacts, questions,
+    project_decisions: projectDecisionReport(root),
     agent_configuration: agentPlan(root, host),
     next_steps: ['Read AGENTS.md, .harness/local.md and the installed project-setup workflow.',
       'Apply installed Core project-conventions.md and relevant adapter conventions; establish mode per affected module even when no setup questions are suggested.',

package/cli/evaluation-contract.js

@@ -30,10 +30,20 @@ export function casesFrom(source, relative) {
     && doc.cases.length > 0, `Invalid evaluation: ${relative}`);
   const ids = new Set();
   for (const c of doc.cases) {
-    requireThat(exact(c, ['id', 'prompt', 'criteria', 'critical'])
+    requireThat(c && Object.keys(c).every(k => ['id', 'prompt', 'criteria', 'critical', 'assertions'].includes(k)) && ['id', 'prompt', 'criteria', 'critical'].every(k => Object.hasOwn(c, k))
       && typeof c.id === 'string' && SLUG.test(c.id) && !ids.has(c.id)
       && text(c.prompt) && Array.isArray(c.criteria) && c.criteria.length > 0 && c.criteria.every(text)
       && typeof c.critical === 'boolean', `Invalid eval case: ${relative}`);
+    if (c.assertions !== undefined) {
+      requireThat(Array.isArray(c.assertions) && c.assertions.length <= 32, `Invalid assertions: ${relative}`);
+      const assertionIds = new Set();
+      for (const a of c.assertions) {
+        requireThat(exact(a, ['id', 'type', 'target', 'value']) && typeof a.id === 'string' && SLUG.test(a.id)
+          && !assertionIds.has(a.id) && ['contains', 'not-contains'].includes(a.type)
+          && ['transcript', 'tool-inputs'].includes(a.target) && text(a.value) && a.value.length <= 4096, `Invalid assertion: ${relative}`);
+        assertionIds.add(a.id);
+      }
+    }
     ids.add(c.id);
   }
   return doc.cases;

package/cli/files.js

@@ -67,8 +67,13 @@ export function assertSeparate(root, source) {
   };
   // npm local installs intentionally place the package in the consumer's node_modules.
   const localPackage = path.relative(root, source).split(path.sep)[0] === 'node_modules';
-  if (inside(source, root) || (inside(root, source) && !localPackage)) {
-    throw new HarnessError('Source and target must not overlap, except a source installed in node_modules');
+  const relativeParts = path.relative(root, source).split(path.sep);
+  const pythonPackage = relativeParts[0] === '.venv' && relativeParts.includes('site-packages')
+    && relativeParts.slice(-2).join('/') === 'ai_harness/_bundle'
+    && stat(path.join(source, '_python_distribution.json'))?.isFile()
+    && readJson(path.join(source, '_python_distribution.json')).name === 'manhd-ai-harness';
+  if (inside(source, root) || (inside(root, source) && !localPackage && !pythonPackage)) {
+    throw new HarnessError('Source and target must not overlap, except a package installed in node_modules or .venv site-packages');
   }
 }
 

package/cli/harness.js

@@ -1,8 +1,13 @@
 import fs from 'node:fs';
+import { localContext } from './knowledge.js';
+import { kiroPayload, KIRO_HOOK } from './kiro.js';
+import { requirementReport } from './skill-requirements.js';
+import { loadStartConfig } from './start-config.js';
+import { PROJECT_DECISIONS, emptyProjectDecisions, loadProjectDecisions, projectDecisionReport } from './project-decisions.js';
 import { checkpointPath, validateCheckpoint } from './checkpoint.js';
 import { readConfig } from './project-config.js';
 import { claudeReport, claudeBlock, linkClaude } from './claude.js';
-import { emptyEnvironment, environmentReport } from './environment.js';
+import { emptyEnvironment, environmentReport, loadEnvironment } from './environment.js';
 import { AGENT_CONFIG, agentDefaults, loadAgentConfig } from './agents.js';
 import { reviewVerification, techspecEvidence } from './verification-report.js';
 import { ARTIFACTS, INTEGRATIONS, emptyArtifacts, emptyIntegrations, loadArtifactContract, artifactReport, docRoute } from './artifacts.js';
@@ -14,7 +19,7 @@ import { resolveModules } from './composition.js';
 import { safe, readJson, manifest, encode, digest, stat, block, mergeAgents, payload, validateAdapters, validateCapabilities, assertSeparate, HarnessError, LOCK, CONFIG, VERSION, SLUG, isObject } from './files.js';
 export * from './files.js';
 
-function projectConfig(root, adapters, capabilities, required = false) {
+export function projectConfig(root, adapters, capabilities, required = false) {
   const filename = safe(root, CONFIG);
   if (required && !stat(filename)) throw new HarnessError(`Missing ${CONFIG}; restore it from Git`);
   const config = stat(filename) ? readJson(filename) : { schema_version: 1, adapters: adapters ?? [], capabilities: capabilities ?? [] };
@@ -94,7 +99,7 @@ export function bundle(source, config) {
 }
 
 function managedName(name) {
-  return name === 'AGENTS.md' || name === 'CLAUDE.md' || ['.harness/core/', '.harness/adapters/', '.harness/capabilities/', '.harness/integrations/', '.harness/templates/', '.agents/skills/harness-', '.claude/skills/harness-'].some(prefix => name.startsWith(prefix));
+  return name === 'AGENTS.md' || name === 'CLAUDE.md' || name === KIRO_HOOK || ['.harness/core/', '.harness/adapters/', '.harness/capabilities/', '.harness/integrations/', '.harness/templates/', '.agents/skills/harness-', '.claude/skills/harness-', '.kiro/skills/harness-'].some(prefix => name.startsWith(prefix));
 }
 
 export function loadLock(root) {
@@ -120,7 +125,7 @@ function drift(root, lock) {
   }).map(([name]) => name);
 }
 
-function guard(root, operation) {
+export function guard(root, operation) {
   const filename = safe(root, '.harness-install.lock');
   let fd;
   try { fd = fs.openSync(filename, 'wx', 0o600); }
@@ -132,12 +137,24 @@ function guard(root, operation) {
   finally { fs.closeSync(fd); fs.unlinkSync(filename); }
 }
 
-export function atomicWrite(filename, data) {
+export function snapshotCheck(root) {
+  const lock = loadLock(root), problems = drift(root, lock);
+  return { status: problems.length ? 'error' : 'ok', version: lock.version, problems };
+}
+
+export function userIgnoreChanges(root) {
+  const name = '.harness/.gitignore', filename = safe(root, name);
+  const data = stat(filename) ? fs.readFileSync(filename, 'utf8') : '';
+  return data.trimEnd().split(/\r?\n/).slice(-2).join('\n') === '/backups/\n/machine.json' ? {}
+    : { [name]: Buffer.from(data + (data && !data.endsWith('\n') ? '\n' : '') + '/backups/\n/machine.json\n') };
+}
+
+export function atomicWrite(filename, data, mode = 0o644) {
   fs.mkdirSync(path.dirname(filename), { recursive: true });
   const tmp = path.join(path.dirname(filename), `.harness-tmp-${randomUUID()}`);
   try {
     fs.writeFileSync(tmp, data, { flag: 'wx', mode: 0o600 });
-    fs.chmodSync(tmp, stat(filename) ? fs.statSync(filename).mode & 0o777 : 0o644);
+    fs.chmodSync(tmp, stat(filename) ? fs.statSync(filename).mode & 0o777 : mode);
     fs.renameSync(tmp, filename);
   } finally { fs.rmSync(tmp, { force: true }); }
 }
@@ -172,6 +189,10 @@ export function install(root, source, { command = 'init', adapters, capabilities
     if (command === 'update' && !hasLock) throw new HarnessError('Not installed; run init first');
     const old = hasLock ? loadLock(root) : null;
     const existingAgents = loadAgentConfig(root);
+    loadStartConfig(root);
+    loadProjectDecisions(root);
+    loadEnvironment(root);
+    localContext(root);
     loadArtifactContract(root); // Validate project-owned declarations before planning any writes.
     if (agentPreset !== undefined && command !== 'init') throw new HarnessError('Agent preset is supported only by init');
     if (agentPreset !== undefined && existingAgents) throw new HarnessError('agents.json is project-owned; edit it explicitly instead of applying an init preset');
@@ -194,6 +215,9 @@ export function install(root, source, { command = 'init', adapters, capabilities
         lock.files[destination] = digest(files[destination]);
       }
     }
+    if (host === 'kiro' || Object.keys(old?.files ?? {}).some(p => p.startsWith('.kiro/skills/harness-'))) {
+      for (const [name, data] of Object.entries(kiroPayload(files))) { files[name] = data; lock.files[name] = digest(data); }
+    }
     lock.files = Object.fromEntries(Object.entries(lock.files).sort(([a],[b]) => a.localeCompare(b)));
     lock.bundle_sha256 = digest(encode(lock.files));
     if (old) {
@@ -221,18 +245,15 @@ export function install(root, source, { command = 'init', adapters, capabilities
       [CONFIG]: encode(config),
       [ARTIFACTS]: encode(emptyArtifacts()),
       [INTEGRATIONS]: encode(emptyIntegrations()),
+      [PROJECT_DECISIONS]: encode(emptyProjectDecisions()),
       '.harness/environment.json': encode(emptyEnvironment()),
       'openspec/config.yaml': fs.readFileSync(safe(source, 'templates/openspec/config.yaml')),
-      '.harness/local.md': Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here. Never weaken security boundaries.\n\n## Stack\nstack: unknown\nRecord actual dependency versions and approved design sources. This field does not select technology.\n\n## Development conventions\nRecord scope/mode (new, maintain or mixed), authoritative source paths, module boundaries, reusable public APIs, naming/error/test conventions and configured checks. Link existing guides instead of duplicating them. Unknowns are not approved defaults; the AI host inspects evidence and asks only consequential questions.\n'),
+      '.harness/local.md': stat(safe(source, 'templates/local.md')) ? fs.readFileSync(safe(source, 'templates/local.md')) : Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here.\n'),
     };
     for (const [name, data] of Object.entries(seeds)) if (!stat(safe(root, name))) changes[name] = data;
     // Project-owned ignore file: preserve all prior rules, place our anchored rule last.
     // This does not remove an already tracked machine file from the Git index.
-    const ignoreName = '.harness/.gitignore', ignorePath = safe(root, ignoreName);
-    const ignore = stat(ignorePath) ? fs.readFileSync(ignorePath, 'utf8') : '';
-    if (ignore.trimEnd().split(/\r?\n/).at(-1) !== '/machine.json') {
-      changes[ignoreName] = Buffer.from(ignore + (ignore && !ignore.endsWith('\n') ? '\n' : '') + '/machine.json\n');
-    }
+    Object.assign(changes, userIgnoreChanges(root));
     const newLock = encode(lock);
     if (!hasLock || !fs.readFileSync(safe(root, LOCK)).equals(newLock)) changes[LOCK] = newLock;
     const plan = Object.entries(changes).map(([name, data]) => ({ path: name, action: data === null ? 'delete' : 'write' }));
@@ -245,12 +266,33 @@ export function check(root) {
   const lock = loadLock(root), config = projectConfig(root, undefined, undefined, true);
   const problems = drift(root, lock);
   loadArtifactContract(root);
+  loadStartConfig(root);
+  loadProjectDecisions(root);
+  localContext(root);
   loadAgentConfig(root); // Optional on legacy installs; validate user config without managing its bytes.
   if (JSON.stringify([...config.adapters].sort()) !== JSON.stringify([...lock.adapters].sort())) problems.push(`${CONFIG}: adapter selection changed; run update`);
   if (JSON.stringify([...(config.capabilities ?? [])].sort()) !== JSON.stringify([...(lock.capabilities ?? [])].sort())) problems.push(`${CONFIG}: capability selection changed; run update`);
   return { status: problems.length ? 'error' : 'ok', version: lock.version, problems };
 }
 
+export function changeSidecars(root, name) {
+  if (!SLUG.test(name) || name === 'archive') throw new HarnessError('Invalid change ID');
+  return guard(root, () => {
+    if (check(root).status !== 'ok') throw new HarnessError('Fix installation drift before creating sidecars');
+    const base = 'openspec/changes/' + name;
+    if (!stat(safe(root, base + '/proposal.md'))) throw new HarnessError('Sidecars require an existing proposal.md');
+    const lock = loadLock(root), changes = {};
+    for (const file of ['.openspec.yaml', 'decisions.json', 'verification.json', 'artifact-impact.json']) {
+      const template = '.harness/templates/openspec/' + file;
+      if (!Object.hasOwn(lock.files, template)) throw new HarnessError('Update Harness to install sidecar templates');
+      const destination = base + '/' + file;
+      if (!stat(safe(root,destination))) changes[destination] = Buffer.from(fs.readFileSync(safe(root,template),'utf8').replaceAll('{{change_id}}',name));
+    }
+    transaction(root, changes);
+    return { status: 'ok', change: name, created: Object.keys(changes), note: 'Draft sidecars only; existing files preserved.' };
+  });
+}
+
 export function newChange(root, name) {
   if (!SLUG.test(name) || name === 'archive') throw new HarnessError('Change ID must be a lowercase hyphenated slug, excluding archive');
   return guard(root, () => {
@@ -317,7 +359,7 @@ export function newDoc(root, name, capability = 'product', options = {}) {
   });
 }
 
-export function doctor(root) {
+export function doctor(root, skill) {
   const extensions = process.platform === 'win32' ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
   const tools = {};
   for (const name of ['git', 'node', 'npm', 'java', 'mvn', 'openspec']) {
@@ -327,8 +369,11 @@ export function doctor(root) {
     }));
   }
   const state = check(root), environment = environmentReport(root);
-  return { ...state, status: state.status !== 'ok' || environment.problems.length ? 'error' : 'ok',
-    tools, environment, claude: claudeReport(root), artifacts: artifactReport(root), note: 'Tool presence only; no commands executed or compatibility claim made. Configured project tools take precedence over generic PATH hints.' };
+  const prerequisites = skill ? requirementReport(root, skill) : null;
+  return { ...state, status: state.status !== 'ok' || environment.problems.length || prerequisites?.status === 'blocked' ? 'error' : 'ok',
+    prerequisites, tools, environment, decisions: projectDecisionReport(root),
+    context: { structured: localContext(root).structured, warnings: localContext(root).structured ? [] : ['Legacy prose is valid; use harness-start to add source-linked structured context when needed.'] },
+    claude: claudeReport(root), artifacts: artifactReport(root), note: 'Tool presence only; no commands executed or compatibility claim made. Configured project tools take precedence over generic PATH hints.' };
 }
 
 export function saveCheckpoint(root, id, report, expected) {