Mrbaeksang · Mrbaeksang · Jul 31, 2026 · Jul 30, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -12,9 +12,11 @@ Before changing this repository:
   test evidence.
 - Keep `AGENTS.md` as a thin entrypoint. Route detailed procedures through
   progressively loaded playbooks.
-- Treat prompts as guidance and enforce deterministic prerequisites with
-  provider hooks or an equivalent fail-closed capability boundary.
-- Use DDD language, cohesive modules, and ports/adapters by default, but create
-  physical layers only when real boundaries or invariants justify them.
+- Treat prompts as workflow guidance. Keep the default provider Hook a thin
+  boundary for secrets, Harness internals, provider configuration, and the
+  verification canary; do not blanket-block normal or future tools.
+- Follow the repository's current architecture first. Use DDD, cohesive
+  modules, ports/adapters, or other patterns only when the actual boundaries
+  and tradeoffs justify them.
 - Do not create progress reports, meeting notes, speculative roadmaps, or
   duplicate documentation.
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -6,8 +6,9 @@
 The single AI the user talks to while working in a configured Project.
 
 **Engineering Harness**:
-The installed project behavior that guides and mechanically constrains the
-Coding Agent from conversation through verified completion.
+The installed project behavior that guides the Coding Agent from conversation
+through verified completion and applies only narrow configured safety
+constraints.
 
 **Setup Skill**:
 The one-shot, idempotent skill that inspects a Project, asks only unresolved
@@ -34,8 +35,9 @@ A focused procedure loaded only when the current Task matches its trigger.
 _Avoid_: Always-loaded prompt, project history
 
 **Gate**:
-A mechanically enforced prerequisite controlling whether a protected action,
-especially a write or completion claim, may proceed.
+A mechanically enforced prerequisite controlling a specifically protected
+action. In default assistive mode this is narrow; strict mode can opt into a
+scoped write lifecycle.
 _Avoid_: Reminder, suggestion, checklist
 
 **Evidence**:

diff --git a/README.md b/README.md
@@ -2,127 +2,68 @@
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
-`setup-engineering-harness` is a one-shot skill that configures a repository so
-one coding AI works evidence-first by default.
-
-It is not a multi-agent manager. It improves the session the user is already
-using:
-
-- ambiguous product choices are asked together before implementation;
-- dependency work starts from the installed version, official sources, types,
-  source, and a reproduction;
-- native library capabilities are checked before custom code;
-- writes require a scoped acceptance contract and lease;
-- completion requires fresh verification and a diff-backed receipt;
-- repository context is loaded progressively instead of dumped into the model;
-- durable documentation is canonical and updated, not accumulated as meeting
-  notes or speculative roadmaps.
-
-The current implementation supports Codex and Claude Code project hooks. It is
-an R&D-quality prototype, not a claim of statistically validated production
-readiness.
+`setup-engineering-harness` configures a repository so one coding agent follows an adaptive,
+evidence-led workflow without imposing a favorite framework or architecture.
+
+The installed workflow:
+
+- aligns consequential requirements in natural conversation and batches independent questions;
+- inspects the existing repository before recommending changes;
+- verifies exact installed versions and re-learns current APIs from primary official sources;
+- compares current stack candidates for greenfield or intentional stack changes;
+- scales from a tiny bug loop to compact specs and tracer-bullet vertical slices;
+- keeps research and planning ephemeral unless durable documentation or tickets are genuinely
+  useful;
+- verifies behavior and inspects the diff before claiming completion.
+
+The default `assistive` mode does not require proposal IDs, hashes, magic approval phrases, or
+write leases. Its Codex Hook is a thin safety boundary for secrets, Harness-owned files, provider
+hook configuration, and the provider canary. Normal repository work and specialized tools such as
+web research, documentation connectors, and image generation remain available.
+
+An optional `strict` mode preserves the original scoped-lease protocol for projects that
+explicitly need it.
 
 ## What Setup installs
 
-The installer preserves existing repository instructions and adds one thin
-provider-native bridge. Detailed behavior lives in task-routed Playbooks under
-`.agent-harness/`.
+The standard-library-only Python installer preserves existing instructions and hooks, then adds a
+thin provider-native bridge:
 
 ```text
 AGENTS.md or CLAUDE.md            thin managed bridge
 .codex/hooks.json or
-.claude/settings.json             merged UserPromptSubmit and PreToolUse hooks
+.claude/settings.json             merged prompt and safety hooks
 .agent-harness/
-  config.json                     user-owned policy
+  config.json                     user-owned policy; defaults to assistive mode
   local.md                        user-owned local constraints
   repo-profile.json               regenerable repository facts
-  router.md                       progressive Playbook router
-  playbooks/                      focused conversation/research/work rules
-  bin/                            read, lifecycle, and verification brokers
+  router.md                       adaptive Playbook router
+  playbooks/                      conversation, research, planning, implementation, verification
+  bin/                            optional read, strict-lifecycle, and verification helpers
   checks/audit.py                 Harness integrity audit
   manifest.json                   ownership and host-runtime pointers
 ```
 
-Authoritative Gate state and trusted runtime code are placed outside the
-repository under the user's XDG state directory. Secrets, raw logs, caches, and
-transient receipts are not added to Git.
-
-## Install
-
-Choose one entrypoint. All three use the same versioned Skill and installer.
-
-### npm executable
-
-Run without permanently installing a package:
-
-```bash
-npx setup-engineering-harness@latest plan \
-  --provider codex --repo /path/to/project
-
-npx setup-engineering-harness@latest install \
-  --provider codex --repo /path/to/project
-```
-
-Use `--provider claude-code` for Claude Code. `plan` is read-only; `install`
-changes only the displayed scope.
-
-### Agent Skill
-
-Install globally into Codex with the open `skills` CLI:
-
-```bash
-npx skills@latest add Mrbaeksang/setup-engineering-harness \
-  --skill setup-engineering-harness \
-  -a codex -g -y
-```
-
-Open Codex in the repository you want to configure and invoke:
-
-```text
-$setup-engineering-harness
-```
-
-The `skills` command copies the versioned Skill from GitHub into the selected
-agent's skill directory. It does not install this repository's npm executable.
+Trusted runtime code and provider-canary receipts live outside the Project under the user's XDG
+state directory. Secrets, logs, caches, and transient receipts are not added to Git.
 
-### Claude Code Marketplace
+## Install from a clone
 
-Register this repository as a marketplace and install its managed plugin:
+No npm installation is required:
 
 ```bash
-claude plugin marketplace add Mrbaeksang/setup-engineering-harness
-claude plugin install setup-engineering-harness@mrbaeksang
-```
-
-Restart Claude Code or run `/reload-plugins`, then invoke:
-
-```text
-/setup-engineering-harness:setup-engineering-harness
-```
-
-The skill first shows a read-only repository profile, unresolved decisions, and
-the exact planned changes. One approval covers that scope; it then installs,
-runs the real-provider canary, and audits the result.
-
-Requirements after installation: Python 3.12 or newer, Git, the selected provider CLI,
-and a supported local isolation mechanism for managed verification
-(`bubblewrap` on Linux/WSL or `sandbox-exec` on macOS).
-
-## Run from a clone
-
-For development or manual inspection, clone this repository and call the same
-installer directly:
+git clone https://github.com/Mrbaeksang/setup-engineering-harness.git
+cd setup-engineering-harness
 
-```bash
 python3 skills/setup-engineering-harness/scripts/setup_harness.py \
   plan --provider codex --repo /path/to/project
 
 python3 skills/setup-engineering-harness/scripts/setup_harness.py \
   install --provider codex --repo /path/to/project
 ```
 
-Then review and trust the exact project hook definitions in the selected
-provider and run:
+The plan is read-only. After approving the exact install scope, verify the real provider Hook and
+audit the installed Harness:
 
 ```bash
 python3 skills/setup-engineering-harness/scripts/setup_harness.py \
@@ -132,42 +73,56 @@ python3 skills/setup-engineering-harness/scripts/setup_harness.py \
   audit --repo /path/to/project
 ```
 
-`install` can intentionally report `INCOMPLETE` until provider trust and the
-write-deny canary are proven. It does not run project commands, install
-packages, read secrets, or change application code.
+Use `--provider claude-code` for Claude Code. The same entrypoint supports explicit `repair` and
+`uninstall` operations. Install and repair never run Project commands, install packages, read
+secrets, or change application code.
+
+## Install as an Agent Skill
+
+The repository also follows the open Agent Skills layout. Install or copy
+`skills/setup-engineering-harness` into the provider's skills directory, restart the provider,
+then invoke `$setup-engineering-harness`.
+
+An npm executable remains available as an optional distribution channel; it runs the same Python
+installer and is not required by the installed Harness.
+
+## Configuration
 
-The same entrypoint supports `repair` and `uninstall`; both are explicit
-operations because managed drift and deletion should not be silently accepted.
+`.agent-harness/config.json` is seeded once and remains user-owned.
+
+```json
+{
+  "write_gate": {
+    "mode": "assistive"
+  }
+}
+```
+
+Set `mode` to `strict` only when the Project intentionally wants the compatibility scoped-lease
+workflow. Missing `mode` is treated as `assistive`, so existing installations adopt the less
+ceremonial default without overwriting user-owned configuration.
 
 ## Development checks
 
 ```bash
 PYTHONDONTWRITEBYTECODE=1 \
 python3 -m unittest discover -s tests -p 'test_*.py'
 
-PYTHONDONTWRITEBYTECODE=1 \
-python3 /path/to/skill-creator/scripts/quick_validate.py \
-  skills/setup-engineering-harness
+npm run verify:distribution
 ```
 
-The benchmark fixture under `benchmarks/fixtures/` is synthetic test data for
-the scoring engine. It is not empirical proof. Actual clean-context behavior
-screens and their limitations are recorded in the canonical
+The benchmark fixture is synthetic test data, not empirical proof. Current design, threat model,
+and verification evidence live in the canonical
 [design document](docs/design/setup-engineering-harness.md).
 
-## Current boundaries
-
-- The installed provider adapter is Codex-specific.
-- Clean-context behavior screens currently have one run per arm, so findings
-  are directional rather than statistically significant.
-- A live canary for the installed provider must pass on the user's machine; a
-  simulated hook replay is not equivalent.
+## Boundaries
 
-The Codex canary deliberately uses a disposable `workspace-write` attempt at
-the reserved `.engineering-harness-provider-canary` path. This ensures the
-`PreToolUse` hook—not Codex's read-only sandbox—is what denies the write. The
-installer removes the reserved file and fails verification if the hook does not
-stop it.
+- The adaptive workflow is guidance; provider permissions and sandboxing remain the authority for
+  normal execution.
+- The thin Hook cannot infer the side effects of every future specialized tool. External writes
+  still require the user's explicit authorization under the provider's normal rules.
+- A live provider canary must pass on the user's machine; simulated Hook replay is not equivalent.
+- Clean-context behavior screens are directional, not statistically significant.
 
 ## License