dsh-gate-agent 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gate-agent",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Phase/node workflow gate with built-in commands, tools, and skills.",
   "exports": {

package/skills/gate-write-agent-notes/SKILL.md

@@ -158,7 +158,9 @@ Status: <状态>
 "verify-notes": "node .agents/gate/verify-notes.mjs"
 ```
 
-这个启动器只调用插件内置脚本，不复制技能。
+这个启动器只调用插件内置脚本，不复制技能。
+
+`/gate-init` 还会生成 `.agents/gate/init-manifest.json`，记录 CI 脚本/启动器的 hash 和 init 结构。需要核对初始化是否被改坏时，用 root-only 只读工具 `gate_init_verify`；它不检查 Note 内容，也不要在每次 Note 操作后运行。`init-manifest.json` 由 git 跟踪，同内容重跑 init 时字节稳定。
 
 - 计划完成前或提交前，运行 `npm run verify-notes`，检查 tree、format、lifecycle、archived。
 - `/gate-init` 同时生成 `.github/workflows/verify-notes.yml` 和 `.agents/gate/ci/` 校验脚本副本；CI 使用项目内副本，不依赖插件安装路径。

package/skills/gate-write-agent-notes/references/verification.md

@@ -33,7 +33,9 @@ Notes 读取/写入命令均接受 `--root <path>` 或 `--root=<path>`，每次
 ## 接入建议
 
 - 轻量（个人/无 git）：前两个脚本即可，归档封印在第一次归档后自然生效。
-- 完整：运行 `npm run verify-notes` 跑 tree/format/lifecycle/archived 四检；该脚本由 `/gate-init` 生成，只调用插件内置脚本。gate 会话内也可用 `/gate-note-verify`。
+- 完整：运行 `npm run verify-notes` 跑 tree/format/lifecycle/archived 四检；该脚本由 `/gate-init` 生成，只调用插件内置脚本。gate 会话内也可用 `/gate-note-verify`。
+
+初始化结构核对用 root-only 的 `gate_init_verify`；它检查 `init-manifest.json`、生成物 hash、artifact-policy schema、AGENTS block、package script、workflow 和 notes 四目录，不检查 Note 内容，也不应随每次 Note 操作运行。
 
 
 ## 脚本路径

package/skills/gate-diagnosing-bugs/SKILL.md

@@ -1,143 +0,0 @@
----
-name: gate-diagnosing-bugs
-description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
-user-invocable: false
----
-
-# Diagnosing Bugs
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, use the domain glossary and applicable contracts, designs and decisions identified by project instructions and the work item to form testable hypotheses. Report required-input gaps or conflicts and their effect on the diagnosis; keep dependent expectations unverified.
-
-## Redact
-
-This skill has you show commands, outputs and captured artifacts. **Redact every secret first**: write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
-
-If the redacted output is not enough to diagnose the bug, say so and ask the user.
-
-## Phase 1: Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug (one that goes red on _this_ bug), you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
-
-### Ways to construct one, in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug: unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) that drives the UI and asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Tighten the loop
-
-Treat the loop as a product. Once you have _a_ loop, **tighten** it:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight, a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not, so keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-List attempts and evidence gaps. Continue useful read-only analysis of code, logs and contracts, labeling hypotheses as unverified. Ask for missing access or redacted artifacts only when needed; production instrumentation requires explicit authorization. Do not claim a confirmed cause or verified fix without sufficient evidence.
-
-### Completion criterion: a tight loop that goes red
-
-Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** (a script path, a test invocation, a curl) that you have **already run at least once** (show the invocation and its output, redacted), and that is:
-
-- [ ] **Red-capable**: it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring"; it must be able to _catch this specific bug_.
-- [ ] **Deterministic**: same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
-- [ ] **Fast**: seconds, not minutes.
-- [ ] **Agent-runnable**: you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
-
-Reading code, logs and contracts before a runnable reproduction is allowed to form testable hypotheses and construct the loop. Until exercised, these remain hypotheses. If the environment prevents reproduction, continue available read-only diagnosis and report the limitation without declaring reproduction complete.
-
-## Phase 2: Reproduce + minimise
-
-Run the loop. Watch it go red as the bug appears.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described, not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-### Minimise
-
-Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut, and keep only what's load-bearing for the failure.
-
-Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
-
-Done when **every remaining element is load-bearing**: removing any one of them makes the loop go green.
-
-Do not proceed until you have reproduced **and** minimised.
-
-## Phase 3: Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe: discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it; proceed with your ranking if the user is AFK.
-
-## Phase 4: Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
-
-## Phase 5: Fix + regression test
-
-Write the regression test **before the fix**, but only if there is a **correct seam** for it.
-
-A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
-
-**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
-## Phase 6: Cleanup
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns
-
-
-
-

package/skills/gate-diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -1,44 +0,0 @@
-#!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
-#
-# `capture` prints its value back to the terminal, where the agent reads it,
-# so capture observations, and leave signing in to the user as a `step`.
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [Enter when done] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- edit below ---------------------------------------------------------
-
-step "Open the app at http://localhost:3000 and sign in."
-
-capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
-
-capture ERROR_MSG "Paste the error message (or 'none'):"
-
-# --- edit above ---------------------------------------------------------
-
-printf '\n--- Captured ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/skills/gate-fix-bug/SKILL.md

@@ -1,99 +0,0 @@
----
-name: gate-fix-bug
-description: "Fix a user-requested post-delivery implementation defect against its authoritative contract, using available diagnosis, focused correction, review, and regression verification."
-user-invocable: false
----
-
-# Fix Bug
-
-Fix a post-delivery **Implementation Bug** that the user has explicitly asked to correct.
-
-This skill changes code. It does not redesign product behavior or architecture.
-
-## Gate worker assets
-
-主 agent 使用本技能的 `assets/worker-briefs/gate-fix-bug.md` 派 fix worker；独立 review 使用 `assets/worker-briefs/fix-bug-review.md`。
-
-## Preconditions
-
-Before fixing, establish:
-
-- observed failure
-- expected behavior
-- authoritative contract establishing the expected behavior
-- available diagnosis and supporting evidence
-- enough evidence to treat this as an implementation defect
-
-Reuse an existing acceptance report or diagnosis when available, identifying the selected failure items and checking that its evidence still applies to the current delivery. A diagnosis explains the cause; it does not replace the contract. A prior report is not required for a direct user bug report.
-
-The user requests the correction; determine its technical classification from evidence rather than requiring the user to confirm the root cause. When the cause is uncertain, investigate using `gate-diagnosing-bugs` before changing code. If evidence identifies a test, contract, design, or environment problem instead, report its ownership and required next action rather than treating it as an implementation bug.
-
-Establish the selected repair scope and execution authorization under the project's workflow rules. Reuse authorization throughout in-scope correction, review, and re-verification.
-
-Inspect the applicable product contract, design and decisions identified by project configuration and the work item, together with code and tests. Report missing or conflicting required inputs and the affected behavior before choosing its expected result. A defect spanning layers is not itself a reason to stop. Pause affected work only if fixing it requires an unresolved change to product behavior, an approved contract, acceptance, compatibility, migration strategy or authorized scope; surface that decision and continue independent authorized work. Do not guess a new contract in code.
-
-## Process
-
-1. Reproduce the reported failure.
-2. Identify the smallest stable seam that captures the real bug.
-3. Add or confirm regression coverage when practical; it should fail before the fix.
-4. Locate the root implementation cause.
-5. Apply the smallest coherent correction.
-6. If unexpected technical failures arise during the fix, use `gate-diagnosing-bugs`.
-7. Re-run the regression check and original reproduction.
-8. Run directly related tests, then broader relevant tests when necessary.
-9. Run typechecking/build checks where applicable.
-10. The main agent uses `gate-code-review` to dispatch an independent review worker with the repair baseline, selected failures, contract references, and the complete repair diff, including new files.
-11. Resolve material in-scope review findings by ownership. Return unresolved contract decisions to Discuss and obtain the required planning or implementation authorization under project gates; keep unrelated findings outside the repair scope.
-12. Re-verify behavior affected by review corrections, including the original reproduction, affected acceptance criteria, and relevant regressions. Continue the correction and review loop until the completion conditions hold or further progress requires an unavailable dependency, a user-owned decision, or additional authorization.
-
-Verify the original observable failure at an appropriate stable boundary. A passing lower-level regression test alone does not demonstrate that the original acceptance condition is restored. Complete this repair's verification within this skill; a separate user invocation of `gate-user-verify` is not a completion prerequisite.
-
-## Scope Rules
-
-Do not use a bug fix to introduce unrelated:
-
-- refactoring
-- architecture changes
-- API redesign
-- dependencies
-- optimization
-- cleanup
-- product behavior
-
-Small refactoring is allowed only when required to implement the correct fix safely.
-
-Do not weaken or delete a valid test merely to make the suite pass.
-
-## Completion
-
-A fix is complete when:
-
-- the original problem no longer reproduces
-- expected behavior is restored
-- the selected failed acceptance criteria have evidence of passing on the repaired delivery
-- regression coverage passes when practical
-- relevant tests/build checks pass
-- no established contract was silently changed
-- material in-scope review findings are resolved and affected behavior has been re-verified
-- no blocker to this repair's completion remains
-
-## Report
-
-Lead with whether the selected repair is complete and verified or remains incomplete. Report:
-
-- selected failure items and their latest results
-- root implementation cause
-- correction made
-- regression coverage
-- original reproduction and acceptance re-verification evidence
-- review outcome and relevant regression results
-- remaining failures, blockers, verification gaps, and required next actions, if any
-
-Limit the conclusion to the selected repair. Unselected failures or blockers in the original acceptance report remain outside this completion claim. If the original behavior cannot be reliably verified, report the repair as incomplete rather than inferring success from code changes or passing checks alone.
-
-
-
-
-
-

package/skills/gate-fix-bug/assets/worker-briefs/fix-bug-review.md

@@ -1,23 +0,0 @@
-# gate-fix-bug independent review worker
-
-```markdown
-你是 Gate 的独立 review worker。只评审 fix worker 的修复 diff，返回 findings，不修复。
-
-## 修复基线
-<fix 前 commit / 固定点、当前 diff 范围>
-
-## 选定失败与合同
-<原失败项、期望行为、验收/合同引用>
-
-## 修复报告
-<fix worker 的根因、改动、回归测试和验证结果>
-
-## 评审范围
-Standards / Spec 两轴；重点确认修复没有改变合同、没有扩大范围、没有削弱测试。
-
-## 输出
-返回 standards、spec 两组 findings，注明证据与严重度；不修改代码，不提交。
-```
-
-
-

package/skills/gate-fix-bug/assets/worker-briefs/gate-fix-bug.md

@@ -1,33 +0,0 @@
-# /gate-fix-bug — fix worker
-
-```markdown
-你是 Gate 的 fix-bug worker。使用 gate-fix-bug 完成这次已授权的实现缺陷修复；执行 Process 1-9，返回修复 receipt。独立 review 由主 agent 另派，不要自行完成 Step 10-12。
-
-## 选定失败
-<现象、复现步骤、最新结果>
-
-## 期望行为与合同
-<需求/验收/设计决定引用>
-
-## 证据/诊断
-<日志、失败测试、已有报告>
-
-## 修复范围
-<只修什么；明确不修什么>
-
-## 基线
-<commit、diff、相关文件>
-
-## 约束
-- 只修选定缺陷；不重构、不改产品行为、不加依赖、不做无关清理。
-- 先复现；回归测试应先失败，修复后通过。
-- 不通过削弱/删除有效测试让套件变绿。
-- 若发现是测试/合同/设计/环境问题，停止并报告属主。
-- 只执行 Process 1-9；不自行 review，不提交。
-
-## 验证
-<复现命令、相关测试、类型检查/构建>
-```
-
-
-