Describe PatchGate by the work it does

.github/ISSUE_TEMPLATE/first-use.yml

@@ -0,0 +1,53 @@
+name: First-use feedback
+description: Report what happened when you tried the first PatchGate check
+labels: ["pilot"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for trying PatchGate. Please do not include tokens, private repository data, or unredacted pull-request contents.
+  - type: input
+    id: version
+    attributes:
+      label: PatchGate version or commit
+      placeholder: v0.1.0-beta.5 or full SHA
+    validations:
+      required: true
+  - type: dropdown
+    id: result
+    attributes:
+      label: First-use result
+      options:
+        - worked
+        - worked with workaround
+        - did not reach first result
+    validations:
+      required: true
+  - type: input
+    id: time-to-result
+    attributes:
+      label: Time to first result
+      placeholder: e.g. 12 minutes
+    validations:
+      required: true
+  - type: textarea
+    id: workflow
+    attributes:
+      label: Repository shape and workflow
+      description: Public repository type, Action mode, and relevant non-sensitive setup details.
+    validations:
+      required: true
+  - type: textarea
+    id: friction
+    attributes:
+      label: First friction or useful result
+      description: What happened, what you expected, and what should change.
+    validations:
+      required: true
+  - type: checkboxes
+    id: consent
+    attributes:
+      label: Evidence consent
+      options:
+        - label: I consent to a redacted summary of this feedback being used in project evidence.
+          required: false

AGENTS.md

@@ -156,6 +156,12 @@ The current milestone audit is [the 2026-08-20 G4/G0 continuation audit](docs/re
 npm run verify
 ```
 
+## Shared repository workflow
+
+The Desktop workspace contains four separate public repositories: [PatchGate](https://github.com/daichunghy/patchgate), [contribkit](https://github.com/daichunghy/contribkit), [OpenSheet-AI](https://github.com/daichunghy/opensheet-ai), and [quant-research](https://github.com/daichunghy/quant-research). They are not a monorepo or a combined adoption claim. The live status, evidence limits, and cross-repository working rules are maintained in the [repository portfolio audit](docs/reviews/2026-08-24-repository-portfolio-audit.md).
+
+When working across them, keep each repository's own `AGENTS.md`, constitution, tests, release boundary, and Git history authoritative. Check live GitHub and package-registry signals before writing a status update. Count outside walkthroughs, downstream installs, outside issues, outside pull requests, and consented pilots as usage evidence; count self-authored activity and bot activity as maintenance evidence only.
+
 Agents must not describe the repository as released, externally piloted,
 live-integrated, merge-blocking, or eligible/selected for Codex for Open Source
 unless the corresponding evidence has been added and independently checked.

README.md

@@ -5,27 +5,30 @@
 [![CI](https://github.com/daichunghy/patchgate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/daichunghy/patchgate/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/daichunghy/patchgate/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/daichunghy/patchgate/actions/workflows/codeql.yml)
 
-PatchGate is an open-source review-readiness gate for GitHub pull requests.
-It answers a narrower question than code review or authorship analysis:
+PatchGate checks whether a GitHub pull request has the issue link, CI evidence,
+code owners, and human approval a repository requires before a maintainer
+reviews it.
 
-> Has this contribution supplied the policy, evidence, ownership, and human
-> boundaries that the repository requires before a maintainer spends review
-> time?
+That is the job. PatchGate does not review code, detect AI authorship, or decide
+whether a change should merge.
 
-The evaluator is deterministic and explainable. It does not determine who or
-what produced the code, whether the code is correct, safe, or merge-worthy, and
-it cannot force external automation to stop working.
+The evaluator is deterministic and produces a receipt that explains which
+requirements passed, which evidence is missing, and which human gate remains.
+It cannot force external automation to stop working.
 
-**Status:** public pre-release. The npm package remains unpublished (`private: true`,
-`0.1.0-dev`). The current Action release is
+**Status (2026-08-24):** public pre-release, 1 GitHub star, 0 forks, and no
+verified external users, downstream repositories, or pilots. The npm package
+remains unpublished (`private: true`, `0.1.0-dev`). The current Action release is
 [`v0.1.0-beta.5`](https://github.com/daichunghy/patchgate/releases/tag/v0.1.0-beta.5),
 and consumers should pin the immutable commit shown on that release page for
 **shadow** evaluation only. This is not production, not a `v0.1` claim, and
-not evidence of external pilots or adoption.
+not evidence of external adoption.
 
-> If PatchGate saved you one wasted review,
-> [star it](https://github.com/daichunghy/patchgate/stargazers). That is the
-> only growth signal this repo tracks.
+The four related repositories and the shared evidence rules are recorded in
+[the repository portfolio audit](docs/reviews/2026-08-24-repository-portfolio-audit.md).
+
+The shortest path to a user result is [one non-blocking first-use check](docs/first-use.md).
+The workspace tracks this alongside the [continuous adoption loop](docs/adoption-loop.md).
 
 ## Try it locally
 

docs/adoption-loop.md

@@ -0,0 +1,54 @@
+# User adoption loop — 2026-08-24
+
+The goal for this workspace is not to produce four busy repositories. It is to
+get real people to a first useful result, learn where the workflow fails, and
+fix that failure without weakening the product boundaries.
+
+## What counts as progress
+
+For each repository, the strongest next signal is one consented outside user
+who completes the first-use path and reports whether the result was useful.
+Stars, releases, self-authored issues, CI runs, and npm downloads are useful
+maintenance or discoverability signals, but they do not establish adoption.
+
+| Project | First useful result | Current blocker | Next evidence |
+| --- | --- | --- | --- |
+| [PatchGate](https://github.com/daichunghy/patchgate) | A maintainer installs the Action in non-blocking shadow mode and receives a useful check | Unpublished CLI, token/permission boundary, and no outside shadow install | One consented shadow run in a repository outside `daichunghy/*` |
+| [contribkit](https://github.com/daichunghy/contribkit) | An agent or human runs preflight on a real local change before opening a PR | Package/plugin discoverability and no outside consumer walkthrough | One outside repository completes `preflight` and reports the decision |
+| [OpenSheet-AI](https://github.com/daichunghy/opensheet-ai) | A typed intent becomes a validated plan, dry-run receipt, and new `.xlsx` file | The boundary is deliberately local/greenfield; no real operator workflow is verified | One researcher or operator completes a real spreadsheet task |
+| [quant-research](https://github.com/daichunghy/quant-research) | A declared instrument produces a codebook, recode output, coverage result, and analysis syntax | No real study workflow has been observed outside the maintainer workspace | One researcher uses an output in a real study and reports what was missing |
+
+## Evidence to record
+
+Every first-use report should record:
+
+- repository and version/commit;
+- user context, without collecting private data;
+- time to first useful result;
+- exact command or workflow used;
+- first error or confusing step;
+- whether the output was used for the intended task;
+- what the user expected next;
+- whether the user consents to a redacted public summary.
+
+The evidence record must distinguish `worked`, `worked_with_workaround`, and
+`did_not_reach_first_result`. Do not collapse a workaround into a success.
+
+## Working cadence
+
+1. Check live GitHub and package signals before writing the weekly status.
+2. Choose one user-facing friction with a reproducible path.
+3. Make the smallest safe change that removes or clarifies that friction.
+4. Run the repository verification command and a clean first-use path.
+5. Ask one relevant person or community for a consented walkthrough; do not
+   manufacture activity or send mass pull requests.
+6. Record the outcome, including a no-go or a failed first run.
+7. If two consecutive cycles produce no outside signal, pause feature growth
+   and spend the next cycle on direct user interviews or a narrower product.
+
+## Decision rule
+
+The next feature is justified by a real first-use failure, a repeated outside
+request, or a documented product boundary. Internal activity alone is not a
+user requirement. A release is a delivery mechanism, not evidence that the
+problem has been solved.

docs/first-use.md

@@ -0,0 +1,39 @@
+# First use: get one PatchGate result
+
+The first useful result is a non-blocking check on a real pull request. It
+should tell a maintainer what evidence is present and what still needs a human
+decision without changing merge eligibility.
+
+## Shadow setup
+
+For a local policy-only first result from this repository, run:
+
+```bash
+npm ci
+npm run first-use
+```
+
+This checks the trusted local `main` Git ref. It does not claim authenticated
+GitHub access or replace the Action shadow setup below.
+
+1. Open the [Action usage guide](github-action-usage.md) and create the
+   workflow on the repository's default branch.
+2. Use `v0.1.0-beta.5`, keep `fail-on: never`, and set
+   `create-check-run: true`.
+3. Open or update one pull request and read the PatchGate check summary.
+
+The workflow reads trusted metadata. It must not check out or execute
+pull-request code in the privileged lane. A standard `GITHUB_TOKEN` cannot
+read Administration, so a complete branch-protection or Rulesets snapshot may
+remain fail-closed. That is an expected boundary, not a successful evaluation.
+
+## What to record
+
+Record the repository type, beta tag or commit, time to the first check, the
+first confusing result, and whether the summary changed what you reviewed.
+Use the [first-use feedback form](https://github.com/daichunghy/patchgate/issues/new?template=first-use.yml)
+for a redacted report. Do not include tokens, private repository data, or
+unredacted pull-request contents.
+
+This walkthrough proves a setup path. It does not prove that PatchGate is
+popular, production-ready, or useful for every repository shape.

docs/implementation-roadmap.md

@@ -218,6 +218,17 @@ tests.
 
 Small samples use raw counts and context, not universal percentages.
 
+## Cross-repository status checkpoint — 2026-08-24
+
+PatchGate is now tracked alongside three separate maintainer repositories in a
+shared workspace: `contribkit`, OpenSheet-AI, and `quant-research`. The live
+portfolio check found no verified external user, downstream repository, or
+pilot for any of the four. GitHub stars, self-authored issues, releases, npm
+downloads, and scheduled maintenance remain supporting signals, not adoption.
+The [portfolio audit](reviews/2026-08-24-repository-portfolio-audit.md) records
+the exact snapshot and the next evidence required. This keeps G2/G4/G7 open;
+it does not create a release or user-value claim.
+
 ## Product measures
 
 | Measure | Definition |

docs/reviews/2026-08-24-repository-portfolio-audit.md

@@ -0,0 +1,74 @@
+# Repository portfolio audit — 2026-08-24
+
+This is the operating register for the four GitHub repositories kept in the
+Desktop workspace. They remain separate projects with separate contracts,
+release decisions, and user evidence. The register does not turn them into a
+suite and does not imply shared adoption.
+
+## Live snapshot
+
+The GitHub and npm checks were run on 2026-08-24. A download is a registry
+event, not a user count. A self-authored issue, release, discussion, star, or
+maintenance log is not external adoption.
+
+| Local folder | Repository | Current public signal | Package signal | Verified usage |
+| --- | --- | --- | --- | --- |
+| `Github/` | [`daichunghy/patchgate`](https://github.com/daichunghy/patchgate) | 1 star, 0 forks, 12 open issues, current Action pre-release `v0.1.0-beta.5` | PatchGate remains unpublished (`private: true`); the npm name `patchgate` belongs to another package | No external user, downstream repository, or pilot verified |
+| `Github 2/contribkit/` | [`daichunghy/contribkit`](https://github.com/daichunghy/contribkit) | 0 stars, 0 forks, 24 open issues, GitHub pre-release `v0.1.0-alpha.7` | npm `alpha` dist-tag resolves `0.1.0-alpha.6`; 528 downloads from 2026-07-25 to 2026-08-23 | No external user, downstream repository, or pilot verified |
+| `Github 3/` | [`daichunghy/opensheet-ai`](https://github.com/daichunghy/opensheet-ai) | 0 stars, 0 forks, 12 open issues, GitHub pre-release `v0.1.0-alpha.5` | npm `alpha` and `latest` resolve `0.1.0-alpha.4`; 109 downloads from 2026-07-25 to 2026-08-23 | No external user, downstream repository, or pilot verified |
+| `Github 4/` | [`daichunghy/quant-research`](https://github.com/daichunghy/quant-research) | 0 stars, 0 forks, 14 open issues, GitHub pre-release `v0.1.0-alpha.5` | npm `alpha` resolves `0.1.0-alpha.5`; 221 downloads from 2026-07-25 to 2026-08-23 | No external user, downstream repository, or pilot verified |
+
+The contributor lists are maintainer-led. PatchGate also has Dependabot
+activity; no outside human contributor was observed in this snapshot.
+
+## What this means
+
+PatchGate is not popular by the observable signals above. More importantly,
+its usefulness is still a product hypothesis, not a demonstrated user result.
+The project has a narrow and testable job, but no independent maintainer has
+yet installed it, completed a pilot, opened an issue from outside this
+workspace, or contributed a change.
+
+The same caution applies to the other three repositories. Their npm download
+counts are worth recording, but they cannot tell us whether a person used the
+package, whether the package solved the intended problem, or whether the
+download came from CI, a mirror, or an automated scan.
+
+The current PatchGate adoption blocker is also concrete: the project is a
+private, unpublished npm package, so a stranger must clone the repository and
+build it before the first CLI command. The existing
+[multi-persona review](2026-08-22-multi-persona-review.md) identifies this as
+the largest first-run friction. More release scaffolding will not answer that
+question; a consented external walkthrough will.
+
+## Shared working method
+
+1. Work in the repository that owns the change. Do not vendor or nest one
+   repository inside another.
+2. Before making an adoption or popularity claim, check GitHub and the
+   relevant package registry, record the date, and separate maintenance from
+   independent usage.
+3. Treat a real external walkthrough, downstream install, outside issue,
+   merged outside pull request, or consented pilot with feedback as usage
+   evidence. Treat self-authored activity and bot activity as maintenance
+   evidence only.
+4. Start each public description with the user's job, state the hard boundary,
+   and label the release stage. Do not lead with an AI-shaped promise or a
+   claim the evidence cannot support.
+5. Prefer one completed user interaction over another internal release, issue,
+   or scheduled post. Record negative results too.
+
+## Next evidence to pursue
+
+- PatchGate: one consented non-blocking shadow install by a maintainer outside
+  `daichunghy/*`, followed by feedback on setup, noise, and usefulness.
+- contribkit: one consumer repository or outside maintainer walkthrough that
+  exercises the preflight boundary.
+- OpenSheet-AI: one researcher or operator completing the documented local
+  quickstart and reporting whether the typed plan and receipt match a real
+  spreadsheet task.
+- quant-research: one researcher using an instrument, recode, or emitter in a
+  real study workflow and reporting what was missing or unnecessary.
+
+Until those checks exist, the accurate description is: four actively maintained
+public pre-release projects with no verified external adoption.

package.json

@@ -2,7 +2,7 @@
   "name": "patchgate",
   "version": "0.1.0-dev",
   "private": true,
-  "description": "Deterministic GitHub pull-request review-readiness evaluator",
+  "description": "Checks GitHub pull requests for required issue links, CI evidence, code owners, and human approval before maintainer review",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -39,6 +39,7 @@
     "prepare": "npm run build",
     "prepublishOnly": "npm run verify",
     "build": "tsc -p tsconfig.json",
+    "first-use": "npm run build && node dist/src/cli.js preflight --repo . --base main",
     "bundle:action": "ncc build src/action/index.ts -o dist/action --minify --transpile-only",
     "audit": "npm audit --audit-level=high",
     "typecheck": "tsc -p tsconfig.json --noEmit",