akc-cycleCAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

mkdir -p ~/.claude/rules
curl -fsSL -o ~/.claude/rules/akc-cycle.md \
https://raw.githubusercontent.com/shimo4228/akc-cycle/main/rules/common/akc-cycle.md

/plugin marketplace add shimo4228/akc-cycle
/plugin install akc-cycle@akc-cy

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: adr-writer
description: "Record a design decision as an ADR in the repo's docs/adr/, or decide whether it clears the filing bar or belongs in a note or the commit body. Use when recording a decision (ADR にして), or when context-sync finds a buried decision."
user-invocable: true
origin: shimo4228
---

# ADR Writer

Capture a design decision as a numbered ADR with consistent structure. The skill handles the boilerplate (directory detection, sequence numbering, index update) in scripted steps, and the main loop writes the prose.

## Why the main loop writes

Deterministic concerns — where the ADR goes, what number it gets, which index needs updating — are easy to get wrong silently (number collisions, sub-directory cwd confusion, index drift), so they live in scripted steps. The prose is written by the main loop that holds the decision: rendering to the house template is cheap for it, and the decision packet (Step 3) is the discipline that keeps *decide* and *render* apart — the packet is settled first, the file is a faithful expression of it, nothing is inferred while writing. A writer renders a decision; it does not make one. The evidence script (Step 4.5) is the fidelity check.

## When to Use (filing conditions — canonical)

Write a new ADR only when the decision meets **all three**:

  - **hard to reverse** — undoing it means changing other artifacts (skills, rules, hooks, scripts) or public outputs too. Being revertible with git alone does not count as easy: nearly every harness change is git-revertible
  - **surprising without context** — a future reader would ask "why is it like this?"
  - **the result of a real trade-off** — chosen between genuine alternatives

"Hard to reverse" is met by most harness changes, so it mainly excludes changes whose effects stay local; "surprising" and "real trade-off" do the filtering.

Superseding or weakening a prior ADR does not by itself call for a new ADR. When the decision that changes it meets all three, write the new ADR (and flip the old Status or add a dated Note — Edge cases). When it does not, add a dated Note under the affected section of the old ADR — `> **注記(YYYY-MM-DD, commit「<subject>」)**: <what changed and what still stands>` — and record the decision in the same commit's body (below). The old ADR then never reads as current when it is not.

Entry points: the user says "let's ADR this" / "record this decision", `context-sync` Phase 3 surfaced a buried decision, a debate concluded and the outcome must outlive the session. Apply the three conditions to the request; when they do not all hold, say so and use the commit body (plus the Note when a prior ADR is affected).

## When NOT to Use — the commit body carries it

Everything else is recorded in the commit body, in three lines, so `git log --grep` finds it later:

```
Context: <what was observed, with its source>
Decision: <what changed, as a commitment>
Review-when: <the observation that would void it, or "none — record">
```

This covers bug fixes, reversible refactors, wording changes to rules / skills that nothing else cites, stocktake outcomes (retire / keep verdicts — the stocktake's own results file plus the commit), and personal preferences. When a commit-body decision later gets superseded or cited by another artifact, promote it: write the ADR then, quoting the commit.

## Workflow

### Step 1: Resolve the ADR directory

```bash
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || REPO_ROOT="$(pwd)"
ADR_DIR="$REPO_ROOT/docs/adr"
```

If `$ADR_DIR` does not exist, create it — the ADR request itself covers the directory, and
git makes it reversible. Mention the creation in your final report. Write a minimal
`README.md` index alongside:

````markdown
# Architecture Decision Records

## Index

| ADR | Title | Status | Date |
|-----|-------|--------|------|

## Template

ADRs in this repository use the 7-section template
(`scripts/adr_lint.py` checks section presence mechanically):

```markdown
# ADR-NNNN: [Title]

## Status
proposed | accepted | superseded | deprecated

## Date
YYYY-MM-DD

## Context
[what was the problem]

## Decision
[what was decided]

## Review-when
[expiry conditions — an ADR is a dated hypothesis, not a permanent constraint]

## Alternatives Considered
[rejected options and why]

## Consequences
[what becomes easier / harder]
```

File name: `NNNN-kebab-case-title.md` (zero-padded 4-digit sequence).
Index rows link the number: `| [NNNN](NNNN-slug.md) | Title | status | YYYY-MM-DD |`.
````

(Index rows make the number a relative link — the same form as existing indexes such as harness / CA.
`adr_lint.py` reads the expected section set from this README's Template fenced block, so
placing the README doubles as the lint's template declaration.)


### Step 2: Pick the next sequence number

```bash
LAST_NUM=$(ls "$ADR_DIR"/[0-9]*-*.md 2>/dev/null | sort -V | tail -1 | sed -E 's|.*/([0-9]+)-.*|\1|')
if [ -z "$LAST_NUM" ]; then
  NEXT_NUM="0001"
else
  NEXT_NUM=$(printf "%04d" $((10#$LAST_NUM + 1)))
fi
```

Verify uniqueness right before writing (race safety):

```bash
[ -e "$ADR_DIR/$NEXT_NUM-"*.md ] && echo "COLLISION" || echo "OK"
```

If `COLLISION`, recompute `NEXT_NUM` from the latest state.

### Step 3: Gather the 7 inputs

Ask the user (or accept from caller) for:

1. **Title** — short, kebab-case-friendly (e.g., `context-sync-cascade-and-writer-agents`). The skill will compose the filename.
2. **Status** — `proposed | accepted | superseded | deprecated`. Default `accepted`.
3. **Context** — what problem prompted this decision (raw text OK).
4. **Decision** — what was decided (raw text OK).
5. **Review-when** — the expiry conditions: which observation or premise failure would void or weaken this decision, 1-3 lines. It can only be captured at write time; an ADR without it reads as permanent. If there genuinely is none, say so explicitly and write "none — a record, not a permanent decision".
6. **Alternatives** — what else was considered and w

CAUTIONgrade B · trust 88/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

declared (1 observation(s))

Network

declared (5 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (11)

`permissions: contents: read` / `persist-credentials: false` / a secret scan job over the whole history

refused = _apply_files(tmp_path, [("a/../../escaped.txt", "x"), ("/tmp/absolute.txt", "x")])

skipped = _apply_setup_commands(tmp_path, ("mkdir -p ../../escaped",))

("mkdir -p missing/../../OUTSIDE/pwned-dir", "touch other/../../OUTSIDE/pwned-file"),

written = place_skill(tmp_path, ("evil/../../escape", "x"))

"http://169.254.169.254/latest/meta-data/",

"http://127.0.0.1:9/admin",

"http://169.254.169.254/latest/meta-data/",

"https://0.0.0.0/",

assert ul._NoRedirect().redirect_request(None, None, 302, "", {}, "http://127.0.0.1/") is None

assert ul.is_internal_host("https://93.184.216.34/x") is False

Gates applied: no_behavioural_pass.