ai-sdlc-commit-prep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ai-sdlc-commit-prep: Commit Preparation

ai-sdlc-commit-prep：提交准备

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Before producing the final artifact, confirm required inputs, target audience, missing facts, output format, and constraints when they are unclear. Do not invent missing information. Ask concise clarification questions when required inputs are absent.

内部AI SDLC技能，默认不面向客户。以下每条规则都必须遵守，无一例外。在生成最终产物前，若所需输入、目标受众、缺失信息、输出格式和约束条件不明确，请先确认。不得编造缺失信息。当所需输入缺失时，提出简洁的澄清问题。

0. Skill Card

0. 技能卡片

Skill name:
```
ai-sdlc-commit-prep
```
Primary audience: Dev
Supporting audience: QA, BA, PM
Audience tags: Dev, QA, BA, PM
SDLC stage: Commit readiness / traceability
Purpose: Prepare and create a safe AI SDLC commit by reviewing the branch and working tree, staging only related files, validating SDD evidence, using a valid Conventional Commit message, and reporting post-commit traceability.
Output: Safe staged set, validated commit readiness, conventional commit message, and post-commit traceability

技能名称：
```
ai-sdlc-commit-prep
```
主要受众：开发人员（Dev）
支持受众：测试人员（QA）、业务分析师（BA）、产品经理（PM）
受众标签：Dev、QA、BA、PM
SDLC阶段：提交就绪/可追溯性
目的：通过审查分支和工作树、仅暂存相关文件、验证SDD证据、使用合规的Conventional Commit信息，并报告提交后可追溯性，来准备并创建安全的AI SDLC提交。
输出：安全的暂存集合、已验证的提交就绪状态、合规的提交信息，以及提交后可追溯性

0.1 Required Inputs

0.1 所需输入

Explicit commit request or completed workflow state.
Current branch, dirty tree, staged files, and diff.
Validation results plus spec traceability when applicable.

明确的提交请求或已完成的工作流状态。
当前分支、未提交的工作树、已暂存文件和差异内容。
验证结果及适用时的规范可追溯性信息。

0.2 Clarification Rules

0.2 澄清规则

Ask concise questions before finalizing when role, artifact, requirements, scope, audience, or constraints are unclear.
If optional information is missing, mark it as
```
TBD
```
,
```
Not provided
```
, or
```
Assumption
```
instead of inventing it.
Separate confirmed facts from assumptions and open questions.
Do not proceed to downstream synthesis when a required upstream artifact or decision is missing.

当角色、产物、需求、范围、受众或约束条件不明确时，在最终确定前提出简洁的问题。
若可选信息缺失，标记为
```
TBD
```
、
```
Not provided
```
或
```
Assumption
```
，不得编造。
将已确认的事实与假设和未解决问题分开。
当所需的上游产物或决策缺失时，不得进行下游合成工作。

0.2.1 Flow Mode Flags

0.2.1 流程模式标志

Support two explicit execution flags:
```
--quick-flow
```
and
```
--full-flow
```
.
If both flags are supplied,
```
--full-flow
```
takes precedence because it is the stricter mode.
```
--quick-flow
```
: move fast, make high-quality progress with available context, avoid clarification questions unless continuing would create material product, security, compliance, data-loss, or irreversible implementation risk.
In
```
--quick-flow
```
, use documented assumptions, recommended defaults, existing repository patterns, and the nearest available artifact evidence; record important assumptions and decisions in
```
decision-log.md
```
.
In
```
--quick-flow
```
, run only focused checks that are directly relevant, cheap, and likely to catch regressions for the requested work; report any skipped broader checks as residual risk.
```
--full-flow
```
: ask concise clarification questions when inputs, scope, ownership, acceptance criteria, or decisions are unclear; do not silently assume material requirements.
In
```
--full-flow
```
, verify upstream and downstream artifacts, decision-log entries, traceability links, acceptance criteria, and validation evidence before finalizing.
In
```
--full-flow
```
, run or recommend the skill-appropriate gates, reviews, scripts, and validation commands needed for end-to-end confidence; document any blocked verification explicitly.
When neither flag is supplied, follow the skill default rules and choose the least risky behavior for the request size and domain.

支持两种明确的执行标志：
```
--quick-flow
```
和
```
--full-flow
```
。
若同时提供两个标志，
```
--full-flow
```
优先，因为它是更严格的模式。
```
--quick-flow
```
：快速推进，利用现有上下文开展高质量工作，除非继续执行会造成产品、安全、合规、数据丢失或不可逆的实施风险，否则避免提出澄清问题。
在
```
--quick-flow
```
模式下，使用文档化的假设、推荐的默认值、现有仓库模式和最近可用的产物证据；将重要的假设和决策记录在
```
decision-log.md
```
中。
在
```
--quick-flow
```
模式下，仅运行与请求工作直接相关、成本低且可能发现回归问题的针对性检查；将任何跳过的更广泛检查作为残余风险报告。
```
--full-flow
```
：当输入、范围、所有权、验收标准或决策不明确时，提出简洁的澄清问题；不得默认关键需求。
在
```
--full-flow
```
模式下，在最终确定前验证上下游产物、决策日志条目、可追溯性链接、验收标准和验证证据。
在
```
--full-flow
```
模式下，运行或推荐适合技能的门控、评审、脚本和验证命令，以实现端到端的信心；明确记录任何被阻止的验证工作。
当未提供任何标志时，遵循技能默认规则，并根据请求规模和领域选择风险最低的行为。

0.3 Output Rules

0.3 输出规则

Keep output structured with headings and bullets.
Make findings, gaps, risks, and blockers explicit.
Tie recommendations to evidence from the provided artifact, repository,
```
specs-refiniment/<feature-name>/<file.md>
```
workspace, or user context.
Include role ownership when the output creates follow-up work for BA, QA, Dev, PM, or Delivery.
Return progress, completion, validation, and handoff summaries directly in the Codex response.

Before the final response, emit the

ai-sdlc-handoff/v1

contract with

result

blockers

next_required

, and

next_optional

; every action includes

reason

command

, and

expected_artifact

Do not create
```
summary.txt
```
,
```
*-summary.txt
```
, or another standalone summary file unless the user explicitly requests one.
Keep durable writes limited to the canonical lifecycle artifacts, decision log, human-readable index, and
```
_ai_sdlc
```
machine files.
Let shared helpers migrate legacy paths on the next write; never overwrite or manually merge divergent legacy and canonical files.

保持输出结构化，使用标题和项目符号。
明确指出发现的问题、差距、风险和障碍。
将建议与提供的产物、仓库、
```
specs-refiniment/<feature-name>/<file.md>
```
工作区或用户上下文的证据关联起来。
当输出为BA、QA、Dev、PM或交付团队产生后续工作时，明确角色归属。
在Codex响应中直接返回进度、完成情况、验证和交接摘要。

在最终响应前，发出包含

result

、

blockers

、

next_required

和

next_optional

的

ai-sdlc-handoff/v1

协议；每个操作都包含

reason

、

command

和

expected_artifact

。

除非用户明确要求，否则不得创建
```
summary.txt
```
、
```
*-summary.txt
```
或其他独立的摘要文件。
仅对规范生命周期产物、决策日志、人类可读索引和
```
_ai_sdlc
```
机器文件进行持久化写入。
让共享助手在下次写入时迁移旧路径；不得覆盖或手动合并分歧的旧文件和规范文件。

0.4 Artifact Routing

0.4 产物路由

Maintain a feature decision log whenever this skill records, resolves, changes, or depends on a product, delivery, QA, security, validation, branching, implementation, or rollout decision.
For PM, BA, QA, Delivery, discovery, planning, refinement, and readiness work, write decisions to
```
specs-refiniment/<feature-name>/decision-log.md
```
.
For developer implementation SDD work, write decisions to
```
specs/<feature-name>/decision-log.md
```
.
Each decision-log entry must include date, decision, context or evidence, options considered when relevant, owner, status, and links to affected artifacts, tasks, tests, or validation evidence.

Use this exact decision-log structure:

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

Use
```
specs/
```
only for developer implementation SDD packages and repo-governance artifacts.
Do not place PM, BA, QA, Delivery, discovery, planning, refinement, or readiness outputs in
```
specs/
```
; those belong at
```
specs-refiniment/<feature-name>/<file.md>
```
.
When consuming
```
specs-refiniment/<feature-name>/<file.md>
```
, treat it as upstream refinement context and create or update
```
specs/
```
only when implementation work is explicitly in scope.

每当该技能记录、解决、更改或依赖产品、交付、QA、安全、验证、分支、实施或发布决策时，维护一个特性决策日志。
对于PM、BA、QA、交付、探索、规划、细化和就绪工作，将决策写入
```
specs-refiniment/<feature-name>/decision-log.md
```
。
对于开发人员实施SDD的工作，将决策写入
```
specs/<feature-name>/decision-log.md
```
。
每个决策日志条目必须包含日期、决策、背景或证据、相关的备选方案（如有）、负责人、状态，以及受影响产物、任务、测试或验证证据的链接。

使用以下精确的决策日志结构：

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

```
specs/
```
仅用于开发人员实施的SDD包和仓库治理产物。
不得将PM、BA、QA、交付、探索、规划、细化或就绪输出放入
```
specs/
```
；这些内容应放在
```
specs-refiniment/<feature-name>/<file.md>
```
。
当使用
```
specs-refiniment/<feature-name>/<file.md>
```
时，将其视为上游细化上下文，仅当实施工作明确在范围内时才创建或更新
```
specs/
```
中的内容。

0.5 Feature State Machine

0.5 特性状态机

Maintain feature lifecycle state in TOON at

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

for refinement work and

specs/<feature-name>/_ai_sdlc/state.toon

for implementation work.

Before executing this skill for a feature, check the state machine with

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

When this skill starts durable work, mark it in progress with
```
begin
```
; when the skill's required artifact or review is complete, mark it done with
```
complete
```
and include
```
--artifacts <path>
```
plus
```
--decision-ref DEC-###
```
when a decision was involved.
In
```
--full-flow
```
, do not proceed when predecessor stages are incomplete, another lifecycle skill is active, or the state file reports a blocker.
In
```
--quick-flow
```
, a predecessor skip is allowed only when continuing is low risk and the command includes
```
--assumption "..."
```
or
```
--decision-ref DEC-###
```
; record the same assumption or decision in
```
decision-log.md
```
.

Use

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

to emit compact LLM-readable state before choosing the next skill.

The state machine is feature-scoped: do not reuse a
```
state.toon
```
across unrelated feature folders.

在TOON中维护特性生命周期状态：细化工作的状态存于
```
specs-refiniment/<feature-name>/_ai_sdlc/state.toon
```
，实施工作的状态存于
```
specs/<feature-name>/_ai_sdlc/state.toon
```
。

在为某个特性执行此技能前，使用

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

检查状态机。

当该技能开始持久化工作时，用
```
begin
```
标记为进行中；当技能所需的产物或评审完成时，用
```
complete
```
标记为已完成，若涉及决策则添加
```
--artifacts <path>
```
和
```
--decision-ref DEC-###
```
。
在
```
--full-flow
```
模式下，当前驱阶段未完成、另一个生命周期技能处于活动状态或状态文件报告存在障碍时，不得继续执行。
在
```
--quick-flow
```
模式下，仅当继续执行风险较低且命令包含
```
--assumption "..."
```
或
```
--decision-ref DEC-###
```
时，才允许跳过前驱阶段；将相同的假设或决策记录在
```
decision-log.md
```
中。

在选择下一个技能前，使用

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

生成紧凑的LLM可读状态。

状态机是特性范围的：不得在不相关的特性文件夹之间复用
```
state.toon
```
。

0.6 Artifact Metadata And Metatags

0.6 产物元数据和元标签

Every Markdown artifact generated or updated by this skill must start with an
```
artifact_metadata
```
YAML frontmatter block before the first visible heading.

Use schema

ai-sdlc-artifact-metadata/v1

and keep these fields current:

feature

artifact

path

workspace

skill

flow_mode

state_file

decision_log

status

owner

created_at

updated_at

trace_ids

related_artifacts

validation

, and

metatags

```
metatags
```
must include at minimum
```
ai-sdlc
```
, the workspace (
```
refinement
```
or
```
implementation
```
), this skill name, the artifact type or filename stem, and a lifecycle/status tag such as
```
draft
```
,
```
review
```
,
```
approved
```
, or
```
validated
```
.
When
```
--quick-flow
```
is active, set
```
flow_mode: quick
```
, keep assumptions visible in the body, and add tags for major defaults or unresolved risk only when they help retrieval.
When
```
--full-flow
```
is active, set
```
flow_mode: full
```
, keep blockers and validation evidence reflected in
```
status
```
,
```
validation
```
,
```
trace_ids
```
, and
```
related_artifacts
```
.
Update metadata whenever the artifact path, status, owner, trace links, validation evidence, related artifacts, or decision references change.
Metadata is an index for routing, retrieval, and traceability; it does not replace the artifact body,
```
decision-log.md
```
, or
```
state.toon
```
.

该技能生成或更新的每个Markdown产物，在第一个可见标题前必须包含
```
artifact_metadata
```
YAML前置块。

使用

ai-sdlc-artifact-metadata/v1

schema，并保持以下字段最新：

feature

、

artifact

、

path

、

workspace

、

skill

、

flow_mode

、

state_file

、

decision_log

、

status

、

owner

、

created_at

、

updated_at

、

trace_ids

、

related_artifacts

、

validation

和

metatags

。

```
metatags
```
必须至少包含
```
ai-sdlc
```
、工作区（
```
refinement
```
或
```
implementation
```
）、该技能名称、产物类型或文件名主干，以及生命周期/状态标签（如
```
draft
```
、
```
review
```
、
```
approved
```
或
```
validated
```
）。
当
```
--quick-flow
```
激活时，设置
```
flow_mode: quick
```
，在正文中显示假设，仅当有助于检索时才添加主要默认值或未解决风险的标签。
当
```
--full-flow
```
激活时，设置
```
flow_mode: full
```
，在
```
status
```
、
```
validation
```
、
```
trace_ids
```
和
```
related_artifacts
```
中反映障碍和验证证据。
当产物路径、状态、负责人、可追溯链接、验证证据、相关产物或决策引用发生变化时，更新元数据。
元数据是用于路由、检索和可追溯性的索引；它不能替代产物正文、
```
decision-log.md
```
或
```
state.toon
```
。

0.7 Specs Index

0.7 规范索引

Before searching across feature folders, inspect the compact LLM index first:
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
for refinement work or
```
specs/_ai_sdlc/specs-index.toon
```
for implementation work.
Use the human-readable index at
```
specs-refiniment/specs-index.md
```
or
```
specs/specs-index.md
```
when reporting feature coverage, artifact inventory, or handoff status to people.

After this skill creates or materially updates an artifact, refresh the matching workspace index with

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

In
```
--quick-flow
```
, rely on
```
specs-index.toon
```
to choose the smallest relevant artifact set before opening files.
In
```
--full-flow
```
, verify the updated artifact appears in both
```
specs-index.toon
```
and
```
specs-index.md
```
before final handoff.
The specs index summarizes artifact metadata and state; it does not replace reading the selected source artifacts when details, approvals, or validation evidence matter.

在跨特性文件夹搜索前，先查看紧凑的LLM索引：细化工作查看
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
，实施工作查看
```
specs/_ai_sdlc/specs-index.toon
```
。
当向人员报告特性覆盖范围、产物清单或交接状态时，使用人类可读的索引
```
specs-refiniment/specs-index.md
```
或
```
specs/specs-index.md
```
。

该技能创建或实质性更新产物后，使用

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

刷新匹配的工作区索引。

在
```
--quick-flow
```
模式下，依赖
```
specs-index.toon
```
选择最小的相关产物集，再打开文件。
在
```
--full-flow
```
模式下，在最终交接前验证更新后的产物是否同时出现在
```
specs-index.toon
```
和
```
specs-index.md
```
中。
规范索引总结了产物元数据和状态；当细节、审批或验证证据很重要时，它不能替代读取选定的源产物。

References

参考资料

Use
```
scripts/check_commit_ready.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.

当工作流需要确定性验证、规划或格式化时，使用
```
scripts/check_commit_ready.py
```
；若支持，传递给该技能的
```
--quick-flow
```
或
```
--full-flow
```
标志也要传递给此脚本。

Script Usage

脚本用法

Run commit readiness before staging final commit content or writing the final commit summary.

Quick flow:

python3 skills/ai-sdlc-commit-prep/scripts/check_commit_ready.py --quick-flow --spec specs/<feature-name> --allow-unstaged --no-require-staged

Full flow:

python3 skills/ai-sdlc-commit-prep/scripts/check_commit_ready.py --full-flow --spec specs/<feature-name>

For an explicitly task-scoped commit in a larger active SDD plan, add
```
--task TNNN
```
. The selected task must be present and complete; later pending tasks remain allowed. Without
```
--task
```
, every spec task must be complete.
Use
```
--allow-unstaged
```
only when intentionally checking readiness before final staging.
Use
```
--no-require-staged
```
only for preflight checks; omit it immediately before commit creation.

在暂存最终提交内容或编写最终提交摘要前，运行提交就绪检查。

快速流程：

python3 skills/ai-sdlc-commit-prep/scripts/check_commit_ready.py --quick-flow --spec specs/<feature-name> --allow-unstaged --no-require-staged

完整流程：

python3 skills/ai-sdlc-commit-prep/scripts/check_commit_ready.py --full-flow --spec specs/<feature-name>

对于较大的活跃SDD计划中明确按任务范围提交的情况，添加
```
--task TNNN
```
。选定的任务必须存在且已完成；后续待处理任务仍被允许。若未添加
```
--task
```
，则所有规范任务必须完成。
仅当有意在最终暂存前检查就绪状态时，使用
```
--allow-unstaged
```
。
仅用于预检时使用
```
--no-require-staged
```
；在创建提交前立即省略此标志。

Purpose

目的

Prepare and create a safe AI SDLC commit by reviewing the branch and working tree, staging only related files, validating SDD evidence, using a valid Conventional Commit message, and reporting post-commit traceability.

通过审查分支和工作树、仅暂存相关文件、验证SDD证据、使用合规的Conventional Commit信息，并报告提交后可追溯性，来准备并创建安全的AI SDLC提交。

Inputs

输入

Collect the user’s explicit commit request or workflow state showing commit prep is justified.
Collect the active spec folder for medium or large work.
Collect validation commands and outcomes that are current for the active diff.
Collect the current branch and dirty tree from
```
git status --short --branch
```
.

收集用户明确的提交请求或表明提交准备合理的工作流状态。
收集中型或大型工作的活跃规范文件夹。
收集针对当前差异内容的最新验证命令和结果。
从
```
git status --short --branch
```
收集当前分支和未提交的工作树信息。

Steps

步骤

Run
```
git status --short --branch
```
.
Run
```
git diff --stat
```
and
```
git diff --cached --stat
```
when staged changes already exist.
Inspect relevant diffs for scope, accidental edits, generated files, secrets, and unrelated user changes.

Confirm medium or large work has current

requirements.md

design.md

test-cases.md

qa.md

tasks.md

_ai_sdlc/plan.toon

, and

plan.md

For medium or large work, confirm the current branch includes the active spec slug after a typed Git-flow prefix, for example
```
feature/NNN-short-feature-name
```
; otherwise report the branch/spec mismatch before committing.
Confirm completed tasks in
```
tasks.md
```
match the diff.
Run or confirm current validation before staging.
Ensure the active spec passes structural validation plus clarify, checklist, and analyze before final commit.
Run the readiness checker before final commit:
bash
```
python3 skills/ai-sdlc-commit-prep/scripts/check_commit_ready.py --spec specs/NNN-feature-name --no-require-staged
```
When the user explicitly requested one commit per SDD task, add
```
--task TNNN
```
and verify that the staged diff belongs only to that task.
Stage only files belonging to the current change.
Leave unrelated dirty files unstaged and report them.
Use
```
$ai-sdlc-conventional-commit
```
to draft and validate the message.
Commit with a non-interactive command, for example
```
git commit -F /tmp/message.txt
```
.
Run
```
git status --short --branch
```
after committing.

运行
```
git status --short --branch
```
。
若已存在暂存变更，运行
```
git diff --stat
```
和
```
git diff --cached --stat
```
。
检查相关差异内容的范围、意外编辑、生成文件、机密信息和无关的用户变更。

确认中型或大型工作拥有最新的

requirements.md

、

design.md

、

test-cases.md

、

qa.md

、

tasks.md

、

_ai_sdlc/plan.toon

和

plan.md

。

对于中型或大型工作，确认当前分支在Git-flow类型前缀后包含活跃规范的短标识，例如
```
feature/NNN-short-feature-name
```
；否则在提交前报告分支/规范不匹配问题。
确认
```
tasks.md
```
中已完成的任务与差异内容匹配。
在暂存前运行或确认最新的验证。
确保活跃规范通过结构验证，以及提交前的澄清、检查清单和分析。
在最终提交前运行就绪检查器：
bash
```
python3 skills/ai-sdlc-commit-prep/scripts/check_commit_ready.py --spec specs/NNN-feature-name --no-require-staged
```
若用户明确要求每个SDD任务对应一次提交，添加
```
--task TNNN
```
并验证暂存的差异内容仅属于该任务。
仅暂存属于当前变更的文件。
保留无关的未提交文件不暂存并报告。
使用
```
$ai-sdlc-conventional-commit
```
草拟并验证提交信息。
使用非交互式命令提交，例如
```
git commit -F /tmp/message.txt
```
。
提交后运行
```
git status --short --branch
```
。

Output Spec

输出规范

Return this final report:

text

Commit:
- Hash: full_hash
- Subject: conventional subject
- Branch: branch-name
- Spec: specs/NNN-feature-name | none

Staging:
- Included: path groups and why they belong.
- Excluded: unrelated dirty paths or none.

Validation:
- command -> outcome

Post-commit:
- Working tree: clean | dirty with listed paths.
- Residual risk: none | concrete issue.

Quality gate:

Pass when the branch/spec relationship is explicit, the commit contains only related files, validation is current, message validation passes, and post-commit status is reported.
Fail when branch/spec mismatch is hidden, unrelated files are staged, validation is stale, the message validator fails, or the final report hides a dirty tree.

返回以下最终报告：

text

Commit:
- Hash: full_hash
- Subject: conventional subject
- Branch: branch-name
- Spec: specs/NNN-feature-name | none

Staging:
- Included: path groups and why they belong.
- Excluded: unrelated dirty paths or none.

Validation:
- command -> outcome

Post-commit:
- Working tree: clean | dirty with listed paths.
- Residual risk: none | concrete issue.

质量门控：

当分支/规范关系明确、提交仅包含相关文件、验证是最新的、信息验证通过且提交后状态已报告时，通过。
当分支/规范不匹配被隐藏、无关文件被暂存、验证过期、信息验证失败或最终报告隐瞒未提交工作树时，失败。

Examples

示例

Valid staging rationale:

text

Staging:
- Included: `skills/*/SKILL.md` because every file is part of the skill instruction upgrade.
- Included: `specs/177-skill-instruction-upgrade/*` because the SDD package documents this change.
- Excluded: `apps/web/.env.local` because it is unrelated and sensitive.

Invalid counter-example:

text

Ran git add -A and committed everything.

Reject this when the working tree contains files not inspected for scope.

有效的暂存理由：

text

Staging:
- Included: `skills/*/SKILL.md` because every file is part of the skill instruction upgrade.
- Included: `specs/177-skill-instruction-upgrade/*` because the SDD package documents this change.
- Excluded: `apps/web/.env.local` because it is unrelated and sensitive.

无效反例：

text

Ran git add -A and committed everything.

当工作树包含未检查范围的文件时，拒绝此操作。

Edge Cases

边缘情况

Stop and ask before staging when unrelated changes are mixed inside a file required for the current change.
Stop and resolve branch state with
```
$ai-sdlc-branching
```
when medium or large work is still on
```
dev
```
,
```
main
```
,
```
master
```
, or a branch that does not include the active spec slug.
Use
```
--allow-unstaged
```
on the readiness checker only when unrelated unstaged files are intentionally left out and reported.
Do not amend an existing commit unless the user explicitly requests amend.
Do not run destructive cleanup commands unless the user requested or approved them.
Report failed commit hooks with the hook output and do not claim a commit exists.

当当前变更所需的文件中混入无关变更时，停止并询问后再暂存。
当中型或大型工作仍在
```
dev
```
、
```
main
```
、
```
master
```
或不包含活跃规范短标识的分支上时，停止并使用
```
$ai-sdlc-branching
```
解决分支状态问题。
仅当有意保留并报告无关的未提交文件时，在就绪检查器上使用
```
--allow-unstaged
```
。
除非用户明确要求，否则不得修改现有提交。
除非用户请求或批准，否则不得运行破坏性清理命令。
报告失败的提交钩子及其输出，不得声称提交已存在。

Scope Boundary

范围边界

Do not draft commit message content without
```
$ai-sdlc-conventional-commit
```
.

Do not decide test coverage; use

$ai-sdlc-test-cases

$ai-sdlc-qa

, and

$ai-sdlc-validation

Do not revert user changes to make staging easier.

不得在未使用
```
$ai-sdlc-conventional-commit
```
的情况下草拟提交信息内容。

不得决定测试覆盖范围；使用

$ai-sdlc-test-cases

、

$ai-sdlc-qa

和

$ai-sdlc-validation

。

不得回滚用户变更以简化暂存操作。