@dotdotgod/codex 0.1.16 → 0.1.18

package/README.md

@@ -1,19 +1,39 @@
 # @dotdotgod/codex
 
+[![npm version](https://img.shields.io/npm/v/@dotdotgod/codex.svg)](https://www.npmjs.com/package/@dotdotgod/codex) [![GitHub](https://img.shields.io/badge/GitHub-dotdotgod%2Fdotdotgod-181717?logo=github)](https://github.com/dotdotgod/dotdotgod/tree/main/packages/codex) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+
 > **Change a file, know what else must be checked.**
 
-Codex adapter for dotdotgod's context curation workflow. It packages reusable skills that help Codex load curated project memory, plan from docs before implementation, and initialize the shared agent documentation scaffold so changes start with the right specs, tests, plans, and archive map.
+Codex adapter for dotdotgod's context curation workflow. It packages reusable skills that help Codex initialize shared agent docs, load bounded project memory, and plan from docs before implementation.
+
+Impact/context in practice:
+
+```text
+dd:init creates the memory scaffold
+dd:load reads a bounded snapshot and relevant docs
+dd:plan captures durable task intent before implementation
+```
+
+The same project-memory graph that powers `dotdotgod graph impact` can surface likely related docs, tests, source, and config for changed files. The graph is not only traceability: it also uses Markdown links, README routes, headings, package metadata, memory-area membership, commands, tests, and deterministic routing hints.
 
 ## What Gets Better?
 
 - Codex can start from `AGENTS.md` and the dotdotgod docs map.
 - Load guidance prefers `dotdotgod load-snapshot <root> --json` when the CLI is available, then falls back to README-index reads.
 - Codex can use docs structure as retrieval intent: specs for behavior, architecture for rationale, tests for verification, plans for current work, and archive indexes for past decisions.
-- Product intent, design rationale, and verification standards stay in durable docs.
 - Planning work captures current intent in `docs/plan/<task-slug>/README.md` before implementation.
 - Completed plans and temporary reports use the same archive structure as Pi and Claude Code, turning outcomes into future context.
 - `dd:load`, `dd:plan`, and `dd:init` can be used as command-like trigger phrases where direct slash commands are unavailable.
 
+## Shared Memory and Traceability Model
+
+By default, `docs/spec/**` has two roles: it is stable shared/fresh project memory, and it is the traceability-enforced behavior-spec path. These concepts are independent:
+
+- `memory.areas` customizes memory classification, freshness, local/shared scope, priorities, and archive-body inclusion.
+- `traceability.required` / `traceability.exclude` customizes which markdown paths must end with `json dotdotgod` blocks.
+
+`docs/archive/README.md` is the history map. Archive bodies remain targeted historical memory and should not be read broadly by default.
+
 ## Included
 
 - Codex plugin manifest: `.codex-plugin/plugin.json`
@@ -30,6 +50,15 @@ Codex can run lifecycle hooks from trusted Codex configuration layers. dotdotgod
 
 Use hooks only when you want opt-in reminders or validation around the same workflow. See [`hooks/README.md`](hooks/README.md) for advisory examples and stricter plan-safety patterns.
 
+## Shared Contract
+
+- `AGENTS.md` remains canonical.
+- `CODEX.md` stays thin and points to `AGENTS.md`.
+- Active plans use `docs/plan/<task-slug>/README.md`.
+- Completed plans move to `docs/archive/plan/<task-slug>/`.
+- Temporary reports move to `docs/archive/report/<report-slug>/`.
+- `docs/archive/README.md` is the archive map; archive bodies should be read only when targeted.
+
 ## Local Development
 
 Run package checks:
@@ -39,17 +68,10 @@ pnpm --filter @dotdotgod/codex run verify
 pnpm --filter @dotdotgod/codex run pack:dry-run
 ```
 
-## Shared Contract
+## Learn More
 
-- `AGENTS.md` remains canonical.
-- `CODEX.md` stays thin and points to `AGENTS.md`.
-- Active plans use `docs/plan/<task-slug>/README.md`.
-- Completed plans move to `docs/archive/plan/<task-slug>/`.
-- Temporary reports move to `docs/archive/report/<report-slug>/`.
-- `docs/archive/README.md` is the archive map; archive bodies should be read only when targeted.
+See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod), [`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
 
-This adapter packages reusable workflow skills. It guides Codex to prefer a bounded dotdotgod load snapshot when available, avoid broad archive scans, and follow README indexes before reading raw files.
-
-The strength is structured retrieval: project docs declare which files are rules, specs, architecture, verification, active intent, or historical memory. That keeps the memory layer portable across Codex runtimes and useful on small tasks where a large graph report would be overhead.
+This adapter packages reusable workflow skills. It guides Codex to prefer a bounded dotdotgod load snapshot when available, avoid broad archive scans, and follow README indexes before reading raw files. The strength is structured retrieval from project-declared memory, not a giant graph report.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/codex",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Codex adapter for dotdotgod project memory workflows.",
   "type": "module",
   "license": "MIT",
@@ -8,14 +8,22 @@
     "access": "public"
   },
   "keywords": [
-    "codex",
-    "dotdotgod",
     "agent-memory",
+    "ai-coding-agent",
+    "codex",
+    "context-curation",
     "documentation",
+    "dotdotgod",
+    "graph-impact",
+    "planning",
     "plugin",
     "project-memory",
-    "planning"
+    "traceability"
   ],
+  "scripts": {
+    "verify": "node -e \"const fs=require('fs'); const req=['.codex-plugin/plugin.json','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/project-initializer/SKILL.md','skills/project-initializer/scripts/init_project.sh','hooks/README.md']; JSON.parse(fs.readFileSync('.codex-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('codex adapter ok')\"",
+    "pack:dry-run": "pnpm pack --dry-run --json"
+  },
   "files": [
     ".codex-plugin",
     "skills",
@@ -23,8 +31,13 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "verify": "node -e \"const fs=require('fs'); const req=['.codex-plugin/plugin.json','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/project-initializer/SKILL.md','skills/project-initializer/scripts/init_project.sh','hooks/README.md']; JSON.parse(fs.readFileSync('.codex-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('codex adapter ok')\"",
-    "pack:dry-run": "pnpm pack --dry-run --json"
+  "homepage": "https://github.com/dotdotgod/dotdotgod/tree/main/packages/codex#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotdotgod/dotdotgod.git",
+    "directory": "packages/codex"
+  },
+  "bugs": {
+    "url": "https://github.com/dotdotgod/dotdotgod/issues"
   }
-}
+}

package/skills/doc-first-planning/SKILL.md

@@ -31,6 +31,7 @@ Prefer live repository docs in this order:
    - If the session is long or noisy, suggest a user-initiated planning-focused compaction before writing or revising the plan; do not compact automatically because compaction is lossy.
 2. Gather evidence before planning.
    - When the request contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<request>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
+   - When the request uses high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, run `dotdotgod expand <root> "<request>" --fuzzy --json`; skip fuzzy expansion for generic low-signal words alone and respect configured fuzzy low-signal add/remove terms.
    - Search docs by domain terms from the user request.
    - Read nearest README indexes and relevant focused docs.
    - For behavior changes, prefer specs with CLI-enforced fenced `json dotdotgod` traceability blocks in the final section; use their source, test, related-doc, and verification-command mappings before editing code.

package/skills/project-load/SKILL.md

@@ -18,6 +18,7 @@ Do not modify files during the load pass unless the user explicitly asks for edi
    - Mention user changes and avoid reverting or cleaning them.
 2. Prefer the bounded CLI snapshot when available.
    - If the user prompt contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<prompt>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
+   - If the prompt has high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, use `dotdotgod expand <root> "<prompt>" --fuzzy --json` before broad scans; avoid fuzzy expansion for low-signal generic words alone and respect configured fuzzy low-signal add/remove terms.
    - If `dotdotgod` is installed or available in the repository, run `dotdotgod load-snapshot <root> --json`.
    - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
    - Treat the snapshot as the first-pass project-memory map for cache status, graph size, memory areas, related communities, and archive inclusion policy.