@dotdotgod/codex 0.1.14 → 0.1.16

package/README.md

@@ -1,13 +1,15 @@
 # @dotdotgod/codex
 
-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.
+> **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.
 
 ## What Gets Better?
 
-- Codex can start from `AGENTS.md` and the dotdotgod docs map instead of rebuilding context manually.
+- 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 instead of transient chat.
+- 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.
@@ -48,6 +50,6 @@ pnpm --filter @dotdotgod/codex run pack:dry-run
 
 ## Compared with Graphify-Style Memory
 
-This adapter packages reusable workflow skills rather than a repo-wide extraction engine. It guides Codex to prefer a bounded dotdotgod load snapshot when available, avoid broad archive scans, and follow README indexes before reading raw files.
+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.

package/hooks/README.md

@@ -13,11 +13,17 @@ Use hooks only when you want opt-in reminders, lightweight validation, or local
 ## Opt-In Levels
 
 - `advisory`: print reminders or read-only status only.
-- `validate`: run `dotdotgod validate` after docs work or at stop time.
+- `validate`: run `dotdotgod validate . --include-local-memory --check-index` after docs work or at stop time.
 - `strict-plan-safety`: add local blocking scripts only when a reliable plan-only state signal exists.
 
 Start with advisory hooks. Do not enable blocking hooks until you have tested the hook payload, Codex trust state, and your local policy script.
 
+## Review Before First Run
+
+Codex may detect a configured hook but keep it disabled until you review it. If Codex shows `1 hook needs review before it can run. Open /hooks to review it.`, open `/hooks`, inspect the command, and approve only commands you trust.
+
+After approval, trigger a small supported edit such as an `apply_patch` documentation comment change and confirm the hook status message or command output appears. If the hook was added while a Codex session was already running, restart Codex before the smoke test so the current configuration is loaded.
+
 ## Advisory `hooks.json` Example
 
 This example reminds Codex to use dotdotgod intentionally at session start:
@@ -51,17 +57,38 @@ matcher = "Edit|Write|apply_patch"
 
 [[hooks.PostToolUse.hooks]]
 type = "command"
-command = "sh .codex/hooks/validate-docs-if-needed.sh"
+command = "dotdotgod validate . --include-local-memory --check-index"
 timeout = 120
-statusMessage = "Checking dotdotgod docs when relevant"
+statusMessage = "Checking dotdotgod docs and index freshness"
 ```
 
-Use validation hooks only by explicit opt-in. They are useful for docs-heavy sessions but can be noisy if they run after every supported edit. Prefer a local wrapper that filters to docs-related edits or writes validation logs without returning invalid hook output.
+Use validation hooks only by explicit opt-in. They are useful for docs-heavy sessions but can be noisy if they run after every supported edit. `--check-index` compares current markdown fingerprints with `.dotdotgod/manifest.json` without refreshing the cache; if the only failure is an index freshness error, run `dotdotgod index .` or `pnpm run verify:cache` intentionally.
 
 ## Prompt Reminder Pattern
 
 A `UserPromptSubmit` hook can add a reminder for implementation-like prompts. Keep the command fast and non-mutating. Prefer reminders over automatic planning because `dd:plan` and the planning skill are the explicit durable workflow.
 
+For planning-like prompts, use an advisory reminder that asks Codex to resolve explicit `[[...]]` project-memory refs with `dotdotgod expand`, identify the complete target file list, and run graph impact checks for every target file before finalizing the plan:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "plan|planning|플랜|계획",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "printf '%s\\n' 'dotdotgod: advisory reminder only. If the prompt contains [[...]] refs, run dotdotgod expand . \"<prompt>\" --json before broad grep/find. For planning work, identify the complete target file list, run dotdotgod graph impact . --changed <path> --compact for every target file, and use impact output to strengthen related docs, risks, and verification steps.'",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Strict Plan Safety Pattern
 
 Strict safety belongs in a local script, not a generic package default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/codex",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Codex adapter for dotdotgod project memory workflows.",
   "type": "module",
   "license": "MIT",

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

@@ -30,10 +30,13 @@ Prefer live repository docs in this order:
    - Preserve user edits and unrelated dirty worktree changes.
    - 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.
    - 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.
-   - Read code only after docs identify likely module boundaries, or when docs are missing/stale.
+   - When the dotdotgod CLI is available and likely target files are known, run `dotdotgod graph impact <root> --changed <path> --compact --json` for a small bounded set of those files. Use the related specs, tests, docs, commands, scores, and reasons to strengthen target files, risks, and verification steps. If impact lookup fails or the CLI is unavailable, continue with README-index and traceability fallback evidence.
+   - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
+   - Read code only after docs identify likely module boundaries, impact output points to relevant files, or docs are missing/stale.
 3. Create or update the active plan at:
 
    ```text
@@ -44,6 +47,7 @@ Prefer live repository docs in this order:
 5. Include:
    - scope and current status
    - target files and rationale
+   - impact-derived related files/checks when available
    - implementation steps
    - risks and edge cases when useful
    - verification method

package/skills/project-initializer/references/agent-docs.md

@@ -20,6 +20,6 @@ Put durable, project-wide instructions in `AGENTS.md`:
 - coding and review expectations
 - environment constraints
 
-For projects using the dotdotgod CLI, `dotdotgod validate` is the enforcement point for machine-readable docs rules such as fenced `json dotdotgod` traceability blocks in behavior specs. Keep the detailed schema in the CLI and its validation errors rather than duplicating it across agent memory files.
+For projects using the dotdotgod CLI, `dotdotgod validate` is the enforcement point for machine-readable docs rules such as fenced `json dotdotgod` traceability blocks in behavior specs. Keep the detailed schema in the CLI and its validation errors.
 
 Do not duplicate the same body in `CLAUDE.md` and `CODEX.md`; duplication causes drift.

package/skills/project-load/SKILL.md

@@ -17,10 +17,12 @@ Do not modify files during the load pass unless the user explicitly asks for edi
    - Check current directory, git root, branch, and dirty worktree status.
    - 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 `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.
    - Use `dotdotgod graph impact <root> --changed <path> --compact --json` as a task-focused impact map when the user identifies a likely source/config/doc file.
+   - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
    - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
    - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
    - Related behavior docs: [load project](../../../docs/spec/LOAD_PROJECT.md), [cross-agent support](../../../docs/spec/CROSS_AGENT_SUPPORT.md), and [cross-agent architecture](../../../docs/arch/CROSS_AGENT_ARCHITECTURE.md).
@@ -34,7 +36,7 @@ Do not modify files during the load pass unless the user explicitly asks for edi
    - `docs/plan/README.md`
    - `docs/archive/README.md`
 4. Start with `AGENTS.md`, `README.md`, and `docs/README.md` when they are not already clear from the CLI snapshot or loaded context.
-5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively instead of re-scanning every listed file unless the task needs a full refresh.
+5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively unless the task needs a full refresh.
 6. List `docs/plan` entries first, then selectively read only relevant active plans.
 7. Use `docs/archive/README.md` as the archive history map. Do not scan archive bodies by default; read targeted completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly relevant.
 8. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.