waypoint-codex 0.1.10 → 0.2.0

package/README.md

@@ -5,8 +5,8 @@ Waypoint is a docs-first repository operating system for Codex.
 It helps the next agent pick up your repo with full context by keeping the important things in markdown files inside the repo:
 
 - `AGENTS.md` for startup instructions
-- `.waypoint/WORKSPACE.md` for live state
-- `.waypoint/docs/` for durable project memory
+- `.waypoint/WORKSPACE.md` for live state, with timestamped multi-topic entries
+- `.waypoint/docs/` for durable project memory, with `summary`, `last_updated`, and `read_when` frontmatter on routable docs
 - `.waypoint/DOCS_INDEX.md` for docs routing
 - repo-local skills for planning and audits
 
@@ -69,6 +69,8 @@ If you initialize with `--with-roles`, Waypoint scaffolds:
 - `docs-researcher`
 - `plan-reviewer`
 
+The intended workflow is post-commit: after your own commit lands, run `code-reviewer` and `code-health-reviewer` in parallel in the background, then fix real findings before you call the work finished.
+
 ## Update
 
 ```bash

package/dist/src/core.js

@@ -11,6 +11,14 @@ const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
 const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
 const STATE_DIR = ".waypoint/state";
 const SYNC_RECORDS_FILE = ".waypoint/state/sync-records.json";
+const TIMESTAMPED_WORKSPACE_SECTIONS = new Set([
+    "## Current State",
+    "## In Progress",
+    "## Next",
+    "## Parked",
+    "## Done Recently",
+]);
+const TIMESTAMPED_ENTRY_PATTERN = /^(?:[-*]|\d+\.)\s+\[\d{4}-\d{2}-\d{2} \d{2}:\d{2} [A-Z]{2,5}\]/;
 function ensureDir(dirPath) {
     mkdirSync(dirPath, { recursive: true });
 }
@@ -183,6 +191,27 @@ function hashFile(filePath) {
 function codexHome() {
     return process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
 }
+function findWorkspaceTimestampViolations(workspaceText) {
+    let currentSection = "";
+    const violations = new Set();
+    for (const rawLine of workspaceText.split("\n")) {
+        const line = rawLine.trim();
+        if (line.startsWith("## ")) {
+            currentSection = line;
+            continue;
+        }
+        if (!TIMESTAMPED_WORKSPACE_SECTIONS.has(currentSection) || line.length === 0) {
+            continue;
+        }
+        if (!/^(?:[-*]|\d+\.)\s+/.test(line)) {
+            continue;
+        }
+        if (!TIMESTAMPED_ENTRY_PATTERN.test(line)) {
+            violations.add(currentSection);
+        }
+    }
+    return [...violations];
+}
 function renderCodexAutomation(spec, cwd) {
     const now = Date.now();
     const rrule = spec.rrule?.startsWith("RRULE:") ? spec.rrule : `RRULE:${spec.rrule}`;
@@ -353,6 +382,16 @@ export function doctorRepository(projectRoot) {
                 });
             }
         }
+        const timestampViolations = findWorkspaceTimestampViolations(workspaceText);
+        if (timestampViolations.length > 0) {
+            findings.push({
+                severity: "warn",
+                category: "workspace",
+                message: `Workspace has untimestamped entries in ${timestampViolations.join(", ")}.`,
+                remediation: "Prefix new or materially revised workspace bullets with `[YYYY-MM-DD HH:MM TZ]`.",
+                paths: [workspacePath],
+            });
+        }
     }
     for (const requiredFile of [
         path.join(projectRoot, ".waypoint", "SOUL.md"),
@@ -387,7 +426,7 @@ export function doctorRepository(projectRoot) {
             severity: "warn",
             category: "docs",
             message: `Doc is missing valid frontmatter: ${relPath}`,
-            remediation: "Add `summary` and `read_when` frontmatter.",
+            remediation: "Add `summary`, `last_updated`, and `read_when` frontmatter.",
             paths: [path.join(projectRoot, relPath)],
         });
     }

package/dist/src/docs-index.js

@@ -13,14 +13,15 @@ const SKIP_NAMES = new Set(["README.md", "CHANGELOG.md", "LICENSE.md"]);
 function parseFrontmatter(filePath) {
     const text = readFileSync(filePath, "utf8");
     if (!text.startsWith("---\n")) {
-        return { summary: "", readWhen: [] };
+        return { summary: "", lastUpdated: "", readWhen: [] };
     }
     const endIndex = text.indexOf("\n---\n", 4);
     if (endIndex === -1) {
-        return { summary: "", readWhen: [] };
+        return { summary: "", lastUpdated: "", readWhen: [] };
     }
     const frontmatter = text.slice(4, endIndex);
     let summary = "";
+    let lastUpdated = "";
     const readWhen = [];
     let collectingReadWhen = false;
     for (const rawLine of frontmatter.split("\n")) {
@@ -30,6 +31,11 @@ function parseFrontmatter(filePath) {
             collectingReadWhen = false;
             continue;
         }
+        if (line.startsWith("last_updated:")) {
+            lastUpdated = line.slice("last_updated:".length).trim().replace(/^['"]|['"]$/g, "");
+            collectingReadWhen = false;
+            continue;
+        }
         if (line.startsWith("read_when:")) {
             collectingReadWhen = true;
             continue;
@@ -42,7 +48,7 @@ function parseFrontmatter(filePath) {
             collectingReadWhen = false;
         }
     }
-    return { summary, readWhen };
+    return { summary, lastUpdated, readWhen };
 }
 function walkDocs(projectRoot, currentDir, output, invalid) {
     for (const entry of readdirSync(currentDir)) {
@@ -58,9 +64,9 @@ function walkDocs(projectRoot, currentDir, output, invalid) {
         if (!entry.endsWith(".md") || SKIP_NAMES.has(entry)) {
             continue;
         }
-        const { summary, readWhen } = parseFrontmatter(fullPath);
+        const { summary, lastUpdated, readWhen } = parseFrontmatter(fullPath);
         const relPath = path.relative(projectRoot, fullPath);
-        if (!summary || readWhen.length === 0) {
+        if (!summary || !lastUpdated || readWhen.length === 0) {
             invalid.push(relPath);
             continue;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

package/templates/.codex/agents/code-health-reviewer.toml

@@ -4,11 +4,10 @@ developer_instructions = """
 Read these files in order before doing anything else:
 1. .waypoint/SOUL.md
 2. .waypoint/agent-operating-manual.md
-3. WORKSPACE.md
+3. .waypoint/WORKSPACE.md
 4. .waypoint/context/MANIFEST.md
 5. every file listed in that manifest
 6. .waypoint/agents/code-health-reviewer.md
 
 After reading them, follow .waypoint/agents/code-health-reviewer.md as your operating instructions.
 """
-

package/templates/.codex/agents/code-reviewer.toml

@@ -4,11 +4,10 @@ developer_instructions = """
 Read these files in order before doing anything else:
 1. .waypoint/SOUL.md
 2. .waypoint/agent-operating-manual.md
-3. WORKSPACE.md
+3. .waypoint/WORKSPACE.md
 4. .waypoint/context/MANIFEST.md
 5. every file listed in that manifest
 6. .waypoint/agents/code-reviewer.md
 
 After reading them, follow .waypoint/agents/code-reviewer.md as your operating instructions.
 """
-

package/templates/.codex/config.toml

@@ -1,13 +1,16 @@
+[features]
+multi_agent = true
+
 [agents]
 max_depth = 1
 max_threads = 4
 
 [agents."code-health-reviewer"]
-description = "Read-only reviewer focused on maintainability drift, dead code, duplication, and refactoring opportunities worth fixing."
+description = "Read-only background reviewer for post-commit maintainability drift, dead code, duplication, and refactoring opportunities worth fixing."
 config_file = "agents/code-health-reviewer.toml"
 
 [agents."code-reviewer"]
-description = "Read-only deep code reviewer focused on real bugs, regressions, and integration mistakes."
+description = "Read-only background reviewer for post-commit bugs, regressions, and integration mistakes."
 config_file = "agents/code-reviewer.toml"
 
 [agents."docs-researcher"]

package/templates/.waypoint/README.md

@@ -3,11 +3,11 @@
 Repo-local Waypoint configuration and optional integration sources.
 
 - `config.toml` — Waypoint feature toggles and file locations
-- `WORKSPACE.md` — live operational state
+- `WORKSPACE.md` — live operational state; new or materially revised entries in multi-topic sections are timestamped
 - `DOCS_INDEX.md` — generated docs routing map
 - `SOUL.md` — agent identity and working values
 - `agent-operating-manual.md` — required session workflow
-- `docs/` — Waypoint-managed project memory (architecture, decisions, debugging knowledge, durable plans)
+- `docs/` — Waypoint-managed project memory (architecture, decisions, debugging knowledge, durable plans); routable docs use `summary`, `last_updated`, and `read_when` frontmatter
 - `agents/` — agent prompt files that optional Codex roles can read and follow
 - `automations/` — optional automation source specs
 - `context/` — generated session context bundle

package/templates/.waypoint/SOUL.md

@@ -30,6 +30,8 @@ You're direct, opinionated, and evidence-driven. You read before you write. You
 
 **Update the durable record.** When behavior changes, update docs. When state changes, update `WORKSPACE.md`. When a better pattern emerges, encode it in the repo contract instead of rediscovering it later.
 
+**Close the loop after commits.** If Waypoint's reviewer roles are available, launch `code-reviewer` and `code-health-reviewer` after your own commits and address the real findings before you call the work finished.
+
 **Prefer small, reviewable changes.** Keep work scoped and comprehensible.
 
 ## What Matters Most

package/templates/.waypoint/agent-operating-manual.md

@@ -42,8 +42,8 @@ If something important lives only in your head or in the chat transcript, the re
 
 - Read code before editing it.
 - Follow the repo's documented patterns when they are healthy.
-- Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes.
-- Update `.waypoint/docs/` when durable knowledge changes.
+- Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes. In multi-topic sections, prefix new or materially revised bullets with a local timestamp like `[2026-03-06 20:10 PST]`.
+- Update `.waypoint/docs/` when durable knowledge changes, and refresh each changed routable doc's `last_updated` field.
 - Rebuild `.waypoint/DOCS_INDEX.md` whenever routable docs change.
 - Use the repo-local skills and optional reviewer agents instead of improvising from scratch.
 
@@ -76,6 +76,15 @@ If the repo was initialized with Waypoint roles enabled, use them as focused sec
 - `docs-researcher` for external dependency research
 - `plan-reviewer` to challenge weak implementation plans before execution
 
+## Post-Commit Review Loop
+
+If Waypoint's optional roles are enabled and you authored a commit, immediately after that commit:
+
+1. Launch `code-reviewer` and `code-health-reviewer` in parallel as background, read-only reviewers.
+2. Scope them to the commit you just made, then widen only when surrounding files are needed to validate a finding.
+3. Do not call the work finished before you read both reviewer results.
+4. Fix real findings, rerun the relevant verification, update workspace/docs if needed, and make a follow-up commit when fixes change the repo.
+
 ## Quality bar
 
 - No silent assumptions

package/templates/.waypoint/agents/code-health-reviewer.md

@@ -9,7 +9,7 @@ You are a Code Health specialist. You find maintainability issues and technical
 
 1. Read `.waypoint/SOUL.md`
 2. Read `.waypoint/agent-operating-manual.md`
-3. Read `WORKSPACE.md`
+3. Read `.waypoint/WORKSPACE.md`
 4. Read `.waypoint/context/MANIFEST.md`
 5. Read every file listed in the manifest
 6. Read the docs relevant to the area under review
@@ -59,7 +59,7 @@ Do not create findings for:
 
 ## Scope
 
-Check recent commits and changes to determine scope. Focus on:
+In Waypoint's default post-commit review loop, start with the latest self-authored commit, then widen only when related files are needed to validate a maintainability issue. Focus on:
 
 - recently changed files
 - their importers
@@ -84,4 +84,3 @@ Each finding needs:
 ## Return
 
 Files analyzed, findings, brief overall assessment.
-

package/templates/.waypoint/agents/code-reviewer.md

@@ -9,7 +9,7 @@ You are a code reviewer. Find bugs that matter — logic errors, data flow issue
 
 1. Read `.waypoint/SOUL.md`
 2. Read `.waypoint/agent-operating-manual.md`
-3. Read `WORKSPACE.md`
+3. Read `.waypoint/WORKSPACE.md`
 4. Read `.waypoint/context/MANIFEST.md`
 5. Read every file listed in the manifest
 6. Read the docs relevant to the changed area
@@ -41,7 +41,7 @@ Not:
 
 ### 1. Get the Changes
 
-Review the actual diff or recent changed files first.
+In Waypoint's default post-commit review loop, start with the latest self-authored commit. Review the actual diff or recent changed files first, then widen only as needed.
 
 ### 2. Deep Research
 
@@ -99,4 +99,3 @@ Do not report:
 - theoretical problems you can't demonstrate
 - style preferences
 - vague "could be cleaner" commentary without concrete benefit
-

package/templates/.waypoint/docs/README.md

@@ -18,10 +18,10 @@ Every routable doc needs YAML frontmatter:
 ```yaml
 ---
 summary: One-line description
+last_updated: "2026-03-06 20:10 PST"
 read_when:
   - task cue
 ---
 ```
 
-`DOCS_INDEX.md` is generated from the docs here.
-
+Refresh `last_updated` whenever you materially change a doc. `DOCS_INDEX.md` is generated from the docs here.

package/templates/.waypoint/docs/code-guide.md

@@ -1,5 +1,6 @@
 ---
 summary: Opinionated rules for writing and changing Waypoint code so behavior stays explicit, strict, observable, and easy to evolve.
+last_updated: "2026-03-05 21:27 PST"
 read_when:
   - writing new code
   - changing existing behavior

package/templates/.waypoint/scripts/prepare-context.mjs

@@ -213,7 +213,9 @@ function mergeConsecutiveTurns(turns) {
 }
 
 function parseSession(sessionFile, projectRoot) {
+  let sessionId = null;
   let sessionCwd = null;
+  let sessionStartedAt = null;
   let compactionCount = 0;
   const rawTurns = [];
   const compactionBoundaries = [];
@@ -231,10 +233,18 @@ function parseSession(sessionFile, projectRoot) {
     }
 
     if (parsed.type === "session_meta") {
+      const sessionMetaId = parsed.payload?.id;
+      if (typeof sessionMetaId === "string") {
+        sessionId = sessionMetaId;
+      }
       const cwd = parsed.payload?.cwd;
       if (typeof cwd === "string") {
         sessionCwd = cwd;
       }
+      const timestamp = parsed.payload?.timestamp;
+      if (typeof timestamp === "string") {
+        sessionStartedAt = timestamp;
+      }
       continue;
     }
 
@@ -279,14 +289,16 @@ function parseSession(sessionFile, projectRoot) {
 
   return {
     path: sessionFile,
+    sessionId,
     sessionCwd,
     turns,
     compactionCount,
     selectedFromPreCompaction,
+    sessionStartedAt,
   };
 }
 
-function latestMatchingSession(projectRoot) {
+function latestMatchingSession(projectRoot, threadIdOverride = null) {
   const matches = [];
   for (const dirName of SESSION_DIR_NAMES) {
     for (const sessionFile of collectSessionFiles(path.join(codexHome(), dirName))) {
@@ -297,13 +309,28 @@ function latestMatchingSession(projectRoot) {
     }
   }
 
-  matches.sort((a, b) => statSync(b.path).mtimeMs - statSync(a.path).mtimeMs);
+  const requestedThreadId = threadIdOverride || process.env.CODEX_THREAD_ID || null;
+  if (requestedThreadId) {
+    const exact = matches.find((item) => item.sessionId === requestedThreadId);
+    if (exact) {
+      return exact;
+    }
+  }
+
+  matches.sort((a, b) => {
+    const left = a.sessionStartedAt || "";
+    const right = b.sessionStartedAt || "";
+    if (left === right) {
+      return b.path.localeCompare(a.path);
+    }
+    return right.localeCompare(left);
+  });
   return matches[0] || null;
 }
 
-function writeRecentThread(contextDir, projectRoot) {
+function writeRecentThread(contextDir, projectRoot, threadIdOverride = null) {
   const filePath = path.join(contextDir, "RECENT_THREAD.md");
-  const snapshot = latestMatchingSession(projectRoot);
+  const snapshot = latestMatchingSession(projectRoot, threadIdOverride);
   const generatedAt = new Date().toString();
 
   if (!snapshot) {
@@ -414,6 +441,11 @@ function main() {
   const projectRoot = detectProjectRoot();
   const contextDir = path.join(projectRoot, ".waypoint", "context");
   ensureDir(contextDir);
+  const threadIdFlagIndex = process.argv.indexOf("--thread-id");
+  const threadIdOverride =
+    threadIdFlagIndex >= 0 && threadIdFlagIndex + 1 < process.argv.length
+      ? process.argv[threadIdFlagIndex + 1]
+      : null;
 
   const docsIndexPath = writeDocsIndex(projectRoot);
 
@@ -557,7 +589,7 @@ function main() {
       "```",
     ].join("\n")
   );
-  const recentThreadPath = writeRecentThread(contextDir, projectRoot);
+  const recentThreadPath = writeRecentThread(contextDir, projectRoot, threadIdOverride);
 
   const manifestPath = path.join(contextDir, "MANIFEST.md");
   const manifestLines = [

package/templates/WORKSPACE.md

@@ -1,5 +1,7 @@
 # Workspace
 
+Timestamp discipline: Prefix new or materially revised bullets in `Current State`, `In Progress`, `Next`, `Parked`, and `Done Recently` with `[YYYY-MM-DD HH:MM TZ]`.
+
 ## Active Goal
 
 Describe the main thing currently being built or changed.
@@ -23,4 +25,3 @@ What is intentionally deferred?
 ## Done Recently
 
 What meaningful progress just landed?
-

package/templates/managed-agents-block.md

@@ -31,8 +31,9 @@ This is mandatory, not optional.
 - Do not skip the context refresh or skip files in the manifest.
 
 Working rules:
-- Keep `.waypoint/WORKSPACE.md` current as the live execution state
-- Update `.waypoint/docs/` when behavior or durable project knowledge changes
+- Keep `.waypoint/WORKSPACE.md` current as the live execution state, with timestamped new or materially revised entries in multi-topic sections
+- Update `.waypoint/docs/` when behavior or durable project knowledge changes, and refresh `last_updated` on touched routable docs
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
+- If optional reviewer roles are present and you make a commit, run `code-reviewer` and `code-health-reviewer` in parallel before calling the work done
 - Treat the generated context bundle as required session bootstrap, not optional reference material
 <!-- waypoint:end -->