redlinegate 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Elzanaty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# Redline
+
+Engineering oversight layer for AI-assisted development at enterprise scale, built on
+GitHub-native primitives: automated code review against versioned standards, branch
+rulesets, reusable Actions workflows, and Pages. No servers, no SaaS, no per-seat fee
+beyond the AI licences already paid for.
+
+One system covering the full delivery loop: AI writes code, automated review against
+versioned standards, readiness gates, decision log, org-wide inbox — plus the measurement
+and distribution that let it evolve from data rather than opinion.
+
+**Vendor-neutral.** The rules live once in `standards/` and render to GitHub Copilot,
+OpenAI Codex / `AGENTS.md`, and Claude. A Cursor adapter exists but ships disabled
+(`vendors.cursor.enabled: false` in `standards/manifest.json`). See
+[docs/vendors.md](docs/vendors.md).
+
+## What's in the box
+
+| Path | What | Where it lives in production |
+| --- | --- | --- |
+| `standards/core.md` | Core standards: security, type safety, error handling, scope, and the severity output contract | source of truth — **the only file a human edits** |
+| `standards/stacks/*.md` | Per-stack rules: javascript, react, react-native, nodejs, microservices, java, go, python, csharp, kotlin, swift, terraform | source of truth |
+| `standards/manifest.json` | Stack globs, profiles, vendor toggles, standards version | source of truth |
+| `cli/` | The `redline` CLI (`redline init`, `redline verify`) — detects the platform, renders standards, installs the gate | run via `npx redlinegate`, or `redline` once installed with `npm i -g redlinegate` |
+| `.github/pull_request_template.md` | Readiness checklist + ADR link | every onboarded repo |
+| `templates/repo-context.md` | Per-repo context template | reference only — a human copies it above the generated block in `AGENTS.md`; `redline init` never installs it |
+| `templates/CODEOWNERS` | Reference shape of the CODEOWNERS pattern that makes `require_code_owner_review` real and protects the enforcement surface | `redline init` writes `.github/CODEOWNERS` on GitHub repos with equivalent content built in code — it does not read this file |
+| `templates/redline.yml` | Thin caller installed as `.github/workflows/redline.yml` | every onboarded repo |
+| `rulesets/redline-ruleset.json` | Reference shape of the per-repo branch ruleset: 1 human approval, thread resolution, automatic review, required `redline-gate / gate` check | nothing reads this file — `redline init` builds the equivalent ruleset at runtime |
+| `rulesets/redline-org-ruleset.json` | Same rules applied org-wide by custom repository property — no per-repo drift | applied once at org level |
+| `workflows/redline-gate.yml` | Reusable gate: checklist, ADR-for-big-diffs, dependency review, diff secret scan, label-aware aggregation | org `.github` repo |
+| `workflows/redline-sync.yml` | Distributes standards, gate caller and template to onboarded repos as PRs — **disabled in Phase 1**, see [CHANGELOG.md](CHANGELOG.md) | this (source) repo |
+| `workflows/redline-collect.yml` + `scripts/collect-telemetry.mjs` | Nightly central pull of review outcomes across the org | `redline-metrics` repo |
+| `workflows/weekly-digest.yml` + `scripts/build-digest.mjs` | Monday Teams digest as an Adaptive Card | `redline-metrics` repo |
+| `workflows/inbox.yml` + `scripts/build-inbox.mjs` | Org-wide prioritised PR inbox on GitHub Pages | this (source) repo |
+| `workflows/dashboard.yml` + `scripts/build-dashboard.mjs` | Static dashboard on Pages: acted-on rate, trends, seed recall history, the rule tuning queue | `redline-metrics` repo |
+| `workflows/seed-canary.yml` | Weekly regression test of the reviewer itself: opens a seeded PR, scores it, closes it | `redline-metrics` repo |
+| `workflows/verify-onboarding.yml` | Weekly re-verification of every onboarded repo; opens an issue on drift — **disabled in Phase 1**, see [CHANGELOG.md](CHANGELOG.md) | this (source) repo |
+| `scripts/validate.mjs` | Bundle self-check, run by this repo's CI | this repo |
+| `scripts/check-pins.mjs` | Re-resolves SHA-pinned actions against their upstream tag | this repo's CI |
+| `scripts/assign-rule-ids.mjs` | Assigns and verifies the stable `<stack>/<slug>` id on every rule | this repo |
+| `seeded/` | Recall corpus (12 stacks, 82 BLOCKER seeds) + precision corpus, scored by `scripts/score-seeds.mjs` | validation only, never merged |
+
+## Language coverage vs org reality
+
+Primary-language tally across the org's active repos (2026-09-01):
+Java 187 · TypeScript 86 · Python 47 · JavaScript 32 · HCL 24 · C# 22 ·
+Kotlin 14 · Swift 9 · Go 6. All covered — including plain JavaScript, which the
+TypeScript-only globs previously missed. Shell/Dockerfile/Gherkin intentionally uncovered
+(linters serve better than LLM review there).
+
+## Onboard a repository
+
+```sh
+cd your-repo
+npx redlinegate init
+```
+
+That is the whole procedure. It detects your stack, renders the standards for it, installs
+the merge-readiness template and the gate (advisory — it reports, it does not block),
+turns on the security floor, and opens a pull request. Anything that needed repository
+admin rights you do not have is listed at the end for an administrator to run.
+
+Install it once and the everyday command is shorter:
+
+```sh
+npm i -g redlinegate
+redline verify
+```
+
+The package is named `redlinegate`, not `redline` — that name is already taken on the public
+npm registry by an unrelated package, so `npx redline …` always resolves to the wrong thing.
+The binary it installs is named `redline`, which is why the everyday command reads `redline
+init` / `redline verify` once it is installed rather than `redlinegate init`.
+
+`redline verify` checks the repository still matches what it claims. Run it any time —
+scheduled estate-wide re-verification is Phase 3 work, not yet wired up; see
+[CHANGELOG.md](CHANGELOG.md) known limitations.
+
+Both GitHub and Azure DevOps are supported. Redline detects which from your git remote.
+
+## Verify before you trust
+
+The single most common silent failure in a system like this is a required status check
+whose name nothing ever reports: every PR sits on "Expected — waiting for status" forever.
+
+Reusable workflows report as `<caller job id> / <called job id>`. Here that is
+**`redline-gate / gate`**, and the name is pinned in two places: the ruleset JSON's
+reference shape, and `scripts/validate.mjs` (CI fails if the job is renamed).
+On GitHub, whether `redline init` makes it a *required* check depends on `--blocking`:
+the default advisory install adds no `required_status_checks` rule at all, but
+`redline init --blocking` writes `redline-gate / gate` into the ruleset
+(`cli/platforms/github/install.ts`'s `REQUIRED_CHECK` constant, not a caller-supplied
+value). `redline verify` reads back whatever the host currently has required and compares
+it to what actually reported on the latest pull request: on a blocking install this is a
+real assertion, failing if the check is required but never reported; on the default
+advisory install nothing is required yet, so `verify` only surfaces the reported name for
+a human to eyeball. See [CHANGELOG.md](CHANGELOG.md) known limitation 5. Run it on every
+onboarded repo either way.
+
+## Making a change to the standards
+
+```sh
+$EDITOR standards/stacks/react.md          # 1. edit the source, never the output
+node scripts/assign-rule-ids.mjs           # 2. give any new rule a permanent id
+$EDITOR standards/manifest.json            # 3. bump version
+node scripts/render-self.mjs               # 4. re-render this repo's own artifacts
+node scripts/validate.mjs                  # 5. self-check
+$EDITOR CHANGELOG.md                       # 6. say what changed and why
+```
+
+Rule ids are permanent. Reword a rule freely; never edit its id, or every historical
+telemetry record for it orphans and the tuning history resets.
+
+Distribution to already-onboarded repos (`redline sync`) is Phase 3 — see
+[CHANGELOG.md](CHANGELOG.md). Until then, an onboarded repo picks up a standards change by
+re-running `redline init`. Redline never pushes to a default branch; every change lands as
+a pull request a team reviews and merges itself.
+
+## Two version axes
+
+Redline carries two versions that move independently. Do not conflate them.
+
+| Axis | Lives in | Bumped by | Example |
+| --- | --- | --- | --- |
+| **CLI version** | `redlinegate` on npm (git `v*` tags) | semantic-release, from conventional commits on `main` | `0.0.1` |
+| **Standards version** | `standards/manifest.json` → `version` | A human, in the same PR as the rule change (see above) | `0.0.1` |
+
+The CLI version is the tool's release line: [CHANGELOG.md](CHANGELOG.md) tracks it, and
+semantic-release computes the next one from commit messages — never edit
+`package.json`'s `version` by hand. The standards version is the rules' release line:
+sync PRs and rendered artifacts quote it, so a repo always knows which ruleset it is
+running. A CLI release does not imply a standards change, and vice versa.
+
+Each onboarded repo's `.redline.json` records both — `cliVersion` (the tool that
+onboarded it) and `standardsVersion` (the ruleset it was rendered from) — so `redline
+verify` can tell "old tool" apart from "old rules".
+
+Releases publish from `.github/workflows/release.yml`: every same-repo PR checks that
+the pinned release toolchain still resolves from the lockfile (`semantic-release
+--dry-run`, which exits early on PR context — no secrets in the job), a manual
+`workflow_dispatch` rehearses the real publish path with a throwaway build on the npm
+`canary` dist-tag without touching `latest`, and the real publish on `main` runs the
+exact semantic-release version pinned in the lockfile.
+
+## Why this works at enterprise scale
+
+- **Feedback loop that measures the right thing.** Every rule carries a permanent id,
+  every finding cites one, and telemetry records not just how often a rule fired but how
+  often it was *acted on* — resolved threads versus findings left stale and outdated. The
+  dashboard turns that into a tuning queue: the specific rules to cut, named. See
+  [docs/measurement.md](docs/measurement.md).
+- **The reviewer itself is regression-tested.** A weekly canary opens a PR of known-bad
+  code against a pilot repo, scores what came back against 82 seeded BLOCKER defects and
+  a corpus of correct code that must draw zero comments, then closes it. "No findings"
+  and "nothing to find" are otherwise indistinguishable.
+- **Distribution.** One source of truth, rendered per profile. `redline sync` — syncing
+  standards to already-onboarded repos as reviewable PRs — is Phase 3 (see
+  [CHANGELOG.md](CHANGELOG.md)); until then a repo picks up a standards change by
+  re-running `redline init`. Never copy-paste per project, never a stale rule file left
+  behind when a repo changes stack.
+- **Hard enforcement.** Org-level ruleset plus a required check that is name-verified.
+  CODEOWNERS on the enforcement surface, so nobody can weaken their own gate unreviewed.
+- **A real security floor.** Secret scanning with push protection, Dependabot alerts,
+  dependency review and a diff secret scan — enabled by `redline init`, not assumed.
+  Security checks in the gate can never be label-exempted. On GitHub, that is; see
+  [CHANGELOG.md](CHANGELOG.md) for what Azure DevOps does not yet get at the gate.
+- **Least privilege.** Telemetry is pulled centrally with a read-only token. Onboarding a
+  repo grants Redline no write access to it.
+- **Enterprise shape.** Per-stack rule composition, human approval always required, full
+  audit trail native to GitHub.
+
+## Design decisions
+
+- Automated review is **advisory input to a human**, never the approver. The ruleset
+  requires one human approval regardless, and `validate.mjs` fails if that is ever
+  lowered to zero.
+- Standards carry an explicit **output contract** (`Redline/BLOCKER:` …). Without it,
+  severity is unparseable and every metric downstream is a guess.
+- Standards carry explicit **What NOT to flag** sections — AI review dies by nitpick
+  spam, so noise control is a first-class rule and a measured one.
+- Everything distributes as **PRs, never pushes** — teams see and own changes to their
+  gates.
+- The gate separates **process checks from security checks**. `redline-exempt` downgrades
+  the checklist and ADR requirements to warnings for a reviewer who accepts the
+  trade-off; it does nothing to dependency review or the secret scan.
+- **Profiles, not glob negation.** Rule sets that would contradict each other are never
+  installed in the same repo, so no rule depends on unsupported negation syntax.

package/commands/redline-init.md

@@ -0,0 +1,54 @@
+---
+description: Onboard this repository to Redline — standards, security floor and merge gate
+---
+
+Run `npx redlinegate init` in the repository root and report what it printed. Do not run
+plain `npx redline` — that resolves to an unrelated package on the public registry; the
+published package is `redlinegate`. If the engineer already has it installed
+(`npm i -g redlinegate`), the everyday command is just `redline init`.
+
+The command is not interactive by default. If the engineer asked for something specific,
+pass it through:
+
+- a stack override: `--profile <name>`
+- which vendors to render for: `--vendors <list>` (comma-separated: copilot, agents, claude,
+  cursor) — overrides both detection and whatever `.redline.json` already recorded, capped by
+  whatever the org manifest enables
+- a blocking rather than advisory gate: `--blocking`
+- the plan only, writing nothing and changing no repository setting: `--dry-run`
+- re-apply every capability even on a repository that looks already onboarded: `--repair` —
+  the fix once an administrator grants rights that a plain re-run cannot recheck on its own
+  (labels, review ownership, the repo property, the gate, the merge policy)
+- capabilities this repository does not want Redline to install because it already has its
+  own: `--skip <list>` (comma-separated: gate, merge-policy, labels, review-ownership), and
+  `--with <list>` to select one again. A deselected capability is not attempted, not written
+  and not reported by `redline verify` as missing — it is reported as off by choice. The
+  security floor is the organisation-wide minimum: `--skip security-floor` is refused by name
+  rather than quietly ignored
+- `--no-a11y` and `--speckit` are recorded in `.redline.json` for later phases; they change
+  nothing in Phase 1, so do not describe them to the engineer as having taken effect
+
+Flags you do not pass keep whatever `.redline.json` already recorded — re-running without
+`--blocking` on a repository onboarded with it does not demote the gate.
+
+When it finishes, tell them three things and nothing else:
+
+1. which profile was detected and what was written
+2. the pull request URL
+3. anything under `partially onboarded` — that list needs a repository administrator, and
+   until it is cleared this repository is not fully onboarded
+
+A bad flag, an unknown profile, or a host failure all exit non-zero. What exits `0` is a
+**denied** capability — the operator lacks the rights, so it is recorded in `.redline.json`
+under `pendingAdmin` for an administrator to grant later. A capability the host reports as
+**unsupported** — for example Azure DevOps Advanced Security when it isn't licensed on this
+repository — is different again: it is never pending admin work, and never appears in
+`pendingAdmin`, because there is nothing an administrator here could grant. A capability the
+host answers with **unknown** — an indeterminate read the host cannot tell apart from a
+genuine refusal — is treated the same way: never filed as pending admin work either, because
+an indeterminate read has told nobody anything they can act on.
+
+Do not edit the files it generated. Content inside `<!-- REDLINE:BEGIN -->` markers is
+owned by Redline and is regenerated on the next `redline init` run; content outside the
+markers in a merged file (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`,
+the pull request template) is the team's own and is never touched.

package/commands/redline-verify.md

@@ -0,0 +1,69 @@
+---
+description: Check this repository still matches the standards and guardrails it claims
+---
+
+Run `npx redlinegate verify` in the repository root and report the findings table. Do not run
+plain `npx redline` — that resolves to an unrelated package on the public registry; the
+published package is `redlinegate`. If the engineer already has it installed
+(`npm i -g redlinegate`), the everyday command is just `redline verify`. Add `--gate` if the
+engineer wants an explicit pass/fail summary line printed after the table, such as when
+running this by hand to mirror what CI's gate check sees.
+
+Each line is a check. For any `FAIL`, explain what it means and what fixes it:
+
+- `onboarded` — the repository has no `.redline.json`. Run `redline init`.
+- `capabilities` — never a `FAIL`. It names what this repository deselected at onboarding, so
+  the report describes the whole surface. The checks a deselection governs say `off by choice`
+  in their own detail rather than reporting the capability as missing: that is the difference
+  between "off because we chose to" and "off because it broke".
+- `merge-policy` — no Redline merge policy was found on the host at all, or the live one has
+  been loosened, or the ruleset that carries it is no longer in force. The finding names what
+  changed: the blocking flag, the approval count, dismissing approvals on push, code-owner
+  review, unresolved-thread resolution — or, on Azure, a blocking Status policy with no
+  matching Build Validation policy to queue the gate pipeline, so the status is never
+  published and every pull request sits blocked; re-run `redline init` with build
+  administrator rights. Settings the host cannot attribute to Redline are listed as
+  "not compared here" rather than held against the repository. A repository that deselected
+  the merge policy is not compared at all — except where Redline itself applied a blocking
+  policy before the deselection: that ruleset is still live, still requires the Redline check,
+  and fails here while nothing in the repository publishes it.
+- `gate-machinery` — the file that runs the gate is missing from this repository, the job that
+  publishes the required check has been renamed, the file is present and correctly named but no
+  pull request will ever trigger it, or the job is unchanged but the merge policy now requires a
+  different check name. Nothing will ever report the gate, so a blocking policy blocks every pull
+  request forever. Re-run `redline init` to restore the file or reapply the policy. Only rename
+  the job back if the workflow itself was the thing that changed — if the policy is what moved,
+  the job is already correct, and renaming it is the wrong fix. A repository that deselected the
+  gate passes here, and is told whether the workflow an earlier run installed is still sitting
+  there — a deselection never deletes it.
+- `check-name-reported` — a check ran on the pull request but the required name was never among
+  the ones reported. Where the policy blocks, this blocks every pull request in the repository.
+  Fix the caller job id, or the policy. "No gate run observed yet" is not a failure: no Redline
+  gate run has published anything on that pull request's head commit — other CI may well have —
+  and `gate-machinery` above is what says whether one ever could.
+- `security-floor` — secret scanning, push protection or dependency alerts has been turned off.
+  A capability nothing could observe is named as unconfirmed, never counted as enabled.
+- `artifacts-current` — the rendered standards are stale against the version this repository
+  recorded. A version difference in either direction is reported without failing, because
+  neither is drift: a newer version upstream is adopted by `redline init`, and an older one
+  means this CLI is behind the repository and wants updating, not re-running.
+- `pull-request-template` — the template the host actually serves is gone, has a broken
+  `REDLINE:BEGIN`/`REDLINE:END` pair, or is missing a section the gate checks for, so the gate
+  fails pull requests opened from it. Re-run `redline init` — but a mangled marker pair has to
+  be repaired by hand first, because `init` refuses to write to it.
+- `pending-admin` — a repository administrator still has work to do. Only capabilities a read
+  came back with an answer for are listed as work to chase. Entries the host reported as
+  unavailable, and entries no read can answer at all (labels, review ownership, the repo
+  property, the gate, the merge policy), are listed separately as recorded-but-unactionable.
+  Under `--gate` only the actionable ones fail, so a record only `redline init` can clear does
+  not block every pull request in the repository.
+
+A capability the host reports as **unsupported** — for example Azure DevOps Advanced Security
+when it isn't licensed on this repository — is not the same as **denied**: it is never listed
+as work an administrator must do, because there is no administrator action that would change
+it. A capability the host answers with **unknown** — a 401/403 this host cannot tell apart
+from a genuine refusal — is treated the same way for the same reason: an indeterminate read
+is not an answer, so it is never counted as work to chase either. Both are still named, so
+nobody mistakes silence for a clean bill.
+
+Do not attempt to fix host settings yourself. Report and stop.