Skip to content

docs(gate): add the text gate v3 design note and STATUS line #230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
twistedmelonman merged 1 commit into from
Oct 26, 2026
Merged

docs(gate): add the text gate v3 design note and STATUS line #230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions docs/STATUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

**As of 2026-09-16, with 2026-10-01, 2026-10-02 (three), 2026-10-05
(three), 2026-10-06, 2026-10-06/07, 2026-10-07 evening, 2026-10-08,
2026-10-12, 2026-10-13 to 10-16, 2026-10-19 and 2026-10-19 to 10-21
updates below.**
2026-10-12, 2026-10-13 to 10-16, 2026-10-19, 2026-10-19 to 10-21 and
2026-10-22 updates below.**
Point-in-time snapshot of the infrastructure backlog
(`docs/superpowers/specs/2026-09-01-infrastructure-backlog-design.md`). The
design doc is authoritative on *what* each item is and why; this file records
Expand Down Expand Up @@ -671,6 +671,15 @@ or be explicitly parked with a resume note, by then — see the tracker.
`standards/markdownlint.json` drifts from dotfiles. Installed and checked
on ASIAGO, TILSIT and MIMOLETTE.

**2026-10-22 update (Pacific): text gate v3:**

- **Text gate v3 shipped 2026-10-22:** routes are `review | exempt`, Pangram
is out, `gate-lint.sh` (Vale plus length caps) warns on exempt and blocks
on review, and approval works by editor, `approve <code>` in chat, or a
draft PR. Full suites run in CI only for claude-config and dotfiles;
`dev-env#224` reverted the dev-env part. Design note:
`docs/superpowers/specs/2026-10-22-text-gate-v3.md`.

**Kanban tracker: GitHub Issues + a Project board in `smartwatermelon/dev-env`**,
using the org's `Priority`/`Target date`/`Effort` issue fields. Board columns
still need one-time setup (see dev-env issue tracker); this file stays the
Expand Down
90 changes: 90 additions & 0 deletions docs/superpowers/specs/2026-10-22-text-gate-v3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Design: text gate v3

Status: APPROVED 2026-10-22 (Andrew). PRs 1 to 3 merged 2026-10-22; PR 4 and
a personify cleanup PR are landing; PR 5 (docs) is
`claude-config#791`, `dotfiles#467` and the PR that adds this file. Plan of
record: `~/.claude/plans/snuggly-dreaming-stearns.md`. Replaces the Pangram
parts of `2026-10-15-copy-gate-design.md`.

## Problem

The v2 gate had three routes: `exempt`, `visual` (BBEdit approval) and
`pangram` (a Pangram check record plus BBEdit approval). Andrew named four
problems on 2026-10-22:

- Pangram cost money, and its "is this AI?" verdict added nothing. Any
verdict passed; the record only proved the check ran.
- Approval needed BBEdit on a GUI desktop. It failed from SSH, cloud or
phone.
- No deterministic prose checks existed beyond character caps. Dash bans,
phrase lists and sentence length lived only as prose in personify.
- Beacon coverage had holes: code comments, docs, Slack and Asana, and
several `gh` forms.

## Decisions (Andrew, 2026-10-22)

1. Pangram leaves the gate. personify becomes a plain style and voice
advisor; its MCP server stays for cloud agents.
2. Routes are `review | exempt`. Any other outcome is a rules error, so the
gate fails closed.
3. Deterministic lint runs everywhere. Exempt routes get warnings. Review
routes block, and an override needs a stated reason.
4. Approval by any one channel: local editor, `approve <code>` in chat, or a
GitHub draft PR that Andrew marks ready himself.
5. Beacon commit messages: lint at commit; approval happens in the draft PR.
6. `andrewmrich/*`: exempt if private, review if public. A failed visibility
lookup counts as review.
7. Slack and Asana: agents have no write access, so all such text is a draft
Andrew posts. No hook work; agents lint the draft before showing it.

## What shipped

| PR | Repo | What |
|---|---|---|
| `claude-config#771`, `personify#122` | routes | `review \| exempt`; no check record; private `andrewmrich` exempt. personify calls Pangram only on the literal route `pangram`, which no rule produces, so the spend stopped. |
| `dotfiles#459`, `claude-config#772` | lint | `gate-lint.sh` runs `length_check.py` and Vale (`prose/.vale.ini`, style `Andrew`, always by explicit `--config`). Warn on exempt, block on review, `--allow <Rule> --reason <text>` to override a Vale rule. A length cap cannot be allowed. Block mode fails closed when `vale` is missing; Vale 3.24.0 was confirmed on all four machines on 2026-10-22, so there was no warn-only period. |
| `claude-config#773`, `dotfiles#461` | approval | Editor from `GATE_EDITOR` (default BBEdit, fallback `open -t`). With no GUI session, `open` prints a 6-hex code per item and the UserPromptSubmit hook `hook-gate-inline-approve.sh` approves on `approve <code>`. Draft `gh pr create` and pending reviews need lint only. `gh pr ready` and review submits are blocked on review routes. The dotfiles pre-push hook checks text added to a ready Beacon PR. |

Landing, not merged on 2026-10-26:

- claude-config gate v3 PR 4: more `gh` forms, and a block on the GraphQL
ready-for-review mutation in `hook-block-personify.sh`. The dotfiles
`gh-wrapper.sh` already refuses that mutation.
- personify: deletes `scripts/pangram_check.py` and removes the detector
check from the MCP server. Until it merges, claude-config keeps writing
`~/.config/personify/route-command` and guarding it, because personify
still reads it.

## CI-only test suites (same day)

Not part of the gate design, but it shipped in the same window and changed
how agents test:

1. `claude-config#774` and `dotfiles#462` made the full suites refuse outside
CI, and #774 added a required hook that blocked full-suite commands.
`dev-env#223` made the three dev-env tool runners CI-only too.
2. The hook blocked far more than the full suites (`npm test`, `make test`,
bare `pytest`, and suite commands quoted in commit text). `claude-config#775`
removed it. The runner guard in claude-config and dotfiles stays, and
`RUN_FULL_SUITE=1` (`dotfiles#463`, `claude-config#775`) is Andrew's
override for hand runs. Agents never set it.
3. `dev-env#224` reverted #223. Those runners take seconds, and Andrew
wanted only the claude-config and dotfiles full suites blocked. dev-env
tool suites run locally again.

## Boundary

Hooks cover Claude Code sessions only. Text drafted in Claude Desktop or
claude.ai is not gated.

## Open

- Live checks from the plan's Verification section, on ASIAGO and
arich-mac.local, after PR 4 merges.
- Memory updates: `project_personify_gate` and
`feedback_let_hooks_decide_gating` to update;
`feedback_pangram_spend` and `feedback_pangram_ai_verdict_not_final` to
mark superseded.
- The `approve <code>` code is the first 6 hex digits (24 bits) of the
content hash. A restage with other text gets another code unless the
prefix collides.
Loading