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

package/custom/templates/shared/gate-workflow.md

@@ -4,6 +4,7 @@
 > **Do not skip, shorten, or merge Gates.**
 
 > **Task type `gen-doc`** uses a **2-gate flow** (Gate 1 + Gate 2 only). See the gen-doc section below — do NOT run Gates 3/4/5 for gen-doc tasks.
+> **Task type `ingest-data`** also uses a **2-gate flow** — see the ingest-data section below. For PM/BrSE/Comtor ingesting customer communication (Backlog ticket/comment/Document/Wiki link, SharePoint link, or pasted text) into `AK-Docs/01.QnA/`.
 
 You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
 - **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
@@ -40,6 +41,7 @@ Read `.aiflow/context/current.json` → check the `taskType` field:
 | `feature`, `bug-fix`, `refactor`, `investigation`, `documentation` | **[DEV] 5-Gate Development Workflow** (below) |
 | `create-spec` | **[BA] 4-Gate Spec Creation Workflow** (below) |
 | `create-testcase` | **[QA] 4-Gate TestCase Creation Workflow** (below) |
+| `ingest-data` | **[COMTOR] Ingest Data — 2-Gate Flow** (below) |
 
 If `taskType` is missing or unrecognized, default to the DEV workflow and ask ONE clarifying question.
 
@@ -670,3 +672,50 @@ Bugs logged: [N] | Skipped: [N]
 8. Display: `GATE 2 DONE: Document generated at [path]`
 
 **Do NOT wait for extra approval before generating the document or opening the MR — only the explicit branch/MR confirmations above gate this; run the gate 2 approved command immediately after.**
+
+---
+
+## ingest-data Task Type — 2-Gate Flow
+
+> This section applies **only** when `taskType === "ingest-data"`. All other task types use the flows above.
+> **For:** PM · BrSE · Comtor ingesting customer communication into `AK-Docs/01.QnA/` — see `docs/internal/PM Workflow_v1.0.md` Flow B for the full design background.
+> **Input formats accepted:** Backlog ticket/comment link, Backlog Document link, Backlog Wiki link, Jira ticket/comment link, SharePoint link (not yet connected — see Gate 1 Step 2), or plain pasted text.
+
+**INVOKE:** `ingest-data` skill (from `.claude/skills/ingest-data/SKILL.md`) for both gates — it has the full classification rules, draft templates, and per-file format. This section only covers the gate mechanics.
+
+### GATE 1 — Fetch, Classify, Draft (auto-start)
+
+0. **Pre-flight (bắt buộc):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+1. Read `.aiflow/context/current.json` — if the primary input is a URL (Backlog/Jira/SharePoint), it's already there as `taskId`/description; if the input was plain pasted text via `ak use --manual`, it's in `description`.
+2. **Resolve the source** (see `ingest-data` skill for full detail):
+   - Backlog/Jira ticket, comment, Document, or Wiki URL → run `ak fetch-links "<url>"`, parse the JSON.
+   - SharePoint URL → `ak fetch-links` returns `{ sourceType: "unsupported" }` (no connector yet — Microsoft Graph API/OAuth not built). Tell the user to paste the comment/document text directly instead of the link.
+   - Plain text → use as-is, no fetch needed.
+3. **Classify** into `QnA-Log.md` / `Meetings-Log.md` / `Confirmations-Log.md` per the `ingest-data` skill's rules. If ambiguous (especially Confirmations — the rule for "official confirm" vs "regular feedback" is not yet finalized, see PM Workflow doc Vấn đề còn mở #1) — **ask the user**, do not guess silently.
+4. Draft the entry using the exact template for the target log file (skill has all 3 templates) — include the trace fields (`Nguồn`, `functionId`, `Người tổng hợp`, `Người approve tại nguồn`).
+5. Display the draft in full (not summarized) plus this footer:
+   ```
+   ⏸️ INGEST DRAFT READY — cần bạn review trước khi mở MR
+
+   Nguồn: [mô tả ngắn](url hoặc "pasted text")
+   Ghi vào: AK-Docs/01.QnA/[QnA-Log.md | Meetings-Log.md | Confirmations-Log.md]
+
+   → Xem draft đầy đủ ở trên
+   → Gõ APPROVED để tạo branch + MR (Gate 2)
+   → Hoặc yêu cầu sửa trực tiếp draft, AI sẽ cập nhật lại rồi hiển thị lại
+   ```
+6. Loop on edits until the user types **APPROVED** — do not proceed to Gate 2 before that.
+
+> **Telemetry:** Run `ak gate 1 start --ticket [ticket-id]` when starting. Run `ak gate 1 approved --ticket [ticket-id]` when APPROVED is received.
+
+### GATE 2 — Branch + Merge Request (runs immediately after APPROVED)
+
+1. Xác định `functionId`: tag đọc được từ Backlog Document (nếu có) → suy từ input → không suy được thì dùng `general` (theo đúng quy ước `custom/rules/project-conventions.md`, tương tự gen-doc dùng `AD-HOC`).
+2. Kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`). Nếu chưa ở `feature/[functionId]/[ticketId]` → hỏi: "Chưa có branch riêng cho task này. Tạo branch `feature/[functionId]/[ticketId]` từ `main` — đồng ý không?" → đồng ý thì chạy `ak docs branch [functionId] [ticketId] --yes`; từ chối thì tiếp tục trên nhánh hiện tại. ❌ Không tự thêm `--yes` khi chưa thấy xác nhận rõ ràng.
+3. Ghi/append entry đã approve vào đúng file log (tạo file + header template nếu chưa tồn tại).
+4. Soạn title + description cho MR (tóm tắt entry vừa ghi, link nguồn gốc), hiển thị cho người dùng xem trước. Hỏi: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?" → đồng ý thì chạy `ak docs submit --title "..." --description "..." --yes`; từ chối thì dừng, để người dùng tự commit khi sẵn sàng. ❌ Không tự thêm `--yes` khi chưa thấy xác nhận rõ ràng.
+5. Thông báo: MR đã mở, chờ **PM review & merge vào `main`** — đây là bước duyệt cuối cùng, không phải tự merge.
+6. Run: `ak gate 2 approved --ticket [ticket-id]` to close the task.
+7. Display: `GATE 2 DONE: Entry ghi vào AK-Docs/01.QnA/[file] — MR: [url hoặc "tạo thủ công"]`
+
+> **Telemetry:** Run `ak gate 2 start --ticket [ticket-id]` when starting. Run `ak gate 2 approved --ticket [ticket-id]` when Gate 2 completes.

package/docs/common/BA-Specs-Structure.md

@@ -15,6 +15,7 @@
 ├── 00.Requirements/                    # Requirements Gathering
 │   └── F-001_User-Login/
 │       ├── Raw-Requirements_v1.md      # Raw input: ticket, meeting note, email
+│       ├── System-Requirement_v2.md    # Dev-facing bridge doc (create-system-requirement task type)
 │       └── assets/                     # Images, attachments, recordings
 │
 ├── 01.Analysis/                        # Gate 1: Business Analysis
@@ -46,6 +47,7 @@
 | Section folder | `{N}.{Pascal-Case}/` | `00.Requirements/`, `03.UI-Prototypes/` |
 | Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
 | Requirements file | `Raw-Requirements_v{N}.md` | `Raw-Requirements_v1.md` |
+| System Requirement file | `System-Requirement_v{N}.md` | `System-Requirement_v2.md` |
 | Analysis file | `Analysis_v{N}.md` | `Analysis_v2.md` |
 | QnA file | `QnA-Log_v{N}.md` | `QnA-Log_v1.md` |
 | Prototype file | `UI-Prototype_v{N}.html` | `UI-Prototype_v1.html` |
@@ -84,3 +86,4 @@
 - Thông báo cho Dev + Tester sau khi UC Spec sẵn sàng
 - Không xóa file cũ — move vào `_archive/` khi có version mới
 - `02.QnA/` là Q&A nội bộ với stakeholder — khác với `01.QnA/` ngoài dự án (dành cho khách hàng)
+- `System-Requirement_v{N}.md` trong `00.Requirements/` do Dev viết (task type `create-system-requirement`, chạy 1 lần/functionId/UC Spec version), không phải do BA — `N` khớp đúng version của `UC-Spec_v{N}.md` mà nó trace tới, không phải bộ đếm riêng

package/docs/common/CHANGELOG.md

@@ -7,6 +7,32 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.2.0] - 2026-08-04
+
+### Added
+
+- **`create-system-requirement` — new task type, bridging UC Spec (BA) into a Dev-facing System Requirement.** Until now, "System Requirement" only existed as whatever a coding ticket's Gate 1 (`read-study-requirement`) happened to write into its own per-ticket `requirement.md` — no single document traced 1-1 to a UC Spec version, so N tickets under one `functionId` (including bug fixes) left no coherent, BA-reviewable picture of what the system as a whole is required to do. New skill `custom/skills/create-system-requirement/SKILL.md` runs as its own 2-gate task type, scoped to a `functionId` (not a ticket):
+  - **Gate 1 — Investigate UC & Draft:** resolve the current UC Spec version, investigate existing source code/error-handling conventions (same methodology as `read-study-requirement`, including the GitNexus MCP shortcut), translate every Main/Alternative/Exception Flow step and Business Rule into Functional/Non-Functional Requirements, Validation Rules, Exception & Error Handling, and Acceptance Test scenarios (Given/When/Then) — every item carries a traced UC reference, nothing is invented. Q&A loops one question at a time until every Fact/Assumption/Gap is Confirmed; a genuinely unanswerable Gap blocks progress to Gate 2 rather than being guessed.
+  - **Gate 2 — Finalize & Approve:** decide single-file vs. split (default is one file, mirroring the UC Spec 1-1; splits only on measurable signals — business-rule domain fan-out, module/service fan-out, flow-count overload, or a ~400-line size ceiling, always along a semantic seam, never by raw line count; a UC Spec that reads like 2+ bundled independent use cases is escalated back to BA instead of silently split), write `AK-Docs/04.Coding/01.Requirements/[functionId]/System-Requirement_v{N}.md` (`N` pinned to the UC Spec version it was traced against, carried in a mandatory `UC-Spec-Version` header), and wait for `APPROVED`.
+  - Selectable via `ak use`'s "Task type:" prompt ("📐 Create System Requirement") or auto-detected by `aiflow prompt` — added to `scripts/detect.js` (keywords), `scripts/use.js` (both task-type selectors), and `scripts/task.js` (`maxGate = 2`, custom gate labels, alongside `gen-doc`'s existing 2-gate handling).
+- **Coding Gate 1 (`read-study-requirement`) now requires System Requirement to exist and match the current UC Spec version before it can run.** New blocking Step 0: resolves the ticket's `functionId`, locates its current UC Spec, and checks for a `System-Requirement_v*.md` whose `UC-Spec-Version` header matches. Missing or stale → Gate 1 cancels outright and tells DEV to run the new `create-system-requirement` task type first (`⏸️ Gate 1 cancelled — run "ak use" and pick "📐 Create System Requirement" for [functionId] first...`); this check runs even in Fast Track mode (it's a 2-file header check, not a heavy investigation). Root `CLAUDE.md`'s Gate 1 section gained a matching "0. Pre-check (blocking)" line.
+  - Once unblocked, Step 1 now reads the System Requirement as mandatory input (`FR-*`/`NFR-*`/`VR-*`/`ER-*` item IDs are referenced, not restated), and a new **Step 3.5 — Reconcile with System Requirement** requires every ticket's scope to trace to an existing item, a UC-Spec-backed case System Requirement missed (proposed as a diff for DEV to confirm, appended with a Change Log row — never written directly, never bumping `System-Requirement-Version`), or a stop-and-ask when a ticket's scope traces to neither document at all.
+- **Memory recall now has a profile for `create-system-requirement`.** `scripts/hooks/session-start.js`'s `inferWorkflow()` previously had no mapping for this task type (it would fall through to `null` → the generic `gen-doc` default), so memory entries tagged for it would never score the `workflows`-match bonus in `memory-store.js`'s `scoreMemory()`. Added the mapping, plus a guidance row in `docs/common/Memory-Architecture-v1.0.md`'s workflow-profile table (§5.2) — `domain` + `glossary` + `architecture`/`lessons-dev` + related `decisions` — since this task type bridges BA business language and Dev technical convention rather than sitting fully in either camp.
+- **`ingest-data` — new task type for PM/BrSE/Comtor, ingesting customer communication into `AK-Docs/01.QnA/`.** Until now the only way link/text content from Backlog or SharePoint reached `AK-Docs` was a developer manually editing `QnA-Log.md` — no fetch, no classification, no drafted trace fields. New skill `custom/skills/ingest-data/SKILL.md`, wired as a 2-gate task type in `custom/templates/shared/gate-workflow.md`:
+  - **Gate 1 — Fetch, Classify, Draft:** resolves the source (Backlog ticket/comment/Document/Wiki link, Jira ticket/comment link, SharePoint link, or plain pasted text — via `ak fetch-links`, see below), classifies it into `QnA-Log.md` / `Meetings-Log.md` / `Confirmations-Log.md`, and drafts the entry with trace fields (`Nguồn`, `functionId`, `Người tổng hợp`, `Người approve tại nguồn`). When the target log is ambiguous — most notably Confirmations vs. regular feedback, a rule PM has not yet finalized (see `docs/internal/PM Workflow_v1.0.md` "Vấn đề còn mở" #1) — it asks instead of guessing. Displays the full draft (never summarized) and loops on edits until `APPROVED`.
+  - **Gate 2 — Branch + Merge Request:** writes the approved entry to `AK-Docs/01.QnA/{QnA-Log,Meetings-Log,Confirmations-Log}.md` (creating the file with its header template if it doesn't exist yet), then reuses the existing `ak docs branch`/`ak docs submit` (no new Git-writing code) behind the same explicit-confirmation gate every other docs-writing flow uses.
+  - Selectable via `ak use`'s "Task type:" prompt ("📥 Ingest Data" — new `PM` category). Output paths documented in `custom/rules/project-conventions.md` as a new, flat (non-`[functionId]/[ticketId]`) section, since these are project-wide logs, not per-ticket documents.
+  - Deliberately keeps `AK-Docs/01.QnA/` as the folder name rather than renaming to `01.Communications/` per the still-undecided proposal in `docs/internal/PM Workflow_v1.0.md` §1 — avoids a breaking rename on projects already using `01.QnA/QnA-Log.md` (e.g. the `ast-ai-agent` pilot). `docs/common/Docs-Management-Flow.md` §3's scope table now explicitly lists `01.QnA/` alongside `02.BA-Specs/`/`03.Testing/`/`04.Coding/`/`99.Memory/` as requiring the branch+MR flow.
+- **`link-resolver.js` / `ak fetch-links` now fetch Backlog Document and Wiki links, not just ticket/comment — built for `ingest-data`, reusable anywhere.** `classifyLink()` gained a `kind` field (`ticket` | `document` | `wiki` | `unsupported`) and two new URL patterns: Backlog Document permalinks (`/document/{id}`, `/alias/document/{id}#comment-{id}`) and Wiki permalinks (`/alias/wiki/{id}`). New fetchers `fetchBacklogDocument`, `fetchBacklogDocumentComment`, `fetchBacklogWiki` call the same read-scoped `BACKLOG_API_KEY` already used for tickets — no new credentials needed. ⚠️ The Document API (`/api/v2/documents/:id`) is a genuinely new Nulab endpoint (added 2026) and its exact path has **not been verified against a live Backlog space** — expect to adjust it if it 404s. Also added `SHAREPOINT_RE` so a `*.sharepoint.com` URL is recognized and returns a clear `{ sourceType: "unsupported", reason: "sharepoint-not-configured" }` stub (with guidance to paste text instead) rather than the generic "not a recognized URL" error — SharePoint still has no real connector (Microsoft Graph API/OAuth is unbuilt, see `docs/internal/PM Workflow_v1.0.md` "Vấn đề 4").
+  - Auto-resolution of links found inside a ticket description (`ak use`'s `resolveLinks`, capped at 5) is **unchanged in scope** — `scanLinks()` now explicitly filters to `kind === 'ticket'` only, so Document/Wiki/SharePoint links are never auto-fetched en masse, only via an explicit single `ak fetch-links <url>` call.
+- **`ak use` now captures `projectId`/`projectKey` from the loaded Backlog/Jira ticket.** `buildContextFromBacklog`/`buildContextFromJira` in `scripts/use.js` read `issue.projectId` (Backlog) and `fields.project.id`/`fields.project.key` (Jira), falling back to parsing the key out of the ticket ID (`PROJ-33` → `PROJ`) via a new `projectKeyFromIssueKey()` helper. Persisted into `.aiflow/context/current.json` and `.aiflow/state.json` (`current_context_project_id`/`current_context_project_key`), and shown in the `ak use` summary output. This is a read-only, informational addition — no code yet uses it to pick a Backlog/Jira project when creating a new ticket (that remains future work, tracked as "Vấn đề 5.1" in the PM Workflow doc).
+
+### Fixed
+
+- **`ak use`'s "Task type:" selector crashed on every invocation once "📐 Create System Requirement" was added to the list.** `td()` (`scripts/use.js`) looks up `CATEGORY_COLOR[cat]` and calls it as a chalk styling function; the `"Dev"` category used by the Create System Requirement entry had no entry in `CATEGORY_COLOR`, so building the choices array threw `TypeError: CATEGORY_COLOR[cat] is not a function` before the prompt could even render — meaning `ak use <ticket>` and `ak use --manual` were both broken outright. Added `Dev` (and `PM`, for the new `ingest-data` entry) to `CATEGORY_COLOR`.
+
+---
+
 ## [0.1.9] - 2026-08-04
 
 ### Added

package/docs/common/Docs-Management-Flow.md

@@ -38,7 +38,7 @@
 
 | Repo | Nội dung | Áp dụng flow này? |
 |---|---|---|
-| `AK-Docs` | `02.BA-Specs/`, `03.Testing/`, `04.Coding/`, `99.Memory/` — tài liệu riêng của từng dự án | ✅ Bắt buộc |
+| `AK-Docs` | `01.QnA/`, `02.BA-Specs/`, `03.Testing/`, `04.Coding/`, `99.Memory/` — tài liệu riêng của từng dự án | ✅ Bắt buộc |
 | `Shared-Docs` | Template dùng chung mọi dự án | ✅ Áp dụng, nhưng approver cuối có thể là AI Testing Team thay vì PM dự án (giống Flow B của Memory-Architecture) — mỗi dự án tự quyết định khi setup |
 
 Flow này **không áp dụng** cho source code repo (Dev vẫn tạo PR code theo quy trình hiện có ở Gate 5 — `superpowers:requesting-code-review`). Đây là flow riêng cho kho **tài liệu**.

package/docs/common/INDEX.md

@@ -28,6 +28,7 @@
 | `AK-Docs/03.Testing/` folder structure (Tester) | [Testing-Structure.md](./Testing-Structure.md) | Strategies → Testcases → evidence, by Function-ID |
 | `99.Memory/` Project Brain — full design, scoring model, mem-id scheme, role/PM permissions | [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md) | v1.1 — Phase 1 (`draft/list/submit/remove`) is what's implemented today; later phases in this doc are roadmap, not shipped yet |
 | How updates to `AK-Docs`/`Shared-Docs` get reviewed — branch/Merge Request flow, who can merge to `main` | [Docs-Management-Flow.md](./Docs-Management-Flow.md) | Doc's own header says `Trạng thái: Draft — chờ PM review` — flag that when answering, don't present it as final policy |
+| PM/BrSE/Comtor — ingest a Backlog/Jira/SharePoint link or pasted text into `AK-Docs/01.QnA/` | [Project-Structure.md](./Project-Structure.md) (§ `01.QnA/`), `.claude/skills/ingest-data/SKILL.md` | `ak use` → taskType `ingest-data`, 2-gate flow (fetch/classify/draft → branch+MR). SharePoint link fetch is **not connected yet** — falls back to pasted text |
 
 ## Unanswered topics (do not invent — say so and stop here)
 

package/docs/common/Memory-Architecture-v1.0.md

@@ -449,6 +449,7 @@ score = 3 × match(memory nằm trong folder functionId của ticket)
 | coding — Gate 1–5 | `architecture` functionId liên quan + `lessons/dev` + `instincts` + `decisions` technical |
 | create-spec | `domain` + `glossary` + `lessons/ba` + `decisions` business liên quan |
 | create-testcase / execute-test | `lessons/qa` + `domain` + `glossary` |
+| create-system-requirement | `domain` + `glossary` (hiểu đúng thuật ngữ nghiệp vụ từ UC Spec) + `architecture` functionId liên quan + `lessons/dev` (convention lỗi/exception hiện có) + `decisions` liên quan — bridge cả 2 phía BA/Dev, không rơi hẳn về 1 bên |
 | gen-doc / không xác định (mặc định) | `decisions` + `03.Retro` gần nhất + `architecture` functionId liên quan |
 
 **Điều chỉnh lượng theo độ phức tạp task:** ticket chạm nhiều module/mô tả dài → tăng N (10→15); hotfix nhỏ → giảm N (10→5) nhưng ưu tiên tuyệt đối lessons của đúng module; bug fix → bơm thêm toàn bộ lessons trong folder functionId liên quan (`01.Lessons/*/<functionId>/`) kể cả vượt N.

package/docs/common/Project-Structure.md

@@ -38,8 +38,10 @@ AK-Docs/
 │   ├── Function-List.md                # F-ID | Feature | BA | Dev | Tester | Status
 │   └── Team.md                         # Member, role, contact
 │
-├── 01.QnA/                             ← Trao đổi với khách hàng (có comtor)
-│   └── QnA-Log.md                      # 1 file duy nhất cho toàn dự án
+├── 01.QnA/                             ← Trao đổi với khách hàng (có comtor/BrSE)
+│   ├── QnA-Log.md                      # Hỏi-đáp thông thường — 1 file duy nhất cho toàn dự án
+│   ├── Meetings-Log.md                 # Tổng hợp meeting minutes (taskType `ingest-data`) — tạo khi cần
+│   └── Confirmations-Log.md            # Mốc khách CHỐT chính thức (taskType `ingest-data`) — tạo khi cần
 │
 ├── 02.BA-Specs/                        ← BA quản lý
 │   ├── 00.Requirements/                # Requirements Gathering
@@ -102,6 +104,7 @@ Mỗi dự án khi cần tạo tài liệu mới (UC Spec, Test Case, Test Repor
 |---|---|---|
 | PM / BrSE | `00.Project-Overview/` | Đầu dự án + mỗi sprint |
 | BA / PM / Comtor | `01.QnA/QnA-Log.md` | Khi có câu hỏi từ khách hàng |
+| PM / BrSE / Comtor | `01.QnA/Meetings-Log.md`, `Confirmations-Log.md` | Ingest link/text đã approve, qua taskType `ingest-data` (`ak use` → "📥 Ingest Data") |
 | BA | `02.BA-Specs/` | Sau khi Gate 4 APPROVED |
 | Tester | `03.Testing/` | Sau khi Gate 4 APPROVED |
 | Dev | `04.Coding/` | Trước khi tạo Pull Request |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.9",
+  "version": "0.2.0-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/detect.js

@@ -85,6 +85,28 @@ class TaskDetector {
                 antiKeywords: ['code', 'fix', 'bug'],
                 icon: '📝',
                 description: 'Generate document from source code / feature analysis'
+            },
+            'create-system-requirement': {
+                keywords: [
+                    'system requirement', 'system requirements', 'srs',
+                    'bridge uc', 'translate uc', 'uc to system requirement',
+                    'uc spec to system', 'tạo system requirement',
+                    'system requirement từ uc', 'dịch uc spec'
+                ],
+                antiKeywords: ['bug', 'fix'],
+                icon: '📐',
+                description: 'Bridge UC Spec into a Dev-facing System Requirement'
+            },
+            'ingest-data': {
+                keywords: [
+                    'ingest', 'meeting minutes', 'meetings log', 'qna log',
+                    'confirmations log', 'tổng hợp buổi họp', 'biên bản họp',
+                    'tổng hợp feedback khách hàng', 'ingest data', 'ingest link',
+                    'ingest text', 'qna-log', 'meetings-log', 'confirmations-log'
+                ],
+                antiKeywords: ['code', 'bug', 'fix'],
+                icon: '📥',
+                description: 'Ingest a Backlog/Jira/SharePoint link or pasted text into AK-Docs/01.QnA/ logs'
             }
         };
     }

package/scripts/hooks/session-start.js

@@ -188,6 +188,7 @@ function inferWorkflow(ctx) {
     if (t === 'gen-doc') return 'gen-doc';
     if (t === 'testing') return 'create-testcase';
     if (t === 'spec') return 'create-spec';
+    if (t === 'create-system-requirement') return 'create-system-requirement';
     if (!t || ['feature', 'bug-fix', 'refactor', 'documentation', 'investigation'].includes(t)) return 'coding';
     return null;
 }

package/scripts/link-resolver.js

@@ -3,8 +3,14 @@ const https = require('https');
 const chalk = require('chalk');
 
 const BACKLOG_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/view\/([A-Z][A-Z0-9_]+-\d+)(?:#comment-(\d+))?/i;
+// Backlog Document permalink — "Copy link" on a Document page gives /alias/document/{id}.
+// NOTE: Nulab's Document REST API is new (2026) — path unverified against a live space, adjust if it 404s.
+const BACKLOG_DOCUMENT_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/(?:alias\/)?document\/(\d+)(?:#comment-(\d+))?/i;
+// Backlog Wiki permalink — "Copy link" on a Wiki page gives /alias/wiki/{id}.
+const BACKLOG_WIKI_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/alias\/wiki\/(\d+)/i;
 const JIRA_RE = /https?:\/\/([\w.-]+\.atlassian\.net)\/browse\/([A-Z][A-Z0-9_]+-\d+)/i;
 const JIRA_COMMENT_RE = /[?&]focusedCommentId=(\d+)/;
+const SHAREPOINT_RE = /https?:\/\/([\w.-]+\.sharepoint\.com)\/\S*/i;
 const URL_RE = /https?:\/\/[^\s\)\]"<>]+/g;
 
 const MAX_AUTO_LINKS = 5;
@@ -13,25 +19,43 @@ function classifyLink(url) {
   const bm = url.match(BACKLOG_RE);
   if (bm) {
     const [, domain, ticketId, commentId] = bm;
-    return { adapter: 'backlog', domain, ticketId, commentId: commentId || null, isComment: !!commentId };
+    return { adapter: 'backlog', kind: 'ticket', domain, ticketId, commentId: commentId || null, isComment: !!commentId };
+  }
+  const dm = url.match(BACKLOG_DOCUMENT_RE);
+  if (dm) {
+    const [, domain, documentId, commentId] = dm;
+    return { adapter: 'backlog', kind: 'document', domain, documentId, commentId: commentId || null, isComment: !!commentId };
+  }
+  const wm = url.match(BACKLOG_WIKI_RE);
+  if (wm) {
+    const [, domain, wikiId] = wm;
+    return { adapter: 'backlog', kind: 'wiki', domain, wikiId };
   }
   const jm = url.match(JIRA_RE);
   if (jm) {
     const [, domain, ticketId] = jm;
     const cm = url.match(JIRA_COMMENT_RE);
     const commentId = cm ? cm[1] : null;
-    return { adapter: 'jira', domain, ticketId, commentId, isComment: !!commentId };
+    return { adapter: 'jira', kind: 'ticket', domain, ticketId, commentId, isComment: !!commentId };
+  }
+  const sm = url.match(SHAREPOINT_RE);
+  if (sm) {
+    const [, domain] = sm;
+    return { adapter: 'sharepoint', kind: 'unsupported', domain };
   }
   return null;
 }
 
+// Auto-resolve (from a ticket description, capped at MAX_AUTO_LINKS) only ever
+// followed ticket/comment links. Document/Wiki/SharePoint are explicit, single-URL
+// lookups only (`ak fetch-links <url>`) — never auto-fetched en masse.
 function scanLinks(text) {
   const found = [];
   let m;
   URL_RE.lastIndex = 0;
   while ((m = URL_RE.exec(text)) !== null) {
     const classified = classifyLink(m[0]);
-    if (classified) found.push({ url: m[0], ...classified });
+    if (classified && classified.kind === 'ticket') found.push({ url: m[0], ...classified });
   }
   return found;
 }
@@ -83,6 +107,47 @@ async function fetchBacklogComment(domain, apiKey, ticketId, commentId) {
   };
 }
 
+async function fetchBacklogDocument(domain, apiKey, documentId) {
+  const doc = await httpsGet(`https://${domain}/api/v2/documents/${documentId}?apiKey=${apiKey}`);
+  return {
+    sourceType: 'document',
+    sourceUrl: `https://${domain}/document/${documentId}`,
+    documentId: String(documentId),
+    title: doc.title || doc.name || '',
+    tag: (doc.tags || []).map(t => t.name).join(', '),
+    content: (doc.plainText || doc.content || '').substring(0, 4000),
+  };
+}
+
+async function fetchBacklogDocumentComment(domain, apiKey, documentId, commentId) {
+  const comments = await httpsGet(
+    `https://${domain}/api/v2/documents/${documentId}/comments?apiKey=${apiKey}&count=100&order=asc`
+  );
+  const comment = (comments || []).find(c => String(c.id) === String(commentId));
+  if (!comment) throw new Error(`Comment ${commentId} not found in document ${documentId}`);
+  const date = comment.created ? new Date(comment.created).toLocaleDateString('vi-VN') : '';
+  return {
+    sourceType: 'document-comment',
+    sourceUrl: `https://${domain}/document/${documentId}#comment-${commentId}`,
+    documentId: String(documentId),
+    commentId: String(commentId),
+    author: comment.createdUser?.name || 'Unknown',
+    date,
+    content: (comment.content || '').substring(0, 2000),
+  };
+}
+
+async function fetchBacklogWiki(domain, apiKey, wikiId) {
+  const wiki = await httpsGet(`https://${domain}/api/v2/wikis/${wikiId}?apiKey=${apiKey}`);
+  return {
+    sourceType: 'wiki',
+    sourceUrl: `https://${domain}/alias/wiki/${wikiId}`,
+    wikiId: String(wikiId),
+    title: wiki.name || '',
+    content: (wiki.content || '').substring(0, 4000),
+  };
+}
+
 function jiraAuth(email, token) {
   return `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`;
 }
@@ -126,17 +191,41 @@ async function fetchJiraComment(domain, email, token, ticketId, commentId) {
   };
 }
 
+function linkDedupeKey(classified) {
+  if (classified.kind === 'document') return 'doc:' + classified.documentId + (classified.commentId ? '#' + classified.commentId : '');
+  if (classified.kind === 'wiki') return 'wiki:' + classified.wikiId;
+  if (classified.ticketId) return classified.ticketId + (classified.commentId ? '#' + classified.commentId : '');
+  return null;
+}
+
 async function fetchLink(url, credentials = {}, alreadyLoadedIds = []) {
   const classified = classifyLink(url);
   if (!classified) return null;
 
-  const { adapter, domain, ticketId, commentId, isComment } = classified;
-  const dedupeKey = ticketId + (commentId ? '#' + commentId : '');
-  if (alreadyLoadedIds.includes(dedupeKey) || alreadyLoadedIds.includes(ticketId)) return null;
+  const dedupeKey = linkDedupeKey(classified);
+  if (dedupeKey && (alreadyLoadedIds.includes(dedupeKey) || alreadyLoadedIds.includes(classified.ticketId))) return null;
+
+  const { adapter, kind, domain, ticketId, commentId, documentId, wikiId, isComment } = classified;
+
+  if (adapter === 'sharepoint') {
+    return {
+      sourceType: 'unsupported',
+      reason: 'sharepoint-not-configured',
+      sourceUrl: url,
+      message:
+        'SharePoint chưa có connector (cần Microsoft Graph API + OAuth — xem "Vấn đề 4" trong PM Workflow_v1.0.md). ' +
+        'Copy/paste nội dung comment/tài liệu trực tiếp vào chat thay vì dán link.',
+    };
+  }
 
   if (adapter === 'backlog') {
     const apiKey = credentials.BACKLOG_API_KEY;
     if (!apiKey) throw new Error('BACKLOG_API_KEY not set');
+    if (kind === 'document') {
+      if (isComment) return await fetchBacklogDocumentComment(domain, apiKey, documentId, commentId);
+      return await fetchBacklogDocument(domain, apiKey, documentId);
+    }
+    if (kind === 'wiki') return await fetchBacklogWiki(domain, apiKey, wikiId);
     if (isComment) return await fetchBacklogComment(domain, apiKey, ticketId, commentId);
     return await fetchBacklogTicket(domain, apiKey, ticketId);
   }
@@ -176,4 +265,9 @@ async function resolveLinks(description, credentials = {}, alreadyLoadedIds = []
   return results;
 }
 
-module.exports = { classifyLink, scanLinks, fetchBacklogTicket, fetchBacklogComment, fetchJiraTicket, fetchJiraComment, fetchLink, resolveLinks };
+module.exports = {
+  classifyLink, scanLinks, fetchLink, resolveLinks,
+  fetchBacklogTicket, fetchBacklogComment,
+  fetchBacklogDocument, fetchBacklogDocumentComment, fetchBacklogWiki,
+  fetchJiraTicket, fetchJiraComment,
+};

package/scripts/prompt.js

@@ -278,6 +278,150 @@ Write documentation based on approved outline.
 **INVOKE:** \`superpowers:verification-before-completion\`
 Verify docs match code. No outdated examples.
 Display: "GATE 3: Documentation complete. Type APPROVED."
+`,
+    },
+    'create-spec': {
+        header: 'Create UC Spec',
+        instruction: 'Create a complete UC Spec from the raw requirement described below, following the BA 4-Gate workflow.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — [BA] 4-Gate Spec Creation
+
+Follow gates IN ORDER. Do NOT skip or merge gates.
+
+### GATE 1 — Analyze Requirement & Draft Q&A (auto-start)
+**INVOKE:** \`read-study-requirement\` skill, then the \`ba-skills\` sub-skills for analysis
+1. Confirm \`functionId\` and ensure AK-Docs is on branch \`feature/[functionId]/[ticketId]\`
+2. Read the raw requirement (ticket/backlog/file) + related source code
+3. Identify Gaps/Assumptions, draft a Q&A list — classify every item as Fact / Assumption / Gap
+4. Output \`AK-Docs/02.BA-Specs/01.QnA/[functionId]/[ticketId].md\`
+5. Display "GATE 1: Q&A draft ready" → wait for **APPROVED**
+
+### GATE 2 — Update Q&A (loop until all Confirmed)
+Integrate BA/stakeholder answers into the analysis doc. Loop: unresolved items remain → keep asking ONE question at a time. All Confirmed → display "GATE 2: All items Confirmed" → wait for **APPROVED**.
+
+### GATE 3 — UI Prototype (HTML/CSS)
+Only runs after Gate 2 APPROVED.
+1. List UI components from the confirmed requirement
+2. Design and write static HTML/CSS prototype (incl. error-state placeholders)
+3. Save under \`AK-Docs/02.BA-Specs/03.Prototypes/[functionId]/\`
+4. Display "GATE 3: Prototype ready" → wait for **APPROVED**
+
+### GATE 4 — Full UC Spec (wait for APPROVED)
+Only runs after Gate 3 APPROVED.
+1. Fill the UC Spec template: Flow of Events (Main/Alternative/Exception), UI Components, Mermaid activity diagram, Business Rules
+2. Save \`AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v[N].md\`
+3. Retrospect — propose a memory draft for any new business rule/decision learned
+4. Submit AK-Docs via Merge Request (title/description shown, explicit user confirmation) — PM reviews & merges into \`main\`
+5. Display "GATE 4: UC Spec ready" → wait for **APPROVED**
+`,
+    },
+    'create-testcase': {
+        header: 'Create Test Cases',
+        instruction: 'Create a complete, execution-ready Test Case set from the requirement described below, following the QA 4-Gate workflow.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — [QA] 4-Gate TestCase Creation
+
+Follow gates IN ORDER. Do NOT skip or merge gates.
+
+### GATE 1 — Requirement & Risk Analysis (auto-start)
+**INVOKE:** \`read-study-requirement\` skill, then the \`test-skills\` sub-skills
+1. Confirm \`functionId\` and ensure AK-Docs is on branch \`feature/[functionId]/[ticketId]\`
+2. Read the requirement (SRS/Backlog/Jira/UC Spec) and assess risk areas
+3. Clarify with QA/stakeholder if anything is ambiguous — ask ONE question at a time
+4. Output requirement + risk analysis under \`AK-Docs/03.QA-Specs/01.Requirements/[functionId]/[ticketId].md\`
+5. Display "GATE 1: Requirement & risk analysis ready" → wait for **APPROVED**
+
+### GATE 2 — Scenario Building
+Only runs after Gate 1 APPROVED.
+Apply scenario-building skills to derive test scenarios (happy path, edge case, negative). Output scenario list. Display "GATE 2: Scenarios ready" → wait for **APPROVED**.
+
+### GATE 3 — Detailed Test Case Design
+Only runs after Gate 2 APPROVED.
+1. Apply TC design techniques (equivalence partitioning, boundary values, etc.)
+2. Design UI, business, and data test cases
+3. Output draft Test Cases under \`AK-Docs/03.QA-Specs/03.TestCases/[functionId]/\`
+4. Display "GATE 3: Draft Test Cases ready" → wait for **APPROVED**
+
+### GATE 4 — Review & Optimize (wait for APPROVED)
+Only runs after Gate 3 APPROVED.
+1. Review coverage against requirements, optimize/dedupe test cases
+2. Confirm sign-off status, generate the final TestCase artifact
+3. Retrospect — propose a memory draft for any lesson learned
+4. Submit AK-Docs via Merge Request (title/description shown, explicit user confirmation) — PM reviews & merges into \`main\`
+5. Display "GATE 4: Final Test Cases ready" → wait for **APPROVED**
+`,
+    },
+    'create-system-requirement': {
+        header: 'Create System Requirement',
+        instruction: 'Bridge the UC Spec into a Dev-facing System Requirement, following the 2-Gate workflow.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — Create System Requirement (2-Gate Bridge)
+
+> Runs once per \`functionId\` per UC Spec version — NOT per ticket. Blocks coding Gate 1 until APPROVED.
+
+### GATE 1 — Investigate & Draft (auto-start)
+**INVOKE:** \`create-system-requirement\` skill
+1. Resolve \`functionId\`; locate the current UC Spec (\`AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v[N].md\`) — not found → STOP, tell DEV the UC Spec must exist and be BA-signed-off first
+2. Read the full UC Spec, then investigate source code (existing error-handling conventions, data model/API surface)
+3. Translate UC → Functional/Non-Functional Requirements, Business Rules → Validation Rules, Exception & Error Handling, Acceptance Test Scenarios — every item traced to a UC reference, no invented content
+4. Classify every item as Fact / Assumption / Gap; ask ONE question at a time until every Gap is Confirmed
+5. Display "GATE 1: All Gaps Confirmed" → wait for **APPROVED**
+
+### GATE 2 — Finalize & Approve (wait for APPROVED)
+Only runs after Gate 1 APPROVED.
+1. Decide single-file vs split (default: single file mirroring the UC Spec 1-1)
+2. Write \`AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v[N].md\` with the Traceability Matrix + all sections
+3. Display "GATE 2: System Requirement ready" with coverage counts (Open Gaps must be 0) → wait for **APPROVED**
+
+**On APPROVED:** coding Gate 1 (\`read-study-requirement\`) unlocks for this functionId.
+`,
+    },
+    'execute': {
+        header: 'Execute Test Cases',
+        instruction: 'Execute the Test Case file described below against the running app, following the EXECUTE 4-Gate workflow.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — [EXECUTE] Executing Flow
+
+Follow gates IN ORDER. Do NOT skip or merge gates.
+
+### GATE 1 — Pre-flight & Work Plan (auto-start)
+**INVOKE:** \`execute-flow\` skill
+Check: MCP Playwright configured, TC file is parseable, \`ak-test/{repo}/\` scaffold exists, \`BASE_URL\` set, Playwright config exists. Display the work plan (TC file, repo, screen, BASE_URL) → wait for **APPROVED**.
+
+### GATE 2 — Script Sync
+Only runs after Gate 1 APPROVED.
+**INVOKE:** \`script-sync\` skill
+Hash-based TC↔script sync: new TC → generate Playwright test via MCP snapshot/locator (never fabricate selectors); changed TC → update; unchanged → skip; manual/blocked → mark Untest/Pending. Display new/updated/skipped/manual counts → wait for **APPROVED**.
+
+### GATE 3 — Execute & Evidence
+Only runs after Gate 2 APPROVED.
+Run \`BASE_URL=<url> npx playwright test scripts/{screenId}/{ScreenID}.spec.ts\`, organize evidence (screenshots/trace/result.md) into \`ak-test/{repo}/results/{screenId}/run-{N}/\`, auto-draft bug reports for failures, update R1/R2 columns in the TC file. Supports \`RETEST: [TC_ID]\` and \`PR: [url]\`. Display pass/fail/untest/pending counts → wait for **APPROVED** (all Critical/High bugs resolved).
+
+### GATE 4 — Report & Bug Logging (wait for APPROVED)
+Only runs after Gate 3 APPROVED.
+Generate \`testreport.md\` (Go/No-Go: 0 unresolved Critical = Go), log each failed TC as a bug one at a time (ask Y/N/edit before logging). Display decision + bug counts → wait for **APPROVED** to sign off.
+`,
+    },
+    'ingest-data': {
+        header: 'Ingest Data',
+        instruction: 'Ingest the customer communication (Backlog/Jira/SharePoint link or pasted text) described below into AK-Docs logs, following the 2-Gate workflow.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — Ingest Data (2-Gate)
+
+**INVOKE:** \`ingest-data\` skill for both gates — it owns the classification rules, draft templates, and per-file format.
+
+### GATE 1 — Fetch, Classify, Draft (auto-start)
+1. Resolve the source: Backlog/Jira ticket/comment/Document/Wiki URL → \`ak fetch-links "<url>"\`; SharePoint → not yet connected, ask for pasted text instead; plain text → use as-is
+2. Classify into \`QnA-Log.md\` / \`Meetings-Log.md\` / \`Confirmations-Log.md\` — ask the user if ambiguous, never guess silently
+3. Draft the entry using the exact template for the target log file, including trace fields (Nguồn, functionId, Người tổng hợp, Người approve tại nguồn)
+4. Display the full draft → wait for **APPROVED** (or edit requests, looped until approved)
+
+### GATE 2 — Branch + Merge Request (runs immediately after APPROVED)
+1. Resolve \`functionId\` (tag from source → inferred from input → fallback \`general\`)
+2. Ensure AK-Docs is on branch \`feature/[functionId]/[ticketId]\` (create only after explicit confirmation)
+3. Append the approved entry to the target log file (create with header template if missing)
+4. Submit AK-Docs via Merge Request (title/description shown, explicit user confirmation) — PM reviews & merges into \`main\`
+5. Display "GATE 2 DONE: Entry written to AK-Docs/01.QnA/[file]"
 `,
     },
     'gen-doc': {

package/scripts/task.js

@@ -331,21 +331,27 @@ async function nextGate(taskId) {
     const nextGateNum = currentGate + 1;
 
     // Save context snapshot if current task is active
-    let taskType = null;
+    // taskType falls back to task-state.json's own stored value — current.json is removed
+    // at the end of this function, so on Gate 2+ of a multi-step task it's already gone.
+    let taskType = existing.taskType || null;
     if (await fs.pathExists(CURRENT_FILE)) {
         const ctx = await fs.readJson(CURRENT_FILE).catch(() => null);
         if (ctx && ctx.taskId === resolvedId) {
-            taskType = ctx.taskType || null;
+            taskType = ctx.taskType || taskType;
             await fs.writeJson(path.join(taskDir, 'context.json'), ctx, { spaces: 2 });
         }
     }
 
     const isGenDoc = taskType === 'gen-doc';
-    const maxGate = isGenDoc ? 2 : 5;
+    const isSystemRequirement = taskType === 'create-system-requirement';
+    const isIngestData = taskType === 'ingest-data';
+    const isTwoGateDoc = isGenDoc || isSystemRequirement || isIngestData;
+    const maxGate = isTwoGateDoc ? 2 : 5;
 
     const taskState = {
         ...existing,
         taskId:        resolvedId,
+        taskType:      taskType || existing.taskType || null,
         status:        nextGateNum > maxGate ? 'done' : 'pending',
         updatedAt:     now,
         pausedAt:      now,
@@ -365,7 +371,7 @@ async function nextGate(taskId) {
     console.log(chalk.green(`✓ Gate ${currentGate} approved for ${resolvedId}.`));
     console.log(chalk.gray(`  Summary saved to: .aiflow/tasks/${resolvedId}/task-summary.md`));
 
-    if (isGenDoc && currentGate >= maxGate) {
+    if (isTwoGateDoc && currentGate >= maxGate) {
         console.log(chalk.green('\n  ✅ Document workflow complete. Task is done.'));
     } else {
         const nextLabel = gateLabel(nextGateNum, taskType);
@@ -374,7 +380,7 @@ async function nextGate(taskId) {
         console.log(chalk.gray(`    1. Open a NEW chatbox or terminal session.`));
         console.log(chalk.gray(`    2. Run: aiflow task resume ${resolvedId} (to load context).`));
         console.log(chalk.gray(`    3. Type "start" or "continue from the current plan".`));
-        if (!isGenDoc) {
+        if (!isTwoGateDoc) {
             console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in the Gate 2 plan doc (AK-Docs/04.Coding/02.Plans/).`));
             console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
         }
@@ -479,7 +485,7 @@ async function detectCurrentGate(taskId) {
 
 async function generateMarkdownSummary(taskState, taskType = null) {
     taskType = taskType || taskState.taskType || 'feature';
-    const maxGate = taskType === 'testing' ? 4 : (taskType === 'gen-doc' ? 2 : 5);
+    const maxGate = taskType === 'testing' ? 4 : ((taskType === 'gen-doc' || taskType === 'create-system-requirement' || taskType === 'ingest-data') ? 2 : 5);
     const lines = [];
     lines.push(`# Task Summary: ${taskState.taskId}`);
     lines.push(`**Title:** ${taskState.title}`);
@@ -517,6 +523,16 @@ function gateLabel(n, taskType = null) {
         if (n === 2) return 'Generate Document';
         if (n >= 3) return 'Done';
     }
+    if (taskType === 'create-system-requirement') {
+        if (n === 1) return 'Investigate UC & Draft';
+        if (n === 2) return 'Finalize & Approve';
+        if (n >= 3) return 'Done';
+    }
+    if (taskType === 'ingest-data') {
+        if (n === 1) return 'Fetch, Classify, Draft';
+        if (n === 2) return 'Branch + Merge Request';
+        if (n >= 3) return 'Done';
+    }
     const labels = {
         1: 'AI Analyze Requirement',
         2: 'Implementation Plan',