@relipa/ai-flow-kit 0.1.9 → 0.2.0-beta.0

package/README.md

@@ -188,6 +188,63 @@ ak use PROJ-33  (taskType: testcase)  →  claude
 
 ---
 
+## Create System Requirement Flow
+
+```
+ak use PROJ-33  (taskType: create-system-requirement)  →  claude
+        │
+        ▼
+⛩️ GATE 1 — Investigate UC & Draft             [AI + BA/Dev]
+  AI resolve UC Spec version hiện tại của functionId
+  AI đọc source code + convention error-handling hiện có
+  AI dịch từng Flow step + Business Rule → FR/NFR/Validation Rules/Exception Handling
+  AI viết Acceptance Test scenarios (Given/When/Then) — mọi item trace về đúng UC, không tự suy diễn
+  Q&A từng câu một tới khi hết Gap chưa rõ → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Finalize & Approve                  [AI + BA/Dev]
+  AI quyết định single-file vs split (mặc định 1 file 1-1 với UC Spec,
+  chỉ split khi có tín hiệu đo được — fan-out business rule/module, quá nhiều flow, ~400 dòng)
+  AI ghi AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md
+  (N khớp đúng version UC Spec đã trace, ghi trong header `UC-Spec-Version`)
+  Review → "APPROVED"
+        │
+        ▼
+       DONE — Coding Gate 1 (read-study-requirement) mới được phép chạy cho functionId này
+```
+
+> **Entry point:** `ak use PROJ-33` → chọn taskType **"📐 Create System Requirement"** trong danh sách. Đây là bước bắt buộc, chạy 1 lần cho mỗi `functionId` (không phải mỗi ticket) — Coding Gate 1 sẽ tự chặn (`⏸️ Gate 1 cancelled`) nếu System Requirement chưa tồn tại hoặc chưa khớp UC Spec version hiện tại.
+
+---
+
+## Ingest Data Flow
+
+```
+ak use <link hoặc paste text>  (taskType: ingest-data)  →  claude
+        │
+        ▼
+⛩️ GATE 1 — Fetch, Classify, Draft              [AI + PM/BrSE/Comtor]
+  Input: Backlog ticket/comment/Document/Wiki link · Jira ticket/comment link ·
+         SharePoint link (chưa có connector — fallback paste text) · text thô
+  AI resolve nguồn: `ak fetch-links <url>` (nếu là link) hoặc dùng text trực tiếp
+  AI phân loại: QnA-Log / Meetings-Log / Confirmations-Log (hỏi lại nếu chưa rõ)
+  AI soạn draft đầy đủ — kèm Nguồn / functionId / Người tổng hợp / Người approve tại nguồn
+  Hiển thị draft nguyên văn, lặp sửa theo yêu cầu tới khi → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Branch + Merge Request              [AI, chờ xác nhận từng bước]
+  Ghi entry vào AK-Docs/01.QnA/{QnA-Log,Meetings-Log,Confirmations-Log}.md
+  `ak docs branch [functionId] [ticketId] --yes` — chỉ chạy sau khi user xác nhận
+  `ak docs submit --title "..." --yes` — chỉ chạy sau khi user xác nhận
+        │
+        ▼
+       DONE — chờ PM review & merge MR vào main (không tự merge)
+```
+
+> **Entry point:** `ak use` → chọn taskType **"📥 Ingest Data"**, hoặc `ak use "<backlog/jira-url>"` rồi chọn taskType tương ứng. SharePoint chưa fetch được nội dung thật — paste trực tiếp nội dung comment/tài liệu vào chat thay vì dán link (xem `docs/internal/PM Workflow_v1.0.md` "Vấn đề 4").
+
+---
+
 ## Installation
 
 ```bash
@@ -590,6 +647,14 @@ Then run `ak update` or `ak sync-skills` to apply.
 
 > Summary of major changes per version. See full details in [CHANGELOG.md](docs/common/CHANGELOG.md).
 
+### v0.2.0 — 2026-08-04
+- **New `create-system-requirement` task type (2-Gate):** bridges a UC Spec (BA) into a Dev-facing System Requirement scoped to a `functionId` (not a ticket) — Gate 1 investigates the UC + source code and drafts FR/NFR/Validation Rules/Exception Handling + Given/When/Then acceptance tests, Gate 2 finalizes and writes `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md`. Coding Gate 1 (`read-study-requirement`) now **blocks** with a Step 0 pre-check if this document is missing or stale against the current UC Spec version. See [Create System Requirement Flow](#create-system-requirement-flow).
+- **New `ingest-data` task type (2-Gate) — for PM/BrSE/Comtor:** ingest a Backlog ticket/comment/Document/Wiki link, a Jira link, a SharePoint link, or pasted text into `AK-Docs/01.QnA/{QnA-Log,Meetings-Log,Confirmations-Log}.md`. Gate 1 fetches + classifies + drafts the entry for self-review; Gate 2 opens the branch + Merge Request via the existing `ak docs branch`/`ak docs submit`. SharePoint has no connector yet (no Microsoft Graph API/OAuth) — falls back to pasted text. See [Ingest Data Flow](#ingest-data-flow) and `docs/internal/PM Workflow_v1.0.md`.
+- **`ak fetch-links` / `link-resolver.js` now fetch Backlog Document and Wiki links**, not just ticket/comment — `fetchBacklogDocument`, `fetchBacklogDocumentComment`, `fetchBacklogWiki`. Auto-resolution from a ticket description (`ak use`) still only follows ticket/comment links, capped at 5 — Document/Wiki/SharePoint are explicit single-URL lookups only.
+- **`ak use` now captures `projectId`/`projectKey`** from the loaded Backlog/Jira ticket (`.aiflow/context/current.json` and `.aiflow/state.json`) — a first step toward letting a future "create ticket" flow default to the right Backlog/Jira project instead of asking every time.
+- Fixed: **`ak use`'s "Task type:" selector crashed** (`CATEGORY_COLOR[cat] is not a function`) whenever it rendered the **"📐 Create System Requirement"** entry — the `"Dev"` category had no color mapping. Added.
+- `docs/common/Docs-Management-Flow.md`'s branch+MR flow now explicitly covers `AK-Docs/01.QnA/`, not just `02.BA-Specs/`/`03.Testing/`/`04.Coding/`/`99.Memory/`.
+
 ### v0.1.9 — 2026-08-04
 - **Codex (OpenAI) support — `ak init --env codex`:** One install covers all three local Codex surfaces, which share the same `CODEX_HOME` config, skills and MCP setup: the **VS Code extension**, **Codex mode in the ChatGPT desktop app**, and the **`codex` CLI**. Generates `AGENTS.md`, `.codex/skills/` (all kit skills, auto-discovered — the kit's `SKILL.md` layout is already Codex-compatible), `.codex/config.toml` (MCP servers mirrored from `.mcp.json`), and `.aiflow/instructions/`.
 - **Four Codex entry-point skills:** `/ak-coding`, `/ak-create-spec`, `/ak-create-testcase`, `/ak-ask` — the same workflows Claude Code exposes as slash commands.

package/bin/aiflow.js

@@ -170,6 +170,11 @@ program
     .option('--cto <id>', 'load comments up to ID N', parseInt)
     .option('-F, --fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
     .option('-U, --full', 'full mode: force complete analysis with Q&A (default)')
+    .option('--task-type <type>', 'skip the interactive Task type prompt (e.g. feature, bug-fix)')
+    .option('--title <title>', 'manual entry: skip the interactive Title prompt')
+    .option('--description <description>', 'manual entry: skip the interactive Description prompt')
+    .option('--ticket-id <id>', 'manual entry: skip the interactive Ticket ID prompt')
+    .option('--preview', 'fetch a ticket/URL target and print its context as JSON to stdout — no save, no prompts')
     .addHelpText('after', `
 Examples:
   $ ak use PROJ-33                                  Single ticket (primary only)
@@ -180,6 +185,12 @@ Examples:
   $ ak use --file task.md                           Load from local file
   $ ak use --manual                                 Manual entry
 
+Non-interactive entry (v0.3.0+, for scripting/GUI callers):
+  $ ak use --manual --task-type feature --title "x" --description "y"
+                                                     Manual entry, zero prompts
+  $ ak use PROJ-33 --task-type bug-fix              Skip the Task type prompt after fetch
+  $ ak use PROJ-33 --preview                        Fetch only — print context JSON, no save/prompts
+
 Auto link resolution (v0.1.0+):
   Backlog/Jira URLs in the primary ticket description are auto-fetched and added
   to supplementaryContext[]. Comment links (#comment-456 or ?focusedCommentId=456)
@@ -195,17 +206,20 @@ Related:
 // ── fetch-links ───────────────────────────────────────────────
 program
     .command('fetch-links <url>')
-    .description('Fetch a backlog/jira link and output SupplementaryContext JSON to stdout. Used by AI at runtime.')
+    .description('Fetch a backlog/jira/sharepoint link and output SupplementaryContext JSON to stdout. Used by AI at runtime.')
     .addHelpText('after', `
 Examples:
   $ ak fetch-links "https://company.backlog.com/view/PROJ-10"
   $ ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
+  $ ak fetch-links "https://company.backlog.com/document/98765"          Backlog Document (ingest-data)
+  $ ak fetch-links "https://company.backlog.com/alias/wiki/1234"         Backlog Wiki (ingest-data)
   $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10"
   $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"
+  $ ak fetch-links "https://company.sharepoint.com/sites/proj/doc.docx"  → { sourceType: "unsupported" }, no connector yet
 
 Exit codes:
-  0   Success — JSON written to stdout
-  1   URL not recognised, or fetch failed (error on stderr)
+  0   Success — JSON written to stdout (including the SharePoint "unsupported" stub)
+  1   URL not recognised at all, or fetch failed (error on stderr)
 `)
     .action(async (url) => {
         const { fetchLink } = require('../scripts/link-resolver');
@@ -214,7 +228,7 @@ Exit codes:
         try {
             const result = await fetchLink(url, credentials);
             if (!result) {
-                process.stderr.write(`Not a recognized backlog/jira URL: ${url}\n`);
+                process.stderr.write(`Not a recognized backlog/jira/sharepoint URL: ${url}\n`);
                 process.exit(1);
             }
             process.stdout.write(JSON.stringify(result, null, 2) + '\n');

package/custom/rules/project-conventions.md

@@ -50,6 +50,22 @@
 
 ---
 
+## ingest-data Workflow Output Paths (`AK-Docs/01.QnA/`)
+
+Áp dụng cho taskType `ingest-data` (PM/BrSE/Comtor ingest communication — xem `.claude/skills/ingest-data/SKILL.md`). Khác với các taskType coding/gen-doc ở trên: **không** ghi vào `04.Coding/`, và **không** theo cấu trúc `[functionId]/[ticketId].md` — cả 3 file dưới đây là log dùng chung, phẳng, cho toàn dự án (append entry mới, không tạo file theo ticket):
+
+| Log | Path | Ghi khi nào |
+|---|---|---|
+| QnA-Log | `AK-Docs/01.QnA/QnA-Log.md` | Trao đổi hỏi-đáp thông thường (file có sẵn — thêm cột `Nguồn` nếu chưa có) |
+| Meetings-Log | `AK-Docs/01.QnA/Meetings-Log.md` | Tổng hợp 1 buổi họp — tạo file nếu chưa có |
+| Confirmations-Log | `AK-Docs/01.QnA/Confirmations-Log.md` | Mốc khách CHỐT chính thức — tạo file nếu chưa có |
+
+`functionId` cho Gate 2 (đặt tên branch `feature/[functionId]/[ticketId]`) vẫn theo đúng quy tắc "functionId & ticketId" ở trên — không suy ra được thì dùng `general` (tương tự gen-doc dùng `AD-HOC`).
+
+> **Chưa đổi tên thư mục** `01.QnA/` thành `01.Communications/` như phương án đang chờ PM chốt trong `docs/internal/PM Workflow_v1.0.md` — giữ nguyên tên hiện có để không phá vỡ project đang chạy; đổi tên (nếu PM chốt) là 1 task migration riêng.
+
+---
+
 ## Execution Handoff Message
 
 When `writing-plans` skill says to announce the saved path, use the **actual path**:

package/custom/skills/create-system-requirement/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: create-system-requirement
+description: Bridges UC Spec (BA, Gate 4) to Dev — investigates source code and translates the UC into System Requirement (Functional/Non-Functional Requirements, Business Rules → Validation Rules, Exception/Error Handling, Acceptance Tests). Runs once per functionId per UC Spec version, BEFORE the first coding ticket. Blocks Gate 1 (`read-study-requirement`) if missing or out of sync with the current UC Spec version.
+keywords: system requirement, uc spec, functionId, trace, acceptance test, exception handling, business rule, matching, version sync
+---
+
+# Create System Requirement — Bridge Gate (before Gate 1)
+
+> **Runs once per functionId per UC Spec version — NOT per ticket.**
+>
+> Principle: System Requirement is the Dev-facing translation of UC Spec (User Requirement). It must trace 1-1 to a specific UC Spec version, cover the full UC (flows, business rules, exceptions, acceptance criteria), and never invent content the UC Spec doesn't support. If anything is unclear, ask until it's Confirmed — do not guess.
+
+---
+
+## Trigger
+
+`create-system-requirement` is its own **task type** — 2 gates, selectable in the "Task type:" prompt of `ak use` (or auto-detected by `aiflow prompt "..."` — see `scripts/detect.js`). It is not invoked inline from within a coding ticket's session; it runs as its own task, tied to the `functionId` (not to a coding ticket).
+
+- **Gate 1** = Steps 0–4 below (resolve UC Spec, investigate source code, draft, Q&A until every Gap is Confirmed).
+- **Gate 2** = Steps 5–7 below (split decision, write output, present for APPROVED).
+
+**Hand-off from coding Gate 1 Pre-flight** (`read-study-requirement`, Step 0) when:
+- No `System-Requirement_v*.md` exists yet for this `functionId`, **or**
+- The existing one's `UC-Spec-Version` header does not match the UC Spec's current version.
+
+Either condition → **the coding Gate 1 session is cancelled.** Tell DEV: start a new task with `ak use`, pick **"📐 Create System Requirement"** at the Task type prompt, run it through both gates to APPROVED, then resume the original ticket.
+
+---
+
+## Steps
+
+> Steps 0–4 = **Gate 1** (investigate & draft). Steps 5–7 = **Gate 2** (finalize & approve). Run `aiflow task next` between them like any other gated task.
+
+### Step 0: Pre-flight — Resolve functionId & Versions [Gate 1]
+
+0. `git status --porcelain` → clean tree → `git pull --ff-only`; dirty tree → skip pull, notify DEV (same rule as `read-study-requirement` Step 1.0).
+1. Resolve `functionId` from `.aiflow/context/current.json` (or ask DEV once if absent).
+2. Locate the current UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (highest non-archived version). **Not found → STOP.** Tell DEV the UC Spec must exist and be BA-signed-off before System Requirement can be created — this skill never fabricates a UC.
+3. Check `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v*.md`:
+   - **None exists** → Mode = `CREATE` (go to Step 1).
+   - **Exists, `UC-Spec-Version` matches current UC Spec version** → nothing to do — this task is not needed; tell DEV the coding Gate 1 (`read-study-requirement`) can proceed directly.
+   - **Exists, `UC-Spec-Version` is older** → Mode = `RESYNC` (go to Step 1, but Step 3 diffs against the existing file instead of starting blank).
+
+---
+
+### Step 1: Read UC Spec (full) [Gate 1]
+
+Read all 5 sections of the UC Spec end-to-end — General Info + Main/Alternative/Exception Flows, Screen Description, UI Components, Activity Diagram, Business Rules (BR1 Validation / BR2 Saving / BR3 Authorization, or whatever domains the BA defined). Do not skim — every Functional Requirement, Validation Rule, Exception, and Acceptance Test written later must trace back to something read here.
+
+`RESYNC` mode: also read the previous `System-Requirement_v{N-1}.md` in full — it's the diff baseline for Step 3.
+
+---
+
+### Step 2: Investigate Source Code [Gate 1]
+
+Same methodology as `read-study-requirement` Step 1 (steps 4–5), reused here:
+- Read `CLAUDE.md` for architecture/conventions.
+- Find modules/files that implement or would implement this UC's Main Flow (existing feature being extended, or nearest analogous feature for a new one).
+- **If GitNexus MCP available:** `gitnexus: query()` / `gitnexus: context()` for the relevant area — same token-saving shortcut as `read-study-requirement`.
+- Identify **existing error-handling conventions** (error code format, message structure, exception class hierarchy) — the Exception & Error Handling section (Step 4 below) must reuse these, not invent a new convention.
+- Identify **existing data model / API surface** touched by this UC (tables, DTOs, endpoints) — feeds Section 6 of the output.
+
+This step exists so System Requirement reflects what the system *can actually do today*, not just what the UC Spec says in the abstract.
+
+---
+
+### Step 3: Draft Content — Translate UC → System Requirement [Gate 1]
+
+For every row in the UC Spec's Main Flow, Alternative/Exception Flows, and Business Rules, produce at least one corresponding item below, and record the UC reference it came from. Nothing goes into the draft without a traced source (UC Spec) or a confirmed answer from DEV — no invented content.
+
+- **Functional Requirements** — one per distinct system behavior in Main/Alternative Flow steps.
+- **Non-Functional Requirements** — from BR3-type rules (security, authz) or explicit constraints in the UC Spec / ticket context; do not invent performance/scale numbers that aren't stated anywhere — mark as Gap and ask instead.
+- **Business Rules → Validation Rules** — translate each BR into a concrete system-level rule, cross-referenced with the existing pattern found in Step 2 (or flagged if no existing pattern applies).
+- **Exception & Error Handling** — one per Exception Flow, using the error-handling convention found in Step 2.
+- **Acceptance Test Scenarios** — Given/When/Then, at least one per Main Flow outcome + one per Alternative/Exception Flow. This is the concrete deliverable requested by proposal #1 (acceptance tests generated from the spec, not copied from the ticket).
+
+**`RESYNC` mode:** diff the new UC Spec version against the previous one section by section; carry forward unchanged items, mark changed/removed items, draft new items only for the delta. Never silently drop an item without noting why in the Change Log.
+
+Classify every item as **Fact** (explicit in UC Spec or confirmed in code) / **Assumption** (inferred, unconfirmed) / **Gap** (missing entirely) — same convention as `read-study-requirement` Step 1.75.
+
+---
+
+### Step 4: Clarify via Q&A (ask until Confirmed) [Gate 1]
+
+- Ask **one question at a time**, prioritizing unresolved Assumptions/Gaps from Step 3.
+- **Do not run `aiflow task next` into Gate 2 while any Gap remains unresolved.** This is the hard rule from proposal #7 — no fabrication, no "reasonable default" for missing UC content. If DEV genuinely cannot answer (needs BA), stop and record it as an open item in Section 8 rather than guessing.
+- Do NOT invoke `superpowers:brainstorming` (same reason as `read-study-requirement`: its terminal state bypasses this gate's approval).
+- All Gaps Confirmed → present a short Gate 1 summary, wait for DEV to run `aiflow task next` before continuing to Step 5.
+
+---
+
+### Step 5: Decide Single File vs Split [Gate 2]
+
+**Default: one file.** `System-Requirement_v{N}.md` mirrors `UC-Spec_v{N}.md` 1-1 — most UCs stay a single, reviewable document. Split is the exception, triggered by any ONE of:
+
+| Signal | Threshold | Split by |
+|---|---|---|
+| Business-rule domain fan-out | 2+ BR domains (e.g. Validation, Authorization) each with 8+ concrete rules, touching different system layers | One sub-file per domain |
+| Module/service fan-out | Step 2 investigation shows 3+ separately deployable modules/services with little shared logic (e.g. separate microservice + separate batch job) | One sub-file per module |
+| Flow-count overload | 6+ Alternative/Exception flows AND draft would exceed ~300 lines | Split Exception & Error Handling into its own sub-file; keep Functional Requirements + Acceptance Tests together |
+| Size ceiling | Draft exceeds ~400 lines even without the above | Split along whichever axis (domain or module) holds the most content — never split by raw line count alone with no semantic seam |
+
+**Anti-pattern — do not split for this, escalate instead:** if the UC Spec itself reads like 2+ independent use cases bundled together (no shared Business Rule, no shared data entity, could be tested/shipped separately) → **stop, do not split System Requirement to cope.** Flag to BA that the UC Spec's granularity may need revisiting (per the kit's own convention, 1 UC should be 1 Function-ID). Splitting Dev's document to paper over a BA-side granularity problem just hides it.
+
+**When split occurs:** keep one master `System-Requirement_v{N}.md` as the index — holds header/metadata, the full Traceability Matrix, links to each sub-file, and the Change Log. Sub-files: `System-Requirement_v{N}_[Domain].md` (e.g. `_Validation.md`, `_BackendAPI.md`). The mandatory `UC-Spec-Version` header lives on the master file only.
+
+---
+
+### Step 6: Write Output [Gate 2]
+
+Save to `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md` (`N` = the UC Spec version this was traced against — **not** an independent counter):
+
+```markdown
+# System Requirement: [functionId] — [Feature Name]
+
+**Date:** [YYYY-MM-DD]
+**System-Requirement-Version:** v{N}
+**UC-Spec-Version:** [functionId] @ v{N}   <!-- MANDATORY — the 1-1 matching anchor -->
+**Source UC Spec:** AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md
+**Status:** ⏸️ Waiting for Approval
+
+---
+
+## 0. Traceability Matrix
+| UC Reference (Flow / BR) | System Requirement Item(s) |
+|---|---|
+| Main Flow step 3 | FR-01 |
+| Exception Flow B | FR-05, ER-02 |
+| BR1.1 | VR-01 |
+
+## 1. Functional Requirements
+| ID | Requirement | Traced UC Ref | Type |
+|---|---|---|---|
+| FR-01 | ... | Main Flow #3 | Fact |
+
+## 2. Non-Functional Requirements
+| ID | Requirement | Traced UC Ref | Type |
+|---|---|---|---|
+| NFR-01 | ... | BR3.1 | Fact |
+
+## 3. Business Rules → Validation Rules
+| ID | System-level Rule | Traced UC BR | Existing Code Pattern |
+|---|---|---|---|
+| VR-01 | ... | BR1.1 | [file:line] |
+
+## 4. Exception & Error Handling
+| ID | Trigger Condition | System Behavior | Traced Exception Flow | Error Convention Used |
+|---|---|---|---|---|
+| ER-01 | ... | ... | Exception Flow B | [existing error code/class] |
+
+## 5. Acceptance Test Scenarios
+### AT-01: [Scenario] (Main Flow)
+- **Given** ...
+- **When** ...
+- **Then** ...
+
+### AT-02: [Scenario] (Exception Flow B)
+...
+
+## 6. Existing System Context
+### Related Modules / Files
+| File | Role | Current Behavior |
+|---|---|---|
+
+### Data / API Impact
+| Entity / Endpoint | Change Type | Note |
+|---|---|---|
+
+## 7. Facts / Assumptions / Gaps
+| Type | Item | Resolution |
+|---|---|---|
+
+## 8. Open Questions Log
+[Question asked → answer received → date. Unresolved Gaps stay listed here, never silently dropped.]
+
+## 9. Change Log
+| Date | Ticket | Change | Note |
+|---|---|---|---|
+| [YYYY-MM-DD] | — | Initial creation from UC Spec v{N} | |
+```
+
+---
+
+### Step 7: Present for Approval [Gate 2]
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️  GATE 2: SYSTEM REQUIREMENT READY
+
+FunctionId: [functionId]
+UC Spec:    v{N} (AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md)
+File:       AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md
+Mode:       CREATE | RESYNC
+
+Coverage:
+  Functional Requirements: [N]   Acceptance Tests: [N]
+  Validation Rules:        [N]   Exception Handling: [N]
+  Open Gaps:                [N]  ← must be 0 to approve
+
+Please review — matching 1-1 with UC Spec v{N} is the point of this document.
+  → Type APPROVED (then run `aiflow task next`) to close this task and unlock
+    coding Gate 1 for tickets on this functionId
+  → Or provide feedback to update
+
+⚠️  Coding Gate 1 for this functionId stays cancelled until this task is APPROVED.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+- Any Gap still open → cannot approve; go back to Step 4 (re-open Gate 1).
+- DEV feedback → update draft → re-show prompt.
+- `APPROVED` → write `Status: ✅ Approved`, task is done — coding Gate 1 unlocks.
+
+---
+
+### Step 8: Later Update (invoked from inside coding Gate 1, not standalone)
+
+`read-study-requirement` Step 3 (end of Gate 1, per ticket) may discover a case, rule, or exception that the UC Spec supports but the current System Requirement missed. That step **proposes** an addition — presents the diff to DEV, does not write directly — and on confirmation appends it to the master file's relevant section plus a `Change Log` row (`Ticket: [ticketId]`). This skill owns the template/contract for that row; `read-study-requirement` owns triggering it.
+
+This does not bump `System-Requirement-Version` — the version stays tied to the UC Spec version. Only a new UC Spec version triggers `RESYNC` (Step 0).
+
+---
+
+## What This Skill Delegates vs Owns
+
+| Concern | Handled by |
+|---|---|
+| Source code investigation methodology | `read-study-requirement` Step 1 pattern (reused inline) / GitNexus MCP |
+| Fact/Assumption/Gap classification | This skill (inline, same convention as `read-study-requirement` Step 1.75) |
+| Q&A loop (one question at a time, no fabrication) | This skill (inline) |
+| UC Spec structure/content | `skill-ba-uc-template-v1.md` (read-only reference, never edited by this skill) |
+| Split decision | This skill (Step 5) |
+| Mid-ticket addition proposals | `read-study-requirement` Step 3 triggers; this skill owns the write contract |
+| Gate/approval mechanics | This skill (Step 7) |
+
+---
+
+## Mandatory Rules
+
+- ❌ **DO NOT** create System Requirement content that isn't traced to the UC Spec or a DEV-confirmed answer — no invented Functional Requirements, error messages, or NFR numbers.
+- ❌ **DO NOT** proceed to Step 5 while any Gap is unresolved.
+- ❌ **DO NOT** split into multiple files unless a Step 5 threshold is actually met — default is one file.
+- ❌ **DO NOT** split to paper over a UC Spec that bundles multiple independent use cases — escalate to BA instead.
+- ❌ **DO NOT** run this skill if the UC Spec isn't BA-signed-off yet — this skill never substitutes for missing UC Spec content.
+- ❌ **DO NOT** bump `System-Requirement-Version` independently of the UC Spec version.
+- ✅ **MUST** read the full UC Spec (Step 1) before drafting anything.
+- ✅ **MUST** investigate source code (Step 2) before drafting Exception/Error Handling or Existing System Context.
+- ✅ **MUST** carry the mandatory `UC-Spec-Version` header on the master file.
+- ✅ **MUST** block/cancel Gate 1 until this skill reaches APPROVED, when triggered by the Gate 1 Pre-flight check.

package/custom/skills/ingest-data/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: ingest-data
+description: Use when taskType is "ingest-data" — PM/BrSE/Comtor ingesting customer communication (Backlog ticket/comment/Document/Wiki link, Jira link, SharePoint link, or pasted text) into AK-Docs/01.QnA/ logs. Covers fetching the source, classifying it into QnA-Log/Meetings-Log/Confirmations-Log, and drafting the entry for self-review before Gate 2 opens the MR.
+keywords: ingest data, comtor, brse, pm workflow, meeting minutes, qna log, confirmations log, backlog document, backlog wiki, sharepoint, gate 1, gate 2
+---
+
+# Ingest Data — Gate 1 (fetch/classify/draft)
+
+> **Vai trò:** PM · BrSE · Comtor. **Bối cảnh đầy đủ:** `docs/internal/PM Workflow_v1.0.md` (Flow A + Flow B).
+> Gate mechanics (khi nào chạy Gate 1 vs Gate 2) nằm ở `custom/templates/shared/gate-workflow.md` § "ingest-data Task Type". File này chỉ mô tả **cách làm** của Gate 1: fetch nguồn → phân loại → soạn draft.
+
+---
+
+## 1. Input được hỗ trợ
+
+| Input | Cách xử lý |
+|---|---|
+| Backlog ticket link (`/view/PROJ-N`) hoặc comment (`#comment-N`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "ticket" \| "comment", ... }` |
+| Backlog Document link (`/document/{id}` hoặc `/alias/document/{id}`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "document" \| "document-comment", ... }`. ⚠️ API Document của Nulab còn mới (2026) — nếu lệnh trả lỗi HTTP 404, báo lại cho người dùng, đây là dấu hiệu endpoint cần điều chỉnh, không phải lỗi ở phía bạn. |
+| Backlog Wiki link (`/alias/wiki/{id}`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "wiki", ... }` |
+| Jira ticket/comment link | `ak fetch-links "<url>"` → JSON `{ sourceType: "ticket" \| "comment", ... }` |
+| SharePoint link (`*.sharepoint.com`) | `ak fetch-links "<url>"` → `{ sourceType: "unsupported", reason: "sharepoint-not-configured" }`. **Không có connector** (cần Microsoft Graph API + OAuth, xem PM Workflow doc "Vấn đề 4" — chưa làm POC). Hiển thị `message` trong JSON cho người dùng, và đề nghị: "Paste trực tiếp nội dung comment/tài liệu vào chat, mình sẽ dùng luôn." |
+| Plain text (paste trực tiếp trong chat, hoặc `ak use --manual`) | Dùng nguyên văn `description` từ `.aiflow/context/current.json` — không cần fetch gì thêm. |
+
+Nếu input không khớp bất kỳ dạng nào ở trên (`ak fetch-links` trả lỗi "Not a recognized... URL", exit code 1) → hỏi lại người dùng: link có đúng không, hoặc paste nội dung trực tiếp.
+
+---
+
+## 2. Phân loại — QnA-Log / Meetings-Log / Confirmations-Log
+
+| Log | Khi nào dùng | Nguồn điển hình |
+|---|---|---|
+| `QnA-Log.md` | Trao đổi hỏi-đáp thông thường với khách hàng | Backlog ticket/comment, Jira ticket/comment, SharePoint comment (paste text), text ngắn |
+| `Meetings-Log.md` | Tổng hợp nội dung 1 buổi họp (khách hoặc nội bộ) | Backlog Document, Backlog Wiki, text dài có cấu trúc (attendees/agenda/action items) |
+| `Confirmations-Log.md` | Mốc khách hàng **CHỐT chính thức** một spec/thay đổi | Bất kỳ nguồn nào, miễn nội dung là 1 xác nhận dứt điểm |
+
+**Heuristic gợi ý** (không phải luật cứng):
+- Nội dung có "họp", "meeting", "kickoff", "sprint review", danh sách người tham dự → nghiêng về **Meetings-Log**.
+- Nội dung có "confirm", "chốt", "OK approved", "đồng ý chính thức", đi kèm 1 quyết định rõ ràng, dứt điểm → nghiêng về **Confirmations-Log**.
+- Còn lại (hỏi/đáp, feedback, trao đổi qua lại chưa dứt điểm) → **QnA-Log**.
+
+> ⚠️ **Quy tắc phân biệt "confirm chính thức" vs "trao đổi thường" CHƯA được PM chốt** (xem `PM Workflow_v1.0.md` § "Vấn đề còn mở" #1). Khi không chắc content nào — **luôn hỏi lại người dùng** để chọn log đích, không tự quyết định âm thầm. Một khi PM ra quy tắc rõ ràng, cập nhật heuristic ở đây.
+
+---
+
+## 3. Template từng file (dùng đúng, không tự đổi cấu trúc)
+
+Cả 3 file nằm trong `AK-Docs/01.QnA/` (giữ nguyên tên thư mục hiện có — **không** đổi thành `01.Communications/` như một phương án còn đang chờ PM chốt trong `PM Workflow_v1.0.md`; nếu PM sau này quyết định đổi tên thư mục, đó là một task migration riêng).
+
+Nếu file đích **chưa tồn tại**, tạo file mới với đúng header dưới đây rồi mới append entry.
+
+### 3.1 `QnA-Log.md` (file có sẵn — mở rộng thêm cột `Nguồn`)
+
+Header hiện tại của file có thể chỉ có 5 cột (`Date | Asked By | Question | Answer | Status`). Nếu vậy, **thêm cột `Nguồn` vào cuối** (sửa header + backfill các dòng cũ bằng `—`) rồi mới append dòng mới — để mọi entry từ giờ đều trace được nguồn gốc (yêu cầu traceability, xem PM Workflow doc § "Vấn đề 6"):
+
+```markdown
+| Date | Asked By | Question | Answer | Status | Nguồn |
+|---|---|---|---|---|---|
+| 2026-08-04 | Khách hàng ABC | <tóm tắt câu hỏi> | <tóm tắt câu trả lời, hoặc "—" nếu chưa có> | Pending / Answered | [<mô tả ngắn>](<url hoặc "pasted text">) |
+```
+
+### 3.2 `Meetings-Log.md` (file mới — tạo nếu chưa có)
+
+```markdown
+# Meetings Log
+
+> Meeting minutes với khách hàng hoặc nội bộ — tổng hợp bởi Comtor/BrSE, PM approve tại nguồn trước khi ingest vào đây (xem Flow A trong PM Workflow_v1.0.md).
+
+---
+
+## [YYYY-MM-DD] <Tiêu đề buổi họp>
+
+| Trường | Giá trị |
+|---|---|
+| **Nguồn** | [<mô tả ngắn>](<url Backlog Document/Wiki, hoặc "pasted text">) |
+| **functionId** | <functionId, hoặc `general` nếu không gắn riêng 1 feature> |
+| **Người tổng hợp** | <Comtor/BrSE — tên người chạy lệnh ingest> |
+| **Người approve tại nguồn** | PM — <ngày approve, nếu biết; nếu không biết, hỏi người dùng> |
+
+**Tóm tắt nội dung:**
+<nội dung — giữ đủ ý, không rút gọn quá mức>
+
+**Action items:**
+- [ ] <action item 1, nếu có>
+
+---
+```
+
+Mỗi lần ingest thêm 1 buổi họp mới → append 1 block `## [YYYY-MM-DD] ...` mới vào cuối file (chronological).
+
+### 3.3 `Confirmations-Log.md` (file mới — tạo nếu chưa có)
+
+```markdown
+# Confirmations Log
+
+> Mốc khách hàng CHỐT chính thức — trích từ Meeting Minutes (Backlog) hoặc comment "OK confirm" (SharePoint/Backlog).
+> ⚠️ Quy tắc phân biệt "confirm chính thức" vs "trao đổi thường" CHƯA được PM chốt (xem PM Workflow_v1.0.md § "Vấn đề còn mở" #1) — khi chưa rõ, hỏi lại người ingest trước khi ghi vào đây.
+
+| Date | Nội dung chốt | functionId | Nguồn |
+|---|---|---|---|
+| 2026-08-04 | <mô tả ngắn mốc chốt> | <functionId hoặc general> | [<mô tả ngắn>](<url hoặc "pasted text">) |
+```
+
+---
+
+## 4. Soạn draft — hiển thị đầy đủ, không tóm tắt
+
+Sau khi fetch + phân loại, soạn đúng 1 entry theo template tương ứng ở mục 3, rồi hiển thị **nguyên văn** entry đó cho người dùng (không tóm tắt, không giấu bớt nội dung) kèm footer theo mẫu trong `gate-workflow.md` § "ingest-data" Gate 1 bước 5.
+
+**Không tự ghi file, không tự tạo branch** ở bước này — chỉ hiển thị draft trong hội thoại. Việc ghi file + branch + MR chỉ chạy ở Gate 2, sau khi người dùng gõ **APPROVED**.
+
+Nếu người dùng yêu cầu sửa (thêm/bớt ý, đổi log đích, sửa functionId...) → cập nhật lại draft, hiển thị lại toàn bộ, chờ APPROVED lại — lặp cho tới khi được duyệt.

package/custom/skills/read-study-requirement/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: read-study-requirement
-description: Gate 1 — AI reads ticket from Backlog/Jira + reads source code, then uses collaborative Q&A and solution proposal. Adds impact analysis and effort estimate. Outputs requirement.md for DEV to approve.
-keywords: ticket, requirement, study, read, context, backlog, jira, analyze, understand, solution, estimate
+description: Gate 1 — AI reads ticket from Backlog/Jira + reads source code, then uses collaborative Q&A and solution proposal. Adds impact analysis and effort estimate. Outputs requirement.md for DEV to approve. Requires System Requirement (bridged from UC Spec via `create-system-requirement`) to exist and match the current UC Spec version — cancels and hands off otherwise.
+keywords: ticket, requirement, study, read, context, backlog, jira, analyze, understand, solution, estimate, system requirement, uc spec
 ---
 
 # Analyze Requirement — Gate 1
@@ -12,6 +12,19 @@ keywords: ticket, requirement, study, read, context, backlog, jira, analyze, und
 
 ---
 
+## Step 0: System Requirement Gate (Pre-flight, blocking — runs before Mode Selection)
+
+Before reading the ticket in depth, verify the bridge document from UC Spec exists — this applies to **every mode**, including Fast Track (it's a 2-file header check, not a heavy investigation):
+
+1. Resolve `functionId` from `.aiflow/context/current.json` (or ask DEV once if absent).
+2. Locate the current UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (highest non-archived version).
+   - **Not found** → notify DEV: `⚠️ No UC Spec found for [functionId] — Gate 1 requires a BA-signed-off UC Spec before coding starts.` STOP.
+3. Check `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v*.md`:
+   - **Missing, or its `UC-Spec-Version` header doesn't match the UC Spec found in step 2** → **CANCEL Gate 1 immediately.** `create-system-requirement` is a separate task type (2 gates), not an inline sub-skill — tell DEV: `⏸️ Gate 1 cancelled — run "ak use" and pick "📐 Create System Requirement" for [functionId] first, complete both its gates to APPROVED, then resume this ticket.`
+   - **Exists and matches** → continue below. Keep this file's path — Step 1 must read it as mandatory input.
+
+---
+
 ## Mode Selection
 
 Check `mode` in `.aiflow/context/current.json` before starting:
@@ -43,6 +56,7 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
    - Uncommitted changes detected → SKIP pull and notify DEV: `⚠️ Uncommitted changes detected — skipping git pull. Analysing local state.`
    - `git pull --ff-only` fails (branch diverged from remote) → notify DEV: `⚠️ Local branch diverged from remote — skipping pull. Resolve manually before next ticket.` Then continue with local state.
 1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
+1b. Read `System-Requirement_v{N}.md` for this functionId (confirmed to exist by Step 0) — the authoritative WHAT. Reference its item IDs (`FR-*`, `VR-*`, `ER-*`) instead of restating them.
 2. Identify **directly affected files** from ticket text and file names only.
    DO NOT trace data flow or read unrelated source files.
 3. Q&A: Ask at most **ONE** question if there is a blocking ambiguity.
@@ -93,6 +107,7 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
    - `git pull --ff-only` fails because the branch has diverged → notify DEV: `⚠️ Local branch diverged from remote — skipping pull. Resolve manually before next ticket.` Continue with local state.
    - Repo has no remote tracking branch (detached HEAD or local-only branch) → skip silently and proceed.
 1. Read `.aiflow/context/current.json` — ticket info from Backlog/Jira
+1b. Read `System-Requirement_v{N}.md` for this functionId (confirmed to exist and in-sync by Step 0) — this is the authoritative WHAT for the whole functionId. Reference its item IDs (`FR-*`, `NFR-*`, `VR-*`, `ER-*`) in your analysis instead of re-deriving requirements it already covers.
 2. **Supplementary Context:** If `current.json` has a `supplementaryContext[]` array, read each item and integrate it as supporting context for your analysis. Items may be:
    - `[ticket]` — linked tickets (related features, dependencies, parent tickets)
    - `[comment]` — specific comments from PM/QA/stakeholders
@@ -237,6 +252,18 @@ After the developer confirms the design direction (Step 2), run full impact anal
 
 ---
 
+### Step 3.5: Reconcile with System Requirement
+
+Compare this ticket's confirmed scope (Steps 1–3) against `System-Requirement_v{N}.md` (read in Step 1):
+
+- Scope already covered by an existing item → reference its ID (e.g. `FR-03`, `ER-02`) in Section 1 of the requirement doc below. Do not restate it.
+- Investigation surfaces a case, rule, or exception the UC Spec supports but System Requirement missed → **propose** an addition: show DEV the exact diff (which section, new row) before writing anything.
+  - DEV confirms → append to `System-Requirement_v{N}.md` (same version — this does **not** bump `System-Requirement-Version`) + add a `Change Log` row citing this ticket.
+  - DEV declines/unsure → leave System Requirement untouched; note the discrepancy in this ticket's own requirement doc (Section 1, Facts/Assumptions/Gaps) instead.
+- Scope doesn't trace to System Requirement **or** UC Spec at all → this is the fabrication risk proposal #7 targets. STOP and ask DEV: is this actually in scope for this functionId, or does the UC Spec need a BA update first? Do not proceed on a guess.
+
+---
+
 ### Step 4: Write Requirement Document
 
 Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
@@ -432,11 +459,17 @@ Please review the requirement document.
 | Effort estimate | This skill |
 | requirement.md template & output | This skill |
 | Gate 1 APPROVED gate | This skill |
+| System Requirement creation/versioning/sync | `create-system-requirement` task type (separate, own 2 gates) |
+| Mid-ticket addition proposal (Step 3.5 triggers it) | `create-system-requirement` owns the write contract (its Step 8) |
 
 ---
 
 ## Mandatory Rules
 
+- ✅ **MUST** verify System Requirement exists and matches the current UC Spec version (Step 0) before proceeding — cancel Gate 1 and hand off to the `create-system-requirement` task type otherwise.
+- ✅ **MUST** read System Requirement as mandatory input (Step 1) — not optional context.
+- ❌ **DO NOT** restate content already covered in System Requirement — reference its item ID instead.
+- ❌ **DO NOT** silently accept ticket scope that doesn't trace to System Requirement or UC Spec (Step 3.5) — stop and ask instead of guessing.
 - ❌ **DO NOT** invoke `superpowers:brainstorming` — its terminal state calls `writing-plans` and bypasses Gate 1 approval
 - ❌ **DO NOT** invoke `superpowers:writing-plans` — that belongs to Gate 2 (`generate-spec` skill)
 - ❌ **DO NOT** proceed past Step 2 if design is not confirmed by developer