feat(compat): 读 AGENTS.md / CLAUDE.md 指令链 + 项目级 skills（P1）

README.md

@@ -611,6 +611,27 @@ until you grant it. See `lisa consent list`.
 
 Claude-Code-compatible plugin format. See [`claude-code` docs](https://github.com/anthropics/claude-code) for the schema. Lisa picks up plugins on every launch.
 
+### `AGENTS.md` / `CLAUDE.md` — the instructions you already wrote
+
+Lisa reads the ecosystem's convention, so moving from Claude Code / Codex / Cursor costs nothing. Layered outermost-first, nearest last:
+
+```
+~/.lisa/AGENTS.md          your own, applies to every project
+<repo root>/AGENTS.md      the project's conventions
+<repo root>/CLAUDE.md      (folded away if identical to AGENTS.md)
+…every directory down to cwd…
+```
+
+Edits hot-reload mid-session, same as the soul files. Capped at 32KB total so a monorepo's instructions can't crowd out her identity.
+
+**They are context, not authority.** These files arrive merely by working in a directory, so the prompt labels each block with its origin and states that project text does not override her constitution — cloning a hostile repo is not a way to give Lisa orders.
+
+### Project skills
+
+Alongside `~/.lisa/skills/`, Lisa reads `<repo>/.lisa/skills/` and `<repo>/.agents/skills/`, so a repo can ship the workflows that only make sense inside it.
+
+On a name collision **the home skill wins** — deliberately the opposite of dsh's nearest-first rule. A skill is prompt material Lisa wrote about how she works; `cd`-ing into a repo must not be enough to redefine one. Project skills are additive, and shown in the prompt tagged `(from this project)`.
+
 ### Executable skills `~/.lisa/skills/<slug>/tool.js`
 
 A skill folder may contain an OPTIONAL `tool.js` that exports a `ToolDefinition`. After explicit approval, it becomes a real registered tool — Lisa can extend her own *capability* set, not just her knowledge.

src/instructions/chain.test.ts

@@ -0,0 +1,190 @@
+import { test, describe, before, after, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * P1 acceptance (docs/PLAN_HARNESS_ALIGNMENT_v1.0.md §7): read the ecosystem's
+ * AGENTS.md / CLAUDE.md convention so a user moving to Lisa keeps the
+ * instructions they already wrote.
+ */
+
+let chain: typeof import("./chain.js");
+let home: string;
+let repo: string;
+
+before(async () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "lisa-instr-"));
+  home = path.join(base, "home");
+  repo = path.join(base, "repo");
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(path.join(repo, ".git"), { recursive: true });
+  fs.mkdirSync(path.join(repo, "pkg", "deep"), { recursive: true });
+  process.env.LISA_HOME = home;
+  chain = await import("./chain.js");
+});
+after(() => {
+  fs.rmSync(path.dirname(home), { recursive: true, force: true });
+});
+beforeEach(() => {
+  for (const dir of [home, repo, path.join(repo, "pkg"), path.join(repo, "pkg", "deep")]) {
+    for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+      fs.rmSync(path.join(dir, name), { force: true });
+    }
+  }
+});
+
+describe("instruction chain — layering", () => {
+  test("nothing to load is not an error", async () => {
+    const loaded = await chain.loadInstructionChain(repo);
+    assert.deepEqual(loaded.files, []);
+    assert.equal(chain.renderInstructionChain(loaded), "");
+  });
+
+  test("home file applies everywhere, project root file adds to it, nearest last", async () => {
+    fs.writeFileSync(path.join(home, "AGENTS.md"), "global rule");
+    fs.writeFileSync(path.join(repo, "AGENTS.md"), "repo rule");
+    fs.writeFileSync(path.join(repo, "pkg", "AGENTS.md"), "package rule");
+
+    const loaded = await chain.loadInstructionChain(path.join(repo, "pkg", "deep"));
+    assert.deepEqual(
+      loaded.files.map((f) => f.content),
+      ["global rule", "repo rule", "package rule"],
+      "outermost first so the most specific text is read last",
+    );
+    assert.deepEqual(
+      loaded.files.map((f) => f.scope),
+      ["home", "project", "project"],
+    );
+  });
+
+  test("the walk stops at the git root, not at the filesystem root", async () => {
+    assert.equal(await chain.findProjectRoot(path.join(repo, "pkg", "deep")), repo);
+    // A directory with no .git anywhere above resolves to itself. Compared
+    // against path.resolve, not realpath: the walk deliberately does not follow
+    // symlinks (on macOS /var is a link to /private/var), and every caller
+    // resolves paths the same way.
+    const orphan = fs.mkdtempSync(path.join(os.tmpdir(), "lisa-orphan-"));
+    try {
+      assert.equal(await chain.findProjectRoot(orphan), path.resolve(orphan));
+    } finally {
+      fs.rmSync(orphan, { recursive: true, force: true });
+    }
+  });
+
+  test("CLAUDE.md is read when AGENTS.md is absent", async () => {
+    fs.writeFileSync(path.join(repo, "CLAUDE.md"), "claude-flavoured rule");
+    const loaded = await chain.loadInstructionChain(repo);
+    assert.deepEqual(loaded.files.map((f) => f.content), ["claude-flavoured rule"]);
+  });
+
+  test("a CLAUDE.md that duplicates AGENTS.md is folded away, not read twice", async () => {
+    fs.writeFileSync(path.join(repo, "AGENTS.md"), "the one rule");
+    fs.writeFileSync(path.join(repo, "CLAUDE.md"), "the one rule");
+    const loaded = await chain.loadInstructionChain(repo);
+    assert.equal(loaded.files.length, 1);
+    assert.equal(loaded.deduped.length, 1);
+    assert.match(loaded.deduped[0]!, /CLAUDE\.md$/);
+  });
+
+  test("differing AGENTS.md and CLAUDE.md are both kept", async () => {
+    fs.writeFileSync(path.join(repo, "AGENTS.md"), "rule A");
+    fs.writeFileSync(path.join(repo, "CLAUDE.md"), "rule B");
+    const loaded = await chain.loadInstructionChain(repo);
+    assert.deepEqual(loaded.files.map((f) => f.content), ["rule A", "rule B"]);
+  });
+
+  test("an empty file contributes nothing", async () => {
+    fs.writeFileSync(path.join(repo, "AGENTS.md"), "   \n\n  ");
+    const loaded = await chain.loadInstructionChain(repo);
+    assert.deepEqual(loaded.files, []);
+  });
+});
+
+describe("instruction chain — bounded and labelled", () => {
+  test("the budget truncates rather than letting a monorepo crowd out the soul", async () => {
+    fs.writeFileSync(
+      path.join(repo, "AGENTS.md"),
+      "x".repeat(chain.INSTRUCTION_BUDGET_BYTES + 5_000),
+    );
+    const loaded = await chain.loadInstructionChain(repo);
+    assert.equal(loaded.budgetExhausted, true);
+    assert.equal(loaded.files[0]!.truncated, true);
+    assert.equal(loaded.files[0]!.content.length, chain.INSTRUCTION_BUDGET_BYTES);
+    assert.match(chain.renderInstructionChain(loaded), /truncated to fit/);
+  });
+
+  test("project text is framed as the project's claims, not as Lisa's principles", async () => {
+    fs.writeFileSync(path.join(repo, "AGENTS.md"), "use tabs");
+    const rendered = chain.renderInstructionChain(
+      await chain.loadInstructionChain(repo),
+    );
+    assert.match(rendered, /the project's stated conventions/);
+    assert.match(
+      rendered,
+      /do not override your constitution/,
+      "these files arrive by cd, so the prompt must not present them as authority",
+    );
+    assert.match(rendered, /disregard the file and say so/);
+  });
+
+  test("home text is labelled as the user's own, distinctly from project text", async () => {
+    fs.writeFileSync(path.join(home, "AGENTS.md"), "always be brief");
+    const rendered = chain.renderInstructionChain(
+      await chain.loadInstructionChain(repo),
+    );
+    assert.match(rendered, /your own home directory/);
+  });
+
+  test("a symlinked AGENTS.md is refused — a hostile repo cannot read a secret into the prompt", async () => {
+    const secret = path.join(path.dirname(home), "id_rsa");
+    fs.writeFileSync(secret, "PRIVATE-KEY-MATERIAL");
+    fs.symlinkSync(secret, path.join(repo, "AGENTS.md"));
+    try {
+      const loaded = await chain.loadInstructionChain(repo);
+      assert.deepEqual(loaded.files, [], "a symlink is never followed");
+      assert.doesNotMatch(chain.renderInstructionChain(loaded), /PRIVATE-KEY-MATERIAL/);
+    } finally {
+      // Remove the LINK before its target, so it never becomes a dangling
+      // symlink (rmSync+force can't clear those, which would poison later tests).
+      fs.rmSync(path.join(repo, "AGENTS.md"), { force: true });
+      fs.rmSync(secret, { force: true });
+    }
+  });
+
+  test("the budget counts UTF-8 bytes, not code units, so CJK cannot claim 3x the room", async () => {
+    // Each CJK char is one UTF-16 code unit but three UTF-8 bytes: char count
+    // well under the budget, byte count far over it. The old `raw.length` test
+    // admitted ~3x; a byte budget must truncate.
+    const chars = chain.INSTRUCTION_BUDGET_BYTES; // ~32k chars ≈ 96 KB of bytes
+    fs.writeFileSync(path.join(repo, "AGENTS.md"), "字".repeat(chars));
+    const loaded = await chain.loadInstructionChain(repo);
+    assert.equal(loaded.budgetExhausted, true);
+    assert.ok(loaded.files[0]!.content.length < chars, "the CJK file was truncated");
+    assert.ok(
+      Buffer.byteLength(loaded.files[0]!.content, "utf8") <= chain.INSTRUCTION_BUDGET_BYTES + 4,
+      "bounded by UTF-8 bytes (a boundary code point may add a few bytes)",
+    );
+  });
+});
+
+describe("instruction chain — hot reload", () => {
+  test("creating, editing and deleting a file each move the fingerprint", async () => {
+    const before1 = await chain.instructionChainFingerprint(repo);
+
+    fs.writeFileSync(path.join(repo, "AGENTS.md"), "v1");
+    const created = await chain.instructionChainFingerprint(repo);
+    assert.notEqual(created, before1, "creating a file must be visible");
+
+    // mtime resolution can be coarse; force a distinct stamp.
+    const future = new Date(Date.now() + 5_000);
+    fs.utimesSync(path.join(repo, "AGENTS.md"), future, future);
+    const edited = await chain.instructionChainFingerprint(repo);
+    assert.notEqual(edited, created, "editing a file must be visible");
+
+    fs.rmSync(path.join(repo, "AGENTS.md"));
+    const deleted = await chain.instructionChainFingerprint(repo);
+    assert.equal(deleted, before1, "deleting returns to the original state");
+  });
+});