You are about to hand a repository to an AI agent that will edit it while nobody reviews every diff. StewardScope answers the question nobody asks before that happens:
If this agent makes a mistake, will anything notice — and can anyone undo it?
It is a deterministic, offline audit of a repository's autonomy readiness: 33 rules across six dimensions, weighted by what kind of repo it is, producing a 0–100 score, a letter grade, a ranked remediation roadmap, and a CI gate that fails when an autonomous change makes the repo less safe.
No LLM calls. No network. No config required. One binary-ish Node CLI, or one container.
The 2026 agent conversation is entirely about capability: agents that drive any software, swarms that run in parallel, skills libraries in the hundreds of thousands of stars, projects maintained with "no human intervention."
Almost nothing asks the boring question underneath all of it: is this repository actually shaped so that an agent can be trusted inside it?
Agent failures are rarely model failures. They are almost always one of these:
| Failure | Missing ground truth |
|---|---|
| The agent "fixes" something and breaks three other things | No test suite that runs on its own |
| The agent invents a different convention every session | No AGENTS.md / CLAUDE.md contract |
git add -A commits node_modules and a real .env |
No .gitignore, no pre-commit hook |
| A bad change ships and nobody notices for a week | No CI, no logs, no metrics |
| The same task succeeds today and fails tomorrow | No lockfile, floating version ranges |
| It cannot be reverted | No git, no remote, no history |
Existing tools cover adjacent ground and none of it is this:
- OpenSSF Scorecard / supply-chain scanners audit security and dependency hygiene. They do not ask whether an agent can verify its own work.
- Linters and test runners are the controls themselves, not an audit of whether you have them.
- Best-practice lists and awesome-repos are prose. They cannot run in CI.
| Dimension | The question | Example rules |
|---|---|---|
| Ground truth | After the agent edits, does anything check the result? | No tests, no CI, no lint, no test command |
| Contract | Can the agent discover the rules without asking a human? | No AGENTS.md, no commands in it, no prohibitions |
| Blast radius | What can the agent reach that it should not? | No .gitignore, no hooks, no CODEOWNERS, committed .env |
| Recoverability | When it goes wrong, can the damage be undone? | Not a git repo, no remote, no history, forward-only migrations |
| Observability | Would anyone notice a bad change after it ships? | No CHANGELOG, no health probe, no logging, no metrics |
| Determinism | Does the same input reproduce the same build tomorrow? | No lockfile, loose pins, FROM x:latest |
Weights are shape-aware. StewardScope classifies the repo as service / library / cli /
frontend / data / unknown and re-weights accordingly — a library that nobody deploys is not
docked for lacking a health probe, but it is docked hard for lacking a lockfile.
- Each dimension starts at 100 and loses points for every rule it fails (floor 0).
- The headline score is the weighted average of the six dimensions.
- Blockers also cost 5 points on the headline score directly. "Not a git repository" is worth far more than a low-weight dimension would otherwise allow it to be.
-5per blocker is deliberate: a repo with no tests, no agent contract, no lockfile, and no git should not be able to hide behind a C.
| Score | Grade | Meaning |
|---|---|---|
| 85–100 | A | Autonomy-ready — let it work unsupervised |
| 72–84 | B | Supervised autonomy — keep PR review and CI |
| 58–71 | C | Assisted only — a human reviews every diff |
| 42–57 | D | Risky — key ground truth is missing |
| 0–41 | F | Not ready — this is a random number generator with write access |
- 33 deterministic rules — every finding carries evidence (the file that triggered it), a rationale written for an autonomous caller, and a concrete fix.
- Shape-aware weighting — service / library / cli / frontend / data / unknown.
- Ranked remediation roadmap — every failure is scored by
gain ÷ effortso you fix the cheap high-impact things first. Blockers are always phase 1. - Conservative patch generation —
stewardscope patch --applywrites the guardrails you are missing (AGENTS.md, CI workflow, pre-commit config,.gitignore,CODEOWNERS,CHANGELOG.md), filled in with the commands actually detected in your repo. It only creates files; it never overwrites one that exists. - Regression gate — snapshot today's score, then fail CI when a change lowers it, introduces a
blocker, or drops any single dimension. Exit codes
0/1/2. - Markdown and JSON reports — for PR comments, dashboards, and audit trails.
- HTTP API + web console — radar chart, dimension breakdown, findings table, patch preview.
- Zero runtime dependencies — nothing to resolve, nothing to break, nothing to audit.
# no install needed
npx stewardscope scan .
# or
npm install -g stewardscope
stewardscope scan /path/to/repo# the same thing in Docker
docker compose up -d --build
open http://127.0.0.1:8080
# audit a specific repo from inside the container
REPO_PATH=/Users/you/code/myrepo docker compose up -d --build
docker compose exec stewardscope node dist/cli.js scan /workspaces/repoFrom a clone:
git clone https://github.com/Eileenes/StewardScope.git
cd StewardScope
npm install
npm run build
node dist/cli.js scan .
node dist/cli.js serve # console on http://127.0.0.1:8080Requires Node 20+. Nothing else.
stewardscope scan [path] text report (default)
stewardscope report [path] full markdown report
stewardscope rules list all 33 rules
stewardscope dimensions list dimensions and weights
stewardscope baseline [path] -o FILE snapshot the current readiness
stewardscope diff [path] -b FILE compare against a baseline
stewardscope gate [path] CI gate: exit 0 pass, 1 warn, 2 fail
stewardscope patch [path] show missing guardrails
stewardscope patch [path] --apply write them (never overwrites)
stewardscope serve -P 8080 HTTP API + web console
Options: -o/--out, -b/--baseline, -m/--min-score, -d/--allow-drop, -f/--format,
-P/--port, --apply, --json.
# once, from a known-good state
npx stewardscope baseline . -o .stewardscope.json# .github/workflows/stewardscope.yml
name: autonomy-readiness
on: [pull_request]
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npx --yes stewardscope gate . --min-score 58| Exit code | Meaning |
|---|---|
0 |
Readiness held or improved |
1 |
Slipped, but within --allow-drop (default 2 points) |
2 |
Regressed: new blocker, dropped dimension, or below --min-score (default 58) |
This is the part that matters for agent work: the agent cannot merge a change that lowers the repo's ability to host an agent. The gate checks the agent's own output.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/health |
Liveness — { status, version } |
| GET | /api/meta |
Version, rule count, default gate thresholds |
| POST | /api/scan |
Full audit. Body: { "path": "/abs/or/rel/path" } |
| GET | /api/scan?path=... |
Same, via query string |
| POST | /api/summary |
Compact verdict: score, grade, blockers, top actions |
| POST | /api/report |
{ path, format: "markdown" } → rendered report |
| POST | /api/score |
Just { score, grade, verdict, shape } |
| POST | /api/baseline |
{ path, target } → writes the baseline file |
| GET | /api/baseline?target=... |
Reads a baseline |
| POST | /api/gate |
{ path, min_score, allow_drop, baseline } → { exit_code, ... } |
| POST | /api/diff |
{ path, baseline } → regression detail |
| GET | /api/rules |
The full 33-rule catalogue |
| GET | /api/dimensions |
Dimensions plus per-shape weights |
| POST | /api/patch |
{ path, apply?, out? } → proposed (or written) files |
| GET | /* |
Web console (served from static/) |
curl -s localhost:8080/api/health
curl -s -X POST localhost:8080/api/scan -H 'content-type: application/json' -d '{"path":"."}'
curl -s -X POST localhost:8080/api/gate -H 'content-type: application/json' -d '{"path":".","min_score":58}'StewardScope/
├── src/
│ ├── core/
│ │ ├── types.ts shared contracts
│ │ ├── scan.ts tree walk, stack + shape detection, git facts
│ │ ├── score.ts dimension roll-up, composite, roadmap ranking
│ │ ├── patch.ts guardrail file generation (additive only)
│ │ ├── report.ts markdown / text renderers
│ │ ├── regress.ts baseline compare + gate verdict
│ │ └── rules/
│ │ ├── catalog.ts 33 rule definitions
│ │ ├── dimensions.ts dimension metadata + shape weights + grades
│ │ ├── helpers.ts shared predicates
│ │ ├── groundtruth.ts contract.ts blast.ts
│ │ ├── recover.ts observe.ts determinism.ts
│ │ └── index.ts registry
│ ├── services/audit.ts orchestration (scan → audit → gate → patch)
│ ├── server/
│ │ ├── index.ts node:http server (zero deps)
│ │ ├── router.ts tiny method-aware dispatcher
│ │ ├── static.ts console asset serving
│ │ └── routers/ health · scan · gate · patch
│ ├── cli.ts
│ └── index.ts library entry
├── web/ React + TypeScript + Vite console
├── static/ built console (committed; Docker needs no Node build)
├── tests/ 70 tests, 6 suites
├── Dockerfile
└── docker-compose.yml
- Runtime: Node 20+, TypeScript 5.7 in strict mode.
- Backend: zero runtime dependencies —
node:http,node:fs,node:path,node:child_process. - Frontend: React 18 + TypeScript + Vite 6, hand-rolled SVG radar, no charting library.
- Tests: Vitest, 70 tests across scan / rules / scoring / patch / regression / HTTP.
- Packaging: single-stage
node:20-alpineimage, pre-built console committed instatic/, so the Docker build never runs a Node toolchain. - No database. Audits are pure functions of the working tree; the only artifact is an optional JSON baseline you commit yourself.
- It never calls an LLM. Every verdict is reproducible from the file tree.
- It never modifies your code.
patch --applyonly adds new files. - It does not require a config file, an account, or a network connection.
MIT — see LICENSE.
你准备把一个仓库交给 AI Agent，让它改代码，而没人逐条 review 每一次 diff。StewardScope 回答一个在 这件事发生之前几乎没人问的问题：
如果这个 Agent 出错，有没有东西会发现？发现了，能不能退回来？
它是一次确定性的、纯离线的自治就绪度（autonomy readiness）体检：6 个维度、33 条规则，按仓库形态 加权，输出 0–100 分、等级、按性价比排序的补齐路线图，以及一个「自治能力不允许下降」的 CI 门禁。
不调大模型，不联网，不需要配置文件。一个 Node CLI，或者一个容器。
2026 年关于 Agent 的讨论几乎全在讲能力：能操作任何软件的 Agent、并行跑的 agent 集群、几十万星的 skills 库、「无人干预维护」的项目。
几乎没人在问底下那个很无聊的问题：这个仓库本身的结构，配得上让一个 Agent 进来吗？
Agent 翻车很少是模型笨，几乎总是下面这几类：
| 翻车现场 | 缺的是哪块地面真相 |
|---|---|
| 改好一个地方，弄坏三个地方 | 没有能自己跑起来的测试 |
| 每次会话都发明一套新约定 | 没有 AGENTS.md / CLAUDE.md 契约 |
git add -A 把 node_modules 和真 .env 提交进去 |
没有 .gitignore、没有 pre-commit |
| 错误上线一周没人发现 | 没有 CI、没有日志、没有指标 |
| 同一个任务今天能跑明天挂 | 没有 lockfile、版本号用 ^ |
| 出事了退不回去 | 没有 git、没有 remote、没有历史 |
现有工具都在旁边，没有一个在做这件事：
- OpenSSF Scorecard / 供应链扫描器 查的是安全与依赖卫生，不问「Agent 能不能验证自己的产出」。
- Linter 和测试框架 是控制手段本身，不是「你到底有没有控制手段」的体检。
- 最佳实践清单、awesome 仓库 是散文，进不了 CI。
| 维度 | 它问的问题 | 规则举例 |
|---|---|---|
| 可验证性 Ground truth | Agent 改完之后，有什么东西会检查结果？ | 没有测试、没有 CI、没有 lint、没有 test 命令 |
| 约定可发现 Contract | Agent 不用问人，能自己找到规矩吗？ | 没有 AGENTS.md、里面没写命令、没有禁令段 |
| 爆炸半径 Blast radius | Agent 能碰到哪些它不该碰的东西？ | 没有 .gitignore、没有钩子、没有 CODEOWNERS、.env 进树 |
| 可恢复性 Recoverability | 出事了，损失能撤销吗？ | 不是 git 仓库、没有 remote、没有历史、migration 只有正向 |
| 可观测性 Observability | 一个错误的改动上线后，有人会发现吗？ | 没有 CHANGELOG、没有健康检查、没有日志、没有指标 |
| 确定性 Determinism | 同样的输入，明天还能复现同一次构建吗？ | 没有 lockfile、版本区间太松、FROM x:latest |
权重是按形态自适应的。StewardScope 先把仓库判为 service / library / cli / frontend /
data / unknown，再据此加权 —— 没人部署的库不会因为缺健康检查被扣分，但会因为没有 lockfile 被
狠扣。
- 每个维度从 100 分起，按未通过的规则扣分（下限 0）。
- 总分 = 六个维度的加权平均。
- blocker 额外直接从总分扣 5 分。「根本不是 git 仓库」这种事，不该因为所在维度权重低就被稀释成 3 分。
- 每个 blocker 扣 5 分是刻意的：一个没测试、没契约、没 lockfile、连 git 都不是的仓库，不该拿得到 C。
| 分数 | 等级 | 含义 |
|---|---|---|
| 85–100 | A | 可自治托管：可以放手让 Agent 干 |
| 72–84 | B | 监督式自治：保留 PR review 和 CI |
| 58–71 | C | 仅可辅助：人类必须逐条 review |
| 42–57 | D | 高风险：关键地面真相缺失 |
| 0–41 | F | 不具备条件：这等于给随机数开了写权限 |
- 33 条确定性规则 —— 每条都带证据（触发它的文件）、面向「自治调用方」写的理由、以及具体修法。
- 形态自适应权重 —— service / library / cli / frontend / data / unknown。
- 按性价比排序的补齐路线图 —— 每条未通过项按
收益 ÷ 成本排序，先补便宜又管用的。blocker 恒为 第一阶段。 - 保守的补丁生成 ——
stewardscope patch --apply补上你缺的护栏（AGENTS.md、CI workflow、 pre-commit 配置、.gitignore、CODEOWNERS、CHANGELOG.md），内容里填的是从你仓库里真实探测到的 命令。只新增文件，绝不覆盖已存在的文件。 - 回归门禁 —— 给今天的分数拍个快照，之后任何改动导致分数下降、新增 blocker、或任一维度下滑，
CI 就失败。退出码
0/1/2。 - Markdown 与 JSON 报告 —— 用于 PR 评论、看板、审计留痕。
- HTTP API + Web 控制台 —— 雷达图、维度明细、规则表、补丁预览。
- 零运行时依赖 —— 没有东西要解析，没有东西会坏，没有东西要审计。
# 免安装
npx stewardscope scan .
# 或者
npm install -g stewardscope
stewardscope scan /path/to/repo# Docker
docker compose up -d --build
open http://127.0.0.1:8080
# 指定要体检的仓库
REPO_PATH=/Users/you/code/myrepo docker compose up -d --build
docker compose exec stewardscope node dist/cli.js scan /workspaces/repo从源码：
git clone https://github.com/Eileenes/StewardScope.git
cd StewardScope
npm install
npm run build
node dist/cli.js scan .
node dist/cli.js serve # 控制台 http://127.0.0.1:8080只需要 Node 20+，别的都不要。
stewardscope scan [path] 文本报告（默认）
stewardscope report [path] 完整 Markdown 报告
stewardscope rules 列出全部 33 条规则
stewardscope dimensions 列出维度与权重
stewardscope baseline [path] -o FILE 给当前就绪度拍快照
stewardscope diff [path] -b FILE 与快照对比
stewardscope gate [path] CI 门禁：0 通过 / 1 警告 / 2 失败
stewardscope patch [path] 列出缺失的护栏
stewardscope patch [path] --apply 写入（绝不覆盖已有文件）
stewardscope serve -P 8080 HTTP API + Web 控制台
参数：-o/--out、-b/--baseline、-m/--min-score、-d/--allow-drop、-f/--format、-P/--port、
--apply、--json。
# 在已知良好的状态下做一次
npx stewardscope baseline . -o .stewardscope.json# .github/workflows/stewardscope.yml
name: autonomy-readiness
on: [pull_request]
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npx --yes stewardscope gate . --min-score 58| 退出码 | 含义 |
|---|---|
0 |
就绪度持平或提升 |
1 |
有下滑，但在 --allow-drop（默认 2 分）容忍范围内 |
2 |
已退化：新增 blocker、某维度下滑、或低于 --min-score（默认 58） |
对 Agent 场景来说这才是关键：Agent 没法合并一个让仓库变得更不能托管 Agent 的改动。 门禁检查的 正是 Agent 自己的产出。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/health |
存活探针，返回 { status, version } |
| GET | /api/meta |
版本、规则数、默认门禁阈值 |
| POST | /api/scan |
完整体检。Body：{ "path": "/绝对或相对路径" } |
| GET | /api/scan?path=... |
同上，走 query |
| POST | /api/summary |
精简结论：分数、等级、blockers、首要动作 |
| POST | /api/report |
{ path, format: "markdown" } → 渲染好的报告 |
| POST | /api/score |
只要 { score, grade, verdict, shape } |
| POST | /api/baseline |
{ path, target } → 写入快照文件 |
| GET | /api/baseline?target=... |
读取快照 |
| POST | /api/gate |
{ path, min_score, allow_drop, baseline } → { exit_code, ... } |
| POST | /api/diff |
{ path, baseline } → 退化明细 |
| GET | /api/rules |
全部 33 条规则 |
| GET | /api/dimensions |
维度 + 各形态权重 |
| POST | /api/patch |
{ path, apply?, out? } → 建议写入（或已写入）的文件 |
| GET | /* |
Web 控制台（由 static/ 提供） |
curl -s localhost:8080/api/health
curl -s -X POST localhost:8080/api/scan -H 'content-type: application/json' -d '{"path":"."}'
curl -s -X POST localhost:8080/api/gate -H 'content-type: application/json' -d '{"path":".","min_score":58}'StewardScope/
├── src/
│ ├── core/
│ │ ├── types.ts 公共类型
│ │ ├── scan.ts 目录遍历、技术栈与形态识别、git 事实
│ │ ├── score.ts 维度汇总、总分、路线图排序
│ │ ├── patch.ts 护栏文件生成（只增不改）
│ │ ├── report.ts Markdown / 文本渲染
│ │ ├── regress.ts 快照对比 + 门禁裁决
│ │ └── rules/
│ │ ├── catalog.ts 33 条规则定义
│ │ ├── dimensions.ts 维度元数据 + 形态权重 + 等级
│ │ ├── helpers.ts 共用判定函数
│ │ ├── groundtruth.ts contract.ts blast.ts
│ │ ├── recover.ts observe.ts determinism.ts
│ │ └── index.ts 注册表
│ ├── services/audit.ts 编排（scan → audit → gate → patch）
│ ├── server/
│ │ ├── index.ts node:http 服务（零依赖）
│ │ ├── router.ts 极简可区分方法的分发器
│ │ ├── static.ts 控制台静态资源
│ │ └── routers/ health · scan · gate · patch
│ ├── cli.ts
│ └── index.ts 库入口
├── web/ React + TypeScript + Vite 控制台
├── static/ 构建好的控制台（已提交，Docker 里不用跑 Node 构建）
├── tests/ 70 个测试，6 个套件
├── Dockerfile
└── docker-compose.yml
- 运行时：Node 20+，TypeScript 5.7 strict 模式。
- 后端：零运行时依赖 —— 只用
node:http、node:fs、node:path、node:child_process。 - 前端：React 18 + TypeScript + Vite 6，雷达图是手写 SVG，没有图表库。
- 测试：Vitest，70 个测试覆盖 scan / rules / score / patch / regress / HTTP。
- 打包：单阶段
node:20-alpine镜像，控制台构建产物直接提交在static/，所以 Docker 构建 不用跑一遍 Node 工具链。 - 没有数据库。 体检结果是工作区的纯函数；唯一产物是可选的 JSON 快照，由你自己提交。
- 不调大模型。每一个结论都能从文件树复现。
- 不改你的代码。
patch --apply只新增文件。 - 不需要配置文件、不需要账号、不需要联网。
MIT —— 见 LICENSE。