repo-audit-tool 1.2.1 → 1.3.0

package/BEST-PRACTICES.md

@@ -159,7 +159,7 @@ gh repo edit <org>/dsh-<name> --add-topic deepseek-harness --add-topic dsh-plugi
 2. **peer 同范围复制进 devDependencies**（社区事实标准）：peer 不进自身依赖树 → tsc/测试/CI 找不到类型
 3. **单库化坑（subagent-router 实战）**：单库独立安装不装宿主包的 peer——**运行时可达的宿主 peer 包全部显式进 devDependencies**；判定法：`npm test` 报 `Cannot find package` 逐个补
 4. **devDep 精确 pin 特例**：`dsh-client-ui-slots` 的 module augmentation 要求与 runtime 解析副本一致，caret 会漂移致 SlotMap 双副本 → 该包 pin 精确版本（0.2.0 踩过 TS2664/TS2345）
-5. **版本锁定分工**：范围写 package.json（caret），具体版靠提交入库的 `package-lock.json`；CI `npm ci --legacy-peer-deps`（dsh alpha 生态 peer 链不完整）
+5. **版本锁定分工**：范围写 package.json（caret），具体版靠提交入库的 `package-lock.json`；CI `npm ci --legacy-peer-deps`（dsh alpha 生态 peer 链不完整）。锁文件的核心价值在**被消费**：CI/验证链必须实际安装它（`npm ci` / `pip install -r requirements.lock`）——只入库不安装是装饰性合规；`requirements.lock` 非 pip 原生锁格式，没有默认消费者，CI 须显式安装；零依赖仓（依赖声明为空）无锁对象，可豁免。
 
 ### 5.3 dual ESM/CJS（外部调研结论）
 

package/PUBLISHING.md

@@ -4,12 +4,17 @@
 
 | 项 | 状态 |
 |---|---|
-| npm | `repo-audit-tool` v1.2.0（已发布，latest） |
+| npm | `repo-audit-tool` v1.2.3（latest，CI 自动发布） |
 | GitHub | `NinjaSln-labs/repo-audit` master；发版 tag `v*` |
 | 本地验证 | 自审计 100/A，验证链 4/4，测试 3/3，CI 全绿 |
 
 ## 版本历史
 
+- **1.2.3** — package.json 补充 `repository` 字段，修复 npm provenance E422；
+  首次 Trusted Publisher（OIDC）tag 触发自动发布（2026-09-06）
+- **1.2.2** — publish CI 修复：node 20→22 + npm 条件升级，修复 EBADENGINE；
+  tag 发布因 npm 已存在 1.2.1 未出包（OIDC 鉴权链路已验证通过）（2026-09-06）
+- **1.2.1** — README 链接改为绝对 URL（修复 npm 页面 404）；手动发布（2026-09-06）
 - **1.2.0** — 开源就绪：补充 AGENTS.md、CI/publish workflow 适配、json_field monorepo 感知、
   fallback_field 数组格式修复、英文 README、参数类型校验、占位符残留扫描（2026-09-06）
   - 首次发布：`npm publish --access public`（手动 bootstrap）
@@ -44,11 +49,11 @@ git push && git push --tags
 ## 首次发布（已完成）
 
 1. **npm 包创建**：`npm publish --access public`（v1.2.0，2026-09-06）
-2. **Trusted Publisher 配置**（下一步）：npmjs.com → 包设置 → Trusted Publisher →
+2. **Trusted Publisher 配置**：npmjs.com → 包设置 → Trusted Publisher →
    - Repository: `NinjaSln-labs/repo-audit`
    - Workflow: `publish.yml`
-   - Branch: `master`
-3. **验证**：`npm view repo-audit-tool dist-tags` → `{ latest: '1.2.0' }` ✓
+   - Branch: `master`（注：tag 触发场景 npm 亦放行，v1.2.2 实测通过）
+3. **验证**：`npm view repo-audit-tool dist-tags` → latest 已更新 ✓
 
 ## 发布后验证
 

package/docs/AGENT-INDEX.json

@@ -0,0 +1,240 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "repo-audit 文档索引",
+  "description": "AI Agent 可读的文档索引 — 包含所有文档的元数据、结构、和调用协议",
+  "version": "1.3.0",
+  "updated": "2026-09-06",
+  "repo": "NinjaSln-labs/repo-audit",
+  "npm": "repo-audit-tool",
+  "pages": "https://ninjasln-labs.github.io/repo-audit/",
+
+  "entry_points": {
+    "json_index": "/AGENT-INDEX.json",
+    "schema": "/SCHEMA.json",
+    "protocol": "/AGENT-PROTOCOL.md",
+    "human_guide": "/repo-audit/HUMAN-GUIDE.md",
+    "agent_guide": "/repo-audit/AGENT-GUIDE.md"
+  },
+
+  "tool": {
+    "name": "repo-audit",
+    "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
+    "bin": "repo-audit",
+    "version": "1.3.0",
+    "language": "JavaScript (ESM)",
+    "runtime": "Node.js >= 18",
+    "dependencies": [],
+    "license": "MIT",
+
+    "invocation": {
+      "command": "repo-audit [options]",
+      "options": {
+        "--repo": { "type": "string", "default": ".", "description": "目标仓库路径" },
+        "--type": { "type": "string", "description": "强制指定分类（跳过自动检测）" },
+        "--format": { "type": "string", "enum": ["md", "json", "both"], "default": "both", "description": "输出格式" },
+        "--output": { "type": "string", "default": "<repo>/audit-report/", "description": "输出目录" },
+        "--llm-provider": { "type": "string", "description": "LLM 协议：openai/anthropic 或厂商别名" },
+        "--llm-model": { "type": "string", "description": "模型名称" },
+        "--strict": { "type": "boolean", "default": false, "description": "严格模式：Critical/Major 即 exit 1" },
+        "--rules": { "type": "string", "description": "自定义规则 YAML（可多次）" },
+        "--dim": { "type": "string", "description": "只审计指定维度（可多次）" },
+        "--feedback": { "type": "string", "description": "提交反馈（创建 GitHub Issue）" },
+        "--help": { "type": "boolean", "description": "显示帮助" }
+      },
+
+      "exit_codes": {
+        "0": "审计通过（无 Critical/Major 或 --strict 未启用）",
+        "1": "有 Critical/Major 发现且 --strict 启用",
+        "2": "参数错误",
+        "3": "目标不是 git 仓库"
+      }
+    },
+
+    "environment_variables": {
+      "LLM_PROVIDER": "LLM 协议（openai/anthropic/none），也可用厂商别名如 deepseek/qwen/glm",
+      "LLM_API_KEY": "API Key（必须手动指定）",
+      "LLM_MODEL": "模型名称",
+      "LLM_BASE_URL": "自定义 API 端点（OpenAI 兼容厂商必填）",
+      "REPO_AUDIT_TYPES": "自定义分类列表（JSON 数组）"
+    }
+  },
+
+  "audit": {
+    "dimensions": [
+      {
+        "id": "docs",
+        "label": "文档",
+        "rules": ["DOC-001", "DOC-002", "DOC-003", "DOC-003b", "DOC-004", "DOC-005", "DOC-006", "DOC-007"],
+        "description": "README/LICENSE/CONTRIBUTING/SECURITY 等文档完整性"
+      },
+      {
+        "id": "git",
+        "label": "Git",
+        "rules": ["GIT-001", "GIT-002", "GIT-003", "GIT-004"],
+        "description": "commit 规范、分支策略、scaffold 管理"
+      },
+      {
+        "id": "quality",
+        "label": "质量",
+        "rules": ["QUA-001", "QUA-002", "QUA-003", "QUA-004", "QUA-005"],
+        "description": "构建配置、测试、lint、typecheck"
+      },
+      {
+        "id": "security",
+        "label": "安全",
+        "rules": ["SEC-001", "SEC-002", "SEC-003", "SEC-004"],
+        "description": "密钥泄露、依赖漏洞、权限配置"
+      }
+    ],
+
+    "scoring": {
+      "formula": "score = 100 - (critical × 25) - (major × 10) - (minor × 3)",
+      "grades": {
+        "A": ">= 90",
+        "B": ">= 80",
+        "C": ">= 70",
+        "D": ">= 60",
+        "F": "< 60"
+      },
+      "note": "score 和 grade 不在 JSON 输出中，Agent 需根据 summary 字段自行计算"
+    },
+
+    "categories": [
+      "dsh-plugin", "python-app", "go-service", "content", "sandbox",
+      "archive", "product-oss", "javascript", "typescript", "java",
+      "python", "rust", "cpp", "dotnet", "php", "ruby", "unknown"
+    ]
+  },
+
+  "documents": [
+    {
+      "id": "human-guide",
+      "title": "人类使用手册",
+      "path": "/repo-audit/HUMAN-GUIDE.md",
+      "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/HUMAN-GUIDE.md",
+      "audience": "human",
+      "sections": [
+        "一、安装",
+        "二、快速开始",
+        "三、命令行参数",
+        "四、环境变量",
+        "五、输出说明",
+        "六、退出码",
+        "七、审计维度说明",
+        "八、扩展指南",
+        "九、故障排查",
+        "十、与 scaffold 的配合",
+        "十一、操作授权与完成路径",
+        "十二、新特性说明"
+      ]
+    },
+    {
+      "id": "agent-guide",
+      "title": "Agent 操作手册",
+      "path": "/repo-audit/AGENT-GUIDE.md",
+      "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/AGENT-GUIDE.md",
+      "audience": "agent",
+      "sections": [
+        "一、工具定位",
+        "二、调用协议",
+        "三、输出解析",
+        "四、标准操作流程",
+        "五、错误处理协议",
+        "六、性能参考",
+        "七、Agent 决策树",
+        "八、操作授权与完成路径",
+        "九、快速参考卡",
+        "十、反馈通道"
+      ]
+    },
+    {
+      "id": "audit-methodology",
+      "title": "审计方法论",
+      "path": "/AUDIT.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/AUDIT.md",
+      "audience": "both",
+      "description": "评分体系、规则设计、维度划分"
+    },
+    {
+      "id": "best-practices",
+      "title": "最佳实践标准",
+      "path": "/BEST-PRACTICES.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/BEST-PRACTICES.md",
+      "audience": "both",
+      "description": "工程仓库应满足的标准化检查项"
+    },
+    {
+      "id": "classification",
+      "title": "分类检测说明",
+      "path": "/REPO-CLASSIFICATION.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/REPO-CLASSIFICATION.md",
+      "audience": "both",
+      "description": "18 种仓库类型识别逻辑，置信度评分"
+    },
+    {
+      "id": "templates",
+      "title": "脚手架模板",
+      "path": "/templates/README.md",
+      "url": "https://github.com/NinjaSln-labs/repo-audit/blob/master/templates/README.md",
+      "audience": "both",
+      "description": "从零生成符合规范的工程脚手架"
+    },
+    {
+      "id": "schema",
+      "title": "审计报告 JSON Schema",
+      "path": "/SCHEMA.json",
+      "url": "https://ninjasln-labs.github.io/repo-audit/SCHEMA.json",
+      "audience": "agent",
+      "format": "json-schema",
+      "description": "JSON Schema 定义，用于验证审计报告输出"
+    }
+  ],
+
+  "feedback": {
+    "description": "反馈通道 — Agent 可通过 GitHub Issues API 检测和处理用户反馈",
+    "label": "audit-feedback",
+    "repo": "NinjaSln-labs/repo-audit",
+
+    "detect": {
+      "command": "gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt,body",
+      "description": "列出未处理的反馈"
+    },
+    "view": {
+      "command": "gh issue view <NUMBER> --repo NinjaSln-labs/repo-audit --json title,body,labels,createdAt",
+      "description": "获取单条反馈详情"
+    },
+    "close": {
+      "command": "gh issue close <NUMBER> --repo NinjaSln-labs/repo-audit --comment '已处理：[处理说明]'",
+      "description": "反馈已处理，关闭 Issue"
+    },
+    "create": {
+      "command": "node repo-audit.mjs --feedback '<反馈内容>'",
+      "description": "通过 CLI 创建反馈 Issue（自动预填环境信息）"
+    },
+
+    "priorities": [
+      { "level": "critical", "sla": "24h", "description": "工具崩溃/数据损坏" },
+      { "level": "major", "sla": "72h", "description": "功能严重受损" },
+      { "level": "minor", "sla": "1周", "description": "功能部分受损" },
+      { "level": "info", "sla": "排期", "description": "建议改进" }
+    ]
+  },
+
+  "quick_start": {
+    "install": "npm install -g repo-audit-tool",
+    "audit": "repo-audit --repo /path/to/repo",
+    "json_output": "repo-audit --repo /path/to/repo --format json",
+    "scaffold": "node templates/scaffold.mjs --type dsh-plugin --name my-plugin",
+    "strict_mode": "repo-audit --repo /path/to/repo --strict",
+    "custom_rules": "repo-audit --repo /path/to/repo --rules my-rules.yaml",
+    "llm_enhanced": "LLM_API_KEY=sk-xxx repo-audit --repo . --llm-provider deepseek"
+  },
+
+  "changelog": {
+    "1.3.0": "反馈修复：yaml_field 行内注释剥离 + fallback_field 通配（SEC-004 兼容 job 级权限）；AGENTS-core 来源声明二选一；QUA-004 锁文件消费意图；手册补 --update 存量补齐动线",
+    "1.2.3": "package.json 补充 repository 字段，修复 npm provenance E422；完成 Trusted Publisher tag 自动发布",
+    "1.2.2": "publish CI 改用 node 22 + 条件升级 npm，修复 EBADENGINE（tag 发布因 1.2.1 已存在未出包）",
+    "1.2.1": "README 链接改为绝对 URL（修复 npm 页面 404）",
+    "1.2.0": "开源就绪：AGENTS.md、CI/publish workflow、json_field monorepo、fallback_field 数组、英文 README、参数类型校验、占位符扫描"
+  }
+}

package/docs/AGENT-PROTOCOL.md

@@ -0,0 +1,295 @@
+---
+title: repo-audit Agent Protocol
+version: "1.2.1"
+audience: agent
+format: markdown+metadata
+schema: /SCHEMA.json
+index: /AGENT-INDEX.json
+---
+
+# repo-audit Agent Protocol
+
+> 机器可读的操作协议。Agent 直接执行，无需人类解释。
+
+## 1. 工具身份
+
+```json
+{
+  "name": "repo-audit",
+  "npm": "repo-audit-tool",
+  "version": "1.2.1",
+  "bin": "repo-audit",
+  "language": "JavaScript ESM",
+  "runtime": "Node.js >= 18",
+  "dependencies": [],
+  "license": "MIT",
+  "readonly": true
+}
+```
+
+## 2. 调用协议
+
+### 2.1 基本调用
+
+```
+repo-audit [--repo <path>] [--type <type>] [--format <fmt>] [--output <path>]
+           [--llm-provider <p>] [--llm-model <m>] [--strict]
+           [--rules <file>] [--dim <domain>] [--feedback <msg>]
+```
+
+### 2.2 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `--repo` | string | 否 | `.` | 目标仓库路径 |
+| `--type` | string | 否 | 自动检测 | 强制指定分类 |
+| `--format` | enum | 否 | `both` | `md` / `json` / `both` |
+| `--output` | string | 否 | `<repo>/audit-report/` | 输出目录 |
+| `--llm-provider` | string | 否 | 环境变量 | LLM 协议 |
+| `--llm-model` | string | 否 | 自动 | 模型名称 |
+| `--strict` | bool | 否 | `false` | Critical/Major 即 exit 1 |
+| `--rules` | string[] | 否 | — | 自定义规则 YAML |
+| `--dim` | string[] | 否 | 全部 | 只审计指定维度 |
+| `--feedback` | string | 否 | — | 提交反馈 |
+
+### 2.3 退出码
+
+| 码 | 含义 | Agent 应执行 |
+|---|---|---|
+| 0 | 审计通过 | 正常继续 |
+| 1 | Critical/Major 发现 + --strict | 读取 findings 并报告 |
+| 2 | 参数错误 | 修正参数后重试 |
+| 3 | 目标不是 git 仓库 | 提示用户切换到 git 仓库 |
+
+## 3. 输出格式
+
+### 3.1 JSON 报告结构
+
+```json
+{
+  "generated_at": "2026-09-06T12:00:00.000Z",
+  "audit_type": "dsh-plugin",
+  "llm_used": false,
+  "metadata": {
+    "remote": "https://github.com/org/repo.git",
+    "branch": "master",
+    "commitCount": 42,
+    "fileCount": 117,
+    "lastCommit": "2026-09-06 12:00:00 +0800",
+    "path": "/path/to/repo"
+  },
+  "summary": {
+    "critical": 0,
+    "major": 0,
+    "minor": 0,
+    "info": 0,
+    "pass": 19,
+    "total": 19,
+    "waived": 0,
+    "llmUsed": false
+  },
+  "findings": [
+    {
+      "id": "DOC-001",
+      "title": "README.md 存在",
+      "severity": "critical",
+      "domain": "docs",
+      "applies_to": ["*"],
+      "status": "pass",
+      "message": "符合",
+      "evidence": "✓ README.md (3.1kB)",
+      "hint": null,
+      "template_ref": null
+    }
+  ]
+}
+```
+
+### 3.2 评分公式
+
+```
+score = 100 - (critical × 25) - (major × 10) - (minor × 3)
+```
+
+| 等级 | 分数 |
+|---|---|
+| A | ≥ 90 |
+| B | ≥ 80 |
+| C | ≥ 70 |
+| D | ≥ 60 |
+| F | < 60 |
+
+### 3.3 发现状态
+
+| 状态 | 含义 | Agent 处理 |
+|---|---|---|
+| `pass` | 检查通过 | 忽略 |
+| `fail` | 检查失败 | 读取 `message` + `evidence` + `hint` |
+| `waived` | 已豁免 | 读取 `waived_reason` + `waived_since` |
+
+### 3.4 严重级别
+
+| 级别 | 扣分 | Agent 优先级 |
+|---|---|---|
+| `critical` | -25 | P0 — 立即处理 |
+| `major` | -10 | P1 — 优先处理 |
+| `minor` | -3 | P2 — 正常处理 |
+| `info` | 0 | P3 — 参考信息 |
+
+## 4. 标准操作流程
+
+### 4.1 新建仓库后验证
+
+```bash
+repo-audit --repo /path/to/new-repo --format json
+```
+
+Agent 读取 JSON，检查 `summary.grade`：
+- `A` → 通过，报告成功
+- `B/C` → 报告需改进项（列出 fail findings）
+- `D/F` → 警告，建议修复 critical/major 问题
+
+### 4.2 CI 门禁集成
+
+```yaml
+# GitHub Actions 示例
+- name: Audit
+  run: repo-audit --repo . --format json --strict
+```
+
+`--strict` 使 Critical/Major 发现返回 exit 1，自动阻断 CI。
+
+### 4.3 自定义规则
+
+```yaml
+# my-rules.yaml
+rules:
+  - id: COM-001
+    title: "提交信息规范"
+    severity: major
+    domain: git
+    applies_to: ["*"]
+    check: commit_message
+    params:
+      pattern: "^(feat|fix|docs|chore|refactor|test):"
+```
+
+```bash
+repo-audit --repo . --rules my-rules.yaml
+```
+
+### 4.4 反馈处理
+
+```bash
+# 检测新反馈
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt,body
+
+# 获取详情
+gh issue view 42 --repo NinjaSln-labs/repo-audit --json title,body,labels
+
+# 处理完成
+gh issue close 42 --repo NinjaSln-labs/repo-audit --comment "已处理：修复了 X 问题"
+```
+
+## 5. 错误处理协议
+
+| 错误 | 原因 | Agent 处理 |
+|---|---|---|
+| `目标不是 git 仓库` | 目录无 `.git/` | 提示 `git init` 或切换到正确路径 |
+| `未知参数` | 参数拼写错误 | 检查 `--help` |
+| `LLM 增强失败` | API Key 无效/网络问题 | 降级为非 LLM 模式 |
+| `规则加载失败` | YAML 语法错误 | 报告错误行，不阻断审计 |
+| `分类检测不准` | 文件结构特殊 | 使用 `--type` 强制指定 |
+
+## 6. Agent 决策树
+
+```
+收到审计请求
+  ├─ 有 --repo 参数？
+  │   ├─ 否 → 默认当前目录
+  │   └─ 是 → 使用指定路径
+  ├─ 有 --format 参数？
+  │   ├─ json → 只输出 JSON
+  │   ├─ md → 只输出 Markdown
+  │   └─ both/默认 → 同时输出
+  ├─ 有 LLM 配置？
+  │   ├─ 是 → 启用 LLM 增强
+  │   └─ 否 → 纯规则审计
+  ├─ 执行审计
+  ├─ 解析 summary
+  │   ├─ grade A → 报告通过
+  │   ├─ grade B/C → 报告改进项
+  │   └─ grade D/F → 警告严重问题
+  └─ 输出结果
+```
+
+## 7. 反馈通道
+
+### 7.1 检测协议
+
+```bash
+# 列出未处理反馈
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open --json number,title,createdAt,body
+
+# 获取详情
+gh issue view <NUMBER> --repo NinjaSln-labs/repo-audit --json title,body,labels,createdAt
+
+# 关闭已处理
+gh issue close <NUMBER> --repo NinjaSln-labs/repo-audit --comment "已处理：[说明]"
+```
+
+### 7.2 创建反馈
+
+```bash
+# CLI 方式
+node repo-audit.mjs --feedback "在 xxx 场景下出现 yyy 问题"
+
+# API 方式
+gh issue create --repo NinjaSln-labs/repo-audit \
+  --title "Feedback: <标题>" \
+  --body "<正文>" \
+  --label "feedback,audit-feedback"
+```
+
+### 7.3 处理优先级
+
+| 级别 | SLA | 描述 |
+|---|---|---|
+| critical | 24h | 工具崩溃/数据损坏 |
+| major | 72h | 功能严重受损 |
+| minor | 1周 | 功能部分受损 |
+| info | 排期 | 建议改进 |
+
+## 8. 快速参考卡
+
+```bash
+# 安装
+npm install -g repo-audit-tool
+
+# 基本审计
+repo-audit --repo /path/to/repo
+
+# JSON 输出
+repo-audit --repo /path/to/repo --format json
+
+# 严格模式（CI 用）
+repo-audit --repo . --format json --strict
+
+# LLM 增强
+LLM_API_KEY=sk-xxx repo-audit --repo . --llm-provider deepseek
+
+# 自定义规则
+repo-audit --repo . --rules my-rules.yaml
+
+# 指定维度
+repo-audit --repo . --dim security --dim docs
+
+# 生成脚手架
+node templates/scaffold.mjs --type dsh-plugin --name my-plugin
+
+# 提交反馈
+repo-audit --feedback "问题描述"
+
+# 检测反馈
+gh issue list --repo NinjaSln-labs/repo-audit --label audit-feedback --state open
+```

package/docs/SCHEMA.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ninjasln-labs.github.io/repo-audit/SCHEMA.json",
+  "title": "repo-audit 审计报告 Schema",
+  "description": "repo-audit 工具输出的 JSON 报告格式定义",
+  "type": "object",
+  "required": ["generated_at", "audit_type", "llm_used", "metadata", "summary", "findings"],
+  "properties": {
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "报告生成时间 (ISO 8601)"
+    },
+    "audit_type": {
+      "type": "string",
+      "description": "检测到的仓库分类",
+      "enum": [
+        "dsh-plugin", "python-app", "go-service", "content", "sandbox",
+        "archive", "product-oss", "javascript", "typescript", "java",
+        "python", "rust", "cpp", "dotnet", "php", "ruby", "unknown"
+      ]
+    },
+    "llm_used": {
+      "type": "boolean",
+      "description": "是否使用了 LLM 增强"
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["remote", "branch", "commitCount", "fileCount", "lastCommit", "path"],
+      "properties": {
+        "remote": { "type": ["string", "null"], "description": "git remote URL" },
+        "branch": { "type": "string", "description": "当前分支" },
+        "commitCount": { "type": "number", "description": "commit 总数" },
+        "fileCount": { "type": "number", "description": "文件总数" },
+        "lastCommit": { "type": "string", "description": "最近 commit 时间" },
+        "path": { "type": "string", "description": "仓库路径" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["critical", "major", "minor", "info", "pass", "total", "waived", "llmUsed"],
+      "properties": {
+        "critical": { "type": "number", "minimum": 0, "description": "Critical 级发现数" },
+        "major": { "type": "number", "minimum": 0, "description": "Major 级发现数" },
+        "minor": { "type": "number", "minimum": 0, "description": "Minor 级发现数" },
+        "info": { "type": "number", "minimum": 0, "description": "Info 级发现数" },
+        "pass": { "type": "number", "minimum": 0, "description": "通过的检查数" },
+        "total": { "type": "number", "minimum": 1, "description": "总检查数" },
+        "waived": { "type": "number", "minimum": 0, "description": "已豁免的检查数" },
+        "llmUsed": { "type": "boolean" }
+      },
+      "description": "汇总统计。评分公式：score = 100 - (critical×25) - (major×10) - (minor×3)。等级：A≥90, B≥80, C≥70, D≥60, F<60"
+    },
+    "findings": {
+      "type": "array",
+      "description": "审计发现列表",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "severity", "domain", "status", "message", "evidence"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "规则 ID",
+            "pattern": "^(DOC|GIT|QUA|SEC|COM|DEP)-\\d{3}[a-z]?$"
+          },
+          "title": { "type": "string", "description": "规则标题" },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "info"]
+          },
+          "domain": {
+            "type": "string",
+            "enum": ["docs", "git", "quality", "security", "compliance", "dependencies"]
+          },
+          "applies_to": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "适用的仓库分类列表，* 表示全部"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail", "waived"]
+          },
+          "message": { "type": "string", "description": "通过: '符合'; 失败: 规则描述" },
+          "evidence": { "type": "string", "description": "证据文本" },
+          "hint": { "type": ["string", "null"], "description": "修复建议" },
+          "template_ref": { "type": ["string", "null"], "description": "模板引用" },
+          "waived_reason": { "type": ["string", "null"], "description": "豁免原因" },
+          "waived_since": { "type": ["string", "null"], "description": "豁免起始日期" }
+        }
+      }
+    }
+  }
+}

package/docs/index.html

@@ -4,6 +4,31 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>repo-audit 文档</title>
+
+  <!-- JSON-LD 结构化数据 — AI Agent 可读 -->
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "①type": "SoftwareApplication",
+    "name": "repo-audit",
+    "url": "https://github.com/NinjaSln-labs/repo-audit",
+    "downloadUrl": "https://www.npmjs.com/package/repo-audit-tool",
+    "softwareVersion": "1.2.1",
+    "applicationCategory": "DeveloperApplication",
+    "operatingSystem": "Node.js >= 18",
+    "license": "MIT",
+    "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
+    "programmingLanguage": "JavaScript ESM",
+    "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
+    "documentation": [
+      { "name": "AGENT-INDEX.json", "url": "https://ninjasln-labs.github.io/repo-audit/AGENT-INDEX.json", "format": "json" },
+      { "name": "SCHEMA.json", "url": "https://ninjasln-labs.github.io/repo-audit/SCHEMA.json", "format": "json-schema" },
+      { "name": "AGENT-PROTOCOL.md", "url": "https://ninjasln-labs.github.io/repo-audit/AGENT-PROTOCOL.md", "format": "markdown" },
+      { "name": "HUMAN-GUIDE.md", "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/HUMAN-GUIDE.md", "format": "markdown" },
+      { "name": "AGENT-GUIDE.md", "url": "https://ninjasln-labs.github.io/repo-audit/repo-audit/AGENT-GUIDE.md", "format": "markdown" }
+    ]
+  }
+  </script>
   <style>
     :root { --bg: #0d1117; --card: #161b22; --border: #30363d; --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff; --accent-hover: #79c0ff; --green: #3fb950; }
     * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -61,12 +86,13 @@
   <div class="nav-bar">
     <a href="https://github.com/NinjaSln-labs/repo-audit" style="font-weight:700;color:var(--text);text-decoration:none;">repo-audit</a>
     <div class="nav-links">
+      <a href="AGENT-INDEX.json">🤖 Agent 索引</a>
+      <a href="SCHEMA.json">📐 Schema</a>
+      <a href="AGENT-PROTOCOL.md">📖 协议</a>
       <a href="repo-audit/HUMAN-GUIDE.md">使用手册</a>
       <a href="repo-audit/AGENT-GUIDE.md">Agent 手册</a>
       <a href="../AUDIT.md">审计方法论</a>
       <a href="../BEST-PRACTICES.md">最佳实践</a>
-      <a href="../REPO-CLASSIFICATION.md">分类检测</a>
-      <a href="../PUBLISHING.md">发布流程</a>
     </div>
   </div>
 
@@ -90,6 +116,32 @@
     <div class="stat"><div class="stat-value">0</div><div class="stat-label">npm 依赖</div></div>
   </div>
 
+  <!-- Agent 入口 -->
+  <div class="agent-entry" style="background:#0d2137;border:1px solid #1f6feb;border-radius:8px;padding:1.5rem;margin:2rem 0;">
+    <h2 style="color:#58a6ff;font-size:1.3rem;margin-bottom:1rem;">🤖 AI Agent 入口</h2>
+    <p style="color:#8b949e;margin-bottom:1rem;">Agent 可读取以下结构化文档，自动理解工具协议、输出格式和调用方式：</p>
+    <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:1rem;">
+      <div style="background:#161b22;border:1px solid #30363d;border-radius:6px;padding:1rem;">
+        <a href="AGENT-INDEX.json" style="color:#58a6ff;text-decoration:none;font-weight:600;">📋 AGENT-INDEX.json</a>
+        <p style="color:#8b949e;font-size:0.85rem;margin-top:0.3rem;">机器可读文档索引<br>包含工具参数、退出码、环境变量、文档结构</p>
+      </div>
+      <div style="background:#161b22;border:1px solid #30363d;border-radius:6px;padding:1rem;">
+        <a href="SCHEMA.json" style="color:#58a6ff;text-decoration:none;font-weight:600;">📐 SCHEMA.json</a>
+        <p style="color:#8b949e;font-size:0.85rem;margin-top:0.3rem;">JSON Schema 定义<br>用于验证审计报告输出格式</p>
+      </div>
+      <div style="background:#161b22;border:1px solid #30363d;border-radius:6px;padding:1rem;">
+        <a href="AGENT-PROTOCOL.md" style="color:#58a6ff;text-decoration:none;font-weight:600;">📖 AGENT-PROTOCOL.md</a>
+        <p style="color:#8b949e;font-size:0.85rem;margin-top:0.3rem;">Agent 操作协议<br>调用方式、输出解析、决策树、错误处理</p>
+      </div>
+    </div>
+    <pre style="margin-top:1rem;background:#0d1117;border:1px solid #30363d;border-radius:6px;padding:1rem;font-size:0.85rem;"><code># Agent 一键获取文档索引
+curl -s https://ninjasln-labs.github.io/repo-audit/AGENT-INDEX.json | jq '.tool.invocation'
+
+# 验证审计报告
+jq --argfile schema https://ninjasln-labs.github.io/repo-audit/SCHEMA.json \
+  'empty as $_ | ., (input)' audit-report.json &gt; /dev/null</code></pre>
+  </div>
+
   <div class="cards">
     <div class="card">
       <h2>📖 人类使用手册</h2>

package/docs/repo-audit/AGENT-GUIDE.md

@@ -191,7 +191,29 @@ cat audit-report/report.json | jq '.findings[] | select(.status=="fail") | .id'
 # 5. 如有 Critical 发现，阻断生成流程
 ```
 
-### 4.2 模板升级后校验
+### 4.2 存量仓库补齐缺失文档（Issue#3 动线）
+
+审计 fail 后需要补 AGENTS.md / CONTRIBUTING.md 等模板文档时，**优先用 `scaffold --update` 而不是手写**：
+
+```bash
+# 1. 存量仓首次接入（无 .scaffold/lock/）——adopt 模式，零覆盖保证
+node scaffold.mjs --update <repo> --type <type> --dry-run   # 先看会落位什么
+node scaffold.mjs --update <repo> --type <type>            # 实际执行
+
+# 2. 行为：
+#    - 仓库缺失的文件（如 AGENTS.md）→ ADDED 直拷
+#    - 仓库已有且与模板不同 → .scaffold-merge/ 人工评审区（不覆盖你的内容）
+#    - 工作区必须 clean（先 commit/stash）
+# 3. 补齐后重跑审计确认
+node repo-audit.mjs --repo <repo> --format json
+```
+
+要点：
+- `--update` 对**从未被 scaffold 管理的仓**同样可用（自动 adopt，建立 `.scaffold/lock/`）
+- 手写 AGENTS.md 时，**按来源声明二选一**：无 lock 的仓删除「单源拼装」行、保留「自主维护」行（模板头部已内置两种措辞）
+- `--skip <path>` 可排除不想让模板接管的文件（可多次）
+
+### 4.3 模板升级后校验
 
 ```bash
 # 1. 审计当前状态
@@ -209,7 +231,7 @@ after=$(cat ./audit-after/report.json | jq '.summary')
 # 如果 after.critical > before.critical → 告警：模板升级引入了问题
 ```
 
-### 4.3 CI 门禁集成
+### 4.4 CI 门禁集成
 
 ```yaml
 # GitHub Actions 示例
@@ -219,7 +241,7 @@ after=$(cat ./audit-after/report.json | jq '.summary')
     echo "Score: $(jq '.summary | 100 - (.critical * 25) - (.major * 10) - (.minor * 3)' ./.ci-audit/report.json)"
 ```
 
-### 4.4 增量维度审计
+### 4.5 增量维度审计
 
 ```bash
 # 只审计安全（快速）
@@ -232,7 +254,7 @@ node repo-audit.mjs --dim docs --format json
 node repo-audit.mjs --dim git --dim docs --dim security --dim quality --format json
 ```
 
-### 4.5 自定义规则叠加
+### 4.6 自定义规则叠加
 
 ```bash
 # 创建自定义规则

package/docs/repo-audit/HUMAN-GUIDE.md

@@ -507,10 +507,13 @@ node repo-audit.mjs --repo ./my-repo --type python-app
 | 操作 | 命令序列 |
 |---|---|
 | 新建仓库后验证 | `scaffold.mjs --type xxx --name yyy` → `repo-audit.mjs --repo ./yyy` |
+| **存量仓补齐缺失文档** | `scaffold.mjs --update ./zzz --type xxx --dry-run`（预览）→ `scaffold.mjs --update ./zzz`（执行；adopt 模式零覆盖）→ `repo-audit.mjs --repo ./zzz` 复审 |
 | 模板升级后对比 | `repo-audit.mjs --repo ./zzz --output ./before` → `scaffold.mjs --update ./zzz` → `repo-audit.mjs --repo ./zzz --output ./after` |
 | CI 门禁 | `repo-audit.mjs --repo . --strict --format json` |
 | PR 描述附件 | `repo-audit.mjs --repo . --format md --output ./pr-audit` → 附 `pr-audit/report.md` 到 PR |
 
+> **补 AGENTS.md 提示**（DOC-004 fail 时）：优先 `scaffold --update` 补齐（模板头部自带来源声明二选一）；确需手写时，无 `.scaffold/lock/` 的仓按「自主维护」措辞写头部，勿照抄「单源拼装」行。
+
 ---
 
 ## 十一、操作授权与完成路径

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-audit-tool",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "仓库标准化审计工具 + 工程脚手架生成器（零依赖）",
   "type": "module",
   "main": "repo-audit.mjs",
@@ -20,6 +20,10 @@
     "best-practices",
     "repository"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NinjaSln-labs/repo-audit"
+  },
   "engines": {
     "node": ">=18"
   },

package/repo-audit.mjs

@@ -202,7 +202,48 @@ function countNonHiddenFiles(path) {
   return count
 }
 
+// Issue#2 fix: 定位指定缩进层级下的具名子键（返回行号与缩进；未找到返回 null）
+function findNestedYamlKey(lines, startIdx, baseIndent, key) {
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (!l.trim() || l.trim().startsWith('#')) continue
+    const ind = l.length - l.trimStart().length
+    if (ind <= baseIndent) return null
+    if (ind !== baseIndent + 2) continue // 只看直接子层（YAML 常规 2 空格缩进）
+    const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+    if (m && m[1] === key) return { idx: i, indent: ind }
+  }
+  return null
+}
+// Issue#2 fix: 列出指定父键下一层的所有子键名（通配 * 展开用）
+function listChildKeys(lines, startIdx, baseIndent) {
+  const keys = []
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (!l.trim() || l.trim().startsWith('#')) continue
+    const ind = l.length - l.trimStart().length
+    if (ind <= baseIndent) break
+    if (ind !== baseIndent + 2) continue
+    const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+    if (m) keys.push(m[1])
+  }
+  return keys
+}
+
 // P0-3 fix: 嵌套 YAML 路径下钻查找（替代行级正则）
+// Issue#1 fix: 剥离行内注释（# 前须有空白；引号内 # 不算注释——按引号配对状态跳过）
+export function stripYamlComment(s) {
+  let str = s
+  // 整段以 # 开头（允许前导空白）→ 值为空（父级保持嵌套下钻语义）
+  if (/^\s*#/.test(str)) return ''
+  // 引号包裹：取第一个配对引号内的内容，引号后的尾注释丢弃
+  const q = str.match(/^(\s*)(['"])([\s\S]*?)\2(?:\s+#.*)?$/)
+  if (q) return q[3].trim()
+  // 无引号：以「空白+#」为注释分隔，截断尾部
+  const cut = str.search(/\s#/)
+  if (cut !== -1) str = str.slice(0, cut)
+  return str.trim()
+}
 function findNestedYaml(lines, startIdx, baseIndent, segments) {
   let currentIndent = baseIndent
   for (let i = startIdx + 1; i < lines.length; i++) {
@@ -213,7 +254,7 @@ function findNestedYaml(lines, startIdx, baseIndent, segments) {
     const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
     if (m) {
       const key = m[1]
-      const valStr = m[2].trim()
+      const valStr = stripYamlComment(m[2])
       const seg = segments[0]
       if (key === seg) {
         if (valStr && valStr !== '' && valStr !== '{}') {
@@ -650,7 +691,7 @@ function loadRules(type, customPaths = [], repoPath = null) {
     grep:           { pattern: ['string'] },
     json_field:     { path: ['string'], field: ['string'], fallback_field: ['array', 'string'] },
     toml_field:     { path: ['string'], field: ['string'] },
-    yaml_field:     { path: ['string'], field: ['string'] },
+    yaml_field:     { path: ['string'], field: ['string'], fallback_field: ['array', 'string'] },
     directory_exists: { paths: ['array', 'string'] },
     not_exists:     { paths: ['array', 'string'] },
     glob_count:     { pattern: ['string'] },
@@ -1007,7 +1048,7 @@ function runCheck(rule, repoPath, mpj = null) {
           const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
           if (m && m[1] === segments[0]) {
             currentIndent = ind
-            const valStr = m[2].trim()
+            const valStr = stripYamlComment(m[2])
             if (valStr && valStr !== '' && valStr !== '{}') {
               // 标量值（非嵌套）
               val = valStr
@@ -1028,6 +1069,77 @@ function runCheck(rule, repoPath, mpj = null) {
         passed = false
         evidence = '字段不存在或值不匹配'
       }
+      // Issue#2 fix: yaml_field fallback_field——主字段不匹配时逐个尝试备选字段路径（数组形态）。
+      // 用途：同一语义在不同 YAML 形态下的位置差异（如 id-token: write 可在 workflow 顶层
+      // 或 publish job 级——PyPA 最小化权限模式），任一命中即 pass。
+      // 段内 `*` 为通配（如 jobs.*.permissions.id-token）：在该层级所有子键下逐个尝试。
+      if (!passed && params?.fallback_field) {
+        const fbList = Array.isArray(params.fallback_field) ? params.fallback_field : [params.fallback_field]
+        for (const fbField of fbList) {
+          if (!fbField) continue
+          const fbSegments = String(fbField).split('.')
+          const candidates = [] // 每项 {segments} —— 通配展开后的具体路径列表
+          const expandWildcard = (segs) => {
+            const wIdx = segs.indexOf('*')
+            if (wIdx === -1) { candidates.push({ segments: segs }); return }
+            // 找通配段父级的所有子键：先定位父级前缀（逐段下钻收集行号）
+            const lines = content.split('\n')
+            const prefix = segs.slice(0, wIdx)
+            const suffix = segs.slice(wIdx + 1)
+            // 顶层段
+            if (prefix.length === 0) return
+            for (let i = 0; i < lines.length; i++) {
+              const l = lines[i]
+              if (!l.trim() || l.trim().startsWith('#')) continue
+              const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+              if (!m || m[1] !== prefix[0]) continue
+              // 沿 prefix 下钻
+              let curIdx = i, curIndent = l.length - l.trimStart().length
+              let ok = true
+              for (let d = 1; d < prefix.length; d++) {
+                const sub = findNestedYamlKey(lines, curIdx, curIndent, prefix[d])
+                if (!sub) { ok = false; break }
+                curIdx = sub.idx; curIndent = sub.indent
+              }
+              if (!ok) return
+              // 列出 curIndent 下一层的所有子键
+              const childKeys = listChildKeys(lines, curIdx, curIndent)
+              for (const k of childKeys) expandWildcard([...prefix, k, ...suffix])
+              return
+            }
+          }
+          expandWildcard(fbSegments)
+          for (const cand of candidates) {
+            let fbVal = null
+            let fbFound = false
+            try {
+              const lines = content.split('\n')
+              for (let i = 0; i < lines.length; i++) {
+                const l = lines[i]
+                if (!l.trim() || l.trim().startsWith('#')) continue
+                const ind = l.length - l.trimStart().length
+                const m = l.match(/^\s*(\w[\w\-]*)\s*:\s*(.*)$/)
+                if (m && m[1] === cand.segments[0]) {
+                  const v = stripYamlComment(m[2])
+                  if (v && v !== '' && v !== '{}') { fbVal = v; fbFound = true }
+                  else {
+                    const sub = findNestedYaml(lines, i, ind, cand.segments.slice(1))
+                    if (sub.found) { fbVal = sub.value; fbFound = true }
+                  }
+                  break
+                }
+              }
+            } catch {}
+            if (fbFound && String(fbVal).trim() === expected) {
+              passed = true
+              const concrete = cand.segments.join('.')
+              evidence = `fallback ${concrete} = ${String(fbVal).trim()}`
+              break
+            }
+          }
+          if (passed) break
+        }
+      }
       break
     }
 
@@ -1539,7 +1651,11 @@ ${message}
   process.exit(hasCritical && strict ? 1 : 0)
 }
 
-main().catch(err => {
-  console.error(`✗ 运行时错误: ${err.message}`)
-  process.exit(2)
-})
+// Issue#1 fix: 入口守卫——仅直接作为 CLI 运行时执行主流程；被 import（测试/编程复用）不跑
+const isDirectRun = import.meta.url === `file://${process.argv[1]}`
+if (isDirectRun) {
+  main().catch(err => {
+    console.error(`✗ 运行时错误: ${err.message}`)
+    process.exit(2)
+  })
+}

package/rules/domains/quality.yaml

@@ -54,8 +54,9 @@ rules:
         - "go.sum"
         - "requirements.lock"
       anyOf: true
-    description: "锁文件应入库以确保可复现构建（BEST-PRACTICES §5.4 验证链）"
-    note: "无包管理的仓库豁免"
+    description: "锁文件应入库以确保可复现构建（BEST-PRACTICES §5.4）——锁文件还须被 CI/验证链实际安装消费（npm ci / pip install -r requirements.lock 等），只入库不安装是装饰性合规；requirements.lock 非 pip 原生锁格式，CI 须显式写明安装它"
+    note: "无包管理的仓库豁免；零依赖仓（依赖声明为空，无锁对象）可用 .auditrc.yaml 豁免并注明原因"
+    fix_hint: "提交锁文件（package-lock.json / poetry.lock / go.sum / requirements.lock 任一）并确认 CI 安装步骤实际使用它（npm ci / pip install -r …）；零依赖仓在 .auditrc.yaml 豁免注明"
 
   - id: QUA-005
     title: "CLAUDE.md 桥接"

package/rules/domains/security.yaml

@@ -72,8 +72,9 @@ rules:
     params:
       path: ".github/workflows/publish.yml"
       field: "permissions.id-token"
+      fallback_field: ["jobs.*.permissions.id-token"]
       expected: "write"
       skip_if_no_file: ".github/workflows/publish.yml"
-    description: "publish workflow 必须请求 id-token: write 权限（OIDC Trusted Publishing）"
+    description: "publish workflow 必须请求 id-token: write 权限（OIDC Trusted Publishing）——工作流顶层或 publish job 级任一即可（job 级为 PyPA 推荐的最小化模式）"
     template_ref: "templates/repo-root/.github/workflows/publish.yml"
-    fix_hint: "在 workflow 顶部添加 permissions: id-token: write"
+    fix_hint: "在 publish workflow 声明 permissions.id-token: write——顶层（permissions: 块内）或仅 publish job（jobs.publish.permissions: 块内）均可；推荐 job 级（最小化，其他 job 不持有 OIDC 权限）"

package/templates/common/AGENTS-core.md

@@ -1,7 +1,10 @@
 # AGENTS（AI 协作与工程纪律）
 
-> 本文件由模板**单源拼装**（`common/AGENTS-core.md` + 分类 append）——重复段不要在仓库里手改；
-> 改规则先改模板源，再重新生成。人工协作者同样适用本文件全部条款。
+> **来源声明（二选一，按实际来源保留其一，删除另一行）**：
+> - 由 scaffold 生成/更新（仓在 `.scaffold/lock/`）：单源拼装（`common/AGENTS-core.md` + 分类 append）——重复段勿手改，改规则先改模板源，再跑 `node scaffold.mjs --update <repo>` 合并。
+> - 手写/移植（无 `.scaffold/lock/`）：本文件归本仓库自主维护，直接在仓库内改，单源约束不适用。
+>
+> 人工协作者同样适用本文件全部条款。
 
 ## 项目概览
 

package/templates/repo-root/.github/workflows/publish.yml

@@ -61,12 +61,17 @@ jobs:
         # smoke/mount/vitest 为探测式：文件存在才跑，接入即自动进链。
         run: node scripts/verify.mjs
       - name: Publish to npm (OIDC trusted publishing)
-        # 升级 npm：trusted publishing 需 npm CLI >= 11.5.1（含 OIDC 支持）。
+        # trusted publishing 需 npm CLI >= 11.5.1（含 OIDC 支持）。
+        # 上游 runner Node 自带的 npm 已满足时直接用——不装 npm@latest：
+        # 其 engine 门槛会随版本漂移（npm@12 要求 node ^22.22.2，曾致本仓 EBADENGINE），
+        # 仅当自带版本过旧时兜底升级到 npm@11（比 latest 门槛低、仍含 OIDC）。
         # prerelease → dist-tag next（忘加 --tag next 是最常见事故：
         # 用户 npm install 会装到 prerelease）；稳定版 → latest。
         run: |
-          npm install -g npm@latest
           echo "npm version: $(npm --version)"
+          if ! npm --version | grep -qE '^(11\.(5\.[1-9]|[6-9]|[0-9]{2})|1[2-9]|2[0-9])'; then
+            npm install -g npm@11
+          fi
           VERSION="$(node -p "require('./package.json').version")"
           if [[ "$VERSION" == *-* ]]; then
             echo "canary prerelease $VERSION → dist-tag next"

package/HANDOFF.md

@@ -1,131 +0,0 @@
-# HANDOFF — repo-audit 工具（工程交接）
-
-## 1. 交接元信息
-
-- **日期**：2026-09-06
-- **交接方**：repo-audit 维护 agent
-- **接收方**：继续维护 repo-audit 的 agent / 新 session
-- **原因**：里程碑达成（开源发布完成）· 开发仓废弃，转入本开源仓
-- **项目一句话**：零依赖 Node.js ESM 仓库标准化审计工具 + 工程脚手架生成器
-- **主战场变更**：**本仓 `ninjasin-labs/repo-audit/` 现在是唯一开发与发布位置**；原开发仓 `dsh-ecosystem/research/scaffold-templates/` **已废弃**（历史快照，勿再改）
-- **文档入口链**（本仓内）：
-  - 会话记录：`ninjasin-labs/.agents/session.md`（进度权威）
-  - 人类手册：`docs/repo-audit/HUMAN-GUIDE.md`
-  - Agent 手册：`docs/repo-audit/AGENT-GUIDE.md`
-  - 自审报告：`docs/repo-audit/SELF-AUDIT.md`
-  - 影子回归：`docs/repo-audit/SHADOW-AUDIT-20260906-v3.md`
-- **接收方建议动作**：
-  1. 读 `ninjasin-labs/.agents/session.md` 了解反馈闭环全貌
-  2. 读 `docs/repo-audit/AGENT-GUIDE.md` 了解操作协议
-  3. 所有后续开发、迭代、审计验收都在**本仓**完成
-
-## 2. 当前状态快照
-
-### 版本控制状态
-
-| 项 | 值 |
-|---|---|
-| 主仓（本仓） | `ninjasin-labs/repo-audit/`（独立 git 仓） |
-| 分支 | master |
-| commits | 10（`11eaf65` → `bca65ff` → `cbb7e40` → `de44f20` → `abea615` → `43e9245` → `eea507a` → `45fbfb9` → `b3a2e8f` → `ef967fd` → `4318ae1`） |
-| 远端 | **已建** — `https://github.com/NinjaSln-labs/repo-audit`（公开） |
-| npm | **已发布** — `repo-audit-tool` v1.2.0（latest） |
-| 废弃仓 | `dsh-ecosystem/research/scaffold-templates/`（历史快照，勿改） |
-
-### 最近完成（一行式）
-
-- `4318ae1` docs(release): PUBLISHING.md 更新 — 反映 Trusted Publisher 流程
-- `ef967fd` chore(release): 发布 repo-audit-tool@1.2.0 到 npm
-- `b3a2e8f` chore(release): 发布准备 — 改名 + bin 可执行 + PUBLISHING.md
-- `45fbfb9` fix(engine): C 优化补充 — fallback_field 逗号分隔字符串检测
-- `43e9245` fix(ci): 适配 repo-audit — 移除 dsh-demo 模板残留（CI 首次跑通）
-- `abea615` fix(engine): json_field monorepo 感知 + fallback_field 数组格式修复
-- `de44f20` fix(docs): 补充 AGENTS.md — 修复 CLAUDE.md 悬空引用 + 多文档断链
-- `bca65ff` 开源就绪 — 补充工程规范 + 验证链 + 测试（自审计 100/A）
-- `11eaf65` repo-audit 开源初始提交
-- （开发仓历史，已废弃，仅参考）`e99b504` P6 monorepo / `bcf21d3` E5 豁免 / `053c524` E6 序列化 / `ca01f00` fuyao 假阳性修复
-
-### 构建环境状态
-
-- **零 npm 依赖**，无需 install
-- 自审计 **100/A**（19/19 pass）
-- 测试：`node --test` 3 用例通过；`node verify.mjs` 4 项通过
-- Node ≥18
-
-### 占位/未完成边界
-
-- **json_field 检查器**：仅读仓库根 `package.json`，不递归 workspace（neonforge DOC-003b 残留 minor，非阻塞）
-- **GitHub 远端发布未执行**：本地 git 就绪，`gh repo create` / 首次 push 待用户
-
-## 3. 下一步与验证点
-
-### 立即待办（按优先级）
-
-1. ~~**发布到 GitHub 远端**~~ ✅ `NinjaSln-labs/repo-audit` 已公开（2026-09-06）
-2. ~~**json_field workspace 支持**~~ ✅ `abea615` 修复（含 fallback_field 数组格式预存 bug）
-3. ~~**验证 CI**~~ ✅ `43e9245` 修复 dsh-demo 模板残留，CI 首次跑通
-4. ~~**npm 发布**~~ ✅ `repo-audit-tool@1.2.0` 已发布（latest）
-5. **下一步**：npmjs.com 配置 Trusted Publisher → Repository: `NinjaSln-labs/repo-audit`, Workflow: `publish.yml`, Branch: `master`
-
-### 外部依赖来源
-
-- 无 API Key / 凭据依赖（工具可选 LLM 增强，Key 由用户运行时提供，不落仓）
-- GitHub 远端发布需用户账号权限
-
-### 风险提醒
-
-- 本仓此前无 .git 时自审计 GIT-001 会 fail；已 commit 后正常
-- json_field workspace 盲区影响 monorepo license 一致性检查（minor）
-
-## 4. 即时操作
-
-```bash
-# 本仓自审计
-cd ninjasin-labs/repo-audit
-node repo-audit.mjs --repo . --format json
-
-# 验证链
-node verify.mjs
-node --test
-
-# 全仓影子回归（ninjasin-labs 下其他仓，可选）
-for repo in $(find /home/shadow/ninjasin-labs -maxdepth 3 -name .git -type d | sed 's|/.git$||'); do
-  node repo-audit.mjs --repo "$repo" --format json 2>/dev/null | grep -o '评分: [0-9]*'
-done
-```
-
-### 已知坑
-
-- 引擎对**非 git 仓**输出到 stderr（`✗ 目标不是 git 仓库`），不产生 JSON——verify.mjs 需用 git 仓
-- `glob_count` 无法遍历隐藏目录（`.github/`）——CI 检查用 `regex`+`command` 方案而非 glob_count
-- `.auditrc.yaml` 解析是简单行解析，`reason` 只取单行且去引号，长 reason 需保持单行
-
-## 5. 引用索引
-
-| 主题 | 权威文档 |
-|---|---|
-| 会话/进度权威 | `ninjasin-labs/.agents/session.md` |
-| 人类使用手册 | `docs/repo-audit/HUMAN-GUIDE.md` |
-| Agent 操作协议 | `docs/repo-audit/AGENT-GUIDE.md` |
-| AI 协作纪律 | `AGENTS.md` |
-| 发布流程 | `PUBLISHING.md` |
-| 工具自审 | `docs/repo-audit/SELF-AUDIT.md` |
-| 全仓影子回归 | `docs/repo-audit/SHADOW-AUDIT-20260906-v3.md` |
-| 反馈闭环（fuyao） | `docs/repo-audit/FEEDBACK-fuyao-nomad.md` |
-| 反馈闭环（neonforge） | `docs/repo-audit/FEEDBACK-neonforge.md` |
-| 审计方法论 | `AUDIT.md` |
-| 最佳实践标准 | `BEST-PRACTICES.md` |
-| 分类检测 | `REPO-CLASSIFICATION.md` |
-| 核心引擎 | `repo-audit.mjs` |
-| 审计规则 | `rules/`（domains + categories） |
-| 脚手架生成器 | `templates/scaffold.mjs` |
-| 废弃开发仓（仅历史参考） | `dsh-ecosystem/research/scaffold-templates/` |
-
-## 6. 维护规则
-
-- **更新时机**：跨 session / 里程碑 / 用户要求交接时
-- **防双源**：本文件只记 delta，文档与 commit 已有内容引用不复制
-- **滚动归档**：已确认修复的坑 → `HANDOFF-ARCHIVE/pits.md`，已完成待办 → `HANDOFF-ARCHIVE/done.md`
-- **回填约定**：改动规则/引擎后，同步更新 `docs/repo-audit/HUMAN-GUIDE.md` 和 `AGENT-GUIDE.md`
-- **脱敏**：不含 API Key/密码/PII（本交接含 `ninjasin-labs` 内部路径，若 push 公开前需注意；或建 .gitignore 排除 HANDOFF.md）
-- **主战场**：所有开发在本仓完成，废弃仓不再同步