@warpgogol/forge 2.8.0 → 2.8.2

package/src/tests/doctor-domain.test.ts

@@ -0,0 +1,113 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for domain-aware forge.doctor (RFC-0640).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0640: initial domain-aware doctor tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-domain-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+test("doctor reports default software domain when no forge.yaml", async () => {
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  expect(result.data!.domain).toBeDefined();
+  expect(result.data!.domain!.domain).toBe("software");
+  expect(result.data!.domain!.source).toBe("default");
+});
+
+test("doctor reports domain from forge.yaml when present", async () => {
+  await writeFile(
+    join(tempDir, "forge.yaml"),
+    `schema: "forge/config@1"\nproject:\n  name: test-project\n  stack: []\n  packageManager: pnpm\n  domain: video\npaths:\n  rfcsDir: docs/rfcs\n  adrsDir: docs/adrs\n  plansDir: docs/plans\n  auditsDir: docs/audits\n  specsDir: docs/specs\n  skillsDir: .agents/skills\n  sessionsDir: docs/sessions\n`,
+    "utf8",
+  );
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  expect(result.data!.domain).toBeDefined();
+  expect(result.data!.domain!.domain).toBe("video");
+  expect(result.data!.domain!.source).toBe("forge.yaml");
+});
+
+test("doctor includes domain-info check in checks array", async () => {
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const domainCheck = result.data!.checks.find((c) => c.name === "domain-info");
+  expect(domainCheck).toBeDefined();
+  expect(domainCheck!.status).toBe("pass");
+});
+
+test("doctor --strict does not affect invariant reporting (reserved for future use)", async () => {
+  await mkdir(join(tempDir, "packages", "forge", "profiles"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "forge", "profiles", "test.yaml"),
+    `schema: "forge/stack-profile@1"\nid: test\ndisplayName: Test\ndetect:\n  anyOf: ["package.json"]\nworkspace:\n  dirs: ["packages"]\n  files: []\ninstall: []\ndomain: video\ninvariants:\n  - id: VIDEO-01\n    rule: "All videos must have audio"\n    severity: error\n`,
+    "utf8",
+  );
+  await writeFile(
+    join(tempDir, "forge.yaml"),
+    `schema: "forge/config@1"\nproject:\n  name: test-project\n  stack: ["test"]\n  packageManager: pnpm\npaths:\n  rfcsDir: docs/rfcs\n  adrsDir: docs/adrs\n  plansDir: docs/plans\n  auditsDir: docs/audits\n  specsDir: docs/specs\n  skillsDir: .agents/skills\n  sessionsDir: docs/sessions\n`,
+    "utf8",
+  );
+
+  const input: ForgeCommandInput = { argv: [], flags: { strict: true } };
+  const result = await runDoctor(input, makeContext());
+
+  const invariantsCheck = result.data!.checks.find((c) => c.name === "domain-invariants");
+  expect(invariantsCheck).toBeDefined();
+  // --strict elevates warn to fail for domain-invariants and profile-validate,
+  // but invariants check is "pass" here (invariants declared), so no elevation
+  expect(invariantsCheck!.status).toBe("pass");
+});
+
+test("doctor runs nested AGENTS.md check for non-software domain (RFC-0640 fix)", async () => {
+  await writeFile(
+    join(tempDir, "forge.yaml"),
+    `schema: "forge/config@1"\nproject:\n  name: test-project\n  stack: []\n  packageManager: pnpm\n  domain: video\npaths:\n  rfcsDir: docs/rfcs\n  adrsDir: docs/adrs\n  plansDir: docs/plans\n  auditsDir: docs/audits\n  specsDir: docs/specs\n  skillsDir: .agents/skills\n  sessionsDir: docs/sessions\n`,
+    "utf8",
+  );
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  // RFC-0640 fix: nested AGENTS.md check now runs for all domains
+  // (previously gated by isSoftwareDomain, which skipped non-software domains)
+  const nestedCheck = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(nestedCheck).toBeDefined();
+  expect(nestedCheck!.status).toBe("pass");
+});

package/src/tests/exploration-handlers.test.ts

@@ -0,0 +1,256 @@
+import { test, expect, describe, beforeAll, afterAll } from "vitest";
+import { join } from "node:path";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import type { ForgeCommandInput, ForgeRuntimeContext, ForgeFlagValue } from "../../src/types.ts";
+import { runExplorationList } from "../../os/exploration/handlers/list.ts";
+import { runExplorationShow } from "../../os/exploration/handlers/show.ts";
+import { runExplorationArchive } from "../../os/exploration/handlers/archive.ts";
+import type {
+  ExplorationListResult,
+  ExplorationShowResult,
+  ExplorationArchiveResult,
+} from "../../os/exploration/types.ts";
+
+async function makeTempDir(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "forge-exploration-test-"));
+}
+
+function makeInput(flags: Record<string, ForgeFlagValue> = {}): ForgeCommandInput {
+  return { argv: [], flags };
+}
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      success: () => {},
+      section: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+const SAMPLE_NOTE = `---
+id: self-hosted-fonts
+title: "Self-hosted fonts vs CDN"
+createdAt: 2026-08-06
+status: open
+related: []
+---
+
+# Exploration: Self-hosted fonts vs CDN
+
+## Idea
+
+Should we self-host fonts or keep using the CDN?
+
+## Options
+
+### Option 1: Self-host
+- **Approach:** Download fonts and serve locally.
+- **Trade-offs:** More bandwidth, better privacy.
+
+### Option 2: Keep CDN
+- **Approach:** Continue using Google Fonts CDN.
+- **Trade-offs:** Less control, faster initial load.
+`;
+
+const ARCHIVED_NOTE = `---
+id: old-idea
+title: "Old idea that was explored"
+createdAt: 2026-07-01
+status: archived
+related: [RFC-0700]
+---
+
+# Exploration: Old idea
+
+Already archived.
+`;
+
+describe("exploration.list", () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = await makeTempDir();
+    await mkdir(join(dir, "docs/explorations"), { recursive: true });
+    await writeFile(join(dir, "docs/explorations/self-hosted-fonts.md"), SAMPLE_NOTE, "utf-8");
+    await writeFile(join(dir, "docs/explorations/old-idea.md"), ARCHIVED_NOTE, "utf-8");
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("lists all exploration notes", async () => {
+    const result = await runExplorationList(makeInput(), makeContext(dir));
+    const data = result.data as ExplorationListResult;
+
+    expect(data.command).toBe("exploration.list");
+    expect(data.status).toBe("ok");
+    expect(data.count).toBe(2);
+    expect(data.explorations).toHaveLength(2);
+
+    const ids = data.explorations.map((e) => e.id).sort();
+    expect(ids).toEqual(["old-idea", "self-hosted-fonts"]);
+  });
+
+  test("filters by status", async () => {
+    const result = await runExplorationList(makeInput({ status: "archived" }), makeContext(dir));
+    const data = result.data as ExplorationListResult;
+
+    expect(data.count).toBe(1);
+    expect(data.explorations[0]!.id).toBe("old-idea");
+    expect(data.explorations[0]!.status).toBe("archived");
+  });
+
+  test("returns empty list when directory does not exist", async () => {
+    const emptyDir = await makeTempDir();
+    try {
+      const result = await runExplorationList(makeInput(), makeContext(emptyDir));
+      const data = result.data as ExplorationListResult;
+
+      expect(data.command).toBe("exploration.list");
+      expect(data.status).toBe("ok");
+      expect(data.count).toBe(0);
+      expect(data.explorations).toEqual([]);
+      expect(result.exitCode).toBeUndefined();
+    } finally {
+      await rm(emptyDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("exploration.show", () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = await makeTempDir();
+    await mkdir(join(dir, "docs/explorations"), { recursive: true });
+    await writeFile(join(dir, "docs/explorations/self-hosted-fonts.md"), SAMPLE_NOTE, "utf-8");
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("shows the full content of an exploration note", async () => {
+    const result = await runExplorationShow(
+      makeInput({ id: "self-hosted-fonts" }),
+      makeContext(dir),
+    );
+    const data = result.data as ExplorationShowResult;
+
+    expect(data.command).toBe("exploration.show");
+    expect(data.status).toBe("ok");
+    expect(data.note.id).toBe("self-hosted-fonts");
+    expect(data.note.title).toBe("Self-hosted fonts vs CDN");
+    expect(data.note.status).toBe("open");
+    expect(data.note.createdAt).toBe("2026-08-06");
+    expect(data.note.related).toEqual([]);
+    expect(data.note.body).toContain("# Exploration: Self-hosted fonts vs CDN");
+  });
+
+  test("returns exit code 1 when slug not found", async () => {
+    const result = await runExplorationShow(makeInput({ id: "nonexistent" }), makeContext(dir));
+    const data = result.data as ExplorationShowResult;
+
+    expect(data.status).toBe("error");
+    expect(result.exitCode).toBe(1);
+  });
+
+  test("returns exit code 1 when --id is missing", async () => {
+    const result = await runExplorationShow(makeInput(), makeContext(dir));
+    const data = result.data as ExplorationShowResult;
+
+    expect(data.status).toBe("error");
+    expect(result.exitCode).toBe(1);
+  });
+});
+
+describe("exploration.archive", () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = await makeTempDir();
+    await mkdir(join(dir, "docs/explorations"), { recursive: true });
+    await writeFile(join(dir, "docs/explorations/self-hosted-fonts.md"), SAMPLE_NOTE, "utf-8");
+    await writeFile(join(dir, "docs/explorations/old-idea.md"), ARCHIVED_NOTE, "utf-8");
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("transitions status from open to archived", async () => {
+    const result = await runExplorationArchive(
+      makeInput({ id: "self-hosted-fonts" }),
+      makeContext(dir),
+    );
+    const data = result.data as ExplorationArchiveResult;
+
+    expect(data.command).toBe("exploration.archive");
+    expect(data.status).toBe("ok");
+    expect(data.id).toBe("self-hosted-fonts");
+    expect(data.previousStatus).toBe("open");
+    expect(data.newStatus).toBe("archived");
+
+    const content = await readFile(join(dir, "docs/explorations/self-hosted-fonts.md"), "utf-8");
+    expect(content).toContain("status: archived");
+  });
+
+  test("adds RFC id to related field", async () => {
+    const result = await runExplorationArchive(
+      makeInput({ id: "self-hosted-fonts", rfc: "RFC-0710" }),
+      makeContext(dir),
+    );
+    const data = result.data as ExplorationArchiveResult;
+
+    expect(data.related).toContain("RFC-0710");
+
+    const content = await readFile(join(dir, "docs/explorations/self-hosted-fonts.md"), "utf-8");
+    expect(content).toContain("RFC-0710");
+  });
+
+  test("is idempotent when already archived", async () => {
+    const result = await runExplorationArchive(makeInput({ id: "old-idea" }), makeContext(dir));
+    const data = result.data as ExplorationArchiveResult;
+
+    expect(data.status).toBe("ok");
+    expect(data.previousStatus).toBe("archived");
+    expect(data.newStatus).toBe("archived");
+    expect(result.exitCode).toBe(0);
+  });
+
+  test("returns exit code 1 when slug not found", async () => {
+    const result = await runExplorationArchive(makeInput({ id: "nonexistent" }), makeContext(dir));
+    const data = result.data as ExplorationArchiveResult;
+
+    expect(data.status).toBe("error");
+    expect(result.exitCode).toBe(1);
+  });
+
+  test("returns exit code 1 when --id is missing", async () => {
+    const result = await runExplorationArchive(makeInput(), makeContext(dir));
+    const data = result.data as ExplorationArchiveResult;
+
+    expect(data.status).toBe("error");
+    expect(result.exitCode).toBe(1);
+  });
+
+  test("rejects invalid slug (non-kebab-case)", async () => {
+    const result = await runExplorationArchive(
+      makeInput({ id: "Invalid_Slug!" }),
+      makeContext(dir),
+    );
+    const data = result.data as ExplorationArchiveResult;
+
+    expect(data.status).toBe("error");
+    expect(result.exitCode).toBe(1);
+  });
+});

package/src/tests/fixtures/agents-generate-business-before.txt

@@ -0,0 +1,288 @@
+<!--
+  GENERATED. Do not change this line unless the file contains project specific changes.
+  DO NOT EDIT THIS FILE. Changes are overwritten on the next build.
+  Owner command: forge.agents.generate
+  Edit instead: the forge.agents.generate generator source (not this file).
+  Regenerate:   forge forge.agents.generate
+-->
+
+
+<!-- Root AGENTS.md template for business register projects.
+     Static prose only — dynamic sections (skills, capabilities, behavioral layer)
+     are inserted at the dynamicSections marker by runAgentsGenerate.
+     Placeholders: projectName, projectStack, projectPm,
+     rfcsDir, adrsDir, plansDir, auditsDir, specsDir,
+     skillsDir, dynamicSections -->
+# Agent Guide: test-project
+
+> This file is generated by `forge.agents.generate` from `forge.yaml`.
+> Do not edit by hand — edit `forge.yaml` and regenerate.
+
+## Project
+
+- **Name:** test-project
+- **Stack:** typescript
+- **Package manager:** pnpm
+
+## Paths
+
+- RFCs: `docs/rfcs`
+- ADRs: `docs/adrs`
+- Plans: `docs/plans`
+- Audits: `docs/audits`
+- Specs: `docs/specs`
+- Skills: `.agents/skills`
+
+## Skills
+
+| Name | Category | Invocation | Concerns |
+| --- | --- | --- | --- |
+| fo-add-tests | fo | user | code-mutation |
+| fo-architecture | fo | user | document-only |
+| fo-compass-annotate | fo | user | content-mutation |
+| fo-design-summit | fo | user | document-only |
+| fo-doc-audit | fo | user | document-only |
+| fo-explore | fo | user | document-only |
+| fo-extract-dna | fo | user | document-only |
+| fo-fix | fo | user | code-mutation |
+| fo-handoff | fo | user | document-only |
+| fo-harvest | fo | user | code-mutation |
+| fo-idea | fo | user | document-only |
+| fo-idea-audit | fo | user | read-only |
+| fo-idea-create-adr | fo | user | document-only |
+| fo-idea-create-rfc | fo | user | document-only |
+| fo-idea-enhance | fo | user | document-only |
+| fo-idea-i-just-want-to-see-the-plan | fo | user | document-only |
+| fo-idea-i-just-want-to-see-the-result | fo | user | code-mutation |
+| fo-idea-implement | fo | user | code-mutation |
+| fo-idea-plan | fo | user | document-only |
+| fo-idea-status | fo | user | read-only |
+| fo-knowledge-distill | fo | user | document-only |
+| fo-memory-sync | fo | user | content-mutation |
+| fo-qa | fo | user | document-only |
+| fo-review | fo | user | read-only |
+| fo-session-retro | fo | user | document-only |
+| fo-session-save | fo | user | document-only |
+| fo-spec-ingest | fo | user | document-only |
+| fo-step-commit | fo | model | code-mutation |
+| fo-triage | fo | user | document-only |
+| forge-bootstrap | meta | user | content-mutation |
+| grilling | shared | user | read-only |
+| my-preferences | shared | user | document-only |
+| port-to-forge | meta | user | code-mutation |
+| skill-create | meta | user | document-only |
+| windows-ai-tooling | shared | user | code-mutation |
+| writing-great-skills | shared | user | read-only |
+
+## Capabilities
+
+Bindings resolved from `forge.yaml`:
+
+| Key | Status | Value |
+| --- | --- | --- |
+| commands.validateRfc | resolved | `pnpm exec forge rfc.validate` |
+| commands.validateAdr | resolved | `pnpm exec forge adr.validate` |
+| commands.typecheck | absent | — |
+| commands.test | absent | — |
+| commands.scopedBuild | absent | — |
+| commands.specValidate | resolved | `pnpm exec forge spec.validate` |
+| commands.sessionSave | resolved | `pnpm exec forge session.save` |
+| paths.invariantsFile | resolved | `docs/architecture-dna.md` |
+| paths.reviewsDir | resolved | `docs/reviews` |
+| paths.handoffsDir | resolved | `docs/handoffs` |
+| paths.sessionsDir | resolved | `docs/sessions` |
+| paths.compassDocs | resolved | `docs/requirements.xml` |
+
+<!-- forge:begin behavioral-layer -->
+
+## Behavioral layer
+
+This section defines the agent's core behavioral contract. It is generated from skill `triggers` and fixed policy text. The agent MUST follow these behaviors in every session.
+
+### Intent-to-skill routing
+
+When the operator expresses an intent in natural language, the agent routes to the matching skill. The routing table is generated from `triggers` fields in skill frontmatter.
+
+| Operator says something like | Skill |
+| --- | --- |
+
+The agent uses judgment to calibrate routing — minor edits (typo fixes, small CSS changes) do not require skill invocation, while significant changes (new features, architectural decisions) do.
+
+### Auto-grilling
+
+When the operator describes a significant idea or change, the agent SHOULD proactively invoke grilling to stress-test the plan before building.
+
+- **Significant:** new feature, architectural change, new RFC/ADR, cross-workspace refactor.
+- **Minor:** typo fix, small CSS change, renaming a variable, updating a dependency version.
+- The operator can say "just do it" to skip grilling — the agent invokes `fo-idea-i-just-want-to-see-the-result` instead.
+
+### Auto-session-save
+
+The agent SHOULD auto-save sessions at the end of each session unless opted out via `PREFERENCES.md` (`saveSessions: false`). Companion-mode session saving can be opted out separately.
+
+Session save mechanism:
+1. Export the conversation as a raw ATIF file to `docs/sessions/.raw/` (create the directory with `mkdir -p docs/sessions/.raw` if it does not exist).
+2. Run `ref(forge.yaml bindings.commands.sessionSave)` to convert the raw file to structured markdown in `docs/sessions/`.
+3. If the command fails or the binding is null, create the session file manually in `docs/sessions/` with frontmatter (id, date, type, relatedRfcs).
+
+### Auto-review
+
+The agent SHOULD auto-run `fo-review` after implementing a significant change. Review results are presented in creator language — only actionable issues are highlighted.
+
+### Context awareness
+
+Before starting significant work, the agent SHOULD read recent ADRs, RFCs, and session transcripts (last 5-10 documents) to understand prior decisions and avoid conflicts. Minor edits do not require context reading.
+
+### Creator-facing communication
+
+The agent communicates in creator language — no CLI commands, no skill names, no internal jargon in user-facing text.
+
+- **Forbidden terms in user-facing text:** `pnpm`, `git commit`, `vitest`, `tsc`, `AGENTS.md`, `forge.yaml`, `RFC-XXXX`, `fo-idea`, `fo-fix`, `fo-review`.
+- **Use instead:** "I'll review the plan with you", "I'll check the code quality", "I'll prepare the changes for you".
+- CLI output and internal logs remain technical — only agent chat output uses creator language.
+
+### Adaptive learning
+
+The agent reads `.agents/operator-profile.md` at the start of each session and calibrates behavior based on the operator's known preferences, communication style, and past feedback.
+
+- The profile is local to the project, git-tracked, and can be deleted by the operator at any time.
+- Developer handoff summaries MUST NOT include `operator-profile.md` contents — only technical architecture, decisions, and code structure.
+- Sections are tagged with Zugangsstufen (Öffentlich/Vertraulich). Only Öffentlich sections are visible to co-creators.
+- Entries in `## Emotional rhythm` and `## Feedback history` expire after 90 days unless refreshed. Stale entries are marked `[expired YYYY-MM-DD]`.
+- The profile is gitignored by default to protect operator privacy.
+
+### Proactive guidance
+
+The agent offers proactive guidance at the right moment — at most once per session per topic. If declined, the suggestion is not repeated.
+
+Built-in guidance triggers:
+- **Long session** (>2 hours): suggest a break or session save.
+- **Complex change** (3+ files in one area): suggest grilling or planning.
+- **Multiple topics** in one session: suggest splitting into separate sessions.
+- **Large scope** (>500 lines changed): suggest an RFC or ADR.
+- **Unclear request**: ask clarifying questions before proceeding.
+
+### Live operator feedback
+
+The agent updates `.agents/operator-profile.md` immediately when the operator expresses a behavior preference (e.g., "I prefer shorter responses", "don't ask me about tests"). The agent confirms understanding before updating: "Just to make sure I understand — you want me to [X] from now on?"
+
+### Register parameter
+
+The current register is **business**.
+
+- **Business register:** core behavioral layer only — professional, efficient communication.
+- **Creative register:** core + extended behavioral layer — creative partnership, emotional support, companion mode.
+- The register can be changed at any time via live operator feedback. The change takes effect immediately.
+
+### Pushback policy
+
+The agent exercises two classes of pushback:
+
+1. **Purpose-drift (soft):** when the operator's request drifts from the project's stated purpose, the agent offers a gentle reminder. The operator can override without explicit confirmation.
+2. **Legal/compliance (hard):** when the operator's request may violate copyright, GDPR/DSGVO, accessibility, or license requirements, the agent refuses and explains the risk. The operator can override only with explicit confirmation that they accept the risk.
+
+### External capabilities (MCP)
+
+The agent uses a two-tier model for external capabilities:
+
+1. **Read-only autonomous:** the agent may use read-only MCP tools (web search, documentation lookup) without asking.
+2. **Connectable (offered):** the agent offers connectable capabilities (email, calendar, analytics) and lets the operator choose. The agent MUST NOT auto-select a specific provider.
+
+### Safety net and graceful failure
+
+The agent provides a safety net for the operator:
+
+- **Undo/rollback:** the agent offers undo or rollback for significant changes.
+- **Auto-recovery:** when something goes wrong, the agent attempts automatic recovery before reporting.
+- **No technical errors shown:** the agent MUST NOT show technical errors, stack traces, or error codes to the operator. Errors are translated to creator language: "Something went wrong with the preview. Let me try again."
+
+### Invisible quality
+
+The agent handles performance, accessibility, SEO, and optimization automatically. Quality is communicated as human impact, not technical metrics.
+
+- Instead of "Lighthouse score 98", say "Your site loads quickly for visitors."
+- Instead of "WCAG 2.1 AA compliant", say "Your site is accessible to all visitors."
+
+### First creation moment
+
+The first creation moment is special — the agent celebrates the operator's first creation and sets a welcoming tone.
+
+### Creative health and time awareness
+
+The agent monitors creative health and time investment:
+
+- **Project health dashboard:** the agent can provide a snapshot of project health (progress, pending items, areas needing attention).
+- **Creative balance:** the agent suggests breaks when sessions are long and reminds the operator that sustainable creative work matters more than marathon sessions.
+- **Time investment:** the agent helps the operator understand where time is being spent.
+- **Rhythm insights:** the agent shares patterns about the operator's creative rhythm (based on `operator-profile.md`).
+
+### Sharing and feedback
+
+The agent helps the operator share work and collect feedback:
+
+- **Share preview:** the agent can prepare a shareable preview without deploying.
+- **External feedback:** feedback from external reviewers is recorded in `operator-profile.md` for future reference.
+
+### Cultural awareness and multilingual support
+
+The agent is culturally aware and supports multilingual communication:
+
+- The agent uses `aiLanguage` from `PREFERENCES.md` for all communication.
+- The agent respects cultural norms and communication styles.
+- The agent does not assume a specific cultural context.
+
+### Indirect teaching
+
+The agent explains significant decisions briefly in creator language — not as lectures, but as natural context. The operator learns by seeing the agent's reasoning, not by being taught.
+
+### Ownership and collaboration
+
+Everything the operator creates belongs to them. The agent makes ownership explicit.
+
+- **Co-creation:** the agent supports collaborative work with co-creators.
+- **Developer handoff:** when the operator needs professional development help, the agent prepares a handoff with technical architecture, decisions, and code structure — excluding `operator-profile.md` contents.
+
+### Commit policy
+
+In the creative register, the agent commits all changes automatically after each completed logical step (e.g. after implementing a feature, after fixing a bug, after creating a file). The operator is never asked about git, commits, or version control. No dirty files remain at any pause point. In the business register, the agent asks before committing.
+
+- **Auto-commit does not skip verification** — the agent still runs typecheck/build before committing. Auto-commit means the agent does not ask for permission, not that it skips quality checks.
+- **Auto-commit does not fire in companion mode** — companion mode is pure creative exploration without code changes, so there is nothing to commit.
+- **Auto-commit applies to forge projects** (bootstrapped projects using `forge create`).
+
+<!-- forge:end behavioral-layer -->
+
+## Project memory layer
+
+`.agents/memory/MEMORY.md` is the curated hot store (versioned). `.agents/memory/daily/YYYY-MM-DD.md` are append-only warm logs (git-ignored).
+
+**Session-start read discipline (advisory):** At session start, read `MEMORY.md` (always), then `daily/<today>.md` and `daily/<yesterday>.md` (if present). Older daily files are cold — use grep when a task references past context.
+
+## RTK — Token Optimization
+
+Always prefix shell commands with `rtk` to minimize token consumption. RTK filters and compresses command output before it reaches the LLM context, cutting up to 90% of bash output on common operations.
+
+```bash
+rtk git status
+rtk pnpm test
+rtk ls src/
+rtk grep "pattern" src/
+rtk find "*.ts" .
+```
+
+Meta commands:
+
+```bash
+rtk gain              # Show token savings
+rtk gain --history    # Command history with savings
+rtk discover          # Find missed RTK opportunities
+rtk proxy <cmd>       # Run raw (no filtering, for debugging)
+```
+
+Use default RTK settings only — do not enable `--ultra-compact` or aggressive `read` modes unless the operator explicitly requests it.
+
+## Conventions
+
+- Use `forge.yaml` as the single source of truth for project configuration.
+- Regenerate this file with `forge.agents.generate` after changing `forge.yaml`.
+- Follow the closest `AGENTS.md` for workspace or directory details.