Add ~/.cache/gh to sandbox allowWrite so gh CLI no longer needs an
XDG_CACHE_HOME=/tmp/... prefix, and replace the five XDG-prefixed allow
entries with two generic `* > /tmp/*` redirect entries that cover any
command capturing output into /tmp. Sync sandbox.md / settings.md /
security.md and normalize the allowWrite path enumerations.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace the one-off literal allow entry for a specific `gh run download`
invocation with the `XDG_CACHE_HOME=* gh run download *` wildcard that
mirrors the existing `view`/`list` env-prefix precedents, and move the
`Skill(update-config*)` wildcard from `allow` to `ask` so settings-file
mutations (permission rules, hooks, sandbox scope) always prompt — the
skill can otherwise self-escalate the agent's own permission surface.
Document both entries in settings.md with matching Env-Prefix and
Privilege-Escalation rationales.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Removes ~/.ssh from sandbox.filesystem.denyRead so SSH auth (keys, known_hosts, config) succeeds inside the sandbox. Bash(git push*) stays in ask, which becomes the effective control point for pushes.
Documents the trade-off:
- security.md: updates Assumption 9 and adds Assumption 10 covering why ~/.ssh is readable, the cost, and the mitigations (passphrase-protected keys, key rotation on incident, settings.local.json opt-out, SSH-agent-socket alternative).
- sandbox.md: removes ~/.ssh from the Read Restrictions table and links back to Assumption 10.
Moves the GitHub Actions workflow catalog under tools/github/ alongside the other GitHub-scoped docs, and updates the internal workflow/artefact links plus the two external references in workflow.md and pipeline.md.
Collapse six literal XDG_CACHE_HOME=/tmp/gh-cache gh run/issue list
allow entries into XDG_CACHE_HOME=* gh run list *, XDG_CACHE_HOME=*
gh issue list *, gh run *, and gh issue *. Plain gh run * / gh issue *
are safe because every mutating verb is caught by gh * <verb>* ask or
gh issue transfer* deny. Env-prefix variants stay narrow (no broader
than list) because env prefix bypasses subcommand ask/deny patterns.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Allow read-only gh api GETs (plus XDG_CACHE_HOME=* prefix variant) so
log-fetch invocations with env prefix + redirect stop prompting. Route
every implicit-POST shape through ask: -f/-F/--field/--raw-field/--input
body flags and graphql*. Path-based deny rules keep precedence.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Centralise the full GitHub Actions workflow catalog in
docs/contributing/tools/actions.md as the single source of truth, link
pipeline.md and workflow.md to it, and introduce
docs/agents/action/push-trigger-pull.md as the authoritative procedure
for the push to draft CI to ready-for-review loop. Retire the stale
flat docs/contributing/tools/agents/claude.md and drop docs README
page-inventories that violate the readme_md.md scope rule.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Mirrors the XDG_CACHE_HOME=* gh run view * precedent: leading env-prefixes fall out of the auto-allow heuristic. Narrow namespace, sandbox boundaries still bound every write / read / network call.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Parallel to head *: tail is the right-hand-side twin that lives after && / | and would otherwise decline auto-allow.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Allow Bash(docker *) under test-only host assumption; keep run/build/push/login in ask
- Catch synonyms: docker container run, docker image build, docker buildx build, docker image push
- New security.md enumerates 9 trust assumptions as single source for rationale
- Shorten settings.md rationales to link by assumption number (DRY)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Add Bash(echo *) and Bash(head *) to allow list for chained stdout/read primitives.
- Move Bash(for *)/Bash(while *)/Bash(until *) to deny: hard-enforces the
CLAUDE.md loop-forbidden rule so violations fail fast and force refactor
to single-command / grep / xargs forms.
- Drop redundant /tmp/* scoping from Bash(XDG_CACHE_HOME=* gh run view *)
and Bash(tee *); sandbox.filesystem.allowWrite is the authoritative
write boundary, so path restrictions on the allow rule added only
maintenance, no safety.
- Update docs/contributing/tools/agents/claude/settings.md to match.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Why: `make` invocations and `… 2>&1 | tee /tmp/<log>` pipelines regularly
fall outside the sandbox auto-allow heuristic and trigger unnecessary
approval prompts. Adding targeted allow entries removes the friction
while keeping the write scope of `tee` bounded to /tmp.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add explicit Bash allow entries for command shapes that slip past the
sandbox auto-allow heuristic: `gh run list *` (jq pipes in --jq string
confuse the parser), `grep *` (to back the new CLAUDE.md rule against
for-loops around per-file greps), and `wc *` (read-only, any flag).
Reorder permissions.allow strictly ASC so the Bash entries live
alongside the other allow rules in sort order, matching how ask/deny
are laid out. Document the three new entries in settings.md and add
the "prefer flat commands" guidance to CLAUDE.md Code Execution.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add explicit Bash allow entries for command shapes where sandbox
auto-allow does not fire reliably (env-variable prefix, output
redirect, &&-chained subcommands). Document the rationale in the
settings reference so future additions follow the same pattern.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Copy-paste prompt templates with selection matrix routing each workflow
to its SPOT procedure file. Covers development, iteration, testing,
refactor, debug (pipeline/local/log), commit, PR, and requirements.
Consolidate gh ask/deny entries via namespace-wildcard patterns, cover
compound subcommands (item-*, field-*, mark-template*), and add a lint
test that enforces ASCII-sorted permission and sandbox arrays in
.claude/settings.json.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Sandbox network gate already bounds curl to allowedDomains, so the
interactive prompt added no real protection on top. Remove the rule
and the matching docs row.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Collapse explicit per-host entries into *.parent.tld patterns where the
sandbox only needs reach to a single domain family (Ansible, AWS, Docker,
Gitea, GitHub + githubusercontent, gstatic, hCaptcha, infinito, npm,
pythonhosted, Taiga). Apex domains stay listed bare. Sorted ASC with the
wildcard block first.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Network gate does not honor wildcards, so allowedDomains is enumerated
explicitly for every host the agent + tooling actually need. Adds
~/.cache/pip, ~/.venvs, ~/.ansible to allowWrite so the pre-commit
make test hook can install the editable package and run ansible.
Adds host shell / editor / tooling state files to .gitignore (and the
auto-generated .dockerignore mirror) so they never become part of the
working tree. Switches the dependabot coverage test to git ls-files
with an os.walk fallback that derives its skip list from the live
.gitignore, so it stays correct in container test environments
without .git/ while still ignoring untracked host artefacts.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds scripts/install/sandbox.sh, a distro-aware installer for the OS-level
dependencies the Claude Code sandbox backend needs (bubblewrap, socat),
and exposes it through a new `make agent-install` target. Documents the
target in docs/contributing/tools/make.md, scripts/install/README.md, and
the Claude sandbox guide so contributors on a fresh host can bring up a
working sandbox without hand-installing distro packages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Move docs/contributing/tools/agents/claude.md to claude/settings.md
- Split sandbox explanations into claude/sandbox.md, add claude/README.md as index
- Enable OS-level sandbox ("sandbox.enabled: true") for project-wide filesystem isolation
- Fail-closed on missing backend ("sandbox.failIfUnavailable: true") to prevent false-security state when bwrap/sandbox-exec is absent
- Add deny rules: "git clean*", "git branch -D*"
- Remove redundant "Read(~/.cache/pre-commit/**)" allow entry
- Update CLAUDE.md to instruct agent to summarize live permission state from settings.json at session start
- Update AGENTS.md and common.md references to new doc paths
- Normalize .md formatting per documentation.md rules (em dash removal, headline emojis)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Split Bash(gh workflow *) into list/view (allow), run (ask), enable/disable (deny)
- Add Bash(break) to allow list
- Remove duplicate /tmp grant from permissions.additionalDirectories; rely on sandbox.filesystem.allowWrite
- Add AGENTS.md "Temporary Files" rule requiring agents to write transient files only under /tmp
- Reorder .claude/settings.json allow entries into logical sections (Git, GitHub CLI, Build, Python, Ansible, Docker, Shell, Read, Web)
- Document new gh workflow entries, break, and Temporary Files cross-link in docs/contributing/tools/agents/claude.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds `Bash(scripts/*)` so repository helper scripts can be invoked
directly by path (shebang-based), required by inner-loop workflows
such as the Playwright spec rerunner. Adds `Bash(chmod +x scripts/*)`
so newly added scripts can be made executable without approval prompts.
Documents both entries in docs/contributing/tools/agents/claude.md
next to the existing `bash scripts/*` and `source scripts/*` rows.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds `Bash(pkill -f *)` to the allowlist so stuck background commands
(pre-commit hooks, `make test`, `git commit`) can be aborted without an
approval prompt. Broad wildcard consciously accepted — narrow per-pattern
entries required repeated allowlist edits for every new abort scenario.
Adds `Read(~/.cache/pre-commit/**)` so pre-commit's stashed patch files
can be reapplied via `git apply` after a manually killed hook run, and
uses `~` instead of a hardcoded username path.
Documents both entries in docs/contributing/tools/agents/claude.md,
including the explicit risk note that `pkill -f` with a regex can
terminate every user-owned process and should use the narrowest pattern
possible.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replaces two over-specific `Bash(awk ...)` allowlist entries (full paths
and exact patterns that would never match again) with a single
`Bash(awk*)` entry next to `jq*`, consistent with how `grep*`, `find*`,
and `sort*` are allowed. Removes the broken `Read(//var/lib/infinito/logs/**)`
entry: `/var/lib/infinito/` is a named Docker volume defined in
compose.yml and never exists on the host, so host-scoped read access
is meaningless (and the path had a double slash).
Documents the new `awk*` entry in docs/contributing/tools/agents/claude.md
with an explicit note that awk's `system()` and `"cmd" | getline` put
it in the same risk class as the already-allowed `find -exec`.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Reorders all documented and scripted `make` invocations from the
`VAR=value make target` shell-env prefix form to the make-native
`make target VAR=value` form. GNU Make auto-exports both command-line
and inherited shell-env variables to recipe shells, so the change is
purely about command-line shape: only the make-suffix form starts with
`make` and is therefore matched by the `Bash(make*)` permission entry
in .claude/settings.json, avoiding unnecessary approval prompts for
agent runs.
Adds an explicit CLAUDE.md rule with ✅/❌ examples and the underlying
reason (permission prefix match, not Makefile semantics).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds `Bash(bash scripts/*)` and `Bash(source scripts/*)` to the Claude
Code allowlist so repository helper scripts (e.g. env exports in
scripts/meta/env) can run without approval prompts, while still keeping
arbitrary paths scoped to review.
Documents both permissions in docs/contributing/tools/agents/claude.md,
including the caveat that `source` bypasses the allowlist for nested
commands.
Extends CLAUDE.md with an explicit rule that agents MUST prefer `make`
targets over direct docker/ansible/python/script invocations whenever
an equivalent target exists.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds the shell built-in `wait` to the Claude Code allow-list so the agent
can block on background commands started via run_in_background without
prompting for operator approval. Documents the new entry in the Claude
Code settings reference.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Extend .claude/settings.json with git mv, rm, cherry-pick, apply, gh run, gh api, bash -n
- Add make chmod-scripts target and document it in make.md
- Move docs/contributing/tools/agents.md to agents/common.md
- Add docs/contributing/tools/agents/README.md and claude.md with full permission reference in table format
- Fix relative links in common.md after directory move
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Use vars.CI_CANCEL_IN_PROGRESS in entry-push-latest.yml so cancellation
can be disabled per-repo without changing workflow code
- Move docs/contributing/tools/github/branch.md into branch/ subdirectory
as security.md; add configuration.md for CI repository variables and
README.md as directory index
- Fix all cross-references in SECURITY.md, pipeline.md, branch.md,
pull-request.md, workflow.md, and repository.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Keep live registry lookups out of the default make test flow.
Add a dedicated external suite, workflow, and docs so the check stays opt-in but still gates code CI when enabled.
Add tests/lint/repository/test_markdown_links.py — a hard-fail lint
test that scans all git-tracked markdown files for broken relative and
repo-root-absolute links. Skips external URLs, anchor-only links, fenced
code blocks, and placeholder targets.
Apply documentation.md rules to all staged files: add emojis after
headlines in docs files, remove emojis from role README headings,
standardize Credits sections to the canonical format, remove empty
sections and orphaned sentences referring to missing documentation files,
fix raw URLs and incorrect link text across role READMEs and docs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Move emojis after headline text (CONTRIBUTING.md, actions/, design/, tools/, tests/)
- Replace em dashes with colons, semicolons, or complete sentences throughout
- Add missing emojis to all headlines in exceptions.md, principles.md, services.md, shell.md, setup.md, pull-request.md, commit.md, act.md, docker.md, pr/README.md
- Update H1 titles to reflect renamed directories (actions/, design/)
- Fix broken relative links in workflow.md after directory moves
- Fix full-path link texts in services.md (style.css.md, javascript.js.md)
- Fix broken principles.md link to lint.md after testing/ → actions/testing/ move
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- document docs README purpose and scope in a dedicated SPOT
- add scope-focused README.md files across docs directories
- remove lint rule that banned README.md files under docs
- Move flow/security/ghcr.md to tools/ghcr/authentication.md
- Move flow/security/mirror-cleanup.md to tools/ghcr/cleanup.md
- Move flow/security/branch.md to tools/github/branch.md
- Move flow/security/repository.md to tools/github/repository.md
- Move code/frameworks/ansible.md to tools/ansible.md
- Merge code/frameworks/Makefile.md into tools/make.md and extract file rules to artefact/files/makefile.md
- Rename tools/makefile.md to tools/make.md
- Add .github/workflows/images-mirror-cleanup.yml for manual GHCR cleanup
- Apply documentation.md standards: emojis on headlines, no em dashes, filename link text
- Fix all cross-references broken by directory restructuring
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add scripts/install/skills/install.sh to restore skills from
skills-lock.json via npx skills experimental_install
- Add scripts/install/skills/update.sh to update all skills by
re-running skills add for each source in skills-lock.json
- Add make install-skills and make update-skills targets
- Add .github/workflows/update-skills.yml for daily automated updates
matching Dependabot schedule (00:00 UTC), opens PR on lock changes
- Add docs/agents/meta/caveman.md as SPOT for caveman mode, startup
notification, and token-budget tier progression
- Update AGENTS.md with RFC 2119-compliant skills installation check
- Update docs/agents/action/commit.md: replace ALWAYS with MUST
- Update pyproject.toml: respect-gitignore = true, exclude .agents
- Track skills-lock.json and add .agents to .gitignore
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds scripts/lint/autoformat.sh that checks tool availability before
running ruff, shfmt, and shellcheck autofixes. Updates Makefile with
the new autoformat target, documents it in makefile.md, and adds a
commit.md rule requiring autoformat to be run before every commit.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Consolidates into one target. FULL_CYCLE defaults to false (deploy only);
set FULL_CYCLE=true for deploy + update pass. Extracts run_pass function
in fresh-purged-app.sh to eliminate duplicated init+deploy logic. Updates
makefile.md, playwright.md, iteration.md, and environment.sh with correct
FULL_CYCLE usage.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add Recording Tests section: Playwright codegen (built-in) and
playwright-recorder (Docker/X11-based) with usage examples
- Replace duplicated spec/env requirement blocks with links to their
SPOT pages in docs/agents/files/role/
- Extend Development Procedure to include optional recording step
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace per-directory README.md index files with automatic glob toctree
in root index.rst (docs/**). Add lint test that fails if any README.md
appears under docs/. Document the no-README rule in documentation.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Update all Make targets, comments, docs, and scripts to use the plural
form, reflecting that APPS can specify more than one application.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
