v0.3.7

Chat Harness v0.3.7

This patch release adds a safe fallback path for canonical file replacement while preserving the existing, proven persistence instructions.

Changed

Safe fallback file replacement

Chat Harness continues to prefer normal in-place replacement because it preserves provider file identity and history where supported.

If an authorized in-place replacement fails after a normal retry, and the provider supports the required create/read/rename/delete primitives, the Project Instructions now allow a bounded copy-on-write fallback:

1. create and verify a complete temporary candidate;
2. re-read the canonical file to detect concurrent changes;
3. rename the canonical file to a unique backup;
4. promote the candidate;
5. re-read and verify the new canonical file;
6. delete the backup only after successful verification.

The last known-good copy is never deleted before the promoted replacement is verified. If promotion or final verification fails, the backup is restored when possible and the operation is reported as a persistence failure.

Existing persistence behavior preserved

The existing Markdown/YAML/MIME/readback persistence instructions are unchanged. The fallback was appended after that block rather than rewriting or compressing it.

Regression coverage now locks the original persistence block unchanged and verifies that the fallback appears after it.

Artifact-type scope

The fallback applies to canonical files/artifacts generally. Raw Markdown remains the primary Chat Harness durable format, but non-Markdown artifacts retain their own expected type/format verification.

Project Instructions size guardrail

The Project Instructions engineering ceiling is now aligned with ChatGPT's 8,000-character limit. The canonical template remains below that ceiling.

Compatibility

No Workstream schema, Workbench taxonomy, Source Policy version, or specialist Workspace contract changed in v0.3.7.

Existing v0.3.6 Workspaces should run:

chat-harness update
chat-harness setup
chat-harness validate
chat-harness doctor

For a recognized Chat-Harness-managed AGENTS.md, normal setup refreshes that file to the v0.3.7 generic instructions.

Normal setup does not replace an existing .chat-harness/WORKSPACE.md unless --replace-workspace is explicitly supplied.

For ChatGPT Projects, after refreshing the Workspace, copy the complete updated AGENTS.md into Project Instructions.

v0.3.6

Chat Harness v0.3.6

This patch release hardens hosted Workspace state handling based on real brownfield ChatGPT smoke tests.

Changed

More precise Workstream ownership

Chat Harness now reuses an existing Workstream only when the request advances the same objective.

Related domain, strategy, client, or subject matter alone is not enough. Related work should split when it develops a distinct objective and independently resumable Next action.

Before substantive handoff, the harness also re-checks ownership so a subtopic that became independent during execution can be split and its Workbench artifacts repointed to the correct Workstream.

Freshness-aware source selection

When current Workspace or control-plane state matters, fresh authorized live reads now take precedence over cached or indexed copies when both can access the same underlying source.

Cached/indexed sources remain useful for discovery, but should not be treated as freshness authority when a live connector/app can retrieve current state.

ChatGPT host documentation now explicitly distinguishes:

• Google Drive content attached as a Project source, whose indexed state may lag until refreshed;
• live Google Drive connector/app reads that can retrieve current Drive content on demand.

Canonical temp-file discipline

.chat-harness/temp/ is now explicitly staging-only.

Temporary files may support safe remote writes, but user-facing references must resolve to the verified canonical Workstream, Workbench artifact, or domain file. Temp staging files must not be cited or presented as authoritative.

Regression coverage

Four behavioral regression scenarios were added:

• related-objective Workstream splitting;
• mid-flight Workstream splitting;
• temp staging not leaking as canonical;
• live-source freshness winning over stale indexed state.

The live-source freshness scenario remains a real-host behavioral contract: deterministic repository validation can preserve the expectation, but cannot reproduce hosted indexing freshness by itself.

Compatibility

No schema, Workstream frontmatter, Workbench taxonomy, Source Policy version, or specialist Workspace contract changed in v0.3.6.

Existing v0.3.5 Workspaces should run:

chat-harness update
chat-harness setup
chat-harness validate
chat-harness doctor

For a recognized Chat-Harness-managed AGENTS.md, normal setup refreshes that file to the v0.3.6 generic instructions.

Normal setup does not replace an existing .chat-harness/WORKSPACE.md unless --replace-workspace is explicitly supplied.

After updating a ChatGPT-hosted Workspace, copy the complete refreshed AGENTS.md into Project Instructions and refresh/sync the Project source before rerunning host regression checks.

Prompt/context guardrails

• Canonical AGENTS.md remains under the project's 7,000-character engineering budget.
• Specialist Workspace seeds are unchanged.
• Semantic Workstream ownership remains a host/model behavioral contract rather than a heuristic deterministic CLI validator.
• Source Policy v1 remains focused on privacy/source handling; freshness is not added to the schema in this release.

v0.3.5

Chat Harness v0.3.5

This release improves brownfield adoption and reduces mandatory instruction-loading overhead without changing the validated Workstream/Workbench persistence lifecycle.

Changed

Simpler context-loading path

Chat Harness now uses a smaller mandatory instruction path:

AGENTS.md
  -> .chat-harness/WORKSPACE.md
  -> matching Workstream for Work
  -> additional Procedures and authoritative context only as needed

Requests are classified as Answer-only or Work from AGENTS.md first. After classification, WORKSPACE.md is loaded before domain reasoning or responding for both classes. Answer-only requests remain lightweight and do not create durable Work state unless the request itself requires it.

The previous mandatory .chat-harness/README.md Workspace Map layer has been removed from the core scaffold and runtime contract.

Brownfield setup safety

chat-harness setup now detects an existing root PROJECT_INSTRUCTIONS.md and preserves it unchanged.

When legacy project instructions are present, setup reports host activation as migration required and does not tell the user to replace hosted Project Instructions immediately. This creates a safe review window to migrate still-needed Workspace-specific behavior into .chat-harness/WORKSPACE.md before activating the Chat Harness host binding.

Setup still does not move, rename, merge, or semantically reorganize unrelated domain content.

Specialist seeds

The built-in specialist seeds remain deliberately compact. A small number of high-leverage domain invariants were added:

• Tech — separate model capability from harness/tools/context/evaluation configuration.
• Career — keep factual truth, positioning, and public-use approval distinct.
• Tax — historical records establish historical facts, not current law.
• Finance — separate investment return from cashflows, fees, tax, insurance, and timing effects before comparison.
• Shopping — verify exact variant/channel and separate dependable economics from uncertain promotional upside.

Detailed domain methodology should continue to live in Workspace-specific Guides, Playbooks, Procedures, repositories, or other canonical sources and be retrieved only when relevant.

Compatibility

The Workstream/Workbench taxonomy, Markdown contracts, checkpoint semantics, same-purpose artifact reuse, and canonical Workstream reconciliation behavior are unchanged from v0.3.4.

Existing v0.3.4 Workspaces should run:

chat-harness update
chat-harness setup
chat-harness validate

setup refreshes the managed AGENTS.md to the new startup contract. An existing .chat-harness/README.md from an older Workspace is no longer managed or required; it may remain as user-owned content until you choose to remove it.

For existing non-Chat-Harness projects with PROJECT_INSTRUCTIONS.md, run normal chat-harness setup. The CLI will preserve those instructions and explicitly tell you that host activation is pending Workspace-specific migration review.

Prompt/context guardrails

• Canonical AGENTS.md remains under the project's 7,000-character engineering budget.
• Specialist seeds are regression-tested to remain compact.
• New behavioral evals cover Answer-only Workspace invariants and brownfield host-activation safety.

v0.3.4

Chat Harness v0.3.4

This patch release fixes Workbench-to-Workstream backlink validation discovered during a clean v0.3.3 ChatGPT Research Workspace test.

Fixed

ChatGPT naturally persisted Workbench ownership links as Workspace-relative paths:

workstream: .chat-harness/workstreams/2026-09-28-home-dev-backup-disaster-recovery.md

The validator previously accepted only artifact-relative paths such as:

workstream: ../../workstreams/2026-09-28-home-dev-backup-disaster-recovery.md

Both forms point to the same canonical Workstream, but the first incorrectly failed with workbench.workstream_invalid.

v0.3.4 now:

• accepts canonical Workspace-relative .chat-harness/workstreams/....md backlinks;
• keeps the existing artifact-relative ../../workstreams/... form backward compatible;
• still rejects references that escape .chat-harness/workstreams/;
• updates published Workbench templates to prefer Workspace-relative backlinks.

Prompt budget

No new always-on agent instructions were added. This is intentionally a deterministic validator/template fix rather than another rule in AGENTS.md.

Upgrade

chat-harness update
chat-harness --version
chat-harness validate

Existing v0.3.3 Workspaces do not need chat-harness setup for this patch because the managed Project Instructions are unchanged.

v0.3.3

Chat Harness v0.3.3

This patch release hardens durable-state reconciliation after a real ChatGPT Research Workspace test exposed stale Workstream state across turns.

Improved

• Reconcile the owning canonical Workstream after material Workbench or state changes.
• Treat a checkpoint as complete only after the canonical Workstream reflects the latest durable state and has been re-read successfully.
• Prefer updating an existing same-purpose Workbench artifact instead of creating parallel near-duplicates.
• Classify artifacts by their primary durable purpose; experiment and benchmark protocols are plans, while their results remain research.
• Require exactly one H1 matching frontmatter title for Workstreams and Workbench artifacts.
• Keep the portable AGENTS.md high-signal: the new persistence rules were added while reducing the instruction file below a stricter 7,000-character budget.

Validation and evals

• Workstream and Workbench validators now enforce H1/title agreement.
• Validation tests cover the title-heading contract.
• The behavioral eval catalog now includes a multi-turn plan-reconciliation regression scenario derived from the real-host local-AI test.
• Architecture and concepts documentation now define canonical checkpoint completion explicitly.

Why this matters

A previous real-host run successfully created Idea, Research, Decision, and Plan artifacts, but left the canonical Workstream stale and later created a second plan-like artifact under Research. v0.3.3 tightens the contract around the authoritative resume point without adding a larger always-on prompt.

Upgrade

For a standalone installation:

chat-harness update
chat-harness --version

For an npm-managed installation:

npm install -g chat-harness@latest
chat-harness --version

After upgrading, rerun chat-harness setup inside each Workspace to refresh the managed AGENTS.md, then copy the complete refreshed AGENTS.md into the ChatGPT Project Instructions.

v0.3.2

Chat Harness v0.3.2

This patch release fixes npm-managed update checks on npm 12.

Fixed

Chat Harness v0.3.1 queried npm with:

npm view chat-harness@latest version --json

npm 12 returns a one-element JSON array for this scalar field, for example:

[
  "0.3.1"
]

v0.3.1 expected a JSON string and incorrectly reported:

lifecycle.update_failed npm returned an invalid latest version

v0.3.2 now queries the single version field using npm's plain scalar output and validates that value directly.

Scope

This is a narrow compatibility fix.

It does not change:

• installation provenance detection;
• standalone update behavior or SHA-256 verification;
• npm update mutation behavior;
• uninstall behavior;
• Windows lifecycle handling;
• Workspace setup, validation, migration, or data-safety boundaries.

Upgrade

If you are on v0.3.1 with an npm-managed installation, upgrade once with:

npm install -g chat-harness@latest
chat-harness --version

After v0.3.2 is installed, the normal lifecycle commands work again:

chat-harness update --check
chat-harness update

v0.3.1

Chat Harness v0.3.1

This patch release adds first-class lifecycle management for the Chat Harness CLI itself.

It does not change the v0.3 Workspace persistence contract. Software update, Workspace setup, Workspace migration, and uninstall remain separate authority boundaries.

First-class CLI updates

Chat Harness can now manage updates through a single channel-aware command:

chat-harness update --check
chat-harness update

• detects standalone release binaries, global npm installations, local development builds, and unknown/custom installations;
• reports the current version, latest version, installation channel, and executable path;
• exits successfully without mutation when already current;
• keeps update --check read-only, including when PATH ambiguity is detected;
• refuses mutation when installation provenance or PATH ownership is ambiguous.

For standalone binaries, updates:

• select the exact GitHub Release asset for the running OS and architecture;
• download the matching SHA-256 sidecar;
• verify the checksum before replacement;
• verify the staged binary reports the expected release version;
• replace transactionally on macOS/Linux with rollback if post-replacement verification fails.

For global npm installations, Chat Harness delegates ownership back to npm with:

npm install -g chat-harness@latest

and verifies the resulting installed package version.

Safe uninstall

The new uninstall command removes Chat Harness software without coupling package removal to user data:

chat-harness uninstall
chat-harness uninstall --yes

Interactive use asks for confirmation. Non-interactive and JSON use require --yes.

Uninstall removes only the detected Chat Harness CLI/package and adjacent Chat-Harness-owned installation metadata. It never deletes or modifies Workspace/project data such as:

AGENTS.md
.chat-harness/
_inbox/
Workstreams
Workbench artifacts
domain/project files
Google Drive Workspace content

There is deliberately no --purge-workspaces option.

Installation provenance

New standalone and local-development installs write a narrow install-adjacent .chat-harness-install.json sidecar containing only the installation channel.

Existing pre-metadata standalone installs remain recognized at the documented default location:

~/.local/bin/chat-harness
~/.local/bin/chat-harness.exe

Stable compiled binaries in other custom locations without provenance metadata fail closed rather than guessing ownership.

Local development builds remain identifiable by their injected <package-version>-<git-sha>[-dirty] version and are never silently replaced by a published release.

Windows lifecycle handling

Windows update and uninstall do not try to overwrite or delete the currently running executable.

Instead, Chat Harness stages and verifies the requested operation, copies itself to a narrowly scoped temporary helper, exits, and lets that helper perform replacement or removal after the parent process has stopped.

The helper validates its target, staging, backup, metadata, job, and helper paths and is not a generic deferred file-operation mechanism.

Automation and qualification

Lifecycle commands support the same machine-readable --json envelope model as the rest of the CLI.

The release includes deterministic coverage for:

• release lookup and network failure;
• checksum mismatch;
• unsupported OS/architecture;
• unwritable installation paths;
• PATH ambiguity;
• unavailable/failing npm;
• candidate and post-replacement version verification;
• POSIX rollback;
• Windows parent-process locking and rollback;
• unknown/custom installation refusal;
• development-build safety;
• uninstall Workspace-data boundaries.

Windows lifecycle behavior is also exercised in CI with a Windows x64 standalone build.

Workspace compatibility

v0.3.1 does not migrate or rewrite Workspace state.

The boundaries remain:

update      = update Chat Harness software
migrate     = transform an existing Workspace contract/schema (future)
setup       = create/reconcile managed Workspace scaffold
uninstall   = remove installed Chat Harness software

Existing v0.3.0 Workspaces require no lifecycle-specific migration.

Upgrade from v0.3.0

Because chat-harness update is introduced by this release, upgrade from v0.3.0 once using the installation channel you already have.

npm:

npm install -g chat-harness@latest
chat-harness --version

Standalone macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/carlosboeing/chat-harness/main/install.sh | sh
chat-harness --version

Standalone Windows:

irm https://raw.githubusercontent.com/carlosboeing/chat-harness/main/install.ps1 | iex
chat-harness --version

After v0.3.1 is installed, future managed updates can use:

chat-harness update --check
chat-harness update

v0.3.0

Chat Harness v0.3.0

This release makes durable project persistence explicit, proactive, and mechanically validated.

It is a deliberate Workspace-contract change from v0.2: agents should now persist Work early and consistently instead of relying on vague judgements such as “substantial” or “qualifying”.

Deterministic Work persistence

• classifies each request as Answer-only or Work;
• keeps direct, disposable lookups Answer-only while still allowing minimal source retrieval when needed;
• biases ambiguity toward Work so resumable state is created rather than reconstructed later;
• requires Workstreams to be created or resumed before extended research, tool use, or multi-step execution;
• requires agents to save/checkpoint proactively instead of waiting for the user to ask.

Workbench lifecycle

The Workbench taxonomy is now purpose-driven:

• 0-ideas/ — frame new open-ended objectives;
• 1-research/ — establish evidence for unresolved questions;
• 2-decisions/ — turn evidence, constraints, and tradeoffs into direction;
• 3-plans/ — make a chosen direction executable;
• 4-reviews/ — evaluate an existing artifact, implementation, plan, or outcome.

2-analysis/ has been renamed to 2-decisions/ because “analysis” was too broad to define a durable artifact reliably.

The categories are trigger-based artifact classes, not a required waterfall.

Markdown and frontmatter contract

Workstreams and textual Workbench artifacts now have a hard storage contract:

• raw .md files only;
• valid YAML frontmatter is mandatory;
• Workstream fields and status values are schema-validated;
• Workbench type must match its folder;
• Workbench status values are draft, approved, completed, or superseded;
• approved requires explicit authorized approval and is never inferred from silence;
• Workbench artifacts must reference their owning Workstream;
• superseded artifacts must reference their replacement;
• created/updated dates and active Workstream Next actions are validated.

For remote storage, Chat Harness instructions explicitly require Markdown (text/markdown) and prohibit silently substituting a native Google Doc or provider-native document when Markdown was required.

Validation and templates

• adds a Workbench frontmatter JSON schema and validator;
• strengthens Workstream validation;
• rejects non-Markdown files in Workstream/Workbench control state;
• adds canonical templates for idea, research, decision, plan, and review artifacts;
• enforces a 7,500-character CI ceiling for the canonical AGENTS.md Project Instructions;
• expands behavioural evals for Answer-only, proactive persistence, lifecycle routing, Markdown/frontmatter, and persistence-failure handling.

Breaking upgrade note

Existing v0.2 Workspaces are not automatically migrated.

After upgrading, review existing Workspace state before relying on chat-harness validate:

• rename existing .chat-harness/workbench/2-analysis/ to 2-decisions/;
• update existing Workstream frontmatter to include type, title, status, created, and updated;
• add required YAML frontmatter and an owning workstream reference to existing textual Workbench artifacts;
• rerun chat-harness setup to refresh recognized managed AGENTS.md files;
• rerun chat-harness validate and reconcile any remaining findings.

Chat Harness does not invent Workbench ownership during upgrade when it cannot be inferred safely.

Upgrade

npm:

npm install -g chat-harness@latest
chat-harness --version

Standalone installer:

curl -fsSL https://raw.githubusercontent.com/carlosboeing/chat-harness/main/install.sh | sh

v0.2.2

Chat Harness v0.2.2

This patch release polishes the interactive setup wizard after live testing of v0.2.1.

Setup wizard presentation

• adds a highlighted Important callout for ChatGPT users during first-time setup;
• uses clearer Google Drive guidance: make sure the Workspace is a Google Drive folder before continuing;
• explains that ChatGPT connects to that folder so it can keep using the latest Workspace files over time;
• keeps the Google Drive guidance scoped to ChatGPT rather than implying it is a universal Chat Harness requirement.

Consistent terminal UI

• renders setup information using Clack UI primitives instead of mixing prompts with raw stdout blocks;
• keeps the introduction, Workspace identity, optional-folder guidance, review, completion, and next steps in one visual language;
• simplifies the already-present optional-folder case, such as Trips/, without repeating explanatory copy unnecessarily.

Workspace tree readability

• keeps the full Workspace tree and deterministic ordering introduced in v0.2.1;
• suppresses repeated child status labels when the parent already communicates the same state;
• preserves meaningful mixed-state labels such as already there and updated.

Scope

This release is presentation-only. It does not add storage-provider detection, new setup decisions, provider abstractions, or changes to the Workspace contract.

Upgrade

npm:

npm install -g chat-harness@latest
chat-harness --version

Standalone installer:

curl -fsSL https://raw.githubusercontent.com/carlosboeing/chat-harness/main/install.sh | sh

v0.2.1

Chat Harness v0.2.1

This patch release focuses on setup usability, local development workflow, and distribution reliability.

Guided setup

• adds a clearer first-run setup introduction and distinguishes first-time setup from reruns;
• asks what the Workspace is mainly for using plain-language purpose labels instead of leading with specialist terminology;
• explains optional organizational folders before asking whether to create them;
• shows whether suggested folders are new or already present;
• keeps existing optional folders visible in the final review instead of omitting them when no filesystem operation is needed;
• renders the complete resulting Workspace tree before setup with deterministic, user-friendly ordering;
• replaces implementation-oriented prompts and receipts with a friendlier confirmation and completion summary;
• preserves exact setup operations in JSON and non-interactive output for automation.

ChatGPT onboarding and documentation

• makes the Google Drive + ChatGPT Project Source path explicit as the current reference setup;
• expands the beginner Getting Started guide and CLI reference;
• improves ChatGPT Project connection guidance, including Project Sources and Project Instructions;
• updates README and specialist documentation to match the guided setup flow.

Local unreleased builds

• adds bun run install:local for testing the current checkout through the standalone binary path without cutting a release;
• identifies local builds as <package-version>-<short-git-sha>[-dirty];
• verifies the installed binary and checks PATH precedence.

Reliability

• expands packaged/distribution smoke coverage for command help, cwd-based setup, specialists, validation, and doctor;
• fixes doctor to match the npm runtime requirement of Node.js 22.12.0 or newer;
• adds deterministic tests for setup tree ordering and existing optional-folder presentation.

Upgrade

npm:

npm install -g chat-harness@latest
chat-harness --version

Standalone installer:

curl -fsSL https://raw.githubusercontent.com/carlosboeing/chat-harness/main/install.sh | sh

After upgrading, rerun chat-harness setup in an existing Workspace to use the improved guided setup and refresh recognized managed files when needed.