BA-kit dùng project memory để giữ context nghiệp vụ ổn định trên disk, không phụ thuộc vào memory tạm thời của từng runtime. Mục tiêu là giảm drift khi rerun artifact, đổi từ Claud

Project memory và runtime parity

BA-kit dùng project memory để giữ context nghiệp vụ ổn định trên disk, không phụ thuộc vào memory tạm thời của từng runtime. Mục tiêu là giảm drift khi rerun artifact, đổi từ Claude Code sang Codex/Antigravity, hoặc chia việc cho nhiều BA theo module.

Source of truth

Thứ tự nguồn chuẩn vẫn là:

backbone.md
intake.md
downstream artifacts như FRD, stories, SRS
project-memory.md hoặc project-memory/ như support context
PROJECT-HOME.md, COLLAB-HOME.md, MODULE-HOME.md và review packet như dashboard/coordination context

Memory và collaboration dashboard không được thay thế backbone. Nếu memory hoặc COLLAB-HOME.md mâu thuẫn với backbone, agent phải dừng, route qua impact hoặc hỏi lại thay vì tự chọn bên có vẻ đúng hơn.

Compact mode

Compact mode dùng một file:

plans/{slug}-{date}/02_backbone/project-memory.md

File này lưu các điểm có thể tái sử dụng:

canonical vocabulary
approved decisions
accepted assumptions
rejected assumptions
accepted corrections
push-back triggers
runtime handoff notes

Compact mode phù hợp với dự án nhỏ, một module, một owner hoặc khi chưa cần index/shard.

Shard mode

Shard mode thêm cây thư mục:

plans/{slug}-{date}/02_backbone/project-memory/
  index.md
  hot/
    canonical-vocabulary.md
    approved-decisions.md
    pushback-triggers.md
  warm/
    modules/{module_slug}.md
  cold/
  log.md

Vai trò từng lớp:

Lớp	Vai trò
`index.md`	Navigator giới hạn, chỉ định tuyến đến shard liên quan
`hot/`	Vocabulary, decisions và push-back triggers global
`warm/modules/`	Context riêng theo module
`cold/`	Archive cho facts đã supersede
`log.md`	Chronology/audit tùy chọn, không đọc mặc định

Activation levels

BA-kit có 3 mức activation:

Level	Khi dùng
`Base`	Dự án đơn giản, một module hoặc một owner
`Modular`	Có từ 2 module hoặc 2 owner trở lên
`Program`	Có cross-module dependency hoặc nhiều delegation slices

Auto-escalation được phép khi tín hiệu dự án tăng độ phức tạp. Auto-downgrade không được làm im lặng; muốn downgrade phải có refresh rõ ràng.

Nếu runtime tính activation khác với trạng thái đã lưu, BA-kit phải freeze về Base và yêu cầu refresh thay vì tiếp tục theo suy diễn riêng.

Deterministic read scope

Mỗi command có phạm vi đọc cố định. Nguyên tắc chung:

đọc contract trước
đọc đúng step file đang chạy
nếu có shard mode, đọc project-memory/index.md trước
chỉ đọc hot/warm shard được index định tuyến
không đọc cold/ hoặc log.md nếu không có lý do audit/escalation

impact là command duy nhất có thể đọc rộng hơn theo module khi cần phân tích thay đổi cross-artifact.

Governance và file-back

Memory canonical chỉ được cập nhật sau một đường đi có kiểm soát:

phát hiện correction hoặc decision có thể tái sử dụng
chạy impact để xác định phạm vi ảnh hưởng
nhận approval rõ ràng cho rerun/mutation
cập nhật artifact theo đúng owner
file-back vào memory với trace schema

Lead BA sở hữu global/hot memory. Module BA sở hữu warm shard của module mình. Nếu một thay đổi module tạo cross-module dependency, phải escalate lên Lead BA.

Collaboration governance

ba-collab dùng cùng governance envelope với memory:

Module BA có thể cập nhật module-local coordination artifact khi scope an toàn.
Lead BA sở hữu shared decisions, global/hot memory, backbone, DESIGN.md và cross-module dependency.
Review packet có thể ghi touched artifacts, trace IDs và risk, nhưng không được tự biến thành source of truth.
Nếu collaboration intent chạm requirement, actor, shared rule, navigation hoặc module khác, phải route impact trước.
Local sync như fetch/pull/switch branch/merge main vào branch module có thể chạy sau plan ngắn nếu không có local changes hoặc conflict.
Commit, push, tạo PR, request reviewer và merge PR là publish/audit-trail side effect; runtime nào cũng phải hỏi approval rõ trước.
Nếu có local changes chưa commit, runtime phải dừng hoặc hỏi; không tự stash, overwrite hoặc discard.
Nếu merge conflict chạm requirement docs, runtime phải dừng và báo file/section cần BA quyết định.

Runtime parity

Claude Code, Codex và Antigravity có interface khác nhau, nhưng BA-kit yêu cầu cùng behavior envelope:

cùng path resolution và không dùng mtime để đoán
cùng prerequisite và overwrite gate
cùng impact-first behavior cho requirement change
cùng activation threshold
cùng read scope và memory escalation rule
cùng collaboration status, review packet behavior và GitHub approval gate
cùng local Git sync guardrails khi runtime có quyền Git
cùng fail-closed behavior khi thiếu context quan trọng

Runtime adapter chỉ được dịch syntax hoặc prompt style. Adapter không được thay đổi source-of-truth hierarchy, approval gate hoặc stop condition.

Project memory và runtime parity

On this page