issue

Issue — the governed issue door

Raw gh issue close / gh issue comment / gh issue create are forbidden by the fence registry (fence/policy.py, gh-issue-mutate). A mutation goes through this one writer, which does two things the raw command never did: it makes the act, and it records the act on the log with provenance. Reads (gh issue view, gh issue list, gh issue status) stay raw — they are witnessed, not gated (the repo's read/write asymmetry).

Forbidding the raw command does not block this pen: the command_guard watches the Bash tool, and this pen shells out to gh from inside Python where no Bash hook sees it — exactly as raw gh pr is forbidden while pr.py works.

Using

# close an issue with a reason (the reason is posted as a closing comment)
python .claude/skills/issue/issue.py close <number> --reason "<why>" --by <who>

# comment on an issue as a recorded act
python .claude/skills/issue/issue.py comment <number> --body "<text>" --by <who>

--repo <owner/repo> is optional; without it gh infers the repo from the working directory's git remote.

Every invocation ends with a result: done | report | needs-you line:

• done — the gh act succeeded and the provenance record is on the log.
• report — refused: … — the door refused the input (an empty reason, an empty body, or a missing --by): a governed mutation must carry accountability. Nothing reached gh; nothing was recorded.
• needs-you — … — gh itself refused (no such issue, auth, network); surface it.

The teeth

• A governed close carries a reason and a signer (--by), refused at the door otherwise — an unattributed close is exactly what this pen exists to prevent.
• The provenance record lands only after the gh call succeeds: a close GitHub refused is never written as if it happened.
• The record is one append-only event ({"type":"issue.closed"|"issue.commented","number":…,"reason"/"body":…, "by":…,"kind":"issue-governance","id":"evt.…","ts":…}), written through loop.reconcile.append_line — the same line-atomic, torn-tail tolerant writer as the rest of the log.

Boundaries

• Outward reach (gh) lives here, in the pen, never in loop/ (which is network-free) — like reflect.py and gate.py.
• This pen is for deliberate, recorded issue acts a session takes by hand. The owner-stamp-queue mirror stays the reflector pen's (reflect.py); a gate's run-issue stays the gate pen's (gate.py).
• Reads are not in scope — a session may always look (gh issue view, gh issue list).
• The §10 proof is tests/test_issue_pen.py: the pen records a well-formed event and refuses an empty reason / missing signer (no reach, no record), and the live command_guard denies gh issue close while passing gh issue view/list — the hole, closed and proven non-vacuous.