Skip to content

docs(quality): deepen issue traceability terminology parity #3218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ootakazuhiko merged 3 commits into from
Apr 10, 2026
Merged

docs(quality): deepen issue traceability terminology parity #3218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4151422
docs(quality): fix traceability doc doctest fences
ootakazuhiko Apr 8, 2026
55ab914
docs(quality): align Issue number terminology
ootakazuhiko Apr 10, 2026
e27c37b
docs(agents): refresh generated commands catalog
ootakazuhiko Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/agents/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
docRole: derived
canonicalSource:
- .github/workflows/agent-commands.yml
lastVerified: '2026-04-08'
lastVerified: '2026-04-10'
---

# Agent Commands Catalog
Expand Down
22 changes: 11 additions & 11 deletions docs/quality/issue-requirements-traceability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ docRole: derived
canonicalSource:
- docs/quality/verify-first-implementation-runbook.md
- docs/reference/CONTRACT-CATALOG.md
lastVerified: '2026-03-27'
lastVerified: '2026-04-08'
---
# Issue Requirements Traceability (LG-*/REQ-*)

Expand Down Expand Up @@ -69,7 +69,7 @@ When `--discovery-pack` is combined, the matrix starts from Context Pack `upstre
- In the same file, keep related Context Pack IDs such as `diagramId`, `morphismId`, or `acceptanceTestId` in comments or metadata.
- Example:

```ts
```text
// LG-CHECKOUT-01 DGM-CHECKOUT-COMMUTE MOR-CALC-TOTAL AT-CHECKOUT-SUCCESS
```

Expand Down Expand Up @@ -99,9 +99,9 @@ ae validate --traceability --strict --sources docs/specs/ISSUE-TRACEABILITY-MATR

## 日本語

Issue本文を一次ソースとして、要件ID抽出 → matrix 生成 → strict validate までを標準CLIで実行する手順です。
Issue 本文を一次ソースとして、要件 ID 抽出 → matrix 生成 → strict validate までを標準 CLI で実行する手順です。

### 1) Issue本文から要件ID抽出
### 1) Issue 本文から要件 ID を抽出

```bash
ae traceability extract-ids \
Expand All @@ -110,11 +110,11 @@ ae traceability extract-ids \
--output docs/specs/issue-traceability-map.json
```

- `--issue` は GitHub Issue URL または issue number を指定可能
- issue number の場合は `--repo <owner/repo>` か `GITHUB_REPOSITORY` が必要
- `--issue` は GitHub Issue URL または Issue 番号を指定できます
- Issue 番号の場合は `--repo <owner/repo>` か `GITHUB_REPOSITORY` が必要です
- private repository では `GH_TOKEN` または `GITHUB_TOKEN` の設定を推奨

### 2) map から matrix 生成（md/json）
### 2) map から matrix を生成（md/json）

```bash
# JSON
Expand Down Expand Up @@ -155,20 +155,20 @@ ae traceability matrix \
- 同じファイル内に、関連する Context Pack ID（`diagramId` / `morphismId` / `acceptanceTestId`）を comment や metadata で残す
- 例:

```ts
```text
// LG-CHECKOUT-01 DGM-CHECKOUT-COMMUTE MOR-CALC-TOTAL AT-CHECKOUT-SUCCESS
```

### 3) strict validate
### 3) strict validate を実行

```bash
ae validate --traceability --strict --sources docs/specs/ISSUE-TRACEABILITY-MATRIX.json
```

- strict では以下のいずれかが 1 件でもあると非 0 終了
- strict モードでは以下のいずれかが 1 件でもあると非 0 終了になります
- tests/code 未リンク
- （matrix に Context Pack 列が存在する場合）diagram / morphism / acceptance test ID 欠落
- CI gate 用途では matrix(JSON) を `--sources` に渡す運用を推奨
- CI ゲート用途では matrix（JSON）を `--sources` に渡す運用を推奨します

### 失敗時の見方

Expand Down
Loading