From a912c503a1d79e318f19a00658f4441b35522265 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Wed, 18 Nov 2026 16:37:08 +1100 Subject: [PATCH] docs(spec-loop): sync specs with contributed functionality Record vetted-op-git, the project-board operations, saved-read pruning and the shared sandbox golden rule in the vetted-command-surface and security-issue-lifecycle specs. Generated-by: Claude Code (Sonnet 5.5) --- tools/spec-loop/.last-sync | 2 +- .../specs/security-issue-lifecycle.md | 4 ++ .../spec-loop/specs/vetted-command-surface.md | 52 +++++++++++++++++++ 3 files changed, 57 insertions(+), 1 deletion(-) diff --git a/tools/spec-loop/.last-sync b/tools/spec-loop/.last-sync index 05a3f7d85..347197892 100644 --- a/tools/spec-loop/.last-sync +++ b/tools/spec-loop/.last-sync @@ -1 +1 @@ -9e979ff3e591ccffd1bc97460e87b99c8e608968 +226ca2d8e4d07ea44a1849b6eb69cd0598cda55f diff --git a/tools/spec-loop/specs/security-issue-lifecycle.md b/tools/spec-loop/specs/security-issue-lifecycle.md index 85e1feb36..9bb87d493 100644 --- a/tools/spec-loop/specs/security-issue-lifecycle.md +++ b/tools/spec-loop/specs/security-issue-lifecycle.md @@ -249,6 +249,10 @@ publication, with a human gate and an audit-log entry at every step. `issue-create-labeled` instead (#1982), and the import skills and `security-issue-invalidate` point at `tools/github/project-board.md` for the orphan-issue, introspection and archive board recipes. +- The tracker's Projects V2 board stays security-only: `security-issue-sync` + adds, moves and archives items through the vetted `board-*` operations and + its end-of-sync sweep archives non-security items (#2179, #2181; see + [vetted-command-surface.md](vetted-command-surface.md)). - Status rollups are written by `tools/github-rollup/` (`append`, `amend-latest`, `fold`, `list`, `latest`). Under the secure setup that CLI's `gh` runs sandboxed and fails, so the diff --git a/tools/spec-loop/specs/vetted-command-surface.md b/tools/spec-loop/specs/vetted-command-surface.md index c6317a5ae..9a32d0733 100644 --- a/tools/spec-loop/specs/vetted-command-surface.md +++ b/tools/spec-loop/specs/vetted-command-surface.md @@ -142,6 +142,13 @@ A read too large to carry through the agent's context goes to a file: sweep's pages reach a deterministic tool such as `tools/pr-management` without passing through the agent (#1570). Writes and procedures refuse it, and `NAME` is a single path component. +Each `--save` also prunes `saved/` entries older than `saved_retention_days` +(under `[values]`, default 7 days): only regular files and symlinks the +caller owns, relative to the same `saved/` descriptor, never following a +link; the marker, dot-files, subdirectories and the file just written stay +(#2183). +Body and title files are removed from the workspace once their write +succeeds (#2163). Because `vetted-op-read` runs outside the sandbox and `--config` can name a policy the agent wrote, `--save` writes only into a `/saved/` directory that already exists and holds a regular `.vetted-ops-save` marker; @@ -225,6 +232,24 @@ registered `--stable-path`, else the account's home from the password database), since Codex execpolicy cannot match `~`; any other root is one the agent could have built and stays refused. +**Project-board operations** (#2179, #2181). +A GitHub-backed tracker's Projects V2 board is kept through five operations +whose ids come from the policy (`board_project_id`, `board_status_field_id`, +`[values.board_columns]`): reads `board-item` and `board-items`, writes +`board-add-item`, `board-set-status` and `board-archive-item`. +`security-issue-sync` adds a missing item, moves it to the column its labels +call for and archives it once closed; its end-of-sync sweep archives anything +that is not a security tracker, keeping the board security-only +(`tools/github/project-board.md`). + +**Every skill carries the sandbox golden rule** (#2162). +The shared block `tools/dev/blocks/sandbox-golden-rule.md`, kept in sync by +`check-shared-blocks.py`, tells the agent that a step the sandbox blocks +becomes a vetted operation (`vetted-op-read`, `vetted-op`, `vetted-op-tracker`, +`vetted-op-git`) or a documented in-sandbox route, never a bypass or a wider +exclusion; if none exists it gives the user the one command and proposes +`setup-upstream-fix`. + ## Scoping — what is real and what is aspiration The dispatcher requires `--caller` and refuses operations outside that caller's @@ -359,6 +384,33 @@ per [`docs/adapters/registry.md`](../../../docs/adapters/registry.md). [`tools/permission-audit`](../../permission-audit/README.md) is the natural place to detect and offer to remove them. +## Git operations the sandbox blocks (`vetted-op-git`) + +A fourth entry point, `vetted-op-git` +(`tools/vetted-ops/src/vetted_ops/git_ops.py`, #2161), runs the git steps a +sandboxed session cannot: a push over SSH (the proxy gives no TCP and a +hardware key's touch prompt never reaches the user) and adding, moving or +removing a linked worktree the session did not create (its administrative +directory is read-only). It is excluded from the sandbox and kept on `ask`, +like `vetted-op`. +Operations are closed shapes: `git-push-branch` (a leased push, `--force-with-lease` +on the caller's expected SHA or `new`, to the policy's `fork` or to an +`upstream_push`-matching branch of upstream, protected branches always +refused, an emptied rebase refused), `git-worktree-sync` (`reset --keep` of a +clean linked worktree), `git-worktree-add` and `git-worktree-remove` (never +`--force`). +The policy's `[git]` table bounds them (`checkouts`, `fork`, `upstream_push`, +`protected`, `worktree_roots`). +Safety rests on: destinations built from policy, never from a configured +remote; refusal while repository config holds any key outside an inert list, +checked in every working tree and again before the acting command; pinned +config (no fsmonitor/gc, `https`/`ssh` only, attributes read from the empty +tree, hooks never run, `--no-verify`); validated directories held by +descriptor and git given the validated git directory; and every `GIT_*` +variable dropped with `HOME` taken from the password database. +Git 2.42 or newer is required. +The `pre-push` checks run in the sandbox first. + ## Codex native integration The Codex marketplace advertises the self-contained vetted-ops substrate plugin.