dsh-gate-agent 0.0.0-stage → 0.1.0

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Gate",
+    "description": "Phase gate and write policy for agent workflows."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Gate 门禁",
+    "description": "按阶段控制 agent 的写入与评审流程。"
+  }
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "dsh-gate-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Full write gate and phase orchestrator with plugin-local skills.",
+  "exports": {
+    ".": "./lib/index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "launchers",
+    "cordis.patch.yml",
+    "README.md",
+    "locale/*.json",
+    "icon.svg"
+  ],
+  "scripts": {
+    "build": "node scripts/bundle.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node scripts/bundle.mjs && node scripts/check-split.mjs && node test/unit.mjs && node test/composition.mjs && node test/registry.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/gate-code-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: gate-code-review
+description: "Gate 实现评审：沿 Standards 与 Spec 两轴评审固定点之后的改动，保留原始 code-review 方法；主 agent 决定 review worker 数量。"
+user-invocable: false
+---
+
+## Gate 使用
+
+主 agent 读取本方法后，按改动规模派一个或多个 review worker；worker 不加载本技能或其他 gate 方法文件。`gate_record({node:'code-review'})` 需要 `reviewAxes.standards.findings` 与 `reviewAxes.spec.findings`；worker 数量由主 agent 决定，但两轴都必须产出。
+
+任务模板：本技能 `assets/worker-briefs/gate-implement-review.md`。
+
+Two-axis review of the requested change scope, including uncommitted work when applicable:
+
+- **Standards**: does the change conform to this repo's documented standards and current authoritative decisions?
+- **Spec**: does the change satisfy the governing work item's scope and acceptance conditions, including any applicable independent Spec?
+
+Both axes are independent. The gate main agent decides worker count: it may run them as parallel sub-agents, or use one worker that covers both; either way both axes must be reported separately.
+
+Resolve work tracking and document ownership from project instructions. A particular tracker configuration path or separate Spec file is not required for a review. In gate sessions the acceptance contract normally comes from the current task/Note; do not invent an independent Spec.
+
+## Process
+
+### 1. Pin the fixed point
+
+Use the fixed point supplied by the user or calling implementation workflow. Reuse the baseline already recorded in the conversation; ask only when the intended scope cannot be established from available context.
+
+Capture the exact review commands once. For committed branch changes use `git diff <fixed-point>...HEAD`; for implementation worktree changes compare the recorded baseline to the working tree and separately inspect scoped untracked files. Include staged and unstaged changes, excluding pre-existing user changes and other tasks. Also record relevant commits. When existing changes overlap, inspect attribution rather than discarding the entire file.
+
+Before dispatch, resolve the fixed point and verify the complete scope, including new files. If it is empty, report no changes to review; do not mistake an empty committed diff for an empty worktree.
+
+### 2. Identify the acceptance contract
+
+First reuse the governing work item, acceptance conditions and applicable design already supplied by the caller or conversation. Otherwise:
+
+1. Resolve a work identifier or path from the user's request, branch or relevant commits; locate it through the project's configured tracker or existing work-item convention.
+2. Read that work item's selected scope and acceptance conditions, then follow its references to the applicable revision and sections of any independently owned Spec. Use the registered document owner to resolve design decisions; do not infer a Spec solely from a matching filename.
+3. For direct changes without a separate work item, use the authorized user request and settled decisions in the conversation as the contract. If the contract still cannot be identified, ask the user for its owner. Skip the Spec axis only when no reliable acceptance contract exists, and report that coverage gap.
+
+### 3. Identify the standards sources
+
+Read project instructions and the document ownership entry, then relevant writing and coding standards such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`. Include the applicable design decisions and constraints identified by the project configuration and governing work item. Report missing or conflicting required inputs as review coverage gaps.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below: a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation. Like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name**: a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code**: the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy**: a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps**: the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession**: a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches**: the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery**: one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change**: one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality**: abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains**: long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man**: a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest**: a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Dispatch the review workers
+
+**Standards review worker prompt** should include:
+
+- The full diff command and commit list.
+- The standards and current-decision sources found in step 3, **plus the smell baseline from step 3** pasted in full (the sub-agent has no other access to it).
+- The brief: "Report, per file/hunk where relevant, (a) every place the diff violates a documented standard or current authoritative decision: cite the source and rule; and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls: documented rules and current decisions can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec review worker prompt** should include:
+
+- The diff command and commit list.
+- The governing work item or conversational acceptance contract and relevant sections of any applicable independent Spec.
+- The brief: "Report: (a) requirements of the acceptance contract that are missing or partial; (b) behaviour in the diff that wasn't requested (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote or identify the exact contract clause for each finding. Under 400 words."
+
+If no reliable acceptance contract exists, skip the Spec axis and note this coverage gap in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings, because the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes: that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.
+
+## Gate 返回格式
+
+worker 返回给 gate 主 agent：
+
+```json
+{"ok":true,"standards":{"findings":[{"axis":"Standards","summary":"...","evidence":"...","severity":"blocking|important"}]},"spec":{"findings":[{"axis":"Spec","summary":"...","evidence":"...","severity":"blocking|important"}]},"summary":"..."}
+```
+
+主 agent 汇总后调用：
+
+```text
+gate_record({node:'code-review', findings, reviewAxes, workerSessionIds})
+```
+
+`reviewAxes` 必须包含 `standards` 与 `spec`；空的 `findings` 表示该轴通过。worker 不修复 findings。
+
+
+
+
+
+

package/skills/gate-code-review/assets/worker-briefs/gate-implement-review.md

@@ -0,0 +1,19 @@
+# /gate-implement-review — review worker
+
+```markdown
+你是 Gate 的只读 Implementation Review worker。只评审改动，不修复，不写代码。
+
+## 评审对象
+<范围、固定点、完整 diff>
+
+## 合同
+<工作项验收条件、适用设计决定>
+
+## 两轴
+Standards / Spec。每轴只报 findings，注明文件/证据与严重度。
+
+## 输出
+返回 standards、spec 两组 findings；不要合并两轴，不要修改代码。
+```
+
+

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

@@ -0,0 +1,143 @@
+---
+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

@@ -0,0 +1,44 @@
+#!/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-domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,64 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+Resolve the root from project instructions before these checks; the current working directory may be a subproject. Use the project documentation hierarchy for ownership; the context map does not create separate record categories. Paths shown in the map are Markdown links relative to the map file.
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+
+

package/skills/gate-domain-modeling/GLOSSARY-FORMAT.md

@@ -0,0 +1,64 @@
+# GLOSSARY.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `GLOSSARY.md` at the repo root.
+
+**Multiple contexts:** A `GLOSSARY-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Glossary Map
+
+## Contexts
+
+- [Ordering](./src/ordering/GLOSSARY.md): receives and tracks customer orders
+- [Billing](./src/billing/GLOSSARY.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/GLOSSARY.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+Resolve the root from project instructions before these checks; the current working directory may be a subproject. Use the project documentation hierarchy for ownership; the context map does not create separate record categories. Paths shown in the map are Markdown links relative to the map file.
+
+- If `GLOSSARY-MAP.md` exists, read it to find contexts
+- If only a root `GLOSSARY.md` exists, single context
+- If neither exists, create a root `GLOSSARY.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+
+

package/skills/gate-domain-modeling/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: gate-domain-modeling
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording a durable decision in its selected owner.
+user-invocable: false
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `GLOSSARY.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Follow the document ownership entry referenced by project instructions for glossary paths and decisions applicable to the model being discussed. If a required input's owner or scope is unclear, report the configuration gap.
+
+Resolve the repository management root from project instructions, using the Git top-level only as a fallback. Working inside a subproject does not change it. A root `GLOSSARY-MAP.md` selects domain documents when the repository has multiple contexts. Do not create a separate record system per context or derive record categories automatically from contexts.
+
+A single-context project may use a root `GLOSSARY.md`. A root `GLOSSARY-MAP.md`, when present, points to the selected contexts' glossaries; context paths need not be under `src/`. Resolve decision paths separately from the document ownership entry and, for Agent Notes, its configured record roots. Create a glossary or decision record only when there is content for its selected owner. Use the `adr` skill when a separate architecture decision record is warranted.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `GLOSSARY.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update GLOSSARY.md inline
+
+When a term is resolved, update `GLOSSARY.md` right there. Don't batch these up: capture them as they happen. Use the format in [GLOSSARY-FORMAT.md](./GLOSSARY-FORMAT.md).
+
+`GLOSSARY.md` should be totally devoid of implementation details. Do not treat `GLOSSARY.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+
+
+
+
+

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

@@ -0,0 +1,99 @@
+---
+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.
+
+
+
+
+
+