regent-code 3.0.0

package/docs/superpowers/specs/2026-08-26-windows-guardrail.md

@@ -0,0 +1,66 @@
+# Windows-Native Shell Guardrail Coverage
+
+**Date:** 2026-08-26
+**Topic slug:** windows-guardrail
+**Phase:** 1 — Spec (Strategist artifact)
+
+## Problem Statement
+
+The Regent shell guardrail (`guardShellReason` in `.opencode/plugins/regent.js`) blocks destructive shell commands deterministically before any shell exists. Its matcher is bash-oriented: it recognizes `rm -rf` flag combinations and drive-root/`$HOME` tokens. On Windows pwsh, the native deletion cmdlet family executes unblocked:
+
+| Command (pwsh, live probe 2026-08-26) | Result |
+| --- | --- |
+| `git clean -f` (scratch repo) | BLOCKED |
+| `git reset --hard` (scratch repo) | BLOCKED |
+| `rm -rf <path>` (bash syntax under pwsh) | fails parameter binding before the hook (untestable as-is) |
+| `Remove-Item -LiteralPath <temp> -Recurse -Force` | **EXECUTED UNBLOCKED** |
+
+A user running pwsh can delete `$HOME` or a drive root with no guardrail trip.
+
+## Solution
+
+Extend `guardShellReason` with a Windows-native section that blocks recursive forced deletion via the PowerShell `Remove-Item` family and cmd `rmdir /s /q`, scoped exactly like the existing `rm -rf` rule (drive roots and `$HOME`/`~` tokens and their descendants), while leaving legitimate cleanup of temp/project paths untouched. The existing bash-oriented rules keep their current semantics byte-for-byte.
+
+## User Stories
+
+1. As a user on Windows pwsh, I want `Remove-Item -Recurse -Force C:\` to be blocked, so that a drive root cannot be wiped.
+2. As a user on Windows pwsh, I want `Remove-Item -Recurse -Force $HOME` / `~\…` / `$env:USERPROFILE\…` to be blocked, so that my home directory cannot be wiped.
+3. As a user on Windows pwsh, I want the aliases `ri`, `rm`, `del`, `erase` with the same flags to be blocked on the same targets, so that alias-based invocation cannot bypass the guardrail.
+4. As a user on Windows pwsh, I want `-Path`/`-LiteralPath` long forms (positional, leading, trailing, quoted, colon form) to be blocked on the same targets, so that argument-style bypass is not possible.
+5. As a user on Windows, I want `cmd /c rmdir /s /q C:\` and `cmd /c rd /s /q C:\` to be blocked on the same targets, so that the cmd surface is covered where trivially detectable.
+6. As a user cleaning scratch space, I want `Remove-Item -Recurse -Force C:\Users\nathan\AppData\Local\Temp\opencode\…` to remain allowed, so that legitimate cleanup still works.
+7. As a maintainer, I want the existing `rm -rf` root/home semantics unchanged and the existing blocked/allowed matrix untouched, so that this change is strictly additive.
+
+## Implementation Decisions
+
+1. **Seam.** The existing pure function `guardShellReason(command): string | null` inside `.opencode/plugins/regent.js`; single new section appended after the `rm -rf` match. No new modules; no plugin API changes; no exports added.
+2. **Command family.** `remove-item`, `ri`, `rm`, `del`, `erase` (PowerShell `Remove-Item` and its aliases; `del`/`erase` are first-class Remove-Item aliases), case-insensitive, word-bounded.
+3. **Flags.** Block only when BOTH `-Recurse` and `-Force` are present (any order, case-insensitive; short `-r` / `-f` forms included — PowerShell resolves these unambiguously for `-Recurse`; `-f` may be ambiguous in some versions, so including it only ever blocks, never endangers). Single-flag invocations pass (mirrors "both R and F" intent of `rm -rf`).
+4. **Target extraction.** Token walk after the command word: values of `-Path` / `-LiteralPath` (space or `-Path:value` colon forms, single- or double-quoted, comma-lists split and each checked), plus positional tokens; all other `-…` tokens treated as switches and skipped (their values are tested as harmless non-targets).
+5. **Root scope matcher** (deterministic, env-token based — no environment resolution, mirroring the existing `rm` design):
+   - `~`, `~\…`, `~/…`
+   - `$HOME`, `$HOME\…`, `$HOME/…`
+   - `$env:USERPROFILE`, `$env:USERPROFILE\…`
+   - `/`, `/…` (current drive root in pwsh)
+   - `.`, `..`, `.\…`, `..\…`, `./…`, `../…`
+   - Drive root itself, exact: `X:\`, `X:/`, plus `X:\*` root-contents glob. Arbitrary `X:\…` descendants are NOT matched (required so `C:\Users\nathan\AppData\Local\Temp\opencode\…` stays allowed).
+6. **cmd surface.** `rmdir` / `rd` with `/s` and `/q` (case-insensitive; `/s/q` grouping accepted), optional `cmd` / `cmd.exe /c` prefix, optional quoting of the inner command; same root-scope matcher. Bare `rmdir /s /q` is also matched: inert in pwsh (parses `/s` as a switch and errors), destructive in cmd — blocking is always safe. Matcher is word-bounded to the whole command, so interactive-but-safe commands stay unmatched.
+7. **Reason strings.** Structured, matching existing style: `Remove-Item -Recurse -Force targets <target>` and `cmd rmdir /s /q targets <target>`.
+
+## Testing Decisions
+
+- Seam: the guardrail hook registered at `shell.create.before` and the pure `guardShellReason` — existing test harness (`setupPlugin` in `.opencode/tests/regent.test.js`, `harness.shellHooks['create.before']`), exactly the existing guardrail test's shape.
+- New test in `regent.test.js`: blocked matrix (drive roots both slash styles, `~`/`$HOME`/`$env:USERPROFILE` descendants, `.`/`..` relatives, `/`, `X:\*`, all aliases, long forms positional/leading/trailing/quoted/colon, flag order swap, `rm -Recurse -Force`, cmd rmdir/rd with optional prefix and quoting) and allowed matrix (temp path all alias/long forms, `node_modules`, single-flag `-Recurse`/`-Force`, cmd rmdir without `/s /q`, cmd rmdir on temp path). Existing matrix untouched — the old test's assertions are the regression guard.
+- Red FIRST: new test written and run failing (red), then implementation, then green. Whole-suite gate: `npm run verify` (format + eslint + typecheck + all five suites) — currently 108/108 green baseline re-verified this session.
+
+## Out of Scope
+
+- Changing the existing `rm -rf` rule, including its drive-letter clause that already blocks any `X:\…` path for `rm -rf` (historical; untouched).
+- Environment resolution of home: literal `C:\Users\nathan` as free text is not matched (env-free by design; the allow-story on temp paths requires it; same asymmetry already exists in the `rm` rule).
+- `${HOME}` token form; `cmd /c del /s /q`; UNC roots (`\\server\share`); pipeline/`ForEach-Object` compositions; `-Confirm:$false`-style bypass attempts (deterministic matcher; these are documented limitations, not regressions).
+- Version bump, doc pins, tag/release, and post-release activation — pipeline-managed release steps, not guardrail behavior.
+
+## Further Notes
+
+- Mission continues from `handoff.md` §3-§6; release cycle steps preserve the `regent.hybrid.v2.6.1.test.js` / `regent.runtime.v2.6.1.test.js` historical contract-suite names.
+- This spec doubles as the `requirements` input for the Phase-4 `verify` gate.

package/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js';
+import prettier from 'eslint-config-prettier';
+import globals from 'globals';
+
+export default [
+  js.configs.recommended,
+  prettier,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    rules: {
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: ['node_modules/', 'package-lock.json'],
+  },
+];

package/handoff.md

@@ -0,0 +1,100 @@
+# Handoff — v2.7.1 Windows-Guardrail Fix (Dogfood Trial)
+
+> Fresh agent: you are the **fleet commander** of the trial that closes the loop. This file is the complete context. Start in this repo (`Q:\PROJECTS\PERSONAL\regent-code`) in a NEW session (must be a fresh session — see §1), read `AGENTS.md` + `CONSTITUTION.md`, then run the mission in §6.
+
+## 1. Session prerequisites (IMPORTANT)
+
+- This must be a **freshly created session** against the currently running OpenCode service.
+- Verify your bootstrap marker contains **`Regent v2.7.0`** — check your own system instructions / `using-regent` skill. If it says `v2.6.1` or older, you are a stale session: the `verify` tool and the six Regent tools may be missing. Start over.
+- A fresh terminal is NOT required; a new session/tab in the same TUI is enough.
+
+## 2. Repo & environment state (verified today)
+
+- Repo: `Q:\PROJECTS\PERSONAL\regent-code` — branch `main`, HEAD merged (`49ac23d` merge of PR #1; `b59baa0` = v2.7.0 release commit).
+- Remote tag `v2.7.0` → `b59baa0` (pushed; GitHub release published).
+- **Git local config already set to:** `core.autocrlf false` + `core.eol lf` (repo `.git/config`). Do NOT revert these.
+- **Known cosmetic artifact:** `git status` shows ~26 ` M` entries on md/js/json files while `git diff HEAD` is EMPTY. This is stale stat-cache noise (content is git-identical; blobs are LF). Ignore the ` M` flags; trust `git diff HEAD`. When committing, `git add -A` is safe and re-adds identical content.
+- **CRLF trap (if you ever see it again):** after any `git checkout`/`git pull`, Windows may re-materialize files as CRLF. Symptoms: frontmatter tests fail (`expected: /^---\n…/` with `\r\n` in actual) and `prettier --check` fails on `regent.js`. Blobs are LF; fix the local copy by normalizing tracked text files to LF content (PowerShell: `ReadAllText` → `.Replace("`r`n","`n")` → `WriteAllText` with `UTF8Encoding($false)`). Do NOT commit anything for this — content is identical.
+- Test gate: `npm run verify` (format + eslint + typecheck + tests). Currently **108/108 pass**.
+- `node_modules/` and `.worktrees/` are gitignored; `/package-lock.json` gitignored.
+
+## 3. The mission (v2.7.1)
+
+**Close the shell-guardrail gap on Windows-native deletion cmdlets.**
+
+### Evidence of the gap (live probes, this session)
+
+| Command (pwsh) | Result |
+|---|---|
+| `git clean -f` (scratch repo) | 🛡️ BLOCKED: "Regent guardrail: blocked shell command — git clean -f deletes untracked files. Use a precise, reviewed alternative." |
+| `git reset --hard` (scratch repo) | 🛡️ BLOCKED: "…discards working tree changes" |
+| `rm -rf <path>` (bash syntax, pwsh) | NOT a valid probe — `rm` is a `Remove-Item` alias; `-rf` fails parameter binding before any hook logic (untestable as-is) |
+| `Remove-Item -LiteralPath <temp> -Recurse -Force` | ⚠️ **EXECUTED UNBLOCKED** (deleted the scratch dir) |
+
+### Required behavior (scope mirrors the existing root/home design)
+
+The current guardrail blocks `rm -rf` **scoped to root / `$HOME`** (it must not block legitimate cleanup of temp/project paths — my own cleanup relied on this). The fix must extend pattern matching to the Windows-native surface while keeping that scope:
+
+- **Block**: `Remove-Item -Recurse -Force` (and the `ri`/`rm` aliases; long forms `-Path`/`-LiteralPath`) when the target resolves to a drive root or `$HOME` (and descendants, same scope as the existing `rm -rf` rule).
+- **Allow**: same commands targeting temp/project paths (e.g., `C:\Users\nathan\AppData\Local\Temp\opencode\…`).
+- Consider also `cmd /c rmdir /s /q …` — evaluate whether the hook sees it (`shell.create.before` events carry `command`/`shell`); add if trivially detectable, otherwise document as out of scope.
+- **TDD**: write failing tests FIRST (block on `$HOME`/root, allow on temp; alias coverage), then implement in `.opencode/plugins/regent.js` (find the guardrail section; existing guardrail tests live in `.opencode/tests/regent.test.js` and possibly `regent.live-test.js` — grep for "guardrail").
+- Do NOT change the `rm -rf` root/home semantics; do NOT broaden the blocks to general paths.
+
+### The release cycle (established convention — follow exactly)
+
+1. Bump: `npm version 2.7.1 --no-git-tag-version` (package.json + ignored root package-lock).
+2. **Version coupling — do not miss:** `.opencode/tests/regent.live-test.js` line ~281 asserts `/"version": "2\.7\.0"/` (via the explore focus test) — update to `2\.7\.1` or the suite fails.
+3. Update doc pins: `README.md` (quick-start `#v2.7.0` → `#v2.7.1`, and the "The `v2.7.0` git tag must be pushed…" line) and `.opencode/INSTALL.md` (same two spots).
+4. `npm run verify` → all green (108/108 + new guardrail tests).
+5. Commit to `main` (this repo's convention: direct-to-main for fixes, e.g. `0b1ef26`) — clean message, e.g. `release: v2.7.1 — guardrail Windows-native delete coverage`.
+6. Push; tag `v2.7.1` on the release commit (annotated, matching `v2.7.0` convention: `git tag -a v2.7.1 <release-sha> -m "…"`), push tag.
+7. `gh release create v2.7.1 …` (this repo publishes releases from tags; v2.7.0 release exists as the template).
+8. Leave the pinned-tag/ref-naming conventions alone (`regent.hybrid.v2.6.1.test.js` / `regent.runtime.v2.6.1.test.js` are historical contract-suite names — DO NOT rename; `package.json` test script + docs reference them by name).
+
+### Post-release activation (user machine, same machine as this repo)
+
+1. Update `C:\Users\nathan\.config\opencode\opencode.jsonc`: pin `#v2.7.0` → `#v2.7.1` (only that string).
+2. Validate: `opencode2 debug config` (shows parsed spec) and `git ls-remote --tags origin "refs/tags/v2.7.1^{}"`.
+3. Clear stale caches: remove `C:\Users\nathan\.cache\opencode\packages\git-d9b13c69d9ce3891d7fde53afad1aa6c240cd4c7fa101777b941151710b97f21` (this cache dir is the current git-spec cache; it gets recreated on next start). Nothing else regent-related remains — verify with a recursive `package.json` search for `regent-code` (expect zero matches after deletion). Do NOT touch `prettier`, `pyright`, `typescript-language-server`, `yaml-language-server`, `bash-language-server` (formatter/LSP caches).
+4. Backup config first: copy to `C:\Users\nathan\AppData\Local\Temp\opencode\opencode.jsonc.bak-v2.7.0`.
+5. `opencode2 service restart` (authorized; it will kill your own shell mid-command — run restart as the LAST step of a command, verify after reconnect).
+6. Verify: `opencode2 plugin list` → `regent (active)`; log (`C:\Users\nathan\.local\share\opencode\log\opencode.log`) grep `loading plugin id=regent-code@…/#v2.7.1`; fresh-clone `package.json` → `"version": "2.7.1"`.
+7. Live probe (fresh session proven): `opencode2 run "Reply with exactly one word: yes or no. Does your system instructions contain the text 'Regent v2.7.1'?"` → expect `yes`.
+
+## 4. Regent rules you must obey (Iron Laws)
+
+- **No code without a failing test first** (TDD red → green).
+- **No fix without root cause** — the root cause here is already established (guardrail matcher is bash-oriented/root-home-scoped; pwsh-native cmdlets absent).
+- **No completion without fresh evidence** — every claim needs command output you ran yourself.
+- **No phase skip** — run the phases in §6 in order.
+- The session's own guardrail will BLOCK `git clean -f`, `git reset --hard`, force-push from you too — use precise alternatives; that is the feature working.
+- Scope: touch only the guardrail code/tests/docs/config pin — nothing else (surgical precision). Note the one caveat: as part of the v2.7.1 release, README/INSTALL/live-test pins MUST change or the release is inconsistent (explicitly in scope).
+
+## 5. Live-environment facts (verified)
+
+- `opencode2` CLI: `service status|restart`, `plugin list`, `debug config`, `debug paths`, `run "<message>"` (positional, NOT `--prompt`), `api …`.
+- Service currently runs v2.7.0; `plugin list` → `regent (active)`.
+- Plugin loads its skills/commands/tools from the cached git package `git-d9b13c69…`; log naming reveals the entrypoint.
+- Regent version markers are injected via `ctx.session.hook("context")` — visible in system instructions; version read from the installed `package.json`.
+- `update V2` caution: the plugins guide + config docs are at `https://opencode.ai/v2/docs/` (use if you need API certainty; do not guess field shapes).
+
+## 6. The trial itself — run the closed loop on this mission
+
+Use `/regent/orchestrate` (or the phase sequence manually):
+
+1. **Clarify/grill** — `grilling` skill: confirm scope (Windows-native delete cmdlets only; root/home scoping preserved; no scope creep).
+2. **Spec** — `spec` skill: `docs/superpowers/specs/2026-08-26-windows-guardrail.md`.
+3. **Plan** — `tickets` skill: `docs/superpowers/plans/windows-guardrail/` (plan.md + tasks.md) with blocking edges; note the release-cycle steps as the final ticket.
+4. **Execute** — `tdd` (red first), `worktrees` if parallelizing, `wizard`/`merge-conflicts` as needed.
+5. **Review** — `code-review` skill: two-axis (standards + spec), parallel sub-agents, P0–P3, default REJECT; re-run `npm run verify` yourself.
+6. **Verify** — `verify` tool + `changed-files`; the freshness gate grades evidence (stale claims fail — that is designed behavior; prove each step fresh).
+7. **Ship & hand off** — `ship` skill: evidence-gated commit/push/PR (or direct-to-main per convention), then §3 post-release steps, then `handoff`/report.
+
+**Success criteria:** (a) failing tests exist before the fix; (b) fix blocks `Remove-Item … -Recurse -Force` on `$HOME`/root, allows temp/project paths; (c) `npm run verify` green with new tests; (d) `v2.7.1` tagged/released/pinned/cache-cleared/restarted; (e) live probe answers `yes` to `Regent v2.7.1`; (f) all artifacts exist (spec, plan, review verdicts, evidence).
+
+## 7. Opening message for the fresh session
+
+```
+Read handoff.md at the repo root (Q:\PROJECTS\PERSONAL\regent-code), read AGENTS.md and CONSTITUTION.md, confirm your bootstrap says Regent v2.7.0, then run the §6 mission: close the Windows-native shell-guardrail gap and release it as v2.7.1, driving the full closed loop (grill→spec→tickets→TDD execute→two-axis review→freshness verify→ship) with evidence at every phase.
+```

package/mcp/cli.js

@@ -0,0 +1,9 @@
+// Launch the Regent MCP server. Used as the package `bin` entry so that
+// `npx -y regent-code` starts the server over stdio without needing a local
+// clone. Keep this file dependency-free and side-effect-only by design.
+import { main } from './index.js';
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});