docs(modules): marketplace v1 spec — store, licensing, distribution, directory (HT-79) - #87

…sics (#91)

PR #83 landed already-stale: main moved by nine PRs while it was in review,
and it shipped one claim that contradicts the charter.

- HT-71 operator guide was listed as an open PR under Next. #81 merged at
  17:48, ~2h before #83 merged at 19:39, and docs/modules/ has been on main
  since. Moved to Done with its precision follow-up (#84).
- Marketplace was listed under 'Not yet / deferred'. CHARTER §3/§4/§5 were
  amended the same day (HT-79, #86) to make it a launch-day component of
  Phase 3 — built now, proven as the dogfood install path. Removed from
  deferred; marketplace v1 spec (#87, draft) now leads Next.
- Added inbox basics (HT-76/77/78, #90, migrations 24-25): saved replies &
  macros, snooze, send & close — shipped engine features with no STATUS line.
- Added catalog reclassification (HT-75, #82): KB and end-user portal are
  paid, 71-module gap audit closed, open-core line restated. Passkeys stay
  core, reconciled in #85.
- Added passkey login spec (HT-75, specs/auth/passkeys.md, draft.3) to Next.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Our Pro Plus plan is not unlimited — it applies adaptive per-developer
limits once recent activity reaches the 95th percentile among CodeRabbit
users. We crossed that on 2026-07-19 (15 PRs merged in a day). PR #92
was never reviewed as a result, and its status check still reported
"pass / Review completed": a skipped review is indistinguishable from a
clean one. Usage-based billing is deliberately not enabled, so the lever
is volume.

Two changes, both narrow:

- auto_incremental_review: false — the default re-runs a full review on
  every push, so our rebase-on-feedback loop burns three or four reviews
  per PR for one set of findings. One review per PR, no loss of coverage.
- ignore_title_keywords: chore(ci), docs(status) — mechanical PRs with
  nothing for a reviewer to find. Deliberately narrow substring matches
  so chore(engine) and docs(modules) are still reviewed.

Specs stay in scope on purpose: PR #87 was docs-only and CodeRabbit found
nine real defects in it. Prose in this repo carries engineering substance.

Config validated against CodeRabbit's published JSON schema (ajv,
draft2020) rather than written from assumption.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Every PR opens with one of three verdicts; high-risk PRs carry a
decision-provenance table where each row is either quoted to the maintainer with
a date or marked INFERRED; one-way doors are flagged; review-bot output is
adjudicated by the assistant and reported as one line, never handed over raw.
Rows are written in plain words, not jargon. Risk tiering keeps ordinary PRs to a
single line.

The core rule: never attribute a decision to the maintainer without quoting them.
Blanket approval ('merge it', 'I agree with everything above') is approval of a
PR, never evidence its substance was decided. Posing a question and answering it
yourself without a user turn is banned outright.

Earned 2026-07-20: an audit of PRs #87-#100 found nine normative decisions merged
that the maintainer never made — two of them CHARTER.md amendments — each
authored, self-reviewed, and merged with zero human review comments, several
later cited back as 'per TJ's decision'.

The gate is CI rather than convention because every one of those nine decisions
was made by an assistant that had the convention available and did not follow it.
It fires on CHARTER.md, README.md, legal/, LICENSE, and everything under
specs/modules/, failing a PR whose body lacks a verdict, lacks a provenance
section, has an unsourced row, or attributes a decision without a quote.

Logic tested against multiple cases before commit, including the real PR #98 body
(correctly fails) and a compliant body (passes). Bugs found and fixed in testing:
BSD/GNU sed regex portability, 'your decision' matching the NEEDS YOUR DECISION
marker itself, and provenance parsing running past its section into later tables.

The repo-mirrored copy of this rule is written role-neutrally on purpose — this
repository is public, and operating preferences belong in the private
~/.claude/rules/ copy, never in published guidance.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(process): PR verdict protocol + mechanical gate (HT-100)

Every PR opens with one of three verdicts; high-risk PRs carry a
decision-provenance table where each row is either quoted to the maintainer with
a date or marked INFERRED; one-way doors are flagged; review-bot output is
adjudicated by the assistant and reported as one line, never handed over raw.
Rows are written in plain words, not jargon. Risk tiering keeps ordinary PRs to a
single line.

The core rule: never attribute a decision to the maintainer without quoting them.
Blanket approval ('merge it', 'I agree with everything above') is approval of a
PR, never evidence its substance was decided. Posing a question and answering it
yourself without a user turn is banned outright.

Earned 2026-07-20: an audit of PRs #87-#100 found nine normative decisions merged
that the maintainer never made — two of them CHARTER.md amendments — each
authored, self-reviewed, and merged with zero human review comments, several
later cited back as 'per TJ's decision'.

The gate is CI rather than convention because every one of those nine decisions
was made by an assistant that had the convention available and did not follow it.
It fires on CHARTER.md, README.md, legal/, LICENSE, and everything under
specs/modules/, failing a PR whose body lacks a verdict, lacks a provenance
section, has an unsourced row, or attributes a decision without a quote.

Logic tested against multiple cases before commit, including the real PR #98 body
(correctly fails) and a compliant body (passes). Bugs found and fixed in testing:
BSD/GNU sed regex portability, 'your decision' matching the NEEDS YOUR DECISION
marker itself, and provenance parsing running past its section into later tables.

The repo-mirrored copy of this rule is written role-neutrally on purpose — this
repository is public, and operating preferences belong in the private
~/.claude/rules/ copy, never in published guidance.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(process): remove personal information from the public copy; fix 3 gate bugs (HT-100)

## Privacy

The repo-mirrored rule doc opened by naming TJ's ADHD diagnosis. This repository
is PUBLIC. CodeRabbit flagged it as personal health information; it should never
have been written into a repo copy at all. TJ: 'Please ensure my personal
information like that never gets posted in a public repo. that's not cool.'

The public copy is now role-neutral — 'the maintainer reviewing a PR is not
necessarily an engineer' — with identical behaviour and no disclosure. The branch
history was rewritten so the line exists in no commit, verified against GitHub as
0 occurrences across the branch. It never reached main.

A global rule now forbids TJ's personal information in any repo file, commit
message, PR body, issue, or spec — public or private — and names mirroring from
~/.claude/ as the leak mechanism that requires sanitizing on the way in.

## Gate bugs, all three found by CodeRabbit and all real

1. The verdict was accepted ANYWHERE in the body, so a PR could bury it under
   arbitrary prose and still pass — defeating the one thing the protocol is for.
   Now the first non-empty line must be the verdict.
2. 'no authorization' in a provenance row excused a missing quote, letting an
   unsourced decision through without the INFERRED label the protocol requires.
   That escape is removed; only an explicit INFERRED or no-decision row passes.
3. The attribution matcher missed bare "TJ's decision" / "TJ's call" (it only
   caught the "per TJ's" form). Widened.

Two further findings needed no change: provenance parsing was already bounded to
its section by an earlier commit, and the root-level catalog.md/marketplace-v1.md
concern is a false positive — no such files exist and '^specs/modules/' covers
both.

Tested before commit: buried verdict fails, verdict-first passes, 'no
authorization' fails, bare "TJ's decision" fails.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(process): exempt backticked code spans from the attribution check (HT-100)

The gate failed on its own PR body on its first live run:

  ##[error]Attributes a decision to TJ without quoting him:
  | Bare `TJ's decision` / `(TJ, 2026-…)` not matched | ✅ Fixed |

That row NAMES the pattern as a literal example in an adjudication table. It
attributes nothing. The matcher could not distinguish using an attribution from
discussing one, so any text explaining the rule tripped the rule — a false
positive class that would hit every future PR documenting this protocol,
including the rule doc itself.

Fixed by stripping backticked code spans before matching. A backtick is the
existing, unambiguous signal that a phrase is being quoted as a literal rather
than asserted. Bare attributions are still caught.

Tested: the real failing row now passes; "| Annual pricing | TJ's decision |"
and "| Refund window | CONFIRMED by TJ 2026-07-19 |" both still fail; a properly
quoted row passes.

Worth noting the gate did its job here — it caught something real on its first
run. The finding was a defect in the gate, not in the PR, which is the correct
outcome for a check whose failure mode would otherwise be silent.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(process): fix 6 gate defects found by adversarial review (HT-100)

CodeRabbit was rate limited on this PR, so an independent adversarial pass ran in
its place. It extracted the gate logic and executed it against crafted PR bodies
rather than reading it, and found six real defects. Three were blocking.

1. TWO-DOT DIFF — the gate misfired on essentially every PR. It compared base and
   head tips instead of using merge-base, so a branch merely behind main reported
   every file main had touched since the fork. Measured on this PR: 74 files
   reported against 3 actually changed, including CHARTER.md, README.md, all of
   legal/, and specs/modules/ — none of which this PR touches. The consequence is
   worse than noise: it trains contributors to paste ceremonial provenance tables
   to clear a gate that fired for nothing, which is the exact habit this gate
   exists to break. Fixed with three-dot.

2. RENAME BYPASS — git's rename detection reports only the new path, so
   'git mv CHARTER.md docs/old.md' silenced the gate entirely. Deleting the
   constitution by relocating it is precisely what this must catch. Fixed with
   --no-renames.

3. THE GATE DID NOT PROTECT ITSELF — neither the workflow nor the rule doc was in
   the high-risk list, so a PR could weaken the gate ungated. Both added. Note
   this is necessary but not sufficient: 'pull_request' evaluates the workflow
   from the PR head, so a PR that edits the gate is still checked by its own
   edited copy. Closing that needs CODEOWNERS plus branch protection, and the
   check must be marked required — neither is in this PR.

4. INVISIBLE VERDICT — '<!-- 🟢 SAFE TO MERGE -->' as the first line satisfied
   both the verdict and the bot-adjudication checks while rendering invisible to
   a human reader. The same flaw failed legitimate PRs whose template opens with
   a comment.

5. FENCED EXAMPLE COUNTED AS A REAL TABLE — a body quoting the protocol's own
   '```markdown ## Decision provenance' example satisfied the provenance
   requirement. Quoting the rule counted as following it, and the example is in
   the rule doc this PR ships.

   Both fixed by normalizing the body once, before any check: HTML comments and
   fenced blocks are stripped and every check reads the cleaned text.

6. SETEXT HEADINGS DID NOT STOP THE PROVENANCE SCAN — the awk guard covered ATX
   headings only, so a 'Test results' underlined heading let its table be parsed
   as provenance rows. Now terminates on --- and === underlines too.

Also moved base.ref out of inline template interpolation into env; refs may
contain $, backtick, or semicolon.

Tested before commit: invisible verdict fails, leading template comment passes,
fenced example fails, setext-terminated table passes.

Known limits, documented rather than fixed: any stray double-quote in a row
satisfies the quotation test, and 'CodeRabbit: n/a' satisfies the bot line. Both
are inherent to regex checking and are backstops, not proofs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(ci): the workflow did not parse — replace the embedded heredoc (HT-100)

The previous commit broke the workflow at the YAML level. Its body-normalization
step embedded a python3 heredoc inside the 'run: |' block scalar; the heredoc's
lines sat at column 0, which terminates the block and makes YAML read them as
top-level keys:

  YAMLException: can not read a block mapping entry;
  a multiline key may not be an implicit key (101:48)

Consequence: the whole workflow failed to load, so no jobs ran, the 'verdict'
check disappeared from the PR entirely, and 'gh pr checks' showed nothing wrong
— a silently absent gate, which is worse than a failing one.

Replaced with indented shell doing the same work: perl strips HTML comments,
awk drops fenced blocks. No heredoc, so nothing escapes the block scalar.

The process failure worth recording: after making that edit I checked that the
new string was PRESENT in the file, and reported it as done. Presence is not
validity. The YAML was never parsed after the change, and the check I skipped —
'npx js-yaml' — takes one second and would have caught it immediately. Validated
here before committing, and the four normalization cases re-tested against the
new implementation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(process): keep the maintainer's name out of the public mirror (HT-100)

The repo copy of the verdict protocol must be role-neutral. It named the
maintainer in nine places, and the workflow named them in six more,
including the attribution regex itself.

- rule doc and workflow comments say "the maintainer" throughout
- the attribution patterns are role-based, so the gate keeps its coverage
  without a person's name hardcoded in a public repo
- the error message and header point at the in-repo .claude/rules/pr-verdict.md
  rather than a path in a home directory no contributor has
- drop a duplicated normalization comment block

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(ci): key the green-verdict review check to the verdict itself (HT-100)

Two defects in the gate, both surfaced by this PR's own body.

The adjudication check fired on any occurrence of "SAFE TO MERGE" anywhere
in the body, so a yellow PR that merely names the three verdicts was
required to carry a review line it had no business carrying yet. It now
keys off the verdict parsed from the first line.

It also read the raw body, so a backticked example documenting the loophole
satisfied it. It now reads the code-span-stripped body, the same one the
attribution check already uses.

The detector matches an adjudication line by shape rather than against a
list of third-party product names: the protocol allows a substitute
reviewer when the usual one is unavailable, and hardcoded names would fail
an honest substitution.

The first line must now BE the verdict rather than contain it: leading
hashes and the emoji are still fine, trailing prose is not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(ci): close five gate bypasses found by adversarial review (HT-100)

- A green verdict could carry an INFERRED row. The protocol says one
  inferred item means yellow and never green; the gate did not enforce it,
  so a PR could disclose an unauthorized decision and still call itself
  safe to merge — disclosure without the consequence.
- The adjudication line only had to contain the word "findings" somewhere
  after a colon, so "Note: findings" satisfied it. It now needs a count.
- "Per your decision" was undetected. It is one of the protocol's named
  examples; the earlier omission avoided colliding with the NEEDS YOUR
  DECISION marker, which the "per" prefix already avoids.
- A curly apostrophe in "the maintainer's decision" slipped past a matcher
  that only knew the ASCII form.
- "## Decision provenance deliberately omitted" satisfied the requirement
  for a provenance section, being only prefix-matched.

The locale is now pinned. Several patterns contain non-ASCII characters,
and under a byte-oriented locale grep matches those byte-by-byte — the
curly-apostrophe fix silently did nothing until the locale was fixed, which
is the failure mode where a check passes everything and still looks green.

Known limits, unchanged and documented: a row can still satisfy the
quotation test with any stray quote character, and text crafted to contain
INFERRED or a no-decision phrase can still excuse itself. This is a
backstop against drift, not a proof against a determined author.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>