v1.0.0 — Delivery Experience

The delivery experience release. Nanostack does not only protect the workflow; it now guides delivery like a professional engineering team, understandable for technical and non-technical users.

The honesty rule from v0.8 is preserved: no skill claims deterministic enforcement when the host adapter declares instructions_only. Adapter capability remains the source of truth.

Two profiles, same rigor

The session now records a profile field that shapes the wording of every phase output. The workflow does not change; the words do.

Profile	When you get it	What output looks like
Guided	Local mode (no git repo), or when you choose it explicitly.	Plain language. No PR/CI/branch/diff jargon. Each phase tells you the result, how to try it, what was checked, and what remains unverified.
Professional	Git repository with the standard developer toolchain, or when you choose it.	Findings, evidence, file paths, PR/CI status preserved. Phase-aware next-step prose.

Wording rules: reference/plain-language-contract.md. Session fields: reference/session-state-contract.md.

Session-state workflow

bin/session.sh writes schema v2 with new fields:

• profile — guided or professional. Resolved per the profile selection rule: explicit flag, then config, then no-git => guided, then all guards instructions_only => guided, else professional.
• run_mode — normal or report_only. In report_only, skills do not edit files, fix issues, commit, or push. They only describe.
• plan_approval — manual, auto, or not_required. /feature always sets auto. --run-mode report_only forces not_required.
• capabilities — snapshot of the host adapter at init time, so audit trails are honest about what the host could enforce when the sprint started.
• policy — defaults follow profile (guided blocks outside-project writes and env reads; professional warns). User overrides via .nanostack/config.json cannot downgrade guided to allow.

bin/next-step.sh --json derives the next action from session state and falls back to fresh artifacts when the session is missing. Skills no longer encode their own next-step prose.

v1 sessions still read: every reader applies a compatibility table for missing fields.

Non-technical delivery output

Every Guided phase output (think, plan, qa, ship, doctor) follows a four-block skeleton:

1. Result. One sentence: what the skill found or did.
2. How to try. The exact command or URL. One action.
3. What was checked. Two or three short bullets.
4. What remains. What this skill could not check.

Spanish parity (Resultado / Como verlo / Que revise / Pendiente) ships across every skill. Local mode implies guided.

The contract is enforced at lint time: every fenced <!-- guided-output --> block is grepped for banned terms (artifact, PR, CI, branch, diff, hook, phase, security audit, QA, scope drift). Outside the fence, those terms are allowed (they are agent instructions, not user output).

/feature is always autopilot

/feature initializes the session with --autopilot --plan-approval auto. Manual feature work uses /think + /nano. There is no --manual flag.

Spanish first-class

README.es.md mirrors the v1.0 framing as "Dos perfiles, mismo rigor". TROUBLESHOOTING.es.md (new) covers the seven highest-traffic entries (slash commands no aparecen, jq, phase gate, puerto en uso, Windows, sprint atascado, conflicto de nombres). Advanced topics still point at canonical English.

Compatibility

No breaking changes. v1 session files written by 0.x installs continue to read correctly under the v2 compatibility layer. Skill APIs and slash commands unchanged.

How v1.0 shipped

Six small PRs, each independently reviewable:

Sprint	PR	Scope
1	#155	Closed v1.0 decisions + technical spec (docs-only)
2	#156	Session schema v2 + next-step.sh --json
3	#158	Skills consume session state + session-state contract
4	#159	Plain-language contract + Guided output rewrites
5	#160	Spanish first-class (TROUBLESHOOTING.es)
6	#161	Release v1.0 + public framing

Install

```sh
npx create-nanostack
```

To migrate an existing project to the v0.8+ hook model with a backup of .claude/settings.json:

```sh
~/.claude/skills/nanostack/bin/init-project.sh --repair
```

Then run /nano-doctor to verify.

v0.9.0

The repair release. Existing installs that predate the v0.8 hook era can now migrate with one command, no JSON editing required. The upgrade flow itself names the next step instead of leaving warnings on the next /nano-doctor run.

Migration UX

bin/init-project.sh gains four flags. Every migration path makes a timestamped backup of .claude/settings.json before changing anything, and re-runs /nano-doctor at the end so the result is visible without a second command.

Flag	What it does
--check	Read-only diagnostic. Runs /nano-doctor and exits.
--repair	Adds missing PreToolUse hooks AND adds narrow rm rules. Additive: never removes anything. Safe to run on any project.
--migrate-hooks	Adds missing PreToolUse hooks only.
--migrate-permissions	Removes Bash(rm:*) and adds Bash(rm:.nanostack/**) + Bash(rm:/tmp/**). The only flag that removes.

SECURITY.md "Existing installs" section now points users at these flags instead of hand-editing JSON.

upgrade.sh closes the loop

After a successful upgrade, bin/upgrade.sh inspects the current project. If .claude/settings.json exists but is missing the Bash and Write/Edit hooks, the upgrade prints the exact init-project.sh --repair command for the project. Silent in every other case (not in a project, hooks already wired, jq unavailable). No central project registry: only the cwd is inspected, with a one-step walk to the git root if needed. Privacy constraint preserved.

Already shipped during v0.8 audit rounds

These v0.9 spec items already landed in the v0.8 audit round 4:

• Symlink-resolving Write/Edit guard.
• Broader secret-disclosure rules covering grep, rg, jq, awk, sed, strings, od, xxd, hexdump, plus bare env / printenv (with env VAR=value cmd still allowed).
• CI matrix expanded with new jobs for guard regression (35 cases), write-guard regression (19 cases), supply-chain checks, adapter-schema validation.

Compatibility

No breaking changes. Default init-project.sh behavior (no flag) is unchanged: create new settings with hooks; merge into existing without touching the hooks block. Backward compatible with installs from before this release.

Install

npx create-nanostack

To migrate an existing project to the v0.8+ hook model:

~/.claude/skills/nanostack/bin/init-project.sh --repair

Full diff

v0.8.0...v0.9.0

v0.8.0

The honest-capabilities release. After three audit rounds today, this version stops claiming uniform enforcement across agents and starts reading from a single source of truth. Setup, nano-doctor, README, and README.es all consume adapters/<host>.json so the difference between Claude Code's enforced hooks and the guided workflow on Cursor / Codex / OpenCode / Gemini is named consistently across every surface.

Adapter contract

• reference/host-adapter-schema.md defines an L0-L3 capability vocabulary (Guided / Checked / Guarded / Blocked when unsafe) with explicit rules for "observation overrides declaration".
• adapters/{claude,codex,cursor,opencode,gemini}.json declare each host's real protection level today, plus last_verified and verification.method so anyone can tell which guarantees are CI-asserted and which are manual.
• New CI job host-adapter-schema validates required fields, capability values, host/filename match, and verification evidence on every PR. The contract is enforced, not aspirational.
• nano-doctor reads the adapter for each detected host CLI and reports protection per host, with drift warnings when the declaration and the observed install disagree.
• setup prints a tight protection-level summary by default. --verbose unlocks the legacy skill listing.
• README and README.es replaced "every step is enforced" with a per-host capability matrix grounded in the adapter files.

Internal audit round 4

• Write/Edit guard resolves symlinks. A mylink/config -> ~/.ssh/config no longer slips past the prefix denylist; both the original and resolved path are evaluated.
• Broader secret-read rules. G-030 now covers grep, rg, jq, awk, sed, strings, od, xxd, hexdump, wc, file, stat, tr, plus the existing cat / head / tail family. New G-031 blocks bare env / printenv while leaving env VAR=value cmd allowed.
• nano-doctor --fix wires hooks for legacy installs. Detects missing PreToolUse matchers, makes a timestamped backup of .claude/settings.json, merges the matchers in via jq. Idempotent; existing permissions stay untouched.
• Doctor JSON output preserves pipes and quotes. Internal separator switched from | to tab; envelope built with jq -R -s. Write|Edit|MultiEdit no longer truncates at the first pipe.
• /feature autopilot contract fixed. Session init now passes --autopilot, so the orchestrator no longer collides with /nano's default approval pause.
• Guard tier docs refreshed. README now describes block-before-allowlist (matching the code), and the cross-agent gap is named explicitly.

Compatibility

No wire-schema breaking changes. init-project.sh continues to leave existing .claude/settings.json untouched on merge. /nano-doctor --fix is the opt-in migration path for legacy installs that want to add the Write/Edit guard hook.

Install

npx create-nanostack

After install, run /nano-doctor to see the honest state of your permissions and hook wiring on the agents you have installed.

Full diff

v0.7.0...v0.8.0

v0.7.0

Third security round of the day. The guard shifts from "Bash-only, allowlist-first" to an authoritative layer: block rules run before the allowlist, and a new hook covers Write, Edit, and MultiEdit. Four PRs (#139, #140, #141, #142) closed all seven findings from the round 3 audit.

Guard becomes authoritative

• Block before allowlist. Binaries on the allowlist (find, cat, head, tail) no longer short-circuit past block rules. find . -delete, find . -exec rm -rf {} +, cat .env, head .env, tail secrets.pem now return exit 1 with the matching block rule. G-005, G-006, G-030 are effective again.
• Write and Edit covered. New guard/bin/check-write.sh PreToolUse hook. Denies secrets by basename (.env and variants, *.pem, *.key, *.p12, *.pfx, SSH keys including id_rsa/id_ed25519/authorized_keys, shell history) and by path prefix (/etc, /var, /usr/bin, /usr/sbin, /usr/lib, /System, /private/etc, ~/.ssh, ~/.gnupg, ~/.aws, ~/.gcp, ~/.config/gcloud, ~/.kube).
• Fresh installs wire both hooks. init-project.sh writes a hooks.PreToolUse block alongside permissions, with matchers for Bash (check-dangerous.sh) and Write|Edit|MultiEdit (check-write.sh). Existing installs are not modified; manual wire-up is in SECURITY.md.
• git push --force-with-lease passes. G-007 tightened from git push --force to git push.*--force([[:space:]]|$) so the guard's own recommended alternative stops tripping the block.

/nano-doctor reports the full model

Five rows across permissions and hook presence:

• rm_scope, write_scope, allowlist_scope — cross-reference the relevant hook.
• bash_guard, write_guard — report hook presence directly.

A broad Write(*) with the hook wired now reads as pass with a note that the hook covers secrets and system paths. Without the hook it warns with concrete remediation pointing at SECURITY.md.

CI coverage

• Guard regression matrix expanded from 12 to 21 cases. New cases cover the allowlist-bypass class (find . -delete, cat .env, etc.) plus the --force-with-lease positive.
• New write-guard-regression job: 19 cases plus two JSON-on-stdin contract checks so a Claude Code protocol drift surfaces on every PR.

Portability and integrity

• feature/bin/enforce-sprint.sh uses BSD stat with a GNU stat fallback, mirroring the pattern in guard/bin/phase-gate.sh. Gates run on Linux agents, not just macOS.
• bin/resolve.sh passes --verify to find-artifact.sh. Tampered artifacts no longer feed downstream phases (gates, review context, conflict precedence).

Compatibility

No breaking changes to the wire telemetry schema. Existing .claude/settings.json files are not modified. The Write/Edit hook is only wired automatically for fresh installs; existing installs opt in via the copy-paste block in SECURITY.md.

Install

npx create-nanostack

Run /nano-doctor in your project to see the honest state of your permission and hook surface.

Full diff

v0.6.0...v0.7.0

v0.6.0

Six weeks of work since the v0.1.0 baseline. This is the first tag since the VERSION file was introduced, and it reflects the features, skills, and hardening that landed along the way.

New surface

• /nano-doctor — install health-check skill. Ten checks across deps, install integrity, home directory permissions, telemetry config, pre-V5 detection, and Worker reachability. Exit code maps to severity: 0 healthy, 1 warnings, 2 critical. Flags: --json, --offline, --fix.
• Observational feedback in /think — optional ## What I noticed block when a coaching pattern fires (jump-to-solution, scope drift, strong pain observation, surprising synthesis). Silence beats a forced observation. Target firing rate under 30% of sessions.
• observational_fired v1 telemetry field — measures firing rate of the feedback block without any content leaving the machine. Additive, nullable; only /think sets it.
• NANOSTACK_DEBUG=1 — surfaces the pre-V5 detection decision (marker-present, pre-V5, or fresh-install) so future silent bugs surface on first run.
• Latent-vs-deterministic reference — linked from /think (Phase 4 Premise Challenge) and /nano (Architecture Checkpoint). Names when to trust the model versus when to build infrastructure.

Internal security round (all findings closed)

• Guard block rules run before the in-project shortcut so recursive operations that resolve inside the repo cannot bypass.
• setup --rename input validated via strict regex plus path_is_under guard before any rm.
• Audit log records built via jq -cn --arg so quoted, backslashed, or newline-laden fields cannot inject extra keys.
• Session lock records owner PID and uses kill -0 to tell stale from live; fails closed at 30s.
• Wrangler bumped from 3.60 to 4.85; bun audit went from 6 vulnerabilities to 0.
• Guard audit trail lands in .nanostack/audit.log regardless of NANOSTACK_STORE state.
• CI adds bun install --frozen-lockfile, bun audit, tsc --noEmit, and a 12-case guard regression matrix.
• Default rm scope narrowed to .nanostack/** and /tmp/**. Existing installs untouched; /nano-doctor surfaces broad legacy entries with an opt-in migration path.
• Permission model documented in SECURITY.md.

Compatibility

No breaking changes to the wire telemetry schema. observational_fired is additive and nullable. Existing opt-in installations continue to send events that pass Worker validation.

init-project.sh never removes entries from an existing .claude/settings.json; pre-v0.6 installs keep whatever they had and can migrate on their own timeline.

Install

npx create-nanostack

See README for the full set of skills and TROUBLESHOOTING.md if you hit anything.

Full diff

v0.1.0...v0.6.0