diff --git a/.github/ISSUE_TEMPLATE/first-use.yml b/.github/ISSUE_TEMPLATE/first-use.yml new file mode 100644 index 0000000..819cf35 --- /dev/null +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index 1444c1d..b509f81 100644 --- a/AGENTS.md +++ b/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. diff --git a/README.md b/README.md index ce8ed0f..b1da7b6 100644 --- a/README.md +++ b/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 diff --git a/docs/adoption-loop.md b/docs/adoption-loop.md new file mode 100644 index 0000000..da30775 --- /dev/null +++ b/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. diff --git a/docs/first-use.md b/docs/first-use.md new file mode 100644 index 0000000..168bea3 --- /dev/null +++ b/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. diff --git a/docs/implementation-roadmap.md b/docs/implementation-roadmap.md index 8ae8745..0b06512 100644 --- a/docs/implementation-roadmap.md +++ b/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 | diff --git a/docs/reviews/2026-08-24-repository-portfolio-audit.md b/docs/reviews/2026-08-24-repository-portfolio-audit.md new file mode 100644 index 0000000..1d22733 --- /dev/null +++ b/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. diff --git a/package.json b/package.json index 51381e6..e65af7e 100644 --- a/package.json +++ b/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",