Tài liệu BA-kit.

Harden state variant generation and anti-hallucination bans in ba-stitch-sync

Replace generate_screen_from_text with generate_variants (REFINE + TEXT_CONTENT) for state variants. Add 8 anti-hallucination bans (brand, logo, buttons, links, styling, pre-filled values, fields, translation). Remove state descriptions from base prompts to prevent figaro_agent shortcut. Fix generate_variants response parsing path.

Add cross-platform python3 bootstrap for Windows

Fix BA-kit stop hooks on Windows Git Bash where python3 resolves to non-functional Microsoft Store stub. Three-layer defense: install.sh bootstrap_python3() creates ~/bin/python3 wrapper, install scripts detect real python3, hooks resolve Python via python3/python fallback.

Bump vitest to 4.1.8 and playwright to 1.55.1 (CVE fixes)

Fix CVE-2026-47429 (CRITICAL 9.8) in vitest 3.1.4 → 4.1.8, CVE-2025-59288 (HIGH) in playwright 1.52.0 → 1.55.1. SkillSpector re-scan: DO NOT INSTALL→SAFE. 49/49 unit tests pass.

Fix pre-tool-use hook in Claude Code and CodeX installers

Update pre-tool-use hook in both install-claude-code-ba-kit.sh and install-codex-ba-kit.sh. Fix guardrail hook behavior for tool-use events.

Prevent context thrashing in ba-content-audit with output-limiting, on-disk indexing, and module batching

Three-level context fix: L1 output-limiting reads (frontmatter offset=0 limit=40, TOC-first 80 lines), L2 incremental writes per file, L3 on-disk indexing via Bash for cross-reference queries. Module batching: ≤60 files single-agent, larger multi-agent. Context reduction ~97% (3.2MB → ~200K for 4 modules).

Add screen state variant generation to ba-stitch-sync

Extract all documented screen states (error, empty, loading, success) with ASCII wireframes from message list backbone. Generate state variants with state-specific prompts. New state prompt sanitizer gate. Cross-state consistency check. stitch-screen-map.json extended schema with {default, states: {state_name: {...}}}. Use generate_variants for structural identity between state variants and base screen.

Harden stitch-sync prompt building against Stitch hallucination

Per-zone negative space markers for all 6 shell zones. Field table priority rule: field table defines widget STRUCTURE, wireframe defines LAYOUT POSITIONS. Zone coverage gate (Check 5) verifies all 6 zones declared. Exact placeholder data directive with 'do NOT invent' instruction. Per-zone ban table: 7 zones × explicit ban lists + 7 common Stitch invention patterns.

Add ba-content-audit: cross-artifact content audit skill

New read-only skill for cross-artifact format and cross-reference consistency audit. Scans all BA-kit lifecycle artifacts (intake → backbone → modules → compiled). Reports frontmatter compliance, mandatory section presence, cross-reference integrity. Supports first-audit and re-audit with finding tracking (NEW/persistent/resolved). Content-hash finding IDs for re-audit comparison.

Add ba-stitch-sync: Stitch MCP design sync command

New skill for downstream BA-kit screen canon → Stitch MCP design sync. Full workflow: preflight gates → design system bootstrap → screen generation → cross-screen audit. Step 0.3a resolves Stitch projectId (list_projects/create_project). Device type respects --device flag instead of hardcoded DESKTOP. New behavior shard at core/behavior/stitch-sync.md.

Add UI library gate enforcement + interactive prompt + DESIGN.md Section 10

Hard enforcement for gate 5.1a: DESIGN.md template now includes Section 10 with TBD defaults, init-control-library CLI parses and blocks if unset, backbone supports dual-path (single-run interactive AskUserQuestion or two-run defer).

Add UI library selection gate between DESIGN.md and control-type-library

Split backbone Step 5: DESIGN.md now created first (Step 5.1), then backbone stops for user to pick UI library (Gate 5.1a). control-type-library deferred to Step 5.2 on next backbone run only after library confirmed. Prevents wrong baseline from premature generation.

Backbone index validator coverage and path resolution

Fix validator hard fail on Source IDs Not Indexed. Add format-sibling detection (FR-1 vs FR-01). Per-section ID extraction replaces global ID list. Separate source-repo and project-repo path resolution across all CLI commands.

Control Type Library + behaviour guardrails

Add Control Type Library to backbone with baseline pruning flow (library-aware). 6 new guardrail scripts: control-type compliance, message placement, CR coverage, terminology consistency, freshness, and postwrite hooks. Wire guardrails into all installers.

Update README layout

Refine README visual hierarchy: move BA-kit description below badges, remove star/fork counters, fix badge formatting for consistent rendering.

Update README badges and description

Add GitHub badge for bakit-org/bakit. Move BA-kit description below centered badge header. Restructure README for cleaner first impression.

Resolve partial SRS compile receipt source paths

Fix check-partial-srs-compile-receipt.py: resolve included file paths relative to module root. Preserve all existing receipt validation checks.

Add check-screen-behaviour.py to Codex installer

Add check-screen-behaviour.py to CodeX installer GUARDRAIL_SCRIPTS array. Fix script count 10 → 14. Ensures parity across all 3 runtimes.

Screen behaviour rules — business language guardrail + QC profiles

Enforce business-language Behaviour Rules in screen canon with 4-layer guard: template patterns, step gate, 230-line guardrail validator detecting API paths/HTTP methods/framework calls, and QC KA #5.5 scoring. Block technical language like POST /api/auth — require 'mở SCR-LRN-12 (Dashboard)'.

install.sh Antigravity deployment + CWD-aware CLI paths

Auto-detect Antigravity via ~/.gemini/antigravity/, ~/.gemini/, or agy CLI. Copy skills/rules/agents/templates/core to ~/.gemini/antigravity/. Call install-antigravity-ba-kit.sh for guardrails + Knowledge Item. Add CWD-aware path resolution: walk CWD for plans/ before falling back to registered repo.

Compile hardening + CLI CWD awareness + index-disk verification

Hardening compile-srs.py: strip YAML frontmatter, auto-fill template placeholders, detect remaining unfilled patterns, hard-block if index references non-existent files. Fix validate-index-quality.py double-dir bug. Extend guardrail_common.py to load contracts from ~/.claude/core/. Add placeholder detection to qc-export.py.

Hard index validation mandate + DESIGN.md system-level ownership + collab subdir cleanup

Add 3-layer index validation enforcement (step-file inline, PostToolUse hook, downstream guardrail). Move DESIGN.md and shared-shell-contract from SRS outputs to backbone outputs. Two-tier change authority: L1 Portal (Lead BA only), L2 Nav Item (Module BA with confirmation). Clean up ba-collab subdir pre-creation.

Global-first paths in SKILL.md + collab incremental module gating

All SKILL.md and step files reference ~/.claude/ paths as primary, repo root as fallback. ba-collab now creates only COLLAB-HOME.md on setup — module directories created incrementally on 'tôi nhận module X'. Add missing ba-qc-export-bridge-note.md to install docs.

Core symlink for SKILL.md relative path resolution

Add symlink ~/.claude/core → ba-kit during install so repo-relative paths in SKILL.md resolve correctly after installation. Add cleanup_previous_install to remove stale symlink on reinstall.

Compile script HTML + token budget recalibration

Recalibrate all token budget baselines across machine contract, behavior shards, bundles, and runtime policy entries. Realign compile receipt fixture with current SRS output schema including cross_function counters and template_compliance fields.

Context budget bootstrap tool, Glob guard, and CodeX hooks

Add context-budget-bootstrap.py for legacy project index generation, extend PreToolUse/PostToolUse matchers to Glob, add CodeX context guard hooks, session budget tracking, fix cached_token_waste calculation to use violation sequence distance, and add index preflight advisory to collab/do workflows.

Context guard token spending fix

Fix has_safe_flags: offset alone no longer considered safe for large files (>=10kB). Fix re-read detection to track after check (avoid self-match on first read). Remove unused SAFE_FLAGS constant.

Context budget enforcement hooks for Claude Code

Add 3-layer context budget enforcement: PreToolUse blocks Reads >10kB without offset+limit, PostToolUse warns on outputs >5kB, Stop audits total context waste. Add CLAUDE.md hard rules for tool selection, output limiting, and re-read prevention.

QC export output grouped by module with flattened UC structure

Restructure qc-export output: UC files now under {module}/UC-{slug}.md instead of UC-{slug}/UC-{slug}.md, screens in UC-{slug}-screens/, usecase-list.md inside module folder. Add stale UC file cleanup between exports.

Write-scope guard hardening for qc-export

Add _guard_path() helper to validate all qc-export output paths (UC markdown, PNGs, common-rules, message-list, usecase-list, summary JSON) through write-scope guard individually, not just top-level output_root.

Node precheck added to CodeX installer

Add command -v node guard to CodeX installer before running inline Node.js scripts, matching the python3 check pattern already in Claude Code installer. Prevents cryptic failures on systems without Node.

Guardrail scripts wired into production across all runtimes

Add guardrail, check-token-budget, and validate-index subcommands to ba-kit CLI. Wire guardrail dispatch into frd, stories, srs, and package steps. Add Claude Code installer with 7 guardrail scripts + 3 hook generators. Migrate raw python3 calls to ba-kit CLI across all step files.

BA-to-QC export bridge command

New ba-kit qc-export CLI command for one-way BA-to-QC artifact handoff: reads UC canon, screens, stories, and registries, then writes QC-kit-compatible per-UC markdown under 04_compiled/qc-kit/ with write-scope guardrails and 20/20 tests.

Cross-function impact declarations across BA-kit

Add Cross-Function Impact section to UC template with within-module and across-module dependency tables, update QC UC Review KA #8 scoring, inline cross-function data into SRS assembly, give ba-impact full propagation awareness, and wire cross-function data into the QC export bridge.

BA-facing output speaks more naturally in Vietnamese

Humanize BA-kit output with a Vietnamese wording layer: friendlier labels, stakeholder-ready SRS summaries, localized status/package wording, docs updates, and refreshed golden strings.

Figma Make per-UC incremental prompt and change-log artifacts

Add per-UC Figma Make paste-ready prompt files and versioned change logs under tool-lanes/figma-make/usecases/, with shared baseline reuse, validator guardrails, and lane docs. BA canon untouched.

BA-start adopts modular artifact source sets

Move BA-start/SRS authoring from legacy index and canon files to explicit module source sets: userstories/, usecases/, ascii-screen/, srs/, compile receipts, source-set validators, doctor-srs checks, and greenfield fixtures.

ASCII wireframes mandatory in screen canon

Require current ASCII wireframe sections in every UI-backed screen canon file. Missing ASCII becomes blocking schema error. Remove legacy wireframe-input, wireframe-map, and wireframe-state templates. Compile ASCII through srs path. Wireframes command becomes read-only compatibility validation.

QC review now runs after SRS, inside each module

Move QC review to the point where a module SRS is already done, read the module's own canon files first, save the report right inside that module, and lock the new timing with parity fixtures.

Shared rule/message guardrails and artifact folder layout

Reorganize BA artifacts into dedicated SRS, wireframe, Figma Make and Figma sync folders; add Common Rules, Message List, Shared Rule Message Index and validator guardrails for CR/MSG references.

SRS canon-first, ASCII wireframes, and Figma sync guardrails

Refactor SRS sang canon-first: screen/use case canon, SRS index, compile receipt, shared shell contracts, hard guardrail scripts, ba-figma-sync downstream-only và guide từng bước cho người dùng Paid.

Figma Make wireframe guardrails

Thêm Step 9 tool-lane artifacts cho Figma Make: screen field contracts machine-facing, shared prompt/rules/component templates, tool-lane state, prototype conformance checklist/report, validator scripts và token-budget/context updates để wireframe handoff có guardrails rõ hơn.

Reverse-web — Playwright crawl engine + synthesis skill + 57 tests

Thêm skill reverse-web: Playwright BFS crawl engine với 7 code-enforced guardrails (G1–G7), passive network capture, DOM extraction, incremental sitemap, --continue mode, evidence-index.md agent-facing index. SKILL.md hướng dẫn Claude điền intake-form-template.md 8 phần tiếng Việt. 57 tests (49 unit + 8 integration).

QC UC Review — platform-parameterized quality gate engine

Thêm skill /qc-review: 38 validation checks trên UC artifacts với 3 platform profiles (mobile/web/API), 3 quality gates tự động (pre_srs, pre_wireframe, pre_package) và auto-remediation loop max 2 retries.

Brainstorm skill — pre-intake idea clarification

Thêm skill /brainstorm như pre-intake feeder: 7-section deep interview để mở rộng ý tưởng thô thành tài liệu có cấu trúc trước khi vào lifecycle. Kèm NLP routing trong ba-do và hint trong ba-next.

Reverse-to-document mode

Thêm lifecycle code-first để BA extract requirements ngược từ source artifact có sẵn, bỏ qua forward design/wireframe gate. Kèm 6 guardrail modules, parity fixtures f21–f26 và Antigravity certifications.

Runtime guardrails và index validation

Thêm guardrail preflight/audit, output modes thấp-token và producer-side validator để index-first execution fail closed khi index stale hoặc mâu thuẫn.

Runtime token shards

Tách behavior runtime thành command-scoped shards, thêm Python token-budget checker đa nền tảng.

Navigation schema guardrails

Thêm validator và workflow gate để Screen Contract Plus không tự suy luận hoặc đổi active menu ngoài Navigation Schema đã duyệt trong DESIGN.md.

Token optimization và compact internal artifacts

Thêm source chunk index, backbone/stories/SRS indexes, artifact profiles và context-budget để agent đọc targeted thay vì nạp toàn bộ artifact lớn.

Community-first site and split public docs

Reposition site sang Community-first, tách public docs thành Community và Paid, đồng thời giữ Terms như boundary page cho private Paid repo.

Pre-backbone options flow

Thêm bước options trước backbone, option pack + comparison và quyết định explicit select/skip khi intake cần nhiều hướng solution.

PlantUML swimlanes và diagram rendering update

Đổi chuẩn swimlane sang PlantUML, giữ Mermaid cho sequence/DFD/ERD và cập nhật HTML packaging để render đúng.

BA-friendly collaboration workflow

Thêm ba-collab, COLLAB-HOME.md, MODULE-HOME.md, review packet và approval gate cho GitHub handoff.

Adaptive memory, activation parity và runtime verification

Thêm project-memory compact/shard, activation contract và parity harness giữa Claude Code, Codex và Antigravity.