goatchain-cli-darwin-x64 0.0.73-beta.9 → 0.1.1

package/bin/skills-assets/docs-sprint/references/contract-discipline.md

@@ -0,0 +1,30 @@
+# Contract Discipline
+
+Design docs are the source of truth for contracts. When code and docs disagree, update docs and confirm before changing code.
+
+## Type And Error Rules
+
+| Situation | Required behavior |
+|---|---|
+| required data missing | fail fast with explicit typed error |
+| unknown variant | fail fast with explicit typed error |
+| invalid input | fail fast with explicit typed error |
+| contract mismatch | fail fast with explicit typed error |
+| optional lookup missing | return absent value (`undefined` in TS, `None` in Python, etc.) |
+| fallback/default value | allowed only when design docs explicitly authorize |
+| empty container / zero / noop fallback | allowed only when design docs explicitly authorize |
+| silent recovery / best-effort normalize | allowed only when design docs explicitly authorize |
+
+Do not use empty containers, zero values, or no-op callbacks to mask missing required state.
+
+## Test Expectations
+
+| Change type | Verification |
+|---|---|
+| type / interface | compile or typecheck + contract tests |
+| error behavior | tests for typed errors and missing optional lookups |
+| storage / state | tests for persistence, versioning, and mutation path |
+| integration | tests using real implementations across boundary |
+| UI / TUI | layout docs + interaction tests or snapshots when implementation exists |
+
+Document any verification that cannot run and why.

package/bin/skills-assets/docs-sprint/references/delivery-plan.md

@@ -0,0 +1,162 @@
+# Delivery Plan Workflow
+
+## Plan Directory
+
+```text
+docs/plan/
+├─ README.md
+├─ analysis/
+│  └─ {topic}.md
+├─ tasks/
+│  └─ {area}-{seq}.md
+├─ reviews/
+│  └─ {id}-{seq}.md
+└─ backlog.md
+```
+
+## Analysis
+
+Write analysis for planning and orchestration. Do not assign analysis docs directly to implementation agents.
+
+Analysis must cover:
+
+1. **Module decomposition**: package/module scope, inputs, outputs, dependencies. Produce module-level delivery tasks.
+2. **Integration enumeration**: enumerate every documented "module A creates/calls/injects module B" relationship. Produce integration tasks that verify each connection with real implementations, not mocks.
+
+Common miss: only analyzing module-internal responsibilities without enumerating creation chains, injection chains, and call chains between modules. Result: every module passes its own tests, but stub boundaries are never broken through.
+
+| Task type | Objective | Verification |
+|---|---|---|
+| Module task | Implement module X | Module tests cover types, contract, and errors |
+| Integration task | Connect A → B, replace stub | Real call path works, integration test covers path |
+| E2E task | Validate user-observable flow | Entry-to-output path executes |
+
+Integration task `depends-on` points to the module tasks it connects.
+
+Task boundary = the smallest independently verifiable deliverable. If fixing task A's blocking findings necessarily produces task B's deliverable, they are one task.
+
+## Task File Format
+
+```yaml
+id: {area}-{seq}
+scope: ...
+status: pending | ready | in-progress | done | blocked
+depends-on: [task-id, ...]
+```
+
+`area` can be a package prefix, module prefix, or capability prefix (e.g. `acp-001`). `scope` identifies which part of the project this task belongs to.
+
+Required sections: `objective`, `context` (design doc paths to read), `path` (files and directories this task touches), `verification`.
+
+```text
+pending ── depends-on all done ──► ready ──► in-progress ──► done
+                                                │
+                                             blocked
+```
+
+## Develop Prompt
+
+```text
+你的任务文件是 docs/plan/tasks/{id}.md。
+
+阅读任务文件，只完成 objective 中定义的开发目标，不超出任务范围。
+
+context 指向的设计文档是你理解需求的来源。docs/INDEX.md 是文档总索引。
+
+完成后运行 typecheck 和任务要求的测试。
+```
+
+For review fixes:
+
+```text
+你的任务文件是 docs/plan/tasks/{id}.md。
+
+阅读 docs/plan/reviews/{id}-{seq}.md，修复其中标记为 blocking 的 findings。
+
+完成后运行 typecheck 和任务要求的测试。
+```
+
+## Verify Prompt
+
+```text
+review 任务 {id} 的开发产出。
+
+任务文件：docs/plan/tasks/{id}.md
+开发产出：任务文件中 path 指向的路径
+设计文档：任务文件中 context 指向的路径
+项目规范：docs/INDEX.md 是文档总索引。
+
+详细阅读源码与设计文档，判断实现是否达到可交付状态，是否与设计文档完全一致。
+
+写入 docs/plan/reviews/{id}-{seq}.md，格式：
+
+1. Findings 列表，每条标注：
+   - 严重程度（P1/P2/P3）
+   - 是否阻塞交付（blocking / non-blocking）
+   - 设计文档位置与代码位置
+
+   blocking = 与设计文档 contract 不一致，或对接路径残留 stub/mock/fake。
+   non-blocking = 实现合理但设计文档未提及。
+
+2. 结论：pass 或 blocked
+```
+
+## Isolation
+
+All task development happens on isolation branches. Branch sees only its creation-time baseline.
+
+| Rule | Detail |
+|---|---|
+| Branch naming | `task/{id}` |
+| Branch base | Main HEAD at creation time |
+| Depends-on | Wait until all predecessors merge to main before creating branch |
+| Commit before verify | Verify agent only sees committed code |
+| Lifecycle | create → develop → commit → verify → (pass → merge → delete) or (blocked → fix → re-verify) |
+
+## Execution Mode
+
+```text
+ready tasks ──► has worktree? ──► no  ──► serialize all
+                                  yes ──► path overlap? ──► yes ──► serialize
+                                                            no  ──► parallel
+```
+
+Without worktree, all tasks execute serially — one working directory cannot sustain concurrent branches.
+
+With worktree, two tasks can run in parallel only when no entry in one task's `path` is a parent, child, or same path as another's. Tasks with `depends-on` chains are inherently serial.
+
+Serial tasks need no extra coordination — each starts from updated main HEAD after its predecessor merges.
+
+For worktree creation, dispatch, and cleanup procedures, see [worktree-guide.md](worktree-guide.md).
+
+## Merge
+
+```text
+develop ──► verify ──► pass ──► merge to main ──► full test ──► done
+              │
+              └─ blocked ──► fix ──► re-verify
+```
+
+On pass:
+
+- Merge to main. Resolve conflicts file-by-file, preserving both sides.
+- Run full test. If tests fail, revert merge — task must rebase and re-verify.
+- Mark task `done`. Append non-blocking findings to `backlog.md`. Delete review file and branch.
+
+On blocked:
+
+- Fix blocking findings on the same branch. Run typecheck and task tests. Re-verify.
+
+When multiple parallel tasks pass simultaneously, merge one at a time. Each subsequent merge may require conflict resolution and re-test.
+
+## Recovery
+
+When resuming after interruption, reconstruct state from task files and git:
+
+| Observed state | Action |
+|---|---|
+| Task `in-progress`, branch `task/{id}` exists, no review file | Resume develop or re-dispatch develop |
+| Task `in-progress`, review file exists with `blocked` | Re-dispatch fix |
+| Task `in-progress`, review file exists with `pass`, not merged | Execute merge |
+| Task `in-progress`, branch missing | Reset task to `ready`, re-dispatch |
+| Task `blocked`, no review file | Reset task to `ready`, re-dispatch |

package/bin/skills-assets/docs-sprint/references/documentation-system.md

@@ -0,0 +1,109 @@
+# Documentation System
+
+## Directory Model
+
+```text
+docs/
+├─ INDEX.md              # documentation entry point (required)
+├─ plan/                 # delivery workflow (required, owned by this skill)
+│  ├─ README.md
+│  ├─ analysis/
+│  ├─ tasks/
+│  └─ backlog.md
+├─ {scope}/              # design docs, organized by project's own scoping
+│  ├─ README.md
+│  └─ {module}/ or {module}.md
+└─ issues/               # optional, for tracking inconsistencies and design gaps
+   └─ archived/
+```
+
+| Directory | Required | Owner | Purpose |
+|---|---|---|---|
+| `docs/INDEX.md` | yes | project | Documentation entry point. Links to all design doc areas |
+| `docs/plan/` | yes | this skill | Delivery plan: analysis, tasks, backlog. See [delivery-plan.md](delivery-plan.md) |
+| `docs/{scope}/` | yes | project | Design docs. Scope is defined by the project — package, feature area, service, etc. |
+| `docs/issues/` | no | project | Issue tracking when the project uses file-based issues |
+
+`{scope}` is whatever grouping the project uses for its design docs. A monorepo might use `docs/packages/{pkg}/`. A single-package project might use `docs/modules/` or `docs/features/`. The skill does not prescribe the scoping — it only requires that design docs exist and are reachable from `INDEX.md`.
+
+## Scope README Contract
+
+Each scope has a README that answers relationship and ownership questions.
+
+Required coverage:
+
+- Purpose and boundary.
+- Relationship to other scopes.
+- Main concepts and one-line definitions.
+- Ownership: who creates whom, who calls whom, who stores state.
+- Lifecycle and state ownership.
+- Public API surface or entry points.
+- Design decisions that affect multiple modules.
+- Module index linking to child docs.
+- Scope-wide constraints.
+
+Use diagrams for structure and flow.
+
+## Module Doc Contract
+
+Module docs cover local contracts. Cross-module collaboration belongs in the parent scope README.
+
+| Section | Content |
+|---|---|
+| Purpose | What the module owns |
+| Boundary | What it handles and what it delegates |
+| Types | Inputs, outputs, optional/nullable fields, invariants |
+| API | Function/method contracts and return types |
+| State | State ownership, persistence, mutation path |
+| Errors | Typed errors and thrown conditions |
+| Extension points | Hooks, adapters, plugin points, injected dependencies |
+| Tests | Required contract and error tests |
+
+## Maintenance Rules
+
+Docs are the source of truth for contracts. Code follows docs, not the other way around.
+
+### When to create
+
+- Before implementation. A task's `context` field points to design docs that must exist before development starts.
+- When a new scope, module, or capability is introduced.
+
+### When to update
+
+- When a task changes the contract defined in a design doc, the same task updates the doc. Doc changes and code changes are one atomic delivery.
+- When verify finds a mismatch between docs and code, the fix updates whichever is wrong — not just the code.
+
+### Task path includes docs
+
+A task's `path` field lists both code paths and doc paths it touches. This ensures overlap detection accounts for doc changes — two tasks modifying the same design doc cannot run in parallel.
+
+### Staleness prevention
+
+- Verify checks docs-code consistency: if code diverges from the design doc referenced in `context`, it is a blocking finding.
+- `INDEX.md` must stay current. When a new scope or doc is added, `INDEX.md` is updated in the same task.
+- Orphaned docs (docs that describe removed code) are deleted or archived when discovered.
+
+## Single Source of Truth
+
+- Each rule or process lives in exactly one location.
+- Cross-module flows go in the parent scope README.
+- Local API details go in module docs.
+- Implementation tasks go in `docs/plan/tasks/`.
+- Non-blocking findings go in `docs/plan/backlog.md` or `docs/issues/`.
+- Reference existing docs instead of repeating rules.
+
+## Writing Style
+
+- Direct, concrete statements.
+- Tables and ASCII diagrams for relationships.
+- Define only terms that reduce ambiguity.
+- Stable, searchable headings.
+- English for code identifiers, package names, API names, type names, and commit messages.
+
+## Issues
+
+When the project uses `docs/issues/`:
+
+- New issues: `状态：待处理`.
+- Fixed issues: `状态：已修复`, then move to `docs/issues/archived/`.
+- One issue per file, focused on a single inconsistency, bug, or design gap.

package/bin/skills-assets/docs-sprint/references/ui-layout.md

@@ -0,0 +1,73 @@
+# UI Layout Documentation
+
+## Scope
+
+Use this reference when documenting UI layouts and interactions — web, mobile, desktop, or terminal.
+
+UI layout docs describe user-visible contracts: what regions exist, how they are arranged, how users reach each function, how input behaves, and how loading/empty/error states display.
+
+## Layout Doc Template
+
+Use this structure when it fits. Shorter files may omit empty sections.
+
+```markdown
+# {Feature} Layout
+
+Status: Draft
+
+## Design Principles
+## Overall Structure
+## Page-Level Layout
+## Region Layout
+## Interactions
+## State Variants
+## Responsive / Size Constraints
+## Component Tree
+## Page Entry Points
+```
+
+Each layout file focuses on one page, shell, dialog family, or component group.
+
+## Visual Layout Rules
+
+Use ASCII art or diagrams for every meaningful layout.
+
+```text
+┌──────────────────────────────────────┐
+│ Header                               │
+├──────────────────────────────────────┤
+│ Main content area                    │
+├──────────────────────────────────────┤
+│ Footer / status bar                  │
+└──────────────────────────────────────┘
+```
+
+Include:
+
+- Region names.
+- Conditional regions (shown/hidden by state).
+- Dialog and overlay layering.
+- Focus target when relevant.
+- Responsive behavior for size constraints.
+
+## Interaction Contract
+
+Document input behavior in tables:
+
+| Input | Scope | Behavior |
+|---|---|---|
+| `Enter` | Input area | submit |
+| `Esc` | Dialog | close |
+| `Tab` | Form | next field |
+
+For dialogs, document: open/close trigger, focus movement, selection behavior, empty state, error state, apply/cancel behavior.
+
+## State Variants
+
+Document these states for each region when applicable:
+
+- **Loading**: what the user sees while data is being fetched.
+- **Empty**: what the user sees when there is no content.
+- **Error**: what the user sees on failure, and how to recover.
+- **Busy**: what the user sees during a long-running operation.
+- **Constrained**: how the layout adapts to limited screen/window size.

package/bin/skills-assets/docs-sprint/references/worktree-guide.md

@@ -0,0 +1,45 @@
+# Worktree Guide
+
+Parallel task execution via git worktrees.
+
+## Convention
+
+- Directory: `.worktrees/<task-id>/`
+- Branch: `task/<task-id>`
+- Base: determine the correct base branch before creating. Check which branch the current delivery targets (main, a feature branch, a release branch, etc.) and verify it is up to date. A stale or wrong base causes the agent to work against an outdated snapshot, and its merge can silently revert other tasks' work.
+- Create: `git worktree add .worktrees/<task-id> -b task/<task-id> <base>`
+- Remove: `git worktree remove .worktrees/<task-id>`
+
+## Workflow
+
+1. Check execution mode from the delivery plan (path overlap, dependency chain).
+2. For parallel tasks, create the worktree before dispatching. Pass the worktree path as the sub-agent's cwd.
+3. Verify agent uses the same worktree as its develop agent.
+4. Sub-agent works in its cwd as normal — it does not need to know it is in a worktree.
+5. After merge, remove the worktree. For abandoned tasks, force remove and delete the branch.
+
+## Rules
+
+- Only the orchestrator creates and removes worktrees. Sub-agents never manage worktrees.
+- Sub-agents operate only within their own cwd. Never touch other worktrees or the main working directory.
+- Serial tasks use the main working directory — no worktree needed.
+
+## Cleanup
+
+| Trigger | Action |
+|---|---|
+| Task merged to base | `git worktree remove .worktrees/<task-id>` then `git branch -d task/<task-id>` |
+| Task abandoned | `git worktree remove --force .worktrees/<task-id>` then `git branch -D task/<task-id>` |
+| Sprint end or session start | Run `git worktree list`, cross-check against task statuses, remove all worktrees whose task is `done` or no longer exists |
+
+Orchestrator is responsible for cleanup. Do not leave worktrees accumulating — clean up immediately after merge or abandonment. On session resume, always run a sweep before creating new worktrees.
+
+## Recovery
+
+See delivery-plan.md Recovery for task-level state→action mapping. For worktree-specific issues:
+
+| Observed state | Action |
+|---|---|
+| Worktree exists but branch is missing | Force remove worktree, reset task to `ready` |
+| Worktree has `.git/worktrees/<id>/locked` | Unlock with `git worktree unlock`, then decide based on task status |
+| Worktree exists for a `done` task | Remove worktree and delete branch (merge cleanup was interrupted) |