tars-backlog-prepare

Files (1)

• SKILL.md

SKILL.md (first lines)

# Backlog Prepare

Prepare the repository for a fresh run of the `tars-backlog-loop` by verifying the shared git state is uncorrupted, resolving where isolated spoke workspaces will live, proving the verification gate recipe against the current baseline, and cleaning up orphaned workspaces and subagent branches.

## Targets and Pre-conditions

- This skill modifies the local git repository state and writes `.tars/run.env` (and may create `.tars/config.yaml` only if you are documenting a new override - do not invent policy without need).
- Run every step in order. Steps 1 through 4 are preconditions; abort the whole preparation if any of them fails rather than continuing with a warning.
- **Config vs run.env (strict split):**
  - **`.tars/config.yaml`** - project **policy** (stable across runs). Humans edit this. Prepare reads it; implement does **not**.
  - **`.tars/run.env`** - **run facts** frozen for this prepare. Prepare writes it every run; implement, `tars-gate`, and `tars-spoke` read **only** this file for paths, commands, land template, CI flags, and weaken banners.

## Configuration schema (`.tars/config.yaml`)

Policy keys and skill defaults. Omit any key to keep the default. Prepare merges repo config over these defaults, then freezes concrete values into `run.env`.

```yaml
worktree:
  spoke_dir: null # or absolute path; overrides TARS_SPOKE_DIR env
  sync_markers: [] # extra replicated-folder markers
  shared_append_files:
    - "project-words.txt"
    - "CHANGELOG.md"
  transfer_files:
    - ".pre-commit-config.yaml"
    - ".env*"
    - ".tars/"
    - "devenv.local.nix"
    - "devenv.local.yaml"

concurrency:
  heavy_commands:
    - "test"
    - "coverage"
    - "run -a"
    - "--all-files"
    - "nix build"

# Opaque command overrides (optional). When set, prepare uses them instead of
# auto-detect - still wraps with devenv enter when applicable, still smokes them.
commands:
  install: null
  hooks: null
  test: null
  # Optional pre-dispatch ticket linter. See "Ticket lint contract" in step 4c.
  # Receives the batch number, runs against the working tree, exits non-zero on
  # a batch with errors. Null (the default) means no pre-dispatch check exists.
  ticket_lint: null

land:
  # {{id}} and {{title}} are substituted by the Hub at merge time.
  subject_template: "chore(backlog): land ticket {{id}}"

review:
  always_full:
    - "hooks/**"
    - "**/*secret*"
    - "**/auth/**"
  # Full dual-axis review when risk: high, post-conflict, rework attempts >= 2,
  # or diff touches always_full. Otherwise Hub lightweight checklist.

ci:
  # null = auto-detect in prepare. true/false force on/off.
  check: null
  block_on_red: true
  # Optional opaque check command; when null, prepare may set a gh-based default.
  command: null

gate:
  # If true, prepare may record a weakened test command after classifying
  # baseline-red product/coverage failure. Still requires reason in run.env.
  allow_weaken: true
```

Implement never re-opens this file for gate, land, or CI decisions - only the frozen `run.env` keys.

## Preparation Workflow

### 1. Shared Git Integrity Check

> Run this **first**, before any other git command. A redirected working tree makes `git status`, `git branch`, and `git diff` report on a different directory entirely, so every later check in this skill would be reading someone else's files without saying so.

The backlog pipeline gives each spoke a private clone precisely so that no spoke can write to the parent's git state. That does not make this check redundant. External tools still reach the shared git directory - most notably a file-sync daemon replicating `.git/config` and `.git/hooks/` between machines, which is outside this pipeline's control - and repositories that ran earlier worktree-based versions of these skills may still carry damage.

1. **Detect a redirected working tree**:

   ```bash
   git config --local --get-all core.worktree
   ```

   Any value here is damage: it silently redirects every git command in this repository at another directory. Repair it by unsetting the key, then re-run the command to confirm it is gone:

   ```bash
   git config --local --unset-all core.worktree
   ```

2. **Detect a redirected hooks directory**:

   ```bash
   git config --local --get core.hooksPath
   ```

   Unset it if it points anywhere outside this repository. Leave it alone if it resolves inside the repository, since that may be a deliberate project setting.

3. **Detect hijacked hook shims**: hook installers (`prek`, `pre-commit`, `lefthook`) bake an **absolute** path into each shim they write, and `.git/hooks/` is shared by every linked worktree. A shim installed from anywhere other than the repository root therefore points the whole repository at a foreign config.

   ```bash
   REPO_ROOT="$(git rev-parse --show-toplevel)"
   GIT_COMMON="$(git rev-parse --git-common-dir)"
   # Any absolute path in a shim that does not point inside $REPO_ROOT is suspect.
   grep -o -- '/[^"'\'' ]*' "$GIT_COMMON"/hooks/* 2>/dev/null | grep -v "$REPO_ROOT"
   ```

   For each matching shim, read the baked path. If it is not exactly `$REPO_ROOT/.pre-commit-config.yaml`, repair it. Write through a temporary file rather than editing in place, because `sed -i` takes an argument on BSD/macOS and none on GNU, so the in-place form is not portable:

   ```bash
   sed 's|--config="[^"]*"|--config="'"$REPO_ROOT"'/.pre-commit-config.yaml"|' \
     "$hook" > "$hook.tars-tmp" && mv "$hook.tars-tmp" "$hook" && chmod +x "$hook"
   ```

From MAHDTech/agent-skills, MIT.

More from MAHDTech/agent-skills