chore: post-bootstrap introspect — doc fixes, skills, mutation-safety test

[OriNachum]

Summary

Outcomes from the post-bootstrap introspect after standing up agentculture/irc-lens. Three CLAUDE.md doc fixes, one new pytest module, two new skills.

• Fix CLAUDE.md scope claim — repo is sufficient for PUT /repos/{owner}/{repo}/environments/{name} per GitHub REST docs; verified empirically during the irc-lens bootstrap with a default classic-PAT (no admin:repo_hook). The previous claim sent agents on an unnecessary gh auth refresh round-trip.
• Add gh auth token bridge to CLAUDE.md — one-liner so users with gh already authenticated can drive ghafi without exporting a separate PAT.
• Add Bootstrap walkthrough section to CLAUDE.md — names the four steps in order and surfaces the cite-don't-import surprise: ghafi repo scaffold writes the afi-cli reference template under .afi/reference/python-cli/ rather than instantiating a runnable project.
• tests/test_mutation_safety.py — closes the "no automated check yet — flag it manually" gap from the mutation-safety contract. Six tests assert that every repo {create,scaffold,env} verb has --apply defaulting to False and performs no HTTP writes or subprocess invocations in dry-run.
• .claude/skills/bootstrap-sibling/ — chains repo create → git clone → repo scaffold → repo env (×2) with a dry-run preview phase and confirmation gate. Bridges from gh auth token if no PAT is set.
• .claude/skills/doc-test-align/ — v0 drift detector. Compares CLAUDE.md endpoint mentions against ghafi/ source and verifies the bootstrap walkthrough's verbs match the live argparse tree.

Coverage stays at 85% (gate 60%); all lints clean (black, isort, flake8, bandit, markdownlint, portability-lint, doc-test-align).

Test plan

• uv run pytest -n auto -v — 49 passed

• uv run pytest --cov-fail-under=60 — 85.07% coverage

• uv run black --check ghafi tests — clean

• uv run isort --check-only ghafi tests — clean

• uv run flake8 ghafi tests — clean

• uv run bandit -c pyproject.toml -r ghafi — 0 issues

• markdownlint-cli2 "**/*.md" — 0 errors

• bash .claude/skills/pr-review/scripts/portability-lint.sh — clean

• bash .claude/skills/doc-test-align/scripts/check.sh — no drift detected (dogfooded)

• Version bumped to 0.0.2 (CI version-check gate satisfied)

• Claude

🤖 Generated with Claude Code

[qodo-code-review]

Review Summary by Qodo

Post-bootstrap introspect: mutation-safety tests, skills, and doc fixes

✨ Enhancement 🧪 Tests 📝 Documentation

Walkthroughs

Description

• Add mutation-safety pytest module enforcing --apply defaults to False on all mutating verbs
• Create bootstrap-sibling skill chaining four-step sibling setup with dry-run-then-apply gates
• Add doc-test-align skill detecting drift between CLAUDE.md claims and live code
• Fix CLAUDE.md scope claims: repo sufficient for Environments; admin:repo_hook not needed; add
  gh auth token bridge
• Document complete Bootstrap walkthrough section with four-step path to Trusted-Publishing-ready
  sibling

Diagram

flowchart LR
  A["CLAUDE.md scope claims"] -->|verified against irc-lens bootstrap| B["Fix: repo scope sufficient"]
  B -->|add bridge| C["gh auth token integration"]
  D["New pytest module"] -->|enforce contract| E["--apply defaults to False"]
  E -->|verify dry-run| F["No API/subprocess writes"]
  G["Bootstrap walkthrough section"] -->|chains steps 1-4| H["bootstrap-sibling skill"]
  H -->|dry-run preview| I["Confirmation gate"]
  I -->|--apply| J["Execute mutations"]
  K["doc-test-align skill"] -->|drift detector| L["CLAUDE.md vs code alignment"]

Loading

File Changes

1. tests/test_mutation_safety.py 🧪 Tests +82/-0

Mutation-safety contract enforcement tests

• New pytest module enforcing the mutation-safety contract across all mutating verbs
• Parametrized tests verify --apply flag exists and defaults to False on `repo
 {create,scaffold,env}`
• Behavioral tests assert dry-run modes perform no HTTP writes or subprocess invocations
• Uses http_stub and afi_stub fixtures to detect leaked mutations

tests/test_mutation_safety.py

---

2. .claude/skills/bootstrap-sibling/scripts/bootstrap.sh ✨ Enhancement +126/-0

End-to-end sibling bootstrap orchestration script

• Bash script chains ghafi repo {create,scaffold,env} with git clone in correct order
• Dry-run preview phase shows all four steps before confirmation gate
• Bridges gh auth token to GITHUB_TOKEN if neither env var is set
• Prints manual PyPI trusted-publisher registration checklist at end
• Supports --name, --description, --org, --private, and --apply flags

.claude/skills/bootstrap-sibling/scripts/bootstrap.sh

---

3. .claude/skills/bootstrap-sibling/SKILL.md 📝 Documentation +72/-0

Bootstrap-sibling skill documentation and usage guide

• Documents when to use bootstrap-sibling skill (new sibling creation, post-release verification)
• Explains what the script does: five steps from repo creation to PyPI registration checklist
• Notes that PyPI trusted-publisher registration is manual (web-only, one-time per project)
• Clarifies when not to use (modifying existing sibling, non-agentculture repos)

.claude/skills/bootstrap-sibling/SKILL.md

---

View more (5)

4. .claude/skills/doc-test-align/scripts/check.sh ✨ Enhancement +87/-0

Doc/test alignment drift detector for CLAUDE.md claims

• Bash drift detector comparing CLAUDE.md claims to ghafi/ source code
• Check 1: validates endpoint URL segments mentioned in CLAUDE.md exist in code
• Check 2: introspects live argparse tree to verify bootstrap walkthrough verbs match registered
 verbs
• Check 3: lists scope claims for manual review (v0 stub; v1 to diff against _api annotations)
• Exit codes: 0 (no drift), 1 (drift detected), 2 (script error)

.claude/skills/doc-test-align/scripts/check.sh

---

5. .claude/skills/doc-test-align/SKILL.md 📝 Documentation +67/-0

Doc-test-align skill documentation and scope

• Documents the doc-test-align skill as a v0 stub drift detector
• Specifies when to use: before approving PRs touching CLAUDE.md or repo module, before releases
• Lists three checks: endpoint mentions, bootstrap verb order, scope claims (v0 manual review)
• Clarifies what it does not check: upstream GitHub API changes, endpoint payloads, prose accuracy
• Encourages extending checks as real drift failures surface

.claude/skills/doc-test-align/SKILL.md

---

6. CLAUDE.md 📝 Documentation +40/-4

Scope fixes, auth bridge, and bootstrap walkthrough documentation

• Fix scope claim: repo scope is sufficient for Environments (verified against irc-lens bootstrap)
• Remove incorrect admin:repo_hook requirement from v0.x verbs
• Add GITHUB_TOKEN=$(gh auth token) bridge for users with gh authenticated but no PAT exported
• Add comprehensive Bootstrap walkthrough section documenting four-step path to
 Trusted-Publishing-ready sibling
• Clarify that ghafi repo scaffold uses cite-don't-import pattern (writes template, does not
 instantiate)
• Reference new .claude/skills/bootstrap-sibling/scripts/bootstrap.sh helper script

CLAUDE.md

---

7. CHANGELOG.md 📝 Documentation +18/-0

Version 0.0.2 changelog entry with all changes

• Add v0.0.2 release entry dated 2026-04-27
• Document new skills: doc-test-align and bootstrap-sibling
• Document new mutation-safety pytest module
• List scope fixes: repo sufficient for Environments, admin:repo_hook not needed, `gh auth
 token` bridge added
• Note Bootstrap walkthrough section addition

CHANGELOG.md

---

8. pyproject.toml ⚙️ Configuration changes +1/-1

Version bump to 0.0.2

• Bump version from 0.0.1 to 0.0.2

pyproject.toml

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (2) 📎 Requirement gaps (0)

1. Skill docs use ../<name> 📘 Rule violation ✧ Quality

Description

The new bootstrap-sibling skill documentation instructs cloning into ../<name>, which traverses
outside the repository root. This violates the requirement that Claude skills use only repo-local
path references and avoid .. traversal.

Code

.claude/skills/bootstrap-sibling/SKILL.md[R37-38]

+Run from the `ghafi` repo root. The script will `git clone` the new repo
+into a sibling path next to ghafi (`../<name>`).

Evidence

PR Compliance ID 423932 requires skill directories to avoid absolute paths and any relative paths
containing .. segments, and to keep references inside the repo. The added skill doc explicitly
uses ../<name>, which is an upward traversal outside the repo root.

Rule 423932: Validate Claude skill structure and local-only references
.claude/skills/bootstrap-sibling/SKILL.md[37-38]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`.claude/skills/bootstrap-sibling/SKILL.md` instructs cloning into `../<name>`, which uses `..` traversal and points outside the repository root. Skills must only use repo-local paths and must not include `..` segments.

## Issue Context
Compliance requires skill documentation/config/scripts to avoid external filesystem references and upward directory traversal.

## Fix Focus Areas
- .claude/skills/bootstrap-sibling/SKILL.md[37-38]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. bootstrap.sh calls gh 📘 Rule violation ⌂ Architecture

Description

The new bootstrap-sibling script shells out to gh auth token, introducing a runtime dependency
on the external gh CLI. This violates the requirement that ghafi not depend on the gh CLI for
runtime functionality.

Code

.claude/skills/bootstrap-sibling/scripts/bootstrap.sh[R44-51]

+# Bridge gh auth → GITHUB_TOKEN if not already set.
+if [[ -z "${GITHUB_TOKEN:-}" && -z "${GH_TOKEN:-}" ]]; then
+  if command -v gh >/dev/null 2>&1; then
+    GITHUB_TOKEN="$(gh auth token 2>/dev/null || true)"
+    if [[ -n "$GITHUB_TOKEN" ]]; then
+      export GITHUB_TOKEN
+      echo "note: bridged GITHUB_TOKEN from \`gh auth token\`"
+    fi

Evidence

PR Compliance ID 423934 forbids invoking the gh binary in the ghafi codebase (including scripts)
and forbids documentation/runtime flows that rely on gh for core functionality. The added script
explicitly runs gh auth token to obtain a token at runtime.

Rule 423934: Disallow runtime dependency on external gh CLI in ghafi
.claude/skills/bootstrap-sibling/scripts/bootstrap.sh[44-51]
CLAUDE.md[58-58]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new bootstrap skill script (`bootstrap.sh`) and updated docs introduce a runtime path that depends on the external `gh` CLI (`gh auth token`). Compliance requires `ghafi` to be self-contained and not rely on `gh` for runtime behavior.

## Issue Context
`ghafi` should require tokens via environment variables and perform GitHub interactions via direct HTTP, without spawning `gh`.

## Fix Focus Areas
- .claude/skills/bootstrap-sibling/scripts/bootstrap.sh[44-51]
- CLAUDE.md[58-58]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Clone path targets repo ☑ 🐞 Bug ≡ Correctness

Description

bootstrap-sibling computes TARGET as <ghafi-repo-root>/<name>, so git clone will clone the new
sibling repository inside the ghafi working tree instead of alongside it as documented.

Code

.claude/skills/bootstrap-sibling/scripts/bootstrap.sh[R55-56]

+GHAFI=(uv run ghafi)
+TARGET="$(cd "$(dirname "$0")/../../../.." && pwd)/$NAME"

Evidence

The script’s TARGET is derived from the ghafi repo root and appends $NAME, and git clone uses
that path. The skill documentation explicitly states the clone should be to a sibling directory
(../<name>), so current behavior contradicts the documented contract and will place a full git
repo inside this repo’s tree.

.claude/skills/bootstrap-sibling/scripts/bootstrap.sh[55-99]
.claude/skills/bootstrap-sibling/SKILL.md[35-40]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`bootstrap.sh` clones the new repo into `<ghafi-repo-root>/$NAME`, but the skill and CLAUDE.md describe cloning into a sibling directory `../<name>`. This will pollute the ghafi working tree with a nested git repository.

### Issue Context
The script is intended to bootstrap a sibling repo next to `ghafi`, not inside it.

### Fix Focus Areas
- .claude/skills/bootstrap-sibling/scripts/bootstrap.sh[55-99]
- .claude/skills/bootstrap-sibling/SKILL.md[35-40]

### Suggested change
Compute `REPO_ROOT` and set `TARGET` to the parent directory:
- `REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"`
- `TARGET="$REPO_ROOT/../$NAME"`

Optionally update the plan output to print the normalized sibling target path, and ensure SKILL.md remains consistent.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. No scaffold dry-run preview 🐞 Bug ☼ Reliability

Description

bootstrap-sibling claims every ghafi step is dry-run previewed before applying, but it never
previews ghafi repo scaffold in dry-run mode and exits before that step.

Code

.claude/skills/bootstrap-sibling/scripts/bootstrap.sh[R67-83]

+# Step 1: repo create (always dry-run first; --apply if requested)
+echo "=== Step 1: repo create (dry-run preview) ==="
+"${GHAFI[@]}" repo create --org "$ORG" --description "$DESCRIPTION" $PRIVATE "$NAME"
+echo
+
+# Step 4 + 5 dry-run preview (envs)
+echo "=== Step 4: repo env pypi (dry-run preview) ==="
+"${GHAFI[@]}" repo env --owner "$ORG" --name pypi --branch main "$NAME"
+echo
+echo "=== Step 5: repo env testpypi (dry-run preview) ==="
+"${GHAFI[@]}" repo env --owner "$ORG" --name testpypi "$NAME"
+echo
+
+if [[ -z "$APPLY" ]]; then
+  echo "Dry-run complete. Re-run with --apply to commit."
+  exit 0
+fi

Evidence

In dry-run mode the script runs previews for repo create and both env operations, then exits when
--apply is not set. The scaffold step only appears in the apply block, so the user cannot review
the scaffold invocation during the preview phase even though SKILL.md describes that behavior.

.claude/skills/bootstrap-sibling/scripts/bootstrap.sh[67-110]
.claude/skills/bootstrap-sibling/SKILL.md[4-9]
.claude/skills/bootstrap-sibling/SKILL.md[48-55]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The bootstrap script’s “dry-run preview” omits `ghafi repo scaffold`, despite documentation claiming each ghafi step is previewed before applying.

### Issue Context
`ghafi repo scaffold` dry-run is descriptive-only (no writes), but still valuable to preview the exact command and confirm `afi` presence before committing.

### Fix Focus Areas
- .claude/skills/bootstrap-sibling/scripts/bootstrap.sh[67-110]
- .claude/skills/bootstrap-sibling/SKILL.md[4-9]
- .claude/skills/bootstrap-sibling/SKILL.md[48-55]

### Suggested change
Before the `if [[ -z "$APPLY" ]]` early-exit, add a Step 3 preview:
- `echo "=== Step 3: repo scaffold (dry-run preview) ==="`
- `"${GHAFI[@]}" repo scaffold "$TARGET"`

If you keep the clone step only in apply-mode, it’s still fine to preview scaffold against the intended target path (it won’t write in dry-run). Update SKILL.md wording if needed to match the actual preview set.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. doctest script hides tool failures ☑ 🐞 Bug ☼ Reliability

Description

doc-test-align’s check.sh does not use set -e and does not validate uv run python success, so
missing/broken tooling can be reported as “DRIFT detected” (exit 1) rather than a script error (exit
2) as documented.

Code

.claude/skills/doc-test-align/scripts/check.sh[R7-66]

+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+cd "$REPO_ROOT"
+
+CLAUDE_MD="CLAUDE.md"
+SRC_DIR="ghafi"
+
+if [[ ! -f "$CLAUDE_MD" ]]; then
+  echo "error: $CLAUDE_MD not found in $REPO_ROOT" >&2
+  exit 2
+fi
+
+drift=0
+
+echo "=== Check 1: endpoint prefixes in CLAUDE.md exist in $SRC_DIR/ ==="
+# Pull each endpoint URL from CLAUDE.md, strip {placeholders}, then
+# check that each non-empty static segment is referenced somewhere in
+# ghafi/. Coarse but stable.
+endpoints=$(grep -oE '/(repos|orgs|user)(/[A-Za-z0-9_{}/.:-]+)?' "$CLAUDE_MD" | sort -u)
+if [[ -z "$endpoints" ]]; then
+  echo "  (no endpoint mentions found in $CLAUDE_MD — nothing to check)"
+else
+  while IFS= read -r ep; do
+    # Replace {placeholder} with a separator and extract static segments.
+    cleaned=$(echo "$ep" | sed -E 's|\{[^}]+\}| |g')
+    miss=()
+    for seg in $cleaned; do
+      seg_trim="${seg#/}"
+      seg_trim="${seg_trim%/}"
+      [[ -z "$seg_trim" ]] && continue
+      if ! grep -RqF -- "$seg_trim" "$SRC_DIR/" 2>/dev/null; then
+        miss+=("$seg_trim")
+      fi
+    done
+    if [[ ${#miss[@]} -gt 0 ]]; then
+      echo "  DRIFT: $CLAUDE_MD mentions '$ep' but these segments are absent from $SRC_DIR/: ${miss[*]}"
+      drift=1
+    fi
+  done <<<"$endpoints"
+  if [[ "$drift" -eq 0 ]]; then
+    echo "  OK — every endpoint segment in $CLAUDE_MD has a code match"
+  fi
+fi
+echo
+
+echo "=== Check 2: bootstrap walkthrough verbs match registered verbs ==="
+# Introspect the live parser instead of regex'ing source — robust to
+# multi-line add_parser() calls.
+registered=$(uv run python -c '
+import argparse
+from ghafi.cli import _build_parser
+p = _build_parser()
+sub = next(a for a in p._actions if isinstance(a, argparse._SubParsersAction))
+repo = sub.choices["repo"]
+sub2 = next(a for a in repo._actions if isinstance(a, argparse._SubParsersAction))
+print("\n".join(sorted(sub2.choices.keys())))
+' 2>/dev/null | sort -u)
+mentioned=$(grep -oE 'ghafi repo [a-z]+' "$CLAUDE_MD" \
+            | awk '{print $3}' | sort -u || true)

Evidence

The script enables -u and pipefail but not -e, and captures uv run python ... output into
registered without checking exit status. If uv is missing or the introspection fails,
registered may become empty and the script can fall through to drift logic and exit 1, even though
SKILL.md defines exit 2 for script errors.

.claude/skills/doc-test-align/scripts/check.sh[7-75]
.claude/skills/doc-test-align/SKILL.md[59-64]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`doc-test-align/scripts/check.sh` can misclassify missing/broken tooling as doc drift because it doesn’t fail fast when `uv run python` fails.

### Issue Context
SKILL.md documents exit code `2` for script errors, but the current implementation primarily uses exit `1` for drift and doesn’t explicitly detect dependency/tool failures.

### Fix Focus Areas
- .claude/skills/doc-test-align/scripts/check.sh[7-75]
- .claude/skills/doc-test-align/SKILL.md[59-64]

### Suggested change
Harden the script by:
- Switching to `set -euo pipefail`.
- Adding explicit checks for required tools (e.g., `command -v uv`), and/or wrapping the `uv run python -c ...` in an `if ! ...; then echo "error: ..."; exit 2; fi` guard.
- Ensuring genuine tooling failures exit `2` (script error), reserving `1` for actual drift.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Scope guidance contradicts runtime ☑ 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md states admin:repo_hook is not needed by any v0.x verb, but ghafi’s runtime remediation
messages still instruct users that admin:repo_hook is required for environments/actions, creating
conflicting operator guidance.

Code

CLAUDE.md[R60-64]

+Required scopes (verified against the v0.x verb set):
+
+- `repo` — create user-owned repositories **and manage Environments** (PUT `/repos/{owner}/{repo}/environments/{name}` accepts classic-PAT `repo` per GitHub REST docs; this is what `gh auth login` gives you by default).
+- `admin:org` — only when creating **org-owned** repositories (org membership with create-repo permission is the actual gate; the scope is required for some org configurations).
+- `admin:repo_hook` — **not currently needed** by any v0.x verb. Will be required if/when ghafi grows verbs that write Actions repository permissions or webhooks.

Evidence

The updated CLAUDE.md scope list explicitly says admin:repo_hook is not currently needed. However,
both the “no token in environment” remediation and the HTTP 401/403 remediation string still mention
admin:repo_hook as required for environments/actions, so users will receive contradictory
instructions depending on which message they see.

CLAUDE.md[60-64]
ghafi/_env.py[16-29]
ghafi/_api.py[72-86]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Docs say `admin:repo_hook` is not needed by any current v0.x verb, but runtime remediation strings still claim it is needed. This creates conflicting guidance during auth failures.

### Issue Context
These remediation strings are shown to users on missing token (`ghafi/_env.py`) and on 401/403 (`ghafi/_api.py`). They should match the updated CLAUDE.md guidance.

### Fix Focus Areas
- CLAUDE.md[60-64]
- ghafi/_env.py[16-29]
- ghafi/_api.py[72-86]

### Suggested change
Update remediation text in `ghafi/_env.py` and `ghafi/_api.py` to match the new scope guidance (e.g., emphasize `repo` and `admin:org` for org repo creation) and remove/qualify the `admin:repo_hook` claim per the updated docs.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[Copilot]

Pull request overview

This PR captures post-bootstrap introspection follow-ups by updating project documentation, adding drift/mutation-safety automation, and introducing two new Claude skills to streamline sibling bootstrapping.

Changes:

• Bump project version to 0.0.2 and add a corresponding CHANGELOG entry.
• Add mutation-safety tests to enforce --apply defaults and prevent dry-run side effects.
• Add/update CLAUDE.md guidance plus two new skills: bootstrap-sibling and doc-test-align.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
uv.lock	Updates locked editable package version to 0.0.2.
pyproject.toml	Bumps project version to 0.0.2.
CHANGELOG.md	Adds 0.0.2 release notes covering docs/tests/skills additions.
CLAUDE.md	Fixes auth scope guidance, adds gh auth token bridge, and adds bootstrap walkthrough.
tests/test_mutation_safety.py	Adds contract tests ensuring mutating verbs are safe-by-default (dry-run).
.claude/skills/doc-test-align/scripts/check.sh	Adds a script to detect doc/code drift (endpoints + verbs).
.claude/skills/doc-test-align/SKILL.md	Documents the purpose/usage of the doc drift detector skill.
.claude/skills/bootstrap-sibling/scripts/bootstrap.sh	Adds an end-to-end bootstrap helper script with dry-run preview + apply gate.
.claude/skills/bootstrap-sibling/SKILL.md	Documents the bootstrap helper skill and intended workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.