@dotdotgod/pi 0.1.21

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2026 JooYoung Kim
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,120 @@
+# @dotdotgod/pi
+
+[![npm version](https://img.shields.io/npm/v/@dotdotgod/pi.svg)](https://www.npmjs.com/package/@dotdotgod/pi) [![GitHub](https://img.shields.io/badge/GitHub-dotdotgod%2Fdotdotgod-kit-181717?logo=github)](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/pi) [![License: Elastic 2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](../../LICENSE)
+
+> **Change a file, know what else must be checked.**
+
+```bash
+$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact
+```
+
+```text
+docs:
+- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
+- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
+- docs/spec/LOAD_PROJECT.md (35.8; related_doc, semantic_similarity)
+
+tests:
+- packages/cli/test/core.test.mjs (78.6; semantic_similarity, incoming:semantic_similarity, verified_by)
+- packages/cli/test/e2e.test.mjs (51.4; verified_by)
+
+files:
+- packages/cli/src/core.mjs (100; changed-file)
+- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
+```
+
+`graph impact` ranks the specs, tests, architecture notes, config docs, and source files most likely to matter for a change. `--compact` keeps the result agent-facing: grouped by docs/tests/files and annotated with the reasons each item is likely relevant. It uses the project-memory graph built from Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, and deterministic routing hints.
+
+Pi adapter for dotdotgod's context curation workflow. It gives Pi the most complete dotdotgod loop: initialize the fixed load-context surface, use explicit maintained graph links for impact-aware planning, execute verified steps, and archive completed work as future project memory.
+
+Use this package when you want Pi to make repository work start from stable specs, tests, architecture, active plans, archive maps, and graph/cache metadata instead of raw chat history. During the loop, agents help keep README routes, traceability, plans, and archives current so `graph impact` quality stays useful over time.
+
+## Start Here: Run the Project Initializer Skill
+
+After installing the package, open Pi in your repository and ask it to initialize or normalize the project memory scaffold. The bundled skill is named `project-initializer`; it uses `dotdotgod init` when the CLI is available, but it also includes a shell fallback.
+
+```bash
+pi install npm:@dotdotgod/pi
+```
+
+Use natural language in Pi:
+
+```text
+Initialize this project with dotdotgod.
+Set up AGENTS.md, CLAUDE.md, CODEX.md, and docs folders.
+Create a doc-first project baseline for this repository.
+```
+
+A good first-run flow is:
+
+1. Install the package.
+2. Start Pi in the target repository.
+3. Ask: `Initialize this project with dotdotgod.`
+4. Review the files the skill plans to create or skip.
+5. Let the skill create the scaffold.
+6. Run `/dd:load` to load bounded project memory.
+7. Use `/plan` before implementation work.
+
+## What You Get
+
+- **Project initializer skill:** create `AGENTS.md`, thin `CLAUDE.md`/`CODEX.md`, docs indexes, active-plan space, archive map, and local memory/cache ignores.
+- **Task-directed loading:** `/dd:load` starts from `dotdotgod load-snapshot` when available, then reads only relevant docs from the fixed memory surface.
+- **Safe planning:** `/plan` keeps source/config changes blocked while the agent writes or updates durable task intent under `docs/plan/`.
+- **Impact-aware context shaping:** Plan Mode can use `dotdotgod expand --with-impact` for explicit `[[...]]` refs and `expand --fuzzy --with-impact` for high-signal natural references from the maintained graph.
+- **Execution continuity:** completed plan steps are reported with explicit `[DONE:n]` markers so progress survives long sessions and compaction.
+- **Reusable history:** completed work moves to `docs/archive/plan/`, while `docs/archive/README.md` remains the lightweight history map.
+- **Cross-agent conventions:** the same `AGENTS.md`, docs, plan, and archive structure works with dotdotgod's CLI, Claude Code, and Codex packages.
+
+## The Memory Shape Initialized by the Skill
+
+```text
+AGENTS.md                    # canonical working rules for agents
+CLAUDE.md                    # thin Claude Code pointer to AGENTS.md
+CODEX.md                     # thin Codex pointer to AGENTS.md
+docs/
+  README.md                  # project documentation map
+  spec/README.md             # behavior, requirements, product truth
+  arch/README.md             # architecture, conventions, boundaries
+  test/README.md             # verification strategy and smoke tests
+  plan/README.md             # active local plans, ignored by git
+  archive/README.md          # completed-work history map, ignored by git
+```
+
+By default, `docs/spec/**` has two roles: it is stable shared/fresh project memory, and it is the traceability-enforced behavior-spec path. Those knobs are separate: projects can customize memory classification with `memory.areas` and traceability enforcement with `traceability.required` / `traceability.exclude`.
+
+## Graph and Bounded Loading
+
+The Pi adapter relies on the CLI graph when available but does not ask agents to read a giant graph report. `load-snapshot` returns bounded cache status, graph size, memory areas, communities, and archive policy. `graph impact` and reference expansion use explicit maintained links to surface related specs, tests, source, and config for a change before broad scanning.
+
+The graph uses more than traceability blocks: Markdown links, README routes, headings, package metadata, memory-area membership, commands, tests, and deterministic routing hints all contribute. Archive bodies are excluded by default; `docs/archive/README.md` is the map.
+
+## Commands
+
+```text
+/plan      Toggle safe planning mode.
+/todos     Show tracked plan progress during execution.
+/load      Load project memory for the current repository.
+/dd:load   Stable namespaced alias for project memory loading.
+```
+
+## Included
+
+- `project-initializer` skill: the starting point for `AGENTS.md`, thin agent entrypoints, docs folders, README indexes, and local memory/cache ignores.
+- `plan-mode` extension: read-first planning mode with restricted tools, optional `--plan-extra-tools`, docs/plan writes, execution tracking, tiered hidden prompts, and `/todos`.
+- `load-project` extension: read-only project context loading through `/load` and `/dd:load`.
+
+## Local Development
+
+```bash
+pi install /Users/dotdot/Workspace/dotdotgod/packages/pi
+pnpm --filter @dotdotgod/pi run verify
+pnpm --filter @dotdotgod/pi run pack:dry-run
+```
+
+## Learn More
+
+See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [`docs/concept/CONTEXT_CURATION.md`](../../docs/concept/CONTEXT_CURATION.md), [`docs/concept/CONTEXT_MECHANICS.md`](../../docs/concept/CONTEXT_MECHANICS.md), [`docs/spec/MEMORY_AREA_CONFIG.md`](../../docs/spec/MEMORY_AREA_CONFIG.md), and [`docs/spec/TRACEABILITY_CONFIG.md`](../../docs/spec/TRACEABILITY_CONFIG.md).
+
+## Compared with Graphify-Style Memory
+
+The Pi adapter focuses on workflow: initialize the project memory scaffold, load a bounded snapshot, plan before source edits, and archive completed work for future sessions. Graph/cache output is a compact map; detail still comes from targeted file reads.

package/extensions/context-metrics/utils.ts

@@ -0,0 +1,66 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { execSync } from "node:child_process";
+
+export interface ContextMetricEvent {
+	event: string;
+	cwd: string;
+	data?: Record<string, unknown>;
+}
+
+function git(cwd: string, command: string): string | undefined {
+	try {
+		return execSync(`git ${command}`, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+	} catch {
+		return undefined;
+	}
+}
+
+function defaultMetricsPath(cwd: string): string {
+	const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+	return join(cwd, "docs", "archive", "report", "context-metrics", `${stamp}.jsonl`);
+}
+
+export function isContextDebugEnabled(getFlag: (name: string) => unknown): boolean {
+	return getFlag("dd-context-debug") === true;
+}
+
+export function recordContextMetric(
+	ctx: ExtensionContext,
+	getFlag: (name: string) => unknown,
+	event: string,
+	data: Record<string, unknown> = {},
+): void {
+	if (!isContextDebugEnabled(getFlag)) return;
+
+	const configuredPath = getFlag("dd-context-debug-output");
+	const outputPath = typeof configuredPath === "string" && configuredPath.trim()
+		? configuredPath.trim()
+		: defaultMetricsPath(ctx.cwd);
+	const absolutePath = outputPath.startsWith("/") ? outputPath : join(ctx.cwd, outputPath);
+	const usage = ctx.getContextUsage();
+	const entry = {
+		event,
+		timestamp: new Date().toISOString(),
+		cwd: ctx.cwd,
+		usage: usage
+			? { tokens: usage.tokens ?? null, contextWindow: usage.contextWindow ?? null, percent: usage.percent ?? null }
+			: null,
+		git: {
+			commit: git(ctx.cwd, "rev-parse --short HEAD") ?? null,
+			dirty: Boolean(git(ctx.cwd, "status --short")),
+		},
+		...data,
+	};
+
+	try {
+		mkdirSync(dirname(absolutePath), { recursive: true });
+		appendFileSync(absolutePath, `${JSON.stringify(entry)}\n`);
+	} catch (error) {
+		if (ctx.hasUI) {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Context metrics debug write failed: ${message}`, "warning");
+		}
+	}
+}

package/extensions/load-project/README.md

@@ -0,0 +1,44 @@
+# Load Project Extension
+
+Pi extension that starts a read-only project memory loading turn for the current working directory.
+
+See the workspace behavior contract in `docs/spec/LOAD_PROJECT.md` and the extension boundary notes in `docs/arch/EXTENSION_ARCHITECTURE.md`.
+
+## Commands
+
+- `/load` — load current project memory.
+- `/dd:load` — stable namespaced alias for command-conflict avoidance.
+
+## Behavior
+
+The command checks for the expected dotdotgod scaffold, then sends a read-only loader prompt to the agent.
+
+Baseline files and directories include:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `CODEX.md`
+- `README.md`
+- `docs/README.md`
+- `docs/spec/`
+- `docs/test/`
+- `docs/arch/`
+- `docs/plan/`
+- `docs/archive/`
+
+The agent is instructed to:
+
+- start with `AGENTS.md`, `README.md`, and `docs/README.md` when available
+- follow local `README.md` indexes
+- follow domain directories such as `docs/<area>/<domain>/README.md`
+- follow expanded convention directories such as `docs/arch/conventions/README.md`
+- list `docs/plan` first, then selectively read relevant active plan files
+- use `docs/archive/README.md` as the archive history map and avoid scanning archive bodies by default
+- distinguish completed plan archives under `docs/archive/plan/` from temporary reports under `docs/archive/report/` when targeted archive lookup is needed
+- summarize project purpose, working rules, commands, docs map, architecture/code conventions, active plans, relevant archives, and TODO/TBD items
+
+## Notes
+
+- The command itself does not modify files.
+- `/load` may conflict with other extensions, so `/dd:load` is always registered as the stable dotdotgod alias.
+- Future indexing/search behavior should extend this runtime entrypoint.

package/extensions/load-project/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Project Memory Loader Extension
+ *
+ * Provides /load and /dd:load commands for loading dotdotgod docs.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { recordContextMetric } from "../context-metrics/utils.js";
+import { buildLoadPrompt, collectSnapshot, estimateTextMetrics, hasOtherLoadCommand, runDotdotgodLoadSnapshot } from "./utils.js";
+
+async function runLoadCommand(pi: ExtensionAPI, ctx: ExtensionCommandContext, args: string, commandName: "load" | "dd:load") {
+	const snapshot = collectSnapshot(ctx.cwd);
+	const loadSnapshot = runDotdotgodLoadSnapshot(ctx.cwd);
+	const conflict = hasOtherLoadCommand(pi.getCommands());
+
+	if (ctx.hasUI && conflict) {
+		ctx.ui.notify(
+			"Another /load command was detected. dotdotgod provides /dd:load as the stable alias.",
+			"info",
+		);
+	}
+
+	const prompt = buildLoadPrompt(ctx.cwd, args, snapshot, loadSnapshot);
+	const promptMetrics = estimateTextMetrics(prompt);
+	recordContextMetric(ctx, (name) => pi.getFlag(name), "load-project:before-send", {
+		commandName,
+		promptMetrics,
+		directorySummaryPaths: snapshot.directories.map((directory) => directory.path),
+		loadSnapshot: {
+			ok: loadSnapshot.ok,
+			command: loadSnapshot.command,
+			error: loadSnapshot.error,
+		},
+	});
+	const deliverAs = ctx.isIdle() ? undefined : "followUp";
+	pi.sendUserMessage(prompt, deliverAs ? { deliverAs } : undefined);
+	pi.appendEntry("project-memory-load", {
+		commandName,
+		entryCount: ctx.sessionManager.getEntries().length,
+		promptMetrics,
+		loadSnapshot: {
+			ok: loadSnapshot.ok,
+			command: loadSnapshot.command,
+			error: loadSnapshot.error,
+		},
+	});
+	recordContextMetric(ctx, (name) => pi.getFlag(name), "load-project:after-send", { commandName, deliverAs: deliverAs ?? "immediate" });
+
+	if (ctx.hasUI) {
+		const queued = deliverAs === "followUp" ? " It will run as a follow-up after the current turn finishes." : "";
+		ctx.ui.notify(`Started project memory loading with /${commandName}.${queued}`, "info");
+	}
+}
+
+export default function loadProjectExtension(pi: ExtensionAPI): void {
+	pi.registerFlag("dd-context-debug", {
+		description: "Record dotdotgod context measurement debug events to a local JSONL file",
+		type: "boolean",
+		default: false,
+	});
+	pi.registerFlag("dd-context-debug-output", {
+		description: "Path for dotdotgod context measurement debug JSONL output",
+		type: "string",
+		default: "",
+	});
+
+	pi.registerCommand("load", {
+		description: "Load dotdotgod docs for the current project",
+		handler: async (args, ctx) => runLoadCommand(pi, ctx, args, "load"),
+	});
+
+	pi.registerCommand("dd:load", {
+		description: "Load dotdotgod docs for the current project (namespaced alias)",
+		handler: async (args, ctx) => runLoadCommand(pi, ctx, args, "dd:load"),
+	});
+}