@sayansr26/agent-os 0.5.2 → 0.6.0

package/plugins/agent-os/lib/features.mjs

@@ -0,0 +1,154 @@
+/**
+ * What counts as a feature, and which features the cartographer has mapped.
+ *
+ * Shared by the session hook, the pre-edit hook and the audit, so the three
+ * never disagree about coverage. Everything here is read-only, synchronous and
+ * swallows its own errors — hooks must never fail a session.
+ *
+ * Feature directories come from `.agent-os/config.json`:
+ *
+ *   { "claude": { "features": ["src/features/*", "apps/*"] } }
+ *
+ * Each entry is `<dir>/*`: every direct subdirectory of `<dir>` is a feature.
+ * With no config, the first of DEFAULT_PARENTS that exists is used.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const DEFAULT_PARENTS = ["src/features", "src/modules", "app/features", "features", "modules"];
+
+const read = (p) => { try { return readFileSync(p, "utf8"); } catch { return null; } };
+const ls = (p) => { try { return readdirSync(p); } catch { return []; } };
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** `.agent-os/config.json`'s `claude` block, or {}. */
+export function claudeConfig(root) {
+  try { return JSON.parse(read(join(root, ".agent-os/config.json")) || "{}").claude || {}; }
+  catch { return {}; }
+}
+
+/** The parent directories whose children are features, relative to root. */
+export function featureParents(root) {
+  const cfg = claudeConfig(root).features;
+  if (Array.isArray(cfg) && cfg.length)
+    return cfg.map((g) => String(g).replace(/\/\*+$/, "").replace(/\/$/, "")).filter(Boolean);
+  const found = DEFAULT_PARENTS.find((d) => isDir(join(root, d)));
+  return found ? [found] : [];
+}
+
+/** Every feature: { name, dir } with dir relative to root. */
+export function listFeatures(root) {
+  const out = [];
+  for (const parent of featureParents(root))
+    for (const name of ls(join(root, parent)))
+      if (!name.startsWith(".") && isDir(join(root, parent, name))) out.push({ name, dir: `${parent}/${name}` });
+  return out;
+}
+
+/** The feature a (relative or absolute) path belongs to, or null. */
+export function featureOf(root, filePath) {
+  let rel = String(filePath || "").replace(/\\/g, "/");
+  const r = root.replace(/\\/g, "/").replace(/\/$/, "") + "/";
+  if (rel.startsWith(r)) rel = rel.slice(r.length);
+  for (const parent of featureParents(root)) {
+    const m = rel.match(new RegExp(`^${esc(parent)}/([^/]+)/`));
+    if (m) return { name: m[1], dir: `${parent}/${m[1]}` };
+  }
+  return null;
+}
+
+/**
+ * The cartographer's memory directory. Plugin agents are namespaced, so the
+ * directory is `agent-os-feature-cartographer`; the bare name is what a copy
+ * installed as a standalone agent writes to.
+ */
+export function cartographerDir(root) {
+  for (const base of [".claude/agent-memory", ".claude/agent-memory-local"])
+    for (const name of ["agent-os-feature-cartographer", "feature-cartographer"]) {
+      const d = join(root, base, name);
+      if (isDir(d)) return d;
+    }
+  return null;
+}
+
+/** Topic files in the cartographer's memory: [{ file, text, mapped }]. */
+export function mapFiles(root) {
+  const dir = cartographerDir(root);
+  if (!dir) return [];
+  return ls(dir)
+    .filter((f) => f.endsWith(".md") && f !== "MEMORY.md")
+    .map((f) => {
+      const text = read(join(dir, f)) || "";
+      const m = text.match(/^mapped:\s*["']?(\d{4}-\d{2}-\d{2})/m);
+      return { file: f, text, mapped: m ? m[1] : null };
+    });
+}
+
+/**
+ * Does some topic file map this feature? A map names its subject in a header
+ * line (description:, entry:, a heading), is named after it, or mentions its
+ * directory at least twice. `_architecture.md` is the system map and never
+ * counts as a feature map. `dashboard` must not match `dashboardV2`.
+ */
+export function findMap(feature, maps) {
+  const named = new RegExp(`${esc(feature.dir)}(?![\\w-])`);
+  const slug = feature.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  for (const m of maps) {
+    if (m.file.startsWith("_")) continue;
+    if (m.file.replace(/\.md$/, "").toLowerCase() === slug) return m;
+    const header = m.text.split("\n").some((l) => /^(description:|entry:|#)/.test(l) && named.test(l));
+    if (header || m.text.split(`${feature.dir}/`).length - 1 >= 2) return m;
+  }
+  return null;
+}
+
+/** Is anything under this directory tracked by git? Unknown counts as yes. */
+export function tracked(root, dir) {
+  try {
+    const out = execFileSync("git", ["ls-files", "--", dir], {
+      cwd: root, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.trim().length > 0;
+  } catch { return true; }
+}
+
+/** Date (YYYY-MM-DD) of the last commit touching dir, or null. */
+export function lastChanged(root, dir) {
+  try {
+    const out = execFileSync("git", ["log", "-1", "--format=%cs", "--", dir], {
+      cwd: root, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return /^\d{4}-\d{2}-\d{2}$/.test(out) ? out : null;
+  } catch { return null; }
+}
+
+/**
+ * Coverage summary. `stale` compares each map's `mapped:` date with the last
+ * commit to its feature, which costs one git call per mapped feature — the
+ * audit asks for it, the hooks do not.
+ */
+export function coverage(root, { stale = false } = {}) {
+  const features = listFeatures(root);
+  const maps = mapFiles(root);
+  const mapped = [], unmapped = [], outdated = [];
+  for (const f of features) {
+    const m = findMap(f, maps);
+    if (!m) { unmapped.push(f); continue; }
+    mapped.push({ ...f, map: m.file, date: m.mapped });
+    if (stale && m.mapped) {
+      const changed = lastChanged(root, f.dir);
+      if (changed && changed > m.mapped) outdated.push({ ...f, map: m.file, date: m.mapped, changed });
+    }
+  }
+  return {
+    parents: featureParents(root),
+    features,
+    mapped,
+    unmapped,
+    outdated,
+    architecture: maps.some((m) => m.file === "_architecture.md"),
+    dir: cartographerDir(root),
+  };
+}

package/plugins/agent-os/skills/init/SKILL.md

@@ -15,7 +15,7 @@ The layout this skill converges on:
 | Always-loaded | `CLAUDE.md`, ≤200 lines | small, fixed | Only what is true in *every* session |
 | On-demand | `.claude/rules/*.md` with `paths:` frontmatter | **zero** | Durable facts scoped to some files |
 | Self-writing | auto memory (`~/.claude/projects/<repo>/memory/`) | index only | Corrections, preferences, decisions |
-| Explored | `.claude/agent-memory/feature-cartographer/` | **zero** (subagent context) | How each feature is actually built |
+| Explored | `.claude/agent-memory/agent-os-feature-cartographer/` | **zero** (subagent context) | How each feature is actually built |
 | Task state | the project's own vault / handoff file | zero (read selectively) | What is in flight right now |
 
 The principle the whole layout serves: **storing a fact and loading a fact are
@@ -28,7 +28,7 @@ a memory-bank read at every startup, a rules file with no `paths:` — is the bu
 |---|---|
 | *(none)* | The full pass: audit, then route by MODE |
 | `audit` | Run the audit and report. Change nothing. |
-| `settings` | The settings and permissions pass only — read `~/.claude/settings.json` and the project's, report what is set, and propose changes. See below. |
+| `settings` | The settings pass only — git write protection and the task tools, applied to project and user settings after one confirmation. See below. |
 
 Related skills: `/agent-os:map` builds the architecture map, `/agent-os:memory`
 inspects and repairs what the project remembers.
@@ -51,12 +51,37 @@ It reports: always-loaded files and their line counts, whether every
 stores (`memory-bank/`, `.serena/memories/`, cursor and windsurf rules, memory-ish
 MCP servers), per-agent memory health, the machine layer (`~/.claude` CLAUDE.md,
 shadowing agents or skills, a duplicate session-resume hook, permissions
-posture), the startup byte and token cost, and a ranked finding list.
+posture), the setup state (fresh, repair or healthy), the startup byte and
+token cost, and a ranked finding list.
 
 **Show the output to the user before you change anything.** Do not restructure a
 repo you have only just opened.
 
-## Step 2 — Route by MODE
+## Step 2 — Fresh setup or repair?
+
+Above `MODE`, the audit prints a `SETUP` block: the install and settings state,
+one line per item, and a verdict. Read it first — it decides how much of this
+skill runs, so a project that is already set up is repaired, never re-initialised.
+
+| SETUP | What it means | Do |
+|---|---|---|
+| `FRESH` | Nothing of agent-os here yet | The full pass: Step 3 by `MODE`, then the settings pass. If `.agent-os/ source` is missing and the user wants rules for other tools too, suggest `npx @sayansr26/agent-os init` once. |
+| `REPAIR` | Set up, but items are `MISSING` | Fix **only** the `MISSING` lines, each by the route below, then `MODE` as usual. Do not rebuild anything marked `ok`. |
+| `HEALTHY` | Every item `ok` | Skip the settings pass; `MODE` alone decides the rest. |
+
+Routes for `MISSING` items — batch them into the **one** confirmation the
+settings pass asks, rather than a question per item:
+
+| Item | Fix |
+|---|---|
+| git write protection, task tools, task-tracking rule | the settings pass below |
+| plugin version (older than latest) | `claude plugin marketplace update sayan-plugins`, then `claude plugin update agent-os@sayan-plugins --scope <its scope> --yes`. Tell the user to run `/reload-plugins` — the running session keeps the old version until then. If `claude` is not on PATH, give them `/plugin update agent-os@sayan-plugins`. |
+| plugin enabled | `claude plugin enable agent-os@sayan-plugins` |
+| CLAUDE.md says when to use each agent | `references/establishing.md`, Step 4b |
+| CLAUDE.md | `MODE` routes it (ESTABLISH) |
+| `.agent-os/ source` | optional — only if the user wants rules compiled for other tools: `npx @sayansr26/agent-os init` |
+
+## Step 3 — Route by MODE
 
 The audit ends with a `MODE` line. It decides what this run is for:
 
@@ -73,55 +98,70 @@ login flow from email to OTP"* execute from known structure instead of
 rediscovering the codebase. `references/changing-a-feature.md` is that workflow —
 point the user at it once the layer exists.
 
-## Step 3 — Act on the findings
+## Step 4 — Act on the findings
 
 Each finding routes to one place. Load only what the audit actually surfaced:
 
 | Finding | Read |
 |---|---|
 | `MODE ESTABLISH` or `MODE MAP` | `references/establishing.md` |
+| `CLAUDE.md` has no "Agents in this project" section | `references/establishing.md`, Step 4b |
 | user asks how to change an existing feature | `references/changing-a-feature.md` |
 | legacy store found; CLAUDE.md over budget | `references/migrating.md` |
 | rule without `paths:`; no rules layer yet; CLAUDE.md to trim | `references/writing-rules.md` |
-| `defaultMode` auto-approves with an empty `deny` | `references/git-permissions.md` |
+| git write protection or task tools missing | the settings pass below — apply, don't hand over |
 | LSP plugin recommended; checked-in generated dirs | `references/establishing.md`, "Stop Claude reading what it should not" |
 | hook target missing | delete the hook entry, or restore the script — say which |
 | shadowing agent or skill in `~/.claude` or `.claude/agents/` | the user removes the standalone copy; a plugin cannot |
 | unindexed or near-duplicate agent memory topic files | merge into the best-named file, delete the rest, rebuild `MEMORY.md` as one line per file |
 | project CLAUDE.md refers to a `~/.claude/CLAUDE.md` that is absent | the user creates it or drops the reference |
 
-Findings on the machine layer are the user's to fix — a plugin cannot write
-`~/.claude`. Hand over the exact change rather than attempting it.
+Shadowing agents and skills on the machine layer are the user's to remove.
+Settings are not: the settings pass below writes them, including `~/.claude`.
 
-## Step 4 — Verify by re-running
+## Step 5 — Verify by re-running
 
-Run the audit again and show the before and after: finding count, startup bytes,
-token estimate. Do not declare success on vibes — the script already produces the
+Run the audit again and show the before and after: the `SETUP` verdict (a
+repair should end `HEALTHY`), finding count, startup bytes, token estimate. Do not declare success on vibes — the script already produces the
 numbers, so quote them.
 
 ## The settings pass
 
-The audit already reads both settings files and reports `defaultMode`, the deny
-list, hook registrations and shadowing. To act on it:
-
-1. **Show what is set** — project `.claude/settings.json` and `~/.claude/settings.json`,
-   side by side, so the user can see which rules exist only in this project and
-   therefore vanish in every other one.
-2. **Propose, do not apply.** Write out the exact JSON block and ask. This is the
-   one place where acting first is wrong: `permissions.deny` is the guardrail on
-   your own behaviour, and a skill that edits its own guardrails without being
-   asked is exactly the thing the setting exists to prevent. Apply only after an
-   explicit yes, and never widen an existing deny list without pointing out what
-   it would stop blocking.
-3. **What to propose**, when the audit flagged it:
-   - git write protection — `references/git-permissions.md` has the rule set
-   - `Read` deny rules for checked-in generated or vendored paths
-   - a code intelligence plugin for the detected language
-   - `claudeMdExcludes` in a monorepo where other teams' files load
-
-Anything under `~/.claude/` affects every project on the machine. Say so before
-proposing it, and prefer the project's own settings file when the rule is really
-about this project.
+Runs when `SETUP` is `FRESH`, or `REPAIR` with a settings item missing (after Step 4), and alone for `settings`. It
+**writes** the setup rather than describing it — handing the user a JSON block
+to paste is how a project ends up with no git protection and no task tools.
+
+1. **Preview.** One call:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/settings.mjs" --scope both
+   ```
+
+   It prints, per file, what it would add to project `.claude/settings.json` and
+   `~/.claude/settings.json` — the git write-protection deny rules, and
+   `env.CLAUDE_CODE_ENABLE_TODO_TOOLS` — plus the task-tracking rule for each
+   `CLAUDE.md`. If it reports everything already present, say so and stop.
+2. **Ask once.** One AskUserQuestion: apply to *project and user* (recommended —
+   `~/.claude` protects every other repo on this machine), *project only*, or
+   *skip*. This is the one confirmation: `permissions.deny` is the guardrail on
+   your own behaviour, so it is changed with the user's yes, never silently.
+3. **Apply** with the same command plus `--apply` and `--scope both` or
+   `--scope project`. The script merges — existing keys, allow rules, deny rules
+   and a user-set env value survive — and backs up any `~/.claude` file it
+   changes to `<file>.agent-os.bak`. Show its output.
+4. **If the Bash call is denied** (writing under `~/.claude` can need approval),
+   do not fall back to pasting JSON. Give the user the exact command to run
+   with the `!` prefix so it runs in this session:
+   `! node "<plugin root>/skills/init/scripts/settings.mjs" --scope both --apply`.
+
+The rule set and every judgment call in it (why `git -C` is denied, why
+`fetch` is allowed) are in `references/git-permissions.md`.
+
+Also propose, when the audit flagged them — these are project-specific, so they
+stay proposals:
+- `Read` deny rules for checked-in generated or vendored paths
+- a code intelligence plugin for the detected language
+- `claudeMdExcludes` in a monorepo where other teams' files load
 
 ## What this skill will not do
 

package/plugins/agent-os/skills/init/references/changing-a-feature.md

@@ -41,6 +41,13 @@ That last line is the whole argument for this step. A cold grep for `login` woul
 not have found the OTP dialog that already exists — and you would have built a
 second one.
 
+**In plan mode** the cartographer still comes first — plan mode's "Explore
+agents only" phase is about not writing code, not about skipping the map. Ask it
+read-only (*"read-only, plan mode: how is the login flow built?"*); it answers
+and files nothing. The first step after plan mode ends is to call it again to
+file the map. If the feature has no map at all and the user would rather not
+wait, `/agent-os:map <feature>` before planning does the same job.
+
 ## Step 2 — Find the nearest precedent
 
 Before designing anything, ask what this codebase already did that resembles the

package/plugins/agent-os/skills/init/references/establishing.md

@@ -75,6 +75,10 @@ The highest-value things to capture are the ones a newcomer gets wrong:
 
 ## Step 4 — Write the rules
 
+If the project has `.agent-os/`, write rules there (`.agent-os/rules/<name>.md`)
+and run `npx @sayansr26/agent-os sync`; the `.claude/rules/` copies are
+generated, and the pre-edit hook blocks edits to them.
+
 Group by **what the reader is touching**, not by topic. Each file gets `paths:`
 frontmatter narrow enough that it is absent most of the time.
 
@@ -95,6 +99,30 @@ Verified across three services; see the ones named in `_architecture.md`.
 Dense agent notes, not prose. Invariants and gotchas. Skip anything a `ls` or a
 grep answers — that is rule 2 in the README and it applies hardest here.
 
+## Step 4b — Wire the agents into CLAUDE.md
+
+An agent nobody is told to use never runs. The session hook announces the
+agents every session; `CLAUDE.md` makes it part of the project's own contract,
+so it survives a machine without the plugin's hooks. Add this section once
+(skip it if `CLAUDE.md` already has one), trimmed to the agents this project
+actually needs:
+
+```markdown
+## Agents in this project (agent-os)
+
+- Before changing an existing feature: ask `agent-os:feature-cartographer` how
+  it is built. In plan mode ask it read-only, and have it file the map as the
+  first step after plan mode ends.
+- New subsystem, cross-module change, shared data model: `agent-os:architect`
+  first.
+- Writing the change: `agent-os:builder`, given the map and the files to change.
+- Done means: `agent-os:tester` verified it and `agent-os:reviewer` found no
+  rule violations.
+- After it is verified: `agent-os:documenter` updates the changelog and docs.
+- Work spanning several of these: `agent-os:orchestrator`.
+- Rules live in `.agent-os/rules/`; `.claude/rules/` is generated.
+```
+
 ## Step 5 — Stop Claude reading what it should not
 
 Two settings with a large effect on how much gets read, both worth proposing:

package/plugins/agent-os/skills/init/references/git-permissions.md

@@ -4,8 +4,11 @@ A `permissions.deny` set that blocks every git command which changes the
 repository, while leaving read-only inspection (`status`, `log`, `diff`, `show`,
 `blame`, `rev-parse`, `ls-files`, `describe`, `grep`, `shortlog`, …) available.
 
-Paste into `~/.claude/settings.json` for every project, or a project's
-`.claude/settings.json` for one.
+You do not paste this. `scripts/settings.mjs` applies it — to the project's
+`.claude/settings.json`, `~/.claude/settings.json`, or both — merged into what
+is already there, as part of `/agent-os:init` or `agent-os settings --apply`.
+The list lives in that script (`GIT_DENY`); it is reproduced here so the
+judgment calls below have something to point at.
 
 ```json
 {

package/plugins/agent-os/skills/init/scripts/audit.mjs

@@ -15,6 +15,9 @@
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
+import { coverage } from "../../../lib/features.mjs";
+import { GIT_DENY, TODO_ENV } from "./settings.mjs";
+import { describeState, setupState } from "./state.mjs";
 
 const ROOT = process.argv[2] || process.cwd();
 const HOME = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
@@ -50,6 +53,8 @@ for (const f of ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"]) {
   if (over) flag("WARN", `${f} is ${n} lines; budget is 200. Move path-scoped content to .claude/rules/.`);
 }
 if (!residentBytes) flag("WARN", "No CLAUDE.md at all — this project has no always-loaded instructions.");
+else if (!/agent-os:(feature-cartographer|builder|reviewer)/.test(read(join(ROOT, "CLAUDE.md")) || ""))
+  flag("INFO", "CLAUDE.md does not say when to use the agent-os agents — add the \"Agents in this project\" section (references/establishing.md, Step 4b).");
 
 // ---------------------------------------------------------- rules
 const rulesDir = join(ROOT, ".claude/rules");
@@ -66,6 +71,27 @@ for (const f of ruleFiles) {
   if (!scoped) { residentBytes += t.length; flag("WARN", `.claude/rules/${f} has no paths: frontmatter, so it loads every session like CLAUDE.md.`); }
 }
 
+// Generated copies edited in place are reverted by the next `sync`, silently.
+// A copy whose source body no longer appears in it has drifted.
+const srcRulesDir = join(ROOT, ".agent-os/rules");
+if (existsSync(srcRulesDir)) {
+  const body = (t) => (t.startsWith("---\n") && t.indexOf("\n---\n", 3) !== -1 ? t.slice(t.indexOf("\n---\n", 3) + 5) : t).trim();
+  const drifted = [], orphans = [];
+  for (const f of ruleFiles) {
+    const gen = read(join(rulesDir, f)) || "";
+    if (!gen.includes("agent-os: generated from .agent-os/")) continue;
+    const src = read(join(srcRulesDir, f));
+    if (src === null) { orphans.push(f); continue; }
+    if (!gen.includes(body(src))) drifted.push(f);
+  }
+  say(`  source .agent-os/rules/ — ${drifted.length ? `${drifted.length} generated cop(ies) DRIFTED` : "generated copies match"}`);
+  for (const f of drifted) {
+    say(`  DRIFT ${f}`);
+    flag("WARN", `.claude/rules/${f} was edited in place and differs from .agent-os/rules/${f} — the next sync reverts it. Port the edit to the source, then sync.`);
+  }
+  for (const f of orphans) flag("WARN", `.claude/rules/${f} is generated but .agent-os/rules/${f} no longer exists — delete it or restore its source.`);
+}
+
 // ---------------------------------------------------------- hooks
 const readJson = (p) => { const t = read(p); if (!t) return null; try { return JSON.parse(t); } catch { return "INVALID"; } };
 const projSettingsPath = join(ROOT, ".claude/settings.json");
@@ -83,6 +109,8 @@ else {
       const m = cmd.match(/\$\{CLAUDE_PROJECT_DIR\}\/([^"']+)/);
       if (!m) { say(`  ok   ${evt.padEnd(14)} ${cmd.slice(0, 60)}`); continue; }
       const target = m[1], exists = existsSync(join(ROOT, target));
+      if (/cartographer-reminder/.test(target))
+        flag("INFO", `${target} duplicates the plugin's own pre-edit reminder — remove the project copy and its hook entry.`);
       say(`  ${exists ? "ok  " : "FAIL"} ${evt.padEnd(14)} ${target}${exists ? "" : "  <- TARGET MISSING"}`);
       if (!exists) flag("FAIL", `${evt} hook points at ${target}, which does not exist. It fires at a missing path every session.`);
     }
@@ -151,6 +179,11 @@ for (const [label, dir] of [["agent memory", join(ROOT, ".claude/agent-memory")]
     const dupes = slugs.filter((s, i) => slugs.indexOf(s) !== i);
     if (dupes.length) flag("WARN", `${agent}: near-duplicate topic filenames (hyphen/underscore variants). Merge them.`);
     if (idx && idx.split("\n").length > 200) flag("WARN", `${agent}: MEMORY.md over 200 lines — everything past that is dropped at startup.`);
+    // An agent that writes `.claude/agent-memory/<agent>/x.md` relative to its
+    // own memory directory nests a copy of the tree inside it.
+    const nested = ls(adir).filter((e) => { try { return statSync(join(adir, e)).isDirectory(); } catch { return false; } });
+    for (const d of nested)
+      flag("WARN", `${agent}/${d}/ is a folder inside agent memory${d === ".claude" ? " — a memory write resolved against the wrong root" : ""}. Move any topic files up into ${agent}/ and delete it.`);
   }
 }
 if (!existsSync(join(ROOT, ".claude/agent-memory")) && !existsSync(join(ROOT, ".claude/agent-memory-local")))
@@ -194,6 +227,21 @@ else if (gs) {
   say(`  SessionStart in user scope${" ".repeat(7)}${(gs.hooks || {}).SessionStart ? "yes" : "no"}`);
 } else say("  settings.json                    absent");
 
+// Git write protection and the task tools, wherever either is set.
+{
+  const norm = (r) => r.replace(/:\*\)$/, " *)").replace(/\s+/g, " ");
+  const denyOf = (st) => new Set(((st && st !== "INVALID" && st.permissions?.deny) || []).map(norm));
+  const envOn = (st) => st && st !== "INVALID" && ["1", "true", true].includes((st.env || {})[TODO_ENV]);
+  const u = denyOf(gs), pj = denyOf(projSettings);
+  const uHave = GIT_DENY.filter((r) => u.has(norm(r))).length, pHave = GIT_DENY.filter((r) => pj.has(norm(r))).length;
+  say(`  git write protection            user ${uHave}/${GIT_DENY.length}  project ${pHave}/${GIT_DENY.length}`);
+  say(`  env.${TODO_ENV}  user ${envOn(gs) ? "on" : "off"}  project ${envOn(projSettings) ? "on" : "off"}`);
+  if (uHave < GIT_DENY.length || pHave < GIT_DENY.length)
+    flag("INFO", `git write protection incomplete (user ${uHave}/${GIT_DENY.length}, project ${pHave}/${GIT_DENY.length}) — the settings pass applies it.`);
+  if (!envOn(gs) && !envOn(projSettings))
+    flag("INFO", `${TODO_ENV} is not on in user or project settings — the settings pass turns it on.`);
+}
+
 // ---------------------------------------------------------- stack + scale
 say();
 say("PROJECT");
@@ -297,13 +345,36 @@ if (rec.length) flag("INFO", `${rec.length} extension(s) this project could use
 
 // ---------------------------------------------------------- mode
 const hasLayer = residentBytes > 0 || ruleFiles.length > 0;
-const mapped = existsSync(join(ROOT, ".claude/agent-memory/agent-os-feature-cartographer"));
+// "Mapped" means the architecture map exists. Feature maps are built lazily —
+// the first change to a feature maps it, and the pre-edit hook reminds — so
+// coverage is reported honestly rather than used as a pass/fail gate.
+const cov = coverage(ROOT, { stale: true });
+const mapped = !!cov.dir && cov.architecture;
+say();
+say("CARTOGRAPHER");
+say(`  memory${" ".repeat(27)}${cov.dir ? cov.dir.slice(ROOT.length + 1) : "none yet"}`);
+say(`  architecture map${" ".repeat(17)}${cov.architecture ? "present" : "MISSING"}`);
+if (cov.features.length) {
+  const pct = Math.round((cov.mapped.length / cov.features.length) * 100);
+  say(`  features mapped${" ".repeat(18)}${cov.mapped.length} of ${cov.features.length} (${pct}%) under ${cov.parents.join(", ")}`);
+  if (cov.mapped.length) say(`    ${cov.mapped.map((f) => f.name).join(", ")}`);
+  for (const f of cov.outdated) say(`  STALE ${f.name.padEnd(26)} mapped ${f.date}, code changed ${f.changed}  (${f.map})`);
+  if (cov.mapped.length < cov.features.length)
+    flag("INFO", `${cov.features.length - cov.mapped.length} of ${cov.features.length} features have no cartographer map. They are mapped on first change; map the ones in active work now with /agent-os:map.`);
+  if (cov.outdated.length)
+    flag("INFO", `${cov.outdated.length} map(s) older than their feature's last commit (${cov.outdated.map((f) => f.name).join(", ")}) — the cartographer re-checks them on next use.`);
+} else say(`  features${" ".repeat(25)}no feature directories found — set "claude.features" in .agent-os/config.json`);
 let MODE;
 if (srcFiles < 5 && !hasLayer) MODE = "TOO-EARLY";
 else if (!hasLayer) MODE = "ESTABLISH";
 else if (anyLegacy || findings.some((f) => f.startsWith("WARN") || f.startsWith("FAIL"))) MODE = "MIGRATE";
 else if (!mapped) MODE = "MAP";
 else MODE = "MAINTAIN";
+// ---------------------------------------------------------- setup state
+// Install and settings, as opposed to MODE, which is about the context layer.
+say();
+for (const l of describeState(setupState(ROOT))) say(l);
+
 say();
 say(`MODE  ${MODE}`);
 say({
@@ -311,7 +382,7 @@ say({
   ESTABLISH:   "  Real code, no context layer. Build one FROM THE CODE: read\n  references/establishing.md. Do not invent conventions.",
   MIGRATE:     "  A layer exists but has problems. Fix the findings below;\n  read references/migrating.md for anything legacy.",
   MAP:         "  Layer is healthy but the codebase has never been mapped. Build the\n  architecture map: read references/establishing.md, 'Map the architecture'.",
-  MAINTAIN:    "  Layer is healthy and the codebase is mapped. Nothing to set up.",
+  MAINTAIN:    `  Layer is healthy and the architecture is mapped${cov.features.length ? ` (${cov.mapped.length} of ${cov.features.length} features)` : ""}.\n  Nothing to set up; remaining features are mapped as they are changed.`,
 }[MODE]);
 
 // ---------------------------------------------------------- verdict