alp-code 0.9.0

package/hooks/compact-record.cjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+"use strict";
+
+// Pre/PostCompact hook: appends exactly one line to context/compact-events.jsonl.
+//
+// Zero dependency, on purpose (plan §1): this hook writes a raw-but-filtered envelope, never
+// normalizes it, never reads the journal back, and never touches checkpoint.json or
+// continuity.md. Normalizing into a CompactEventV1 happens later, in TypeScript with Zod, when
+// `alp context status|validate` replays the journal — so this file cannot regress a compiled
+// dependency graph and stays a single `appendFileSync` at its core.
+//
+// Fail-open by design (invariant 7): every branch below either appends one line or does
+// nothing, and nothing here may throw past `main()`. A missing execution ID means this launch
+// did not go through ALP at all — that is not an error, just silence.
+//
+// argv: `compact-record.cjs <pre|post> <claude|codex>`. Both are supplied by the adapter that
+// registers the hook, not read from the payload — trusting the payload's own idea of its phase
+// or runtime would let it pick which bucket it lands in.
+
+const fs = require("node:fs");
+
+const MAX_STDIN_BYTES = 1024 * 1024;
+const MAX_LINE_BYTES = 16 * 1024;
+const MAX_VALUE_LENGTH = 256;
+const EXECUTION_ID_PATTERN = /^exec_[a-zA-Z0-9_-]+$/;
+
+// Mirrors `SOURCE_WHITELIST` in src/context/compact-payload.ts. Kept as a second copy rather
+// than a shared import: this file has no dependency graph to begin with, and the two lists are
+// pinned against the same measured schema (§Runtime capability), so a drift between them would
+// show up immediately as a normalizer that drops a field the hook thought it kept.
+const SOURCE_WHITELIST = {
+  claude: ["session_id", "trigger", "model", "prompt_id", "agent_id", "agent_type"],
+  codex: ["session_id", "trigger", "model", "turn_id", "agent_id", "agent_type"],
+};
+
+function filterSource(runtime, payload) {
+  const whitelist = SOURCE_WHITELIST[runtime] || [];
+  const source = {};
+  if (payload !== null && typeof payload === "object") {
+    for (const key of whitelist) {
+      const value = payload[key];
+      if (typeof value === "string") source[key] = value.slice(0, MAX_VALUE_LENGTH);
+      else if (typeof value === "number" || typeof value === "boolean") source[key] = String(value);
+    }
+  }
+  return source;
+}
+
+/** Reads stdin fully; returns `null` rather than the buffer when it exceeds the 1 MiB cap. */
+function readStdin() {
+  let buffer;
+  try {
+    buffer = fs.readFileSync(0);
+  } catch {
+    return Buffer.alloc(0);
+  }
+  return buffer.length > MAX_STDIN_BYTES ? null : buffer;
+}
+
+function main() {
+  const phase = process.argv[2];
+  const runtime = process.argv[3];
+  if (phase !== "pre" && phase !== "post") return;
+  if (runtime !== "claude" && runtime !== "codex") return;
+
+  // A native launch that never went through `alp` sets none of this — silence, not an error.
+  const executionId = process.env.ALP_DELEGATION_EXECUTION_ID || "";
+  const policyHash = process.env.ALP_POLICY_HASH || "";
+  const journal = process.env.ALP_COMPACT_EVENTS || "";
+  if (!EXECUTION_ID_PATTERN.test(executionId) || policyHash.length === 0 || journal.length === 0) return;
+
+  const buffer = readStdin();
+  let source;
+  if (buffer === null) {
+    source = { parseError: "stdin exceeded 1 MiB" };
+  } else {
+    try {
+      source = filterSource(runtime, JSON.parse(buffer.length === 0 ? "{}" : buffer.toString("utf8")));
+    } catch (error) {
+      // Name the failure only — never the content that failed to parse.
+      source = { parseError: String(error && error.message || "invalid JSON").slice(0, MAX_VALUE_LENGTH) };
+    }
+  }
+
+  const envelope = {
+    v: 1,
+    at: new Date().toISOString(),
+    executionId,
+    policyHash,
+    runtime,
+    phase,
+    source,
+  };
+  const line = `${JSON.stringify(envelope)}\n`;
+  if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) return;
+
+  try {
+    fs.appendFileSync(journal, line, { encoding: "utf8", mode: 0o600, flag: "a" });
+  } catch {
+    // A read-only or missing journal must never fail the compaction it is recording.
+  }
+}
+
+try {
+  main();
+} catch {
+  // Nothing above should throw, but this hook's contract is exit 0 no matter what.
+}
+process.exit(0);

package/hooks/session-boot.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+"use strict";
+
+// SessionStart hook: puts the session context into the model's view before turn 1, and — for
+// every `source` including `"compact"` — the continuity checkpoint right after it.
+//
+// This is the *only* channel ALP identity and continuity travel on, for both runtimes. Claude
+// Code and Codex CLI both turn `additionalContext` into a developer-role message ahead of the
+// first user turn, which is exactly the guarantee an interactive session needs: fully briefed,
+// zero turns spent. Measured 2026-09-04: `SessionStart(source="compact")` is the one point both
+// runtimes agree on for reinjection after native compaction — Claude fires it *during*
+// compaction, Codex at the start of the next turn — so this hook runs unchanged for every
+// `source` rather than branching on it.
+//
+// Two identity sources, in priority order:
+//   1. `ALP_SESSION_CONTEXT` — this execution's own file, written by the runtime adapter.
+//      It carries identity plus the invariants, policy context and workspace grant that
+//      only ALP knows. Every session launched through `alp` gets this.
+//   2. `.alp/agents/<role>.md` — the static role document, for the native path where the
+//      principal ran `claude`/`codex` directly and no adapter was involved.
+//
+// One continuity source, appended after whichever identity source loaded: `ALP_CONTINUITY_
+// CONTEXT`, the pre-rendered `continuity.md` (plan §9). It is optional in a way identity is
+// not — a fresh execution with no pins yet renders to an empty string, and `alp` launches
+// with the bridge flag off never carry an objective worth mentioning either — so a missing or
+// empty file is quiet, not a warning. Only a continuity file that exists but cannot be trusted
+// (unreadable, or over the same 24 KiB bound the renderer itself enforces) gets one, because
+// that state means something ALP wrote is no longer being read back correctly.
+//
+// Speed is why both sources are pre-rendered files: no `dist/` load, no registry
+// construction, no TypeScript runtime, no Zod. Pointing the agent at a file and asking it to
+// Read would cost a tool round-trip before any real work starts.
+//
+// Fail-open by design, unlike the policy hooks: if context cannot be loaded, the session
+// still starts and the reason surfaces as a warning rather than being swallowed. Managed
+// launches fail closed earlier and elsewhere — the adapter writes these files before it
+// spawns anything, so an unwritable one aborts `prepare()` and no process ever starts.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const P = require("../scripts/lib/install-paths.cjs");
+
+const ROLE_PATTERN = /^[a-z][a-z0-9-]*$/;
+// Same bound as `renderContinuity`'s `MAX_RENDERED_BYTES` (plan §9) — there is only one
+// injection limit, so a file over it did not come out of that renderer and is not trusted.
+const MAX_CONTINUITY_BYTES = 24 * 1024;
+
+function emit(context, warning) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context },
+    ...(warning ? { systemMessage: `⚠️  ${warning}` } : {}),
+  }));
+}
+
+function repoRoot() {
+  return process.env.ALP_REPO_ROOT || path.join(__dirname, "..");
+}
+
+function loadSessionContext() {
+  const sessionContext = process.env.ALP_SESSION_CONTEXT;
+  if (sessionContext) return fs.readFileSync(sessionContext, "utf8");
+  const role = process.env.ALP_ROLE || "main";
+  if (!ROLE_PATTERN.test(role)) throw new Error(`invalid role \`${role}\``);
+  // `~/.alp/agents`, không phải `<thư mục cài>/.alp/agents`: từ v0.9.0 thư mục cài là artifact
+  // bị thay nguyên khối mỗi lần update, nên tài liệu identity sinh trong đó biến mất đúng lúc
+  // hook này cần đọc. Vẫn thử chỗ cũ để một bản cài chưa `alp init` lại vẫn boot có identity.
+  const file = path.join(P.agentsDir(process.env), `${role}.md`);
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    const legacy = path.join(repoRoot(), ".alp", "agents", `${role}.md`);
+    try {
+      return fs.readFileSync(legacy, "utf8");
+    } catch {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Best-effort load of `continuity.md`. Never throws: a problem here must not cost the
+ * session its identity, which is why it is read after — and independently of —
+ * `loadSessionContext()` rather than folded into the same try/catch.
+ */
+function loadContinuity() {
+  const file = process.env.ALP_CONTINUITY_CONTEXT;
+  if (!file) return { text: "", warning: null };
+  let content;
+  try {
+    content = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    // Missing is the common case — a bridge-off launch, or an execution from before this
+    // feature — and not worth a warning. Anything else (a directory, a permissions error)
+    // means the path is wrong in a way worth surfacing.
+    return { text: "", warning: error.code === "ENOENT" ? null : `ALP continuity not loaded: ${error.message}` };
+  }
+  if (content.trim().length === 0) return { text: "", warning: null };
+  if (Buffer.byteLength(content, "utf8") > MAX_CONTINUITY_BYTES) {
+    return { text: "", warning: "ALP continuity exceeds its injection bound and was skipped" };
+  }
+  return { text: content, warning: null };
+}
+
+try {
+  const sessionContext = loadSessionContext();
+  const continuity = loadContinuity();
+  const context = continuity.text.length > 0 ? `${sessionContext}\n\n${continuity.text}` : sessionContext;
+  emit(context, continuity.warning);
+} catch (error) {
+  emit("", `ALP identity not loaded: ${error.message}. Run \`alp identity sync\`.`);
+}

package/hooks/session-end.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+
+// Stop hook: records the execution's final answer and closes out its state file.
+//
+// This hook does NOT judge the answer. It used to parse the last assistant message as
+// JSON and reply `{"decision":"block"}` when that failed, which forced every role —
+// including the principal-facing one — to speak JSON instead of prose. Roles now return
+// text, so the only job left here is bookkeeping: write the output into `state.json` so
+// `run-main.ts` and `delegation-service.ts` can reconcile status afterwards.
+//
+// Fail-open by design. A bookkeeping error must never trap a finished session.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function note(message) { process.stdout.write(JSON.stringify({ systemMessage: message })); }
+
+async function main() {
+  const executionId = process.env.ALP_DELEGATION_EXECUTION_ID || "";
+  try {
+    const payload = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+    const bridge = require(path.join(__dirname, "..", "dist", "src", "hooks", "execution-bridge.js"));
+    const output = payload.last_assistant_message ?? payload.output ?? payload.final_output ?? payload.result;
+    const result = await bridge.finalizeExecution({ executionId, output });
+    return note(result.ok
+      ? `execution ${executionId} finalized`
+      : `execution ${executionId} finalized with issues: ${result.issues.join("; ")}`);
+  } catch (error) {
+    return note(`execution ${executionId} could not be finalized: ${error.message}`);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "alp-code",
+  "version": "0.9.0",
+  "description": "Code-native agent layer for Claude Code and Codex CLI",
+  "license": "MIT",
+  "author": "Phúc Anh (https://github.com/phucanh08)",
+  "bin": {
+    "alp": "scripts/alp.cjs"
+  },
+  "files": [
+    "dist/src",
+    "scripts",
+    "!scripts/test-*.cjs",
+    "!scripts/cut-release.cjs",
+    "!scripts/pack-release.cjs",
+    "!scripts/probe-compact-hooks.cjs",
+    "hooks",
+    "skills",
+    "scaffold",
+    "alp.config.yaml",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phucanh08/alp-code.git"
+  },
+  "homepage": "https://github.com/phucanh08/alp-code#readme",
+  "bugs": {
+    "url": "https://github.com/phucanh08/alp-code/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}

package/scaffold/memory/INDEX.md

@@ -0,0 +1,27 @@
+# INDEX — mục lục trí nhớ dùng chung
+
+> **Mục lục, không phải nơi chứa nội dung.** Mỗi dòng trỏ tới một file trong `shared/`.
+> Memory grant của vai (khai trong `src/agents/`) **lọc** danh sách này khi dựng execution
+> — mỗi vai chỉ thấy dòng trỏ tới thứ nó được đọc. Quy ước & luật ghi: [`README.md`](README.md).
+>
+> **Phạm vi:** chỉ fact **xuyên project**. Thứ gắn với một project ở `projects/<slug>/`.
+> Nháp riêng của một vai ở `private/<role>/` và **không** được liệt kê ở đây.
+
+## Quyết định chung
+
+_Chưa có._
+
+## Con người & tổ chức
+
+_Chưa có._
+
+## Tham chiếu
+
+_Chưa có._
+
+## Nhật ký phiên
+
+_Chỉ giữ các mốc gần nhất. Diễn biến đầy đủ ở `projects/<slug>/log/`._
+
+| Ngày | Nội dung chính |
+|---|---|

package/scaffold/memory/README.md

@@ -0,0 +1,76 @@
+# memory/ — trí nhớ dùng chung của cả hệ
+
+Mục lục: [`INDEX.md`](INDEX.md). Thư mục này chứa nội dung thật.
+Luật ghi đầy đủ: skill `agent-memory`.
+
+## Ba khoang, ba mục đích khác nhau
+
+```
+memory/
+├── shared/       fact xuyên project — MỌI vai đọc được
+│   ├── decisions/   quyết định chung, không thuộc project nào
+│   ├── people/      người & tổ chức
+│   └── reference/   link, dashboard, ticket, tài liệu ngoài
+├── projects/     Project Layer 3 tầng — MỌI vai đọc được, quyền ghi tuỳ vai
+│   ├── INDEX.md     L0 — bảng tổng, sinh tự động
+│   ├── PROTOCOL.md  giao thức 3 tầng
+│   └── <slug>/      L1 PROJECT.md · L2 decisions|log|refs
+└── private/      nháp riêng từng vai — CHỈ vai đó đọc được
+    └── <role>/
+```
+
+## Ranh giới — luật quan trọng nhất của thư mục này
+
+| Loại nội dung | Đích | Vì sao |
+|---|---|---|
+| Fact về principal | `identity/_shared/PRINCIPAL.md` | một bản duy nhất cho mọi vai |
+| Fact xuyên project | `shared/` | mọi vai cần thấy |
+| Fact về một project | `projects/<slug>/` | một fact một nhà |
+| Nháp, giả thuyết chưa kiểm chứng | `private/<role>/` | chưa đáng tin, đừng lan ra |
+| Bài học về chính agent | `identity/<role>/journal/` | không phải fact về thế giới |
+
+**Cấm:** ghi fact về principal / project / thế giới vào `private/`.
+Làm vậy = fact bị nhân bản giữa các vai rồi lệch nhau, và không vai nào biết bản nào đúng.
+`private/` **chỉ** chứa thứ mà nếu mất đi cũng không ai thiệt.
+
+## Cách ly hai chiều
+
+`private/<role>/` là riêng **thật**. Main **không** đọc được private của Search,
+Librarian hay Read Thread và ngược lại. Không có vai nào là root. Muốn biết vai khác nghĩ
+gì → hỏi vai đó.
+
+## Định dạng chuẩn mỗi file
+
+```markdown
+---
+id: <slug-kebab-case>
+type: decision | person | reference | log | project
+layer: L1 | L2 | L3
+visibility: private | team
+owner: <role>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: []
+source: <link | phiên>
+---
+
+# <Tiêu đề>
+
+<Nội dung. Một fact chính mỗi file.>
+
+**Vì sao quan trọng:** <một dòng>
+**Áp dụng thế nào:** <một dòng>
+
+Liên quan: [[slug-khac]]
+```
+
+## Luật
+
+- **Một fact = một file.** Đừng dồn.
+- **Ngày tuyệt đối.** "tuần sau" → `2026-08-21`.
+- **Kiểm tra trùng trước khi tạo.** Có rồi thì cập nhật.
+- **Sai thì xoá.** Trí nhớ sai nguy hiểm hơn không nhớ.
+- **Không ghi thứ repo đã ghi** — cấu trúc code, lịch sử git, nội dung CLAUDE.md.
+- Mỗi file mới trong `shared/` → thêm một dòng vào [`INDEX.md`](INDEX.md).
+- Liên kết chéo bằng `[[slug]]`. Link tới file chưa tồn tại là bình thường — ghi chú
+  cho việc cần viết sau, không phải lỗi.

package/scaffold/memory/projects/INDEX.md

@@ -0,0 +1,22 @@
+# INDEX — L0
+
+> Tầng luôn được nạp. Một dòng mỗi project, không hơn.
+> Chi tiết nằm ở `<slug>/PROJECT.md` (L1) — chỉ mở khi project đó nằm trong phạm vi phiên.
+> Giao thức: [`PROTOCOL.md`](PROTOCOL.md). Sinh lại bằng `scripts/sync-project-index.sh --write`.
+
+**Đừng sửa tay vùng giữa hai marker.** Sửa frontmatter ở L1 rồi chạy `--write`.
+
+## Đang chạy
+
+<!-- BEGIN:INDEX -->
+| Slug | P | Trạng thái | Tóm tắt | Cập nhật |
+|---|---|---|---|---|
+<!-- END:INDEX -->
+
+## Đã đóng
+
+<!-- BEGIN:DONE -->
+_(chưa có)_
+<!-- END:DONE -->
+
+Chú giải trạng thái & ưu tiên: [`PROTOCOL.md`](PROTOCOL.md).

package/scaffold/memory/projects/PROTOCOL.md

@@ -0,0 +1,128 @@
+# PROJECT LAYER — Giao thức
+
+> Cách Phở biết về các project mà không đốt hết context.
+> Mô hình: **progressive disclosure 3 tầng**, kiểm soát bằng `modified`.
+> Tham chiếu: Hermes Agent skills system (L0 index → L1 content → L2 refs).
+
+## 1. Ba tầng
+
+| Tầng | File | Khi nào nạp | Ngân sách |
+|---|---|---|---|
+| **L0 — INDEX** | `projects/INDEX.md` | **Luôn**, ở bước boot | ≤ 1 dòng/project, mục tiêu < 2k token kể cả khi có 30 project |
+| **L1 — CARD** | `projects/<slug>/PROJECT.md` | Khi project đó nằm trong phạm vi phiên | ≤ 60 dòng |
+| **L2 — REFS** | `projects/<slug>/{decisions,log,refs}/*.md` | Chỉ khi cần đúng file đó | tuỳ ý |
+
+**Luật vàng:** không bao giờ nạp L1 của mọi project. Đọc L0, xác định project liên quan,
+chỉ mở L1 của nó. L2 chỉ mở khi L1 trỏ tới và câu hỏi thật sự cần.
+
+Nếu principal hỏi "tình hình chung thế nào?" → **chỉ cần L0**. Mở L1 lúc này là lãng phí.
+
+## 2. Vì sao L0 phải ổn định
+
+L0 nằm trong phần đầu context mỗi phiên. Mỗi lần nó đổi byte, prompt cache hỏng và toàn bộ
+phần sau phải tính lại. Nên:
+
+- **L0 chỉ đổi khi trạng thái project đổi thật** — không sửa vì lý do vụn vặt.
+- **Ngày trong L0 ghi theo ngày, không ghi giờ** (`2026-08-14`, không `2026-08-14 13:55`).
+  Timestamp mịn hơn ngày sẽ phá cache mỗi lần chạm file.
+- **Thông tin hay đổi không đặt ở L0** — tiến độ chi tiết, việc đang làm, ghi chú phiên
+  thuộc về L1/L2.
+- Sắp xếp hàng trong bảng **cố định** (theo priority rồi slug), không sắp lại tuỳ hứng.
+
+## 3. Kiểm soát bằng `modified`
+
+Có hai đồng hồ, và chúng phải khớp nhau:
+
+| Đồng hồ | Ai ghi | Ý nghĩa |
+|---|---|---|
+| `updated:` trong frontmatter L1 | **Phở**, thủ công | "Lần cuối Phở thật sự xem lại và xác nhận nội dung này đúng" |
+| mtime của file (hệ thống) | Máy | "Lần cuối file bị chạm vào" |
+
+### Ba tín hiệu
+
+**DRIFT** — `mtime > updated`
+File đã bị sửa mà `updated` chưa được cập nhật. Nghĩa là có người (hoặc agent khác) sửa
+ngoài quy trình, hoặc Phở sửa mà quên đóng dấu. → Đọc lại L1, xác nhận nội dung, cập nhật
+`updated`, đồng bộ lại dòng L0 nếu cần.
+
+**STALE** — `status: ACTIVE` và `updated` cách hôm nay > 14 ngày
+Project khai là đang chạy nhưng không ai đụng tới hai tuần. Một trong hai điều sai: hoặc
+trạng thái sai, hoặc project thật sự bị bỏ quên. → Nêu trong heartbeat, hỏi principal.
+
+**ORPHAN** — có `PROJECT.md` mà không có dòng trong L0, hoặc ngược lại
+→ Đồng bộ ngay. L0 là nguồn sự thật về *danh sách*; L1 là nguồn sự thật về *nội dung*.
+
+### Công cụ
+
+```bash
+scripts/sync-project-index.sh          # quét, báo cáo DRIFT / STALE / ORPHAN
+scripts/sync-project-index.sh --write  # ghi lại bảng L0 từ frontmatter L1
+```
+
+Chạy ở bước boot (rẻ, chỉ đọc frontmatter) và trong mỗi heartbeat.
+`--write` chỉ đụng vùng giữa `<!-- BEGIN:INDEX -->` và `<!-- END:INDEX -->`.
+
+## 4. Cấu trúc một project
+
+```
+projects/<slug>/
+├── PROJECT.md          L1 — card, có frontmatter
+├── decisions/          L2 — mỗi quyết định một file, YYMMDD-slug.md
+├── log/                L2 — nhật ký phiên, YYYY-MM.md (gộp theo tháng)
+└── refs/               L2 — link, spec, tài liệu ngoài
+```
+
+Thư mục L2 tạo khi cần, không tạo sẵn cho rỗng.
+
+## 5. Frontmatter L1 — bắt buộc
+
+```yaml
+---
+slug: ten-project              # trùng tên thư mục
+name: Tên đầy đủ
+status: ACTIVE                 # ACTIVE | WAITING | BLOCKED | PAUSED | DONE
+priority: P1                   # P0 khẩn | P1 chính | P2 phụ | P3 nền
+summary: Một câu ≤ 100 ký tự — dòng này lên thẳng L0
+path: ~/AnhlpProjects/ten-project
+updated: 2026-08-14            # ngày, không giờ
+---
+```
+
+`summary` là thứ duy nhất từ L1 được phép leo lên L0. Viết nó cho người đọc lướt: nói
+project *làm gì*, không nói nó *đang ở đâu* (trạng thái đã có cột riêng).
+
+## 6. Vòng đời
+
+**Thêm project**
+1. `cp -r projects/_template projects/<slug>`
+2. Điền frontmatter + card
+3. `scripts/sync-project-index.sh --write`
+
+**Đổi trạng thái**
+Sửa `status` + `updated` ở L1 → `--write` → L0 tự cập nhật. Không sửa tay L0.
+
+**Đóng project**
+`status: DONE` → `--write` đẩy nó xuống mục Đã đóng ở L0 (một dòng, không chi tiết).
+Giữ thư mục lại; lịch sử có giá.
+
+## 7. Ranh giới với phần còn lại của `memory/`
+
+Dễ nhầm, nên nói rõ:
+
+| Thuộc về | Đặt ở |
+|---|---|
+| Bất cứ thứ gì gắn với **một** project | `memory/projects/<slug>/` |
+| Fact xuyên project (người, tài khoản, quyết định chung) | `memory/shared/` |
+| Sở thích ổn định của principal | `identity/_shared/PRINCIPAL.md` |
+| Nháp chưa kiểm chứng của một vai | `memory/private/<role>/` |
+
+Một fact chỉ có một nhà. Luật đầy đủ: skill `agent-memory`.
+
+**Quyền ghi khác nhau theo vai.** `PROJECT.md` (L1) và `decisions/` là quyền của
+main. `refs/` mở cho vai research. Xem `identity/<role>/loadout.yaml`.
+
+## 8. Chú giải L0
+
+**Trạng thái:** `ACTIVE` đang làm · `WAITING` chờ bên ngoài · `BLOCKED` cần principal gỡ ·
+`PAUSED` cố ý dừng · `DONE` đã đóng
+**Ưu tiên:** `P0` khẩn · `P1` chính · `P2` phụ · `P3` nền

package/scaffold/memory/projects/_template/PROJECT.md

@@ -0,0 +1,45 @@
+---
+slug: ten-project
+name: Tên đầy đủ của project
+status: ACTIVE
+priority: P1
+summary: Một câu ≤ 100 ký tự, nói project LÀM GÌ — dòng này leo lên L0
+path: ~/AnhlpProjects/ten-project
+updated: 2026-08-14
+---
+
+# <Tên project>
+
+## Mục tiêu
+<Một đoạn. Xong project này thì điều gì đúng mà hôm nay chưa đúng?>
+
+## Trạng thái hiện tại
+<2–3 dòng. Đang ở đâu, vừa xong gì.>
+
+## Việc tiếp theo
+1. <việc cụ thể, làm được ngay>
+2. <việc kế>
+
+## Đang chặn
+- <cái gì chặn, cần ai/cái gì để gỡ. Xoá mục này nếu không có.>
+
+## Stack & lệnh
+| | |
+|---|---|
+| Stack | <ngôn ngữ, framework chính> |
+| Chạy | `<lệnh dev>` |
+| Test | `<lệnh test>` |
+| Deploy | `<lệnh / nền tảng>` |
+
+## Người liên quan
+- <tên> — <vai trò>. Chi tiết: `[[shared/people/ten]]`
+
+## Cạm bẫy đã biết
+- <thứ đã cắn mình một lần rồi, đừng để cắn lần hai>
+
+## Quyết định
+<Chỉ liệt kê, nội dung ở L2 — đừng chép vào đây.>
+- [YYMMDD — tiêu đề](decisions/YYMMDD-slug.md)
+
+## Nhật ký
+- [2026-08](log/2026-08.md)