slice-land

Files (2)

• SKILL.md
• land.py

SKILL.md (first lines)

> Spec 007 created this skill from scratch. The deterministic readiness
> checks + report generation live in `land.py`; this SKILL.md drives the
> judgment layer (when to invoke, how to interpret blockers, what mode to
> pick).

## What this skill does

Closes the worktree-drift gap: every slice in jig today commits to a
worktree branch and stays there until a human remembers to merge. The
skill provides a deterministic landing path:

- **Verify** the slice is actually done — STATUS=DONE in spec.md, full
  test suite green, deviation log section present, DoD checkboxes all
  ticked.
- **Emit** a structured markdown report with five readiness checks
  (STATUS=DONE, tests green, deviation log present, DoD ticked, and the
  Class-A cross-ref backstop — spec 112: refuse when the slice/ADR is already
  integrated on `origin/main`, `JIG_CROSSREF_GATE=0` to bypass) and
  (in `--mode direct` or `--mode pr`) a Next-steps section of suggested
  git commands.

`prepare` is **non-destructive on git state**: it may read branch state and
fetch `origin/main` to surface a branch-freshness warning, but it never
switches branches, merges, pushes, or removes worktrees.  `execute --mode
direct` runs the destructive merge sequence by pushing the current branch to
`origin/main`, then fast-forwards the canonical local `main` worktree to
`origin/main` or reports why local sync was skipped (slice 007-02 + 081-01);
`execute --mode pr` runs the destructive push + PR-open sequence (slice
007-03).  `git worktree remove` and `gh pr merge` are never executed — both
stay user-driven post-landing suggestions.

## How to use

### Run the readiness check

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/slice-land/land.py" prepare \
  <path-to-spec.md> <slice-fragment> [--mode {direct,pr}]
```

- `spec.md` — path to the spec file (e.g. `docs/specs/007-slice-land/spec.md`).
- `<slice-fragment>` — case-insensitive substring against `## Slice X — Y`
  headings. Same lenient match as `workflow.py transition`.
- `--mode` — optional. Without it, only the readiness check runs.
  - `direct` — for solo / merge-to-main projects. Suggested commands:
    push the branch to `origin/main`, then fast-forward local `main` to
    `origin/main` when a clean canonical `main` worktree exists.
  - `pr` — for team / PR-shaped flows. Suggested commands: `git push -u
    origin <branch> && gh pr create --body-file <path>`. A PR body is
    written to `/tmp/jig-slice-<NNN-NN>-pr-body.md` containing the
    slice's ACs and a deviation-log excerpt.

### Run the merge sequence (execute --mode direct)

After `prepare` confirms the slice is ready, `execute --mode direct`
runs the direct landing sequence:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/slice-land/land.py" execute \
  --mode direct <path-to-spec.md> <slice-fragment> [--dry-run]
```

- `--dry-run` — print the git commands that would run without executing
  them. Use this for a final sanity check before committing.
- Without `--dry-run` — runs `git push origin <branch>:main` from the
  current worktree after the fast-forward guard passes, then fetches and
  fast-forwards the canonical local worktree checked out at
  `refs/heads/main` to `origin/main` when that worktree exists and is
  clean. The caller's feature/detached worktree is not switched to `main`.
  Stops and reports if the authoritative push fails. If the post-push
  local sync cannot run because `main` is missing, dirty, locked, diverged,
  or unavailable, the report says
  `local main sync skipped: <reason>` while preserving the successful
  authoritative push. Never runs `git worktree remove` (printed as a
  post-landing suggestion only).

**Safety guards** (checked before any git mutation):
- Refuses if current branch is `main` or `master`.
- Refuses if `main` has diverged (fast-forward not possible).

### Open the PR (execute --mode pr)

For PR-shaped flows, `execute --mode pr` pushes the branch and opens
the PR via the GitHub CLI:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/slice-land/land.py" execute \
  --mode pr <path-to-spec.md> <slice-fragment> [--dry-run]
```

- `--dry-run` — print the commands that would run, write the PR body
  file for inspection, but do NOT push or open the PR.
- Without `--dry-run` — runs `git push -u origin <branch>` followed by
  `gh pr create --title "<title>" --body-file <body-path>`.  Stops if
  push fails (gh is NOT called after push failure).  Title shape is
  `feat(<scope>): <subject>`: scope comes from a single `skill:`
  frontmatter value or falls back to the spec directory slug, and subject
  drops the numeric slice prefix so the PR-title workflow accepts it.
- Push runs from the **current worktree** (not the main worktree root,
  since the feature branch is checked out here).
- Never runs `gh pr merge` (printed as a post-landing suggestion only).
- Local `main` sync is pending until the PR actually merges. PR mode never
  claims local `main` was updated before `origin/main` moves.

**Safety guards** (checked before any subprocess mutation):
- Refuses if current branch is `main` or `master`.
- Refuses if `gh` CLI is not on PATH (install instructions printed).
- Refuses if `origin` does not point at github.com (HTTPS or SSH form).

### Exit codes

- `0` — all five readiness checks pass; the slice is ready to land
  (for `prepare`) or was merged successfully (for `execute`).
- `1` — at least one check failed, a safety guard fired, or a git
  command failed (the report still emits; the user sees what's wrong).
- `2` — user error (missing spec, ambiguous fragment, invalid `--mode`).

### Test-check warnings

From ramboz/jig, MIT.

More from ramboz/jig