return-path-gate

Files (1)

• SKILL.md

SKILL.md (first lines)

# return-path-gate — Skill Chain Closure Audit

A skill chain is CLOSED when the callee's verdict folds back into the caller's decision logic. A chain is OPEN (fire-and-forget) when the caller dispatches a downstream skill but proceeds independently of the result.

This skill audits `§Chains` and `§Done When` sections across SKILL.md files to detect OPEN chains and prescribe specific closures.

## Role Separation from harness-doctor

| Dimension | harness-doctor | return-path-gate |
|---|---|---|
| **What it checks** | Structural completeness (files, references, line counts, drift) | Chain closure compliance (caller/callee verdict handoff) |
| **Core question** | "Are the required harness files present and consistent?" | "Does the caller wait for the callee's verdict?" |
| **Failure mode detected** | Missing CLAUDE.md, broken refs, complexity drift | Fire-and-forget chains, unverified CONDITIONAL_PASS conditions |
| **Output** | L1–L5 structural health report | CLOSED/OPEN chain table with fix prescriptions |

---

## Trigger Phrases

| Phrase | Situation |
|---|---|
| "chain audit", "chain closure audit" | Full scan of all skill chains in plugins/ |
| "return-path check", "return-path gate" | Explicit compliance audit |
| "fire-and-forget detection", "fire-and-forget chain" | Targeting known anti-pattern |
| "skill chain compliance" | Pre-flight check before pipeline execution |
| "does this skill wait for verdict" | Single-skill targeted check |
| "check chains in [skill-name]" | Scoped audit on a named skill |
| `/return-path-gate` | Explicit call |

---

## Audit Scope Options

| Flag | Scope | When to use |
|---|---|---|
| `--skill [name]` | Single named skill | Targeted check during development |
| `--all` | All SKILL.md files under `plugins/` | Full compliance sweep |
| `--pr` | Skills changed relative to `origin/main` | Pre-PR gate mode (worktree-aware) |
| *(default)* | Modified + newly added SKILL.md files in working tree | Pre-commit gate mode |

---

## Execution Steps

### Step 0. Determine Scope

```bash
# Default: modified and newly added SKILL.md files in working tree
{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } | grep "SKILL\.md"

# --pr mode: PR-relative, worktree-aware (use for pre-PR audits)
git diff --name-only origin/main...HEAD | grep "SKILL\.md"

# --all: full scan
find plugins/ -name "SKILL.md" | sort

# --skill [name]: targeted
find plugins/ -path "*[name]/SKILL.md"
```

If 0 SKILL.md files are in scope, **distinguish the two causes before stopping** — a failed scope
command and a genuinely empty scope both render as zero lines, and only one of them is skippable:

```bash
git rev-parse --git-dir >/dev/null 2>&1 \
  || { echo "HARNESS_ERROR: git unavailable — scope could NOT be measured (not an empty scope)"; exit 10; }

# Repo-liveness alone is NOT enough: a broken ref (e.g. missing origin/main in --pr mode) fails the
# scope command with rc=1 and empty output while rev-parse stays green. Capture the scope command's
# OWN exit status — before the grep, which legitimately returns 1 on no-match:
scope_out=$(git diff --name-only origin/main...HEAD 2>&1); scope_rc=$?
[ "$scope_rc" -ne 0 ] \
  && { echo "HARNESS_ERROR: scope command failed (rc=$scope_rc): $scope_out"; exit 10; }
printf '%s\n' "$scope_out" | grep "SKILL\.md"
# (same rc-capture shape applies to the default and --all scope commands)
```

With both controls green and genuinely 0 files in scope, output:
"No SKILL.md files in scope — audit skipped (control: git rev-parse OK)." and stop.
A HARNESS_ERROR is a distinct non-pass — it must never be reported as "audit skipped", because this
skill is pipeline-conductor's Step 0.5 pre-flight and a tooling-down skip would render as a pass there.

---

### Step 1. Extract Chain Declarations

For each SKILL.md in scope, extract:

1. **`§Chains` section** — every `→ [skill-name]` reference (downstream dispatch)
2. **`§Done When` section** — completion conditions listed by the caller

**Two-pass extraction** (mandatory — do not conflate the two passes):

**Pass A — Caller-wait signals** (look for in §Done When of the *caller* skill):
```
"wait for"          ← waits for callee verdict before proceeding
"verdict received"
"folds back"
"gates on"
"callee returns"
```
These signals indicate the caller waits for the callee's verdict. They are the primary CLOSED gate.

**Pass B — Callee-output signals** (look for in §Done When of the *callee* skill):
```
Verdict: PASS | CONDITIONAL_PASS | FAIL | ESCALATE
```
These signals indicate the callee emits a structured verdict. They confirm the callee side is closeable. They do **not** indicate the caller waits — treat as callee-role evidence only and never conflate with Pass A.

**Step 1 output**:

```
## Step 1 — Chain Extraction

Skill: [skill-name]
  §Chains dispatches: → [callee-1], → [callee-2]
  §Done When (Pass A — caller-wait signals): [extracted text or "none"]
  [callee-1] §Done When (Pass B — callee-output signals): [extracted text or "none"]
```

From chrono-meta/forge-harness, MIT.

More from chrono-meta/forge-harness