aimship 0.1.0-preview.8 → 0.1.0-preview.9

package/docs/reference.md

@@ -1,78 +0,0 @@
-# Aimship Delivery Document Reference
-
-[中文](reference.zh-CN.md) · [Guide](guide.md) · [README](../README.md)
-
-Use this reference to look up document generation conditions, stage outputs and identifier rules. Start with the Guide for everyday use.
-
-Use the [annotated directory tree in the Guide](guide.md#delivery-structure) as the layout reference. Formal documents are directly in the request directory, new prototypes in `prototype/`, preserved inputs in `source/`, and machine records/evidence in `.aimship/`. There is no extra `docs/` or `sql/` layer within a delivery.
-
-## Choose the requirement authority
-
-| Input condition | Requirement document | Prototype handling |
-| --- | --- | --- |
-| An authoritative PRD/prototype is supplied for adoption | `scope.md` records adopted versions, scope, gaps, decisions and acceptance; originals remain unchanged | Reuse covered interactions; create a prototype for uncovered interaction changes within the commissioned endpoint |
-| An idea, discussion, screenshots or scattered references | Author `prd.md`, including scope and acceptance | Create a prototype when the commissioned work changes interactions and existing material does not cover them |
-| Technical refactoring or a known-cause fix | Author `prd.md` describing the technical goal, boundaries, behavior constraints and acceptance | No prototype when there is no interaction change |
-| Independent investigation, review-only or verification-only | PRD/Scope defines that commission and its endpoint | Do not invent a future implementation or prototype |
-
-`prd.md` and `scope.md` are alternatives for the requirement authority, not duplicate descriptions to create together. If you explicitly commission maintenance of an existing editable authoritative PRD and it fully expresses this delivery's scope, authorization and endpoint, register and reuse it. Earlier authorship alone does not make adopted material editable.
-
-Preserve incoming versions in `source/`, including externally supplied PRDs, prototypes and images. Generated formal documents stay in the locations above. External originals are not rewritten when requirements change. A URL alone may not preserve a version; the agent records the available source/version and any access gaps. Reading text, inspecting a visual, interacting with a prototype and editing its original format are distinct capabilities.
-
-## Stage outputs and content
-
-Stage names are stable identifiers. This table is a catalog, not a fixed sequence; the accepted arrangement selects stages and dependencies. Every delivery retains the original request, a requirement/scope authority and state records, even when no separate requirements stage is needed. Sharing `plan.md` or `testing.md` does not complete both stages automatically: each stage retains its own status and result. Documents are drafted when their stage begins, and file creation alone does not establish completion.
-
-| Stage | When used | Output and content |
-| --- | --- | --- |
-| `frame` | The problem or intended result needs clarification | Goal/background section of PRD/Scope: problem, outcome, non-goals and assumptions |
-| `requirements` | Requirements need authoring or adoption | `prd.md`: goals, scope, requirements, states, acceptance and arrangement; or `scope.md`: source adoption, scope, exclusions, decisions, acceptance and arrangement |
-| `scope` | Commission boundaries need explicit resolution | Update PRD scope or Scope goals/boundaries; no second requirements document |
-| `prototype` | Required interaction changes are not covered by existing material | New HTML at `prototype/index.html` with related assets; other agreed formats or reused entries are registered |
-| `diagnose` | An independent investigation is explicitly arranged | `diagnosis.md`: goal, symptoms, environment, evidence, causes, unknowns and conclusion |
-| `tech-design` | Technical solution needs designing | `tech-design.md`: basis, architecture, modules, data/contracts, errors, risks and requirement coverage; SQL is produced and reviewed in contract after this design is approved |
-| `contract` | Interfaces or database changes need formal artifacts | HTTP: `openapi.yaml` or the registered authority; agreed non-HTTP format; independent SQL per target, reviewed individually |
-| `test-design` | Test cases need authoring | `testing.md`: basis, environment, cases/assertions and requirement/acceptance coverage |
-| `plan` | Before any implementation, including one small batch | `plan.md`: basis, batches, tasks, validation approach, execution section and remaining work |
-| `implement` | Execute the accepted plan | Code in its repositories; actual task status, objects and deviations in the same `plan.md` |
-| `review` | Review a batch, the integrated result or a review-only commission | `review.md`: review basis, each review's scope/findings/resolution and conclusion |
-| `verify` | Execute versioned cases after the required review, or a verification-only commission | Append execution batches/RUNs, actual results/evidence, retests and conclusion to the same `testing.md` |
-| `handoff` | Deliver the agreed endpoint | `handoff.md`: goal, artifacts, usage, review/verification results, limits and completion/acceptance/integration outcomes |
-
-During development, test-design precedes plan; each document follows the [review flow](guide.md#review-documents-and-continue). `plan` completes before the first implementation. Each implementation batch is reviewed, followed by overall review and independent verification. Test code can be authored during implementation; there is no full testing gate imposed after each batch. For one batch, one review may cover both batch and overall scope if explicitly recorded. Verification-only work may adopt existing versioned cases without claiming to have executed `test-design`.
-
-Ordinary debugging and known-cause bugs do not add `diagnose`. Fix implementation defects in implementation, design errors in technical design, requirement gaps in PRD/Scope, and incorrect expectations in versioned cases. A major unknown requiring separate investigation needs a recorded stage adjustment; dependent work waits.
-
-## SQL, changes and progress
-
-| Artifact | Generation rule and content |
-| --- | --- |
-| `database.sql` | Required when database structures or data change; one database target uses this single root-level file |
-| `database-<id>.sql` | Multiple independent database targets get one file each; use a stable target ID |
-| `change-log.md` | Record meaningful changes: reason, old/new meaning, decision, affected documents/work and remaining actions |
-| `status.md` | Generated reading entry: goal, progress, blockers, next action and document links |
-| `.aimship/state.json` | Managed state: goal/stages, document references, version binding and associated repositories/worktrees/code locations |
-
-SQL identifies the target, dialect, version/schema basis and execution conditions, and links ordered statements to requirements/design. It is prepared and individually reviewed in contract after technical design approval and before test cases. A Markdown SQL snippet or migration reference does not replace this deliverable. Generating SQL does not authorize executing it or changing a repository's migration mechanism.
-
-Existing engineering HTTP contracts remain authoritative; avoid a second competing copy. Project current and target versions are recorded in PRD/Scope with their engineering source and observation basis; an unspecified version remains unspecified. `plan.md` records actual changes, while review and test results identify the exact commit/build or uncommitted content. Each repository has its own version and object references. These differ from Aimship’s rules version, state schema and save revision. The handoff records final code objects and actual merge/release status; a target version does not establish publication.
-
-## Fixed outlines and traceable identifiers
-
-New documents follow [shared templates and rules](../skills/aimship/references/document-patterns.md). Section order and stable anchors are retained; visible headings can be translated. Inapplicable sections explain why. Short tasks use the same outline, with shorter content. Unselected stages do not produce empty documents, and there is no arbitrary small-task merging.
-
-| Identifier | Meaning |
-| --- | --- |
-| `REQ-001`, `AC-001` | Requirement and acceptance criterion |
-| `B-001`, `TASK-001` | Implementation batch and task |
-| `PAGE-001`, `Q-001` | Prototype page and tracked question |
-| `TC-001`, `RUN-001` | Test case and actual verification run |
-| `REV-001`, `CHG-001` | Review and meaningful change |
-
-Each series starts at `001` and advances beyond its historical maximum, including retired items; three digits are the minimum width. An ID is never reused for a different obligation. Within a namespace and version, an identity has one effective definition; other documents reference it. Classification or layout changes retain the ID, while splits/merges create new IDs linked to the originals.
-
-References connect requirements/acceptance to design, tasks, code objects, reviews, case versions and actual runs. These relationships may be many-to-many: `REQ-001` and `TC-001` are not related merely because their numbers match. Shared rules, permissions and quality requirements receive independent identities when independently testable. External IDs retain their spelling and source/version namespace; sources without IDs receive local mappings to their original locations. Changed case meaning gets a new version; earlier failures and their case/code versions remain traceable.
-
-For example: `REQ-001 → AC-002 → TC-004@1 → RUN-003` records the explicit requirement-to-result relationship. A RUN also identifies the tested code/build and evidence; the case ID alone does not prove execution.
-
-The tools check structure, references and basic coverage. The agent must still assess whether the content and assertions actually satisfy the requirement; valid metadata alone is not proof.

package/docs/reference.zh-CN.md

@@ -1,78 +0,0 @@
-# Aimship 交付文档参考
-
-[English](reference.md) · [使用指南](guide.zh-CN.md) · [README](../README.zh-CN.md)
-
-本文供需要查阅文档生成条件、阶段产物及编号规则时使用；日常操作请先阅读使用指南。
-
-目录位置以 [使用指南的注释目录树](guide.zh-CN.md#delivery-structure)为准：正式文档直接放在需求目录，新原型放在 `prototype/`，原始资料放在 `source/`，内部状态和证据放在 `.aimship/`。交付内不再增加 `docs/` 或 `sql/` 层级。
-
-## 需求依据与输入条件
-
-| 输入条件 | 需求文档 | 原型处理 |
-| --- | --- | --- |
-| 提供权威 PRD／原型供本次采用 | 用 `scope.md` 记录采用版本、本次范围、缺口、决定和验收，保留原件 | 已覆盖的交互复用；委托范围内有未覆盖的交互变化时补原型 |
-| 只有想法、讨论、截图或零散参考 | 自编 `prd.md`，其中包含范围和验收 | 委托范围内涉及交互变化、且现有材料未覆盖时生成原型 |
-| 技术重构或已知原因的修复 | 自编 `prd.md`，说明技术目标、边界、行为约束和验收 | 不涉及交互变化就不生成原型 |
-| 独立调查、只做 review 或只做验证 | PRD／Scope 只定义本次委托及终点 | 不虚构后续实施需求或原型 |
-
-`prd.md` 和 `scope.md` 是需求依据的两种选择，不应默认同时创建两份重复描述。如果你明确委托维护一份已有、可编辑的权威 PRD，且它完整表达本次范围、授权和终点，可以登记复用。仅凭“以前由我们编写”不能认定采用的原件可以修改。
-
-外来的 PRD、原型、图片等按采用版本保留在 `source/`，自己生成的正式文档按上述位置存放。需求变化时不改写外部原件。单独一个链接未必能保留资料版本，Agent 应记录可用来源、版本和访问缺口。提取文本、查看视觉内容、操作原型和编辑原格式，是不同能力。
-
-## 阶段产物与内容
-
-阶段名称是稳定标识。下表是阶段目录，不是强制顺序；实际选用哪些阶段及其依赖，由接受后的执行安排决定。即使无需单独执行需求阶段，每次交付仍保留原始委托、需求／范围依据和状态记录。共用 `plan.md` 或 `testing.md` 不代表两个阶段同时完成，各阶段分别记录状态和结果。文档在对应阶段开始时形成草稿，文件已创建不等于阶段已完成。
-
-| 阶段 | 使用条件 | 产物及内容 |
-| --- | --- | --- |
-| `frame` 问题定义 | 问题或预期结果仍需澄清 | PRD／Scope 的目标与背景章节：问题、目标、非目标和假设 |
-| `requirements` 需求 | 需要编写或采用需求 | `prd.md`：目标、范围、需求、状态、验收和执行安排；或 `scope.md`：资料采用、本次范围、排除项、决定、验收和执行安排 |
-| `scope` 范围确认 | 需要明确本次委托边界 | 更新 PRD 的范围或 Scope 的目标／边界，不再新建另一份需求说明 |
-| `prototype` 原型 | 所需交互变化未被现有资料覆盖 | 新 HTML 使用 `prototype/index.html`，相关资源放在同目录；其他约定格式或复用入口单独登记 |
-| `diagnose` 调查定位 | 明确安排了独立调查 | `diagnosis.md`：目标、现象、环境、证据、原因、未知项和结论 |
-| `tech-design` 技术方案 | 需要设计技术实现 | `tech-design.md`：依据、架构、模块、数据／契约、异常、风险和需求覆盖；通过后在 contract 生成并审核所需 SQL |
-| `contract` 契约及 SQL | 接口或数据库变化需要正式产物 | HTTP 使用 `openapi.yaml` 或已登记的工程权威契约；非 HTTP 使用约定格式；每个目标库的独立 SQL 逐份审核 |
-| `test-design` 测试设计 | 需要编写测试用例 | `testing.md`：依据、环境、用例／断言，以及需求和验收覆盖 |
-| `plan` 实施计划 | 任何实施开始前，包括单个小批次 | `plan.md`：依据、批次、任务、验证安排、执行记录章节和剩余工作 |
-| `implement` 实施 | 执行已确定的计划 | 在代码仓库实施；同一份 `plan.md` 记录实际任务状态、代码对象和偏差 |
-| `review` 审核 | 审核某批、整体成果，或单独受托 review | `review.md`：审核依据、各次审核范围、发现与处理、结论 |
-| `verify` 验证 | 必要 review 后执行带版本用例，或单独受托验证 | 在同一份 `testing.md` 追加执行批次／RUN、实际结果、证据、重测和结论 |
-| `handoff` 交接 | 交付约定终点的成果 | `handoff.md`：目标、产物、使用方式、审核／验证结果、限制，以及完成／验收／集成状态 |
-
-开发流程中，test-design 先于 plan；文档按[审核流程](guide.zh-CN.md#逐份审核与自动衔接)处理。`plan` 必须先于首次实施完成。每批实施后 review，全部完成后整体 review，再独立验证。实施时可以编写测试代码，但不额外设置逐批全量测试门禁。只有一批时，一次 review 可以明确覆盖批次和整体范围。单独委托验证时，可以采用已有、明确版本的用例，不声称重新执行过 `test-design`。
-
-普通开发调试、已知原因的 Bug 不增加 `diagnose`。实现错误回到实施，设计错误回到技术方案，需求缺口回到 PRD／Scope，错误的测试预期回到带版本的用例。出现需要独立调查的重大未知项时，应记录阶段调整，相关依赖工作暂停。
-
-## SQL、变更和进度
-
-| 产物 | 生成规则与内容 |
-| --- | --- |
-| `database.sql` | 数据库结构或数据发生变化时需要；一个数据库目标在需求根目录使用这一份文件 |
-| `database-<id>.sql` | 多个独立数据库目标各一份，`id` 使用稳定的目标标识 |
-| `change-log.md` | 有重要变更时记录原因、旧／新含义、决定、影响文档与工作，以及剩余动作 |
-| `status.md` | 自动生成的阅读入口，显示目标、进度、阻塞、下一步和文档链接 |
-| `.aimship/state.json` | 工具维护的状态，包含目标／阶段、文档引用、版本绑定及关联仓库／worktree／代码位置 |
-
-SQL 标明目标、方言、版本／结构依据、执行条件，按顺序组织语句并关联需求和设计，在技术方案通过后的 contract 阶段、测试用例之前准备并逐份审核。Markdown 中的 SQL 片段或迁移文件引用不能替代它。生成 SQL 不代表获准执行数据库操作或修改工程迁移机制。
-
-已有工程 HTTP 契约继续作为权威来源，避免维护另一份相互冲突的副本。项目当前版本和目标版本在 PRD／Scope 中记录，并注明工程来源和观察依据；未设置版本时如实说明。`plan.md` 记录实际改动，审核与测试结果定位准确的 commit、构建或未提交内容。多仓库分别记录版本和对象引用，与 Aimship 规则版本、状态格式及保存 revision 区分。交接记录最终代码对象和真实合并／发布状态，目标版本不代表已发布版本。
-
-## 固定大纲和可追溯编号
-
-新文档遵循[统一模板和规则](../skills/aimship/references/document-patterns.md)，保留章节顺序和稳定锚点，可翻译展示标题。不适用章节说明原因，小需求使用相同大纲、缩短内容。未选择的阶段不生成空文档，也不按“小需求”随意合并文件。
-
-| 编号 | 含义 |
-| --- | --- |
-| `REQ-001`、`AC-001` | 需求、验收标准 |
-| `B-001`、`TASK-001` | 实施批次、任务 |
-| `PAGE-001`、`Q-001` | 原型页面、待决问题 |
-| `TC-001`、`RUN-001` | 测试用例、实际验证执行 |
-| `REV-001`、`CHG-001` | 审核、重要变更 |
-
-各类编号从 `001` 开始，在包含已废弃条目的历史最大值后递增，三位是最小补零宽度。旧编号不用于另一项义务。同一命名空间和适用版本内，一个编号只有一处有效定义，其他文档引用该定义。分类或排版变化保留编号，拆分／合并则创建新编号并关联原编号。
-
-需求／验收通过引用关联到设计、任务、代码对象、审核、用例版本和实际执行，允许多对多关联；不能因数字相同就认定 `REQ-001` 对应 `TC-001`。可独立测试的公共规则、权限和质量要求应具有独立身份。外部编号保留原样，并携带来源／版本命名空间；无原编号时建立指向原文位置的本地映射。用例含义改变后产生新版本，先前失败及当时的用例和代码版本仍可追溯。
-
-例如，`REQ-001 → AC-002 → TC-004@1 → RUN-003` 表示明确的需求到结果关联。RUN 同时记录被测代码／构建及证据，仅存在用例编号不能证明已执行。
-
-工具检查结构、引用和基础覆盖；Agent 仍需判断正文和断言是否真正满足需求。元信息合法不等于内容正确。