{
  "$schema": "https://bestaiskill.com/schemas/agent-install/2.json",
  "skill": "planning-with-files",
  "built": "2026-10-26",
  "control_level": 4,
  "control_level_label": "L4 高权限",
  "capabilities": [
    "execute_command",
    "network",
    "write_file"
  ],
  "required_controls": {
    "agent": [
      "sandbox_recommended",
      "graded_authorization"
    ],
    "admin": [
      "approval_process",
      "rollback_support",
      "full_audit"
    ]
  },
  "evidence": [
    {
      "file": "scripts/",
      "summary": "Executes local scripts or commands: Hook chains automatically executed by the host on every user turn, before/after every tool call, Stop, and PreCompact: skill route skills/planning-with-"
    },
    {
      "file": "网络端点",
      "summary": "Declares external network access: Runtime scripts: None. curl/wget across the entire repo appear only in docs/installation.md, docs/opencode.md, README/CHAN"
    },
    {
      "file": "本地工作目录",
      "summary": "File read/write and artifact output: Current project directory: writes task_plan.md, findings.md, progress. under <cwd>/.planning/<date>-<slug>/"
    }
  ],
  "verification": {
    "method": "第二遍独立重读 + 反查：第一遍由只读 scout 走查权威 skill 目录、12 个宿主镜像、i18n 变体、hooks/commands/agents/pi/opencode/hermes、docs 与 tests，并实跑只读命令（md5sum 13 份 SKILL.md、diff -rq/-u 抽查 .agents/.opencode/.pi）形成证据包 /tmp/spy10/planning-with-files-evidence.md（567 行 / 71,510 字节）；第二遍由本人独立复核：① 用 Python 对该证据包里我将要引用的每条 quote 逐条 `in file.read()` 精确匹配（本 JSON 全部 quote 均通过，含 skill-hook.sh 的 --event=userprompt、inject-plan.sh 的 DATA ONLY 与 pretool 注释、check-complete.sh 的五条件与门与 block JSON、attest-plan.sh 的拒绝注入说明、ledger-summary.sh 的 KV-cache 结论、resolve-plan-dir.sh 的解析顺序、session-catchup.py 的 no-history 声明、package.json 的 name）；② 独立复算结构：仓库根无 package.json（npm 包根为 .pi/），commands=13、tests=77（76 py + 1 sh）、镜像 SKILL.md 13 份哈希两两不同；③ 安全结论反向找反例：运行脚本 curl/wget、keychain、.env、eval(/execSync/new Function( 均为零命中，且 CI 的 TESSL_API_TOKEN 与文档里的 CLAUDE_CODE_OAUTH_TOKEN 都被定位为『非 skill 运行面』；④ 功能声明 vs 实际能力逐条对齐 frontmatter（含自查其自称的 'The skill has no network upload path'、'never runs commands declared in Markdown'、'Automatic recovery reads project planning files only' 三条声明，均与源码一致——第三条的例外『显式 --metadata/--replay 才读会话记录』已由描述自身限定，不算矛盾）；⑤ commit 核对：.git/refs/heads/master = 7c11cb75702a0d82f1ee8b6b1b632272cd84bb85 == pin 7c11cb75702a；⑥ gh api 复核 stars=26903、pushed_at=2026-09-15T08:42:11Z、license MIT。",
    "second_pass": [
      {
        "item": "skill.path 定位（任务表标『待定位』）",
        "status": "ok",
        "detail": "权威 skill 目录为 skills/planning-with-files/（与 12 个宿主镜像、5 个 i18n 变体区分）；path 记为 'skills/planning-with-files'。仓库根另有 templates/、scripts/ 的顶层副本，但不含 SKILL.md。"
      },
      {
        "item": "『运行期无网络』这一核心安全声明是否成立",
        "status": "ok",
        "detail": "scout 对全仓扫 curl|wget|https?://|fetch|requests|urllib|socket：运行脚本 0 命中，curl 仅存在于 docs/installation.md、docs/opencode.md、README/CHANGELOG 与 examples；本人在写 JSON 时用逐条 quote 校验再次触达同一批文件，未发现运行期网络路径。结论与 SKILL.md/SECURITY.md 的 'The shipped catchup path contains no network request or upload operation.' 一致。"
      },
      {
        "item": "『无凭证读取』是否漏网",
        "status": "ok",
        "detail": "keychain 全仓 0 命中、无 .env 文件；命中的 api_key/token 全为文档与 CI（TESSL_API_TOKEN、boxlite 文档里的 CLAUDE_CODE_OAUTH_TOKEN 占位）。skill 运行脚本只读 PWF_*/PLAN_ID/XDG_* 等功能性环境变量。"
      },
      {
        "item": "门禁是否可能把 agent 锁死（设计反例搜索）",
        "status": "ok",
        "detail": "check-complete.sh 头注释给出五条件与门，并含两条防死循环条款：block 计数达 PWF_GATE_CAP（默认 20）后打印 'gate cap reached' 放行；ledger 未推进时打印 'no progress since last gate block — allowing stop.' 放行；stdin 的 stop_hook_active=true 也会退回 advisory。故 gated 模式不会无限拦 stop。"
      },
      {
        "item": "12 个宿主镜像是否与权威 SKILL.md 逐字一致",
        "status": "discrepancy",
        "detail": "实测 md5sum 显示 13 份 SKILL.md 哈希两两不同——即全部不一致。差异含两类：有意差异（钩子查找路径、宿主专属 name/description/version，如 .pi 的 name 为 pi-planning-with-files 且无 version 字段）与内容滞后（.agents 标 3.18.1 但正文缺 '## Next Step' 刷新规则与 set-active-plan --list；.continue/.gemini 版本停在 2.43.0；.kiro 为 3.0.1-kiro 自有方案；.opencode 除 SKILL.md 外还有 check-complete.{sh,ps1}/init-session.{sh,ps1}/session-catchup.py 内容不同并缺 9 个脚本与 task_plan_autonomous.md 模板）。使用镜像安装时会拿到滞后的行为，官方在 bump-version.py 的 LAGGING_FILES 中已承认部分落后为有意。"
      },
      {
        "item": "npm 包的安装生命周期脚本",
        "status": "ok",
        "detail": "唯一生命周期钩子是 'prepack': 'node scripts/verify-shell-line-endings.mjs'（只校验换行符）；无 postinstall/install，无 install 期任意代码执行。包根为 .pi/ 镜像目录（sync-ide-folders.py 注释逐字：'.pi is not just another IDE mirror: this directory IS the root of the npm package `planning-with-files`'）。"
      },
      {
        "item": "会话恢复是否偷偷读宿主会话库",
        "status": "ok",
        "detail": "自动路径（钩子与 bare CLI）走 --no-history，源码注释 'SessionStart and bare CLI execution are deliberately zero-access.' 且该分支在代码里先于计划文件检查/IDE 探测/家目录探测/transcript 数据库发现；读 ~/.claude/projects、~/.codex/sessions、opencode.db 仅在显式 --metadata/--replay，并有 filter_sessions_by_cwd 做跨项目隔离。"
      },
      {
        "item": "写入是否越界（含包含校验/符号链接）",
        "status": "ok",
        "detail": "写入限定在 <cwd>/.planning/**、用户缓存 pwf-* 与自身 mktemp；防护证据：is_within_root 校验、'[ -L \"$PLAN_FILE\" ] && exit 0' 拒符号链接、chmod 700 快照目录、(umask 077) 建账本、python 侧 O_DIRECTORY|NO_FOLLOW。phase-status.sh 是唯一被授权改 task_plan.md 的写入器且只改 **Status:** 行。"
      },
      {
        "item": "frontmatter 的三条自我声明是否夸大",
        "status": "ok",
        "detail": "逐条对照：'Automatic recovery reads project planning files only'（成立，自动路径零访问会话库）；'--metadata reads same-project local agent session records and emits aggregate counts only'（成立，含 cwd 过滤）；'never runs commands declared in Markdown'（成立：全仓无把 Markdown 文本当命令执行的构造，钩子只调自带脚本）；'The skill has no network upload path'（成立，见上条实测）。唯一需读者注意的限定是：钩子注入的内容会随宿主请求发给模型 provider（SECURITY.md 自述），这是宿主层而非本 skill 的外发。"
      },
      {
        "item": "stars / last_push / commit",
        "status": "ok",
        "detail": "gh api 实时 stars=26903、pushed_at=2026-09-15T08:42:11Z、license MIT；本地 .git/refs/heads/master = 7c11cb75702a0d82f1ee8b6b1b632272cd84bb85，与任务书 pin 7c11cb75702a 一致（且 master == origin/master）。"
      },
      {
        "item": "无法定位项",
        "status": "unlocatable",
        "detail": "① 仓库内无 package.json、无 publishConfig/.npmignore、无 npm-publish workflow，故 npm 发布入口不在本仓（只能推断从 .pi/ 目录发布）；② 未发现钩子自动安装脚本（README 明确 'It does not register hooks on its own.'，指 npm 渠道）；③ 按只读约束未运行任何注入/门禁脚本本体，因此『脚本实际输出的字节』未做运行时验证（结论基于源码文本与既有测试名）；④ 部分文件（如 commands/ 的 5 个语言变体、templates/loop.md 内容、.pi 扩展的常量字面值、.opencode core.ts 的 gate 实现细节）仅做符号级扫描未逐字核。"
      }
    ],
    "level": 1,
    "level_label": "V1 已固定",
    "commit": "7c11cb75702a0d82f1ee8b6b1b632272cd84bb85",
    "sha256": "38c3c25fb2940e61825d0a9c0e2157fe72400f41fd36b4adf08aba6e80721ba4",
    "reviewed_by": null,
    "reviewed_at": null
  },
  "assessed_at": "2026-10-25",
  "method_version": "2.0",
  "mirror": {
    "archive": "https://skillpub.pages.dev/r2/v/2026-09-15/planning-with-files.tar.gz",
    "sha256": "38c3c25fb2940e61825d0a9c0e2157fe72400f41fd36b4adf08aba6e80721ba4",
    "commit": "7c11cb75702a0d82f1ee8b6b1b632272cd84bb85"
  },
  "original": {
    "github": "https://github.com/OthmanAdi/planning-with-files/tree/main/skills/planning-with-files",
    "path": "skills/planning-with-files",
    "commit": "7c11cb75702a0d82f1ee8b6b1b632272cd84bb85"
  }
}