codexkit 1.0.2 → 1.0.4

package/.codex/scripts/audit_memory_hygiene.sh

@@ -3,9 +3,17 @@ set -euo pipefail
 
 # Script: audit_memory_hygiene
 # Audits context/memory health without mutating repository files.
+# Use --auto-fix to auto-generate worklog archive drafts when budget is exceeded.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
+AUTO_FIX=false
+for arg in "$@"; do
+  case "$arg" in
+    --auto-fix) AUTO_FIX=true ;;
+  esac
+done
+
 WORKLOG="$SCRIPT_DIR/context/worklog.md"
 DECISION_LOG="$SCRIPT_DIR/context/decision-log.md"
 SESSION_CONTEXT="$SCRIPT_DIR/context/session-context.md"
@@ -94,9 +102,66 @@ echo "Counts:"
 printf "INFO     %-28s %s\n" "worklog entries" "$worklog_entries"
 printf "INFO     %-28s %s\n" "decision-log entries" "$decision_count"
 
+echo
+echo "Token budget (context docs, target <4000 tokens):"
+CONTEXT_DIR="$SCRIPT_DIR/context"
+total_tokens=0
+# Only count top-level .md files; context/archive/ is intentionally excluded by the non-recursive glob.
+if [[ -d "$CONTEXT_DIR" ]]; then
+  for ctx_file in "$CONTEXT_DIR"/*.md; do
+    [[ -f "$ctx_file" ]] || continue
+    word_count=$(wc -w < "$ctx_file" 2>/dev/null | tr -d ' ')
+    est_tokens=$(( (word_count * 13 + 9) / 10 ))
+    total_tokens=$((total_tokens + est_tokens))
+  done
+fi
+if [[ "$total_tokens" -le 4000 ]]; then
+  printf "OK       %-28s ~%s tokens (budget: 4000)\n" "context/ total" "$total_tokens"
+else
+  printf "WARN     %-28s ~%s tokens (budget: 4000)\n" "context/ total" "$total_tokens"
+fi
+
+echo
+echo "Staleness checks:"
+STALE_DAYS=30
+now_epoch=$(date +%s)
+for stale_file in "$SESSION_CONTEXT" "$STATE_FILE"; do
+  if [[ -f "$stale_file" ]]; then
+    file_label="${stale_file#$SCRIPT_DIR/}"
+    file_mtime=$(stat -f '%m' "$stale_file" 2>/dev/null || stat -c '%Y' "$stale_file" 2>/dev/null || echo "0")
+    age_days=$(( (now_epoch - file_mtime) / 86400 ))
+    if [[ "$age_days" -ge "$STALE_DAYS" ]]; then
+      printf "WARN     %-28s %s days old (threshold: %s)\n" "$file_label" "$age_days" "$STALE_DAYS"
+    else
+      printf "OK       %-28s %s days old\n" "$file_label" "$age_days"
+    fi
+  fi
+done
+
 echo
 echo "Recommended next actions:"
 echo "- Run .codex/scripts/prepare_worklog_archive.sh <archive-path> if worklog needs pruning."
 echo "- After reviewing both drafts, run .codex/scripts/apply_worklog_archive.sh <archive-draft> <retained-draft> to update worklog.md and save an archive copy."
 echo "- Trim duplicate next-action bullets so session-context.md stays the precise restart cue."
 echo "- Keep only still-relevant durable decisions in decision-log.md."
+echo "- Review stale files (>$STALE_DAYS days) and update or clear outdated content."
+
+# Auto-fix: generate worklog archive drafts if budget is exceeded
+if $AUTO_FIX; then
+  worklog_lines=$(wc -l < "$WORKLOG" 2>/dev/null | tr -d ' ')
+  worklog_lines="${worklog_lines:-0}"
+  if [[ "$worklog_lines" -gt 200 ]]; then
+    archive_draft="/tmp/codexkit-worklog-archive-draft.md"
+    retained_draft="/tmp/codexkit-worklog-retained-draft.md"
+    echo
+    echo "Auto-fix: worklog exceeds 200 lines ($worklog_lines). Generating archive drafts..."
+    "$SCRIPT_DIR/scripts/prepare_worklog_archive.sh" "$archive_draft" 20 --retained-output "$retained_draft"
+    echo "  Archive draft: $archive_draft"
+    echo "  Retained draft: $retained_draft"
+    echo "  Review both, then run:"
+    echo "    bash .codex/scripts/apply_worklog_archive.sh $archive_draft $retained_draft"
+  else
+    echo
+    echo "Auto-fix: worklog is within budget ($worklog_lines/200 lines). No action needed."
+  fi
+fi

package/.codex/scripts/build_startup_brief.sh

@@ -2,9 +2,24 @@
 set -euo pipefail
 # Script: build_startup_brief
 # Generates session startup context and prints to stdout.
+# Also rebuilds the derived memory index if source files have changed.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
+# Rebuild derived memory index if source files are newer
+INDEX_DB="$SCRIPT_DIR/memory/.index/memory-index.db"
+if [[ -f "$SCRIPT_DIR/scripts/build_memory_index.sh" ]]; then
+  SOURCE_CHANGED=false
+  if [[ ! -f "$INDEX_DB" ]]; then
+    SOURCE_CHANGED=true
+  elif find "$SCRIPT_DIR/context" "$SCRIPT_DIR/memory/project" "$SCRIPT_DIR/memory/research" -type f -name '*.md' -newer "$INDEX_DB" -print -quit 2>/dev/null | grep -q .; then
+    SOURCE_CHANGED=true
+  fi
+  if $SOURCE_CHANGED; then
+    "$SCRIPT_DIR/scripts/build_memory_index.sh" >/dev/null 2>&1 || true
+  fi
+fi
+
 echo "━━━ Startup Brief ━━━"
 
 # Current git branch and status

package/.codex/scripts/start_bead.sh

@@ -6,9 +6,10 @@ set -euo pipefail
 PROJECT_ROOT="${CODEXKIT_PROJECT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 BEAD_ID="${1:-}"
 USE_CURRENT_BRANCH=false
+WORKTREE=false
 
 if [[ -z "$BEAD_ID" ]]; then
-  echo "Usage: $0 <bead-id> [--use-current-branch]" >&2
+  echo "Usage: $0 <bead-id> [--use-current-branch] [--worktree]" >&2
   exit 1
 fi
 shift || true
@@ -18,9 +19,12 @@ while [[ $# -gt 0 ]]; do
     --use-current-branch)
       USE_CURRENT_BRANCH=true
       ;;
+    --worktree)
+      WORKTREE=true
+      ;;
     *)
       echo "Unknown option: $1" >&2
-      echo "Usage: $0 <bead-id> [--use-current-branch]" >&2
+      echo "Usage: $0 <bead-id> [--use-current-branch] [--worktree]" >&2
       exit 1
       ;;
   esac
@@ -95,13 +99,13 @@ print(f"BEAD_SLUG={shlex.quote(slug)}")
 PY
 )"
 
-if [[ "$BEAD_STATUS" != "in_progress" ]]; then
-  (cd "$PROJECT_ROOT" && br update "$BEAD_ID" --status in_progress >/dev/null)
+if [[ "$BEAD_STATUS" == "open" ]]; then
+  (cd "$PROJECT_ROOT" && br update "$BEAD_ID" --claim >/dev/null)
 fi
 
 BRANCH_NAME="$(git -C "$PROJECT_ROOT" branch --show-current)"
 TARGET_BRANCH="$BRANCH_NAME"
-if ! $USE_CURRENT_BRANCH; then
+if ! $USE_CURRENT_BRANCH && ! $WORKTREE; then
   case "$BEAD_TYPE" in
     feature) prefix="feat" ;;
     bug) prefix="fix" ;;

package/.codex/scripts/verify_bead.sh

@@ -7,6 +7,8 @@ PROJECT_ROOT="${CODEXKIT_PROJECT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.
 BEAD_ID="${1:-}"
 FULL=false
 NO_CACHE=false
+QUICK=false
+FIX=false
 
 if [[ -z "$BEAD_ID" ]]; then
   echo "Usage: $0 <bead-id> [--full] [--no-cache]" >&2
@@ -23,8 +25,10 @@ while [[ $# -gt 0 ]]; do
       NO_CACHE=true
       ;;
     --quick)
+      QUICK=true
       ;;
     --fix)
+      FIX=true
       ;;
     *)
       echo "Unknown option: $1" >&2
@@ -81,13 +85,14 @@ fi
 
 CURRENT_STAMP="$(
   cd "$PROJECT_ROOT" &&
-  printf '%s\n%s\n%s' \
+  printf '%s\n%s\n%s\n%s' \
+    "$BEAD_ID" \
     "$(git rev-parse HEAD)" \
     "$(git diff HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx')" \
     "$(git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx' | xargs cat 2>/dev/null)" \
     | shasum -a 256 | cut -d' ' -f1
 )"
-LAST_STAMP="$(tail -1 "$VERIFY_LOG" 2>/dev/null | awk '{print $1}' || true)"
+LAST_STAMP="$(grep -F "$CURRENT_STAMP" "$VERIFY_LOG" 2>/dev/null | tail -1 | awk '{print $1}' || true)"
 
 if ! $NO_CACHE && ! $FULL && [[ -n "$LAST_STAMP" && "$CURRENT_STAMP" = "$LAST_STAMP" ]]; then
   echo "cached-pass=$CURRENT_STAMP"
@@ -135,15 +140,22 @@ for raw_line in text.splitlines():
 PY
 }
 
+if $FIX; then
+  run_npm_script_if_present "lint:fix"
+  run_npm_script_if_present "format"
+fi
+
 run_npm_script_if_present typecheck
 run_npm_script_if_present lint
 run_npm_script_if_present test
 run_npm_script_if_present build
 
-while IFS= read -r verify_cmd; do
-  [[ -z "$verify_cmd" ]] && continue
-  (cd "$PROJECT_ROOT" && bash -lc "$verify_cmd" >/dev/null)
-done < <(run_verify_commands)
+if ! $QUICK; then
+  while IFS= read -r verify_cmd; do
+    [[ -z "$verify_cmd" ]] && continue
+    (cd "$PROJECT_ROOT" && bash -lc "$verify_cmd" >/dev/null)
+  done < <(run_verify_commands)
+fi
 
 mkdir -p "$(dirname "$VERIFY_LOG")"
 echo "$CURRENT_STAMP $(date -u +%Y-%m-%dT%H:%M:%SZ) PASS" >> "$VERIFY_LOG"

package/.codex/skills/compaction/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: compaction
 description: >
-  Use when context is growing large during long-running tasks and needs server-side or client-side
-  summarization to continue effectively. Covers compaction triggers, custom summarization patterns,
-  session handoff, and context preservation strategies.
-version: 1.0.0
+  Use when context is growing large during long-running tasks and needs
+  summarization to continue effectively. Covers compaction triggers, custom
+  summarization patterns, session handoff, and context preservation strategies.
+  Uses Codex-native /compact command.
+version: 2.0.0
 tags: [context, workflow]
 dependencies: []
 ---
@@ -19,7 +20,6 @@ dependencies: []
 
 - Short sessions with low context usage where no compaction is needed.
 
-
 ## Overview
 
 **Compaction = Summarization + Preservation + Continuity**
@@ -32,54 +32,53 @@ Long-running sessions accumulate context (tool outputs, code reads, exploration
 
 | Context Usage | Status      | Action                                        |
 | ------------- | ----------- | --------------------------------------------- |
-| 0-50%         | 🟢 Normal   | Work freely                                   |
-| 50-70%        | 🟡 Watch    | Start compressing completed explorations      |
-| 70-85%        | 🟠 Compact  | Actively compress and sweep stale noise       |
-| 85-95%        | 🔴 Critical | Emergency compaction, prepare session handoff |
-| 95%+          | ⛔ Limit    | Session handoff required                      |
+| 0-50%         | Normal      | Work freely                                   |
+| 50-70%        | Watch       | Start compressing completed explorations      |
+| 70-85%        | Compact     | Actively compress; write summaries to durable files |
+| 85-95%        | Critical    | Emergency compaction, prepare session handoff |
+| 95%+          | Limit       | Session handoff required                      |
 
 ### Monitoring
 
 Pay attention to these signals:
 
-- Completed phases accumulating without being compressed
+- Completed phases accumulating without being summarized
 - Repeated file reads of the same content
 - Large bash outputs from builds/tests
 - Multiple exploration rounds without synthesis
 
 ## Compaction Strategies
 
-### Strategy 1: Phase Compression (Preferred)
-
-Compress completed conversation phases into dense summaries. This is the primary DCP instrument in the installed beta.
+### Strategy 1: Codex-Native `/compact` (Preferred)
 
-
-Compress completed conversation phases into dense summaries.
+Use the built-in `/compact` command to summarize conversation history while preserving key context.
 
 ```
-WHEN: A research phase is complete and findings are clear
-DO: compress({
-  topic: "Auth Research Complete",
-  content: {
-    startString: "unique text at phase start",
-    endString: "unique text at phase end",
-    summary: "Complete technical summary of findings..."
-  }
-})
+WHEN: A research or implementation phase is complete
+DO: /compact focus on [completed phase topic]
 ```
 
-**Key principle**: Only compress CLOSED chapters. Never compress active work.
+The `/compact` command:
+- Summarizes conversation history server-side
+- Preserves key decisions and findings
+- Frees context budget for new work
+- Accepts an optional focus instruction to guide what it preserves
 
-### Strategy 2: Sweep Stale Noise
+**Key principle**: Only compact CLOSED chapters. Never compact active work.
 
-Use `/dcp sweep` after a phase is complete to remove stale/noisy content automatically.
+### Strategy 2: Manual Phase Summarization
+
+When `/compact` is too broad, manually write a dense summary to a durable file before the context is lost.
 
 ```
-WHEN: Wrong-target searches or superseded outputs are no longer needed
-DO: /dcp sweep
+WHEN: A research phase is complete and findings are clear
+DO:
+  1. Write summary to `.codex/context/worklog.md` or `.codex/memory/research/`
+  2. Record key decisions in `.codex/context/decision-log.md`
+  3. The summarized content can now be safely forgotten by the session
 ```
 
-**Key principle**: Sweep only after the relevant phase is closed. If in doubt, keep it.
+**Key principle**: Persist durable findings to repo files before they leave the context window.
 
 ### Strategy 3: Session Handoff
 
@@ -88,10 +87,10 @@ When context is too large to compact further, hand off to a new session.
 ```
 WHEN: Context > 85% and significant work remains
 DO:
-  1. Create handoff document with memory-update
-  2. Save all decisions with observation tool
-  3. Document current state and remaining work
-  4. Start new session with handoff reference
+  1. Update `.codex/context/session-context.md` with exact stop point
+  2. Update `.codex/memory/project/state.md` with durable state
+  3. Append milestone to `.codex/context/worklog.md`
+  4. Start new session with `/prompts:resume`
 ```
 
 ## Compaction Decision Tree
@@ -100,8 +99,8 @@ DO:
 Is context growing large?
 ├── NO → Continue working normally
 └── YES → What type of content is consuming space?
-    ├── Completed conversation phases → COMPRESS
-    ├── Stale/noisy closed-phase outputs → SWEEP
+    ├── Completed conversation phases → /compact
+    ├── Research findings not yet persisted → Write to memory/research/, then /compact
     └── Everything is still relevant → SESSION HANDOFF
 ```
 
@@ -150,9 +149,9 @@ Is context growing large?
 
 ### Verification
 
-- TypeScript: ✅ passing
-- Tests: ✅ 12/12 passing
-- Lint: ✅ no issues
+- TypeScript: passing
+- Tests: 12/12 passing
+- Lint: no issues
 
 ### Remaining
 
@@ -187,131 +186,83 @@ Is context growing large?
 
 - Added null check in middleware (src/auth/middleware.ts:42)
 - Added token refresh attempt before rejecting (src/auth/refresh.ts)
-- Added test for expired token scenario (src/auth/**tests**/middleware.test.ts)
+- Added test for expired token scenario (src/auth/tests/middleware.test.ts)
 
 ### Verification
 
-- Tests: ✅ all passing including new test
-- Manual: ✅ expired token now triggers refresh
+- Tests: all passing including new test
+- Manual: expired token now triggers refresh
 ```
 
 ## Session Handoff Protocol
 
 When you must hand off to a new session:
 
-### 1. Create Handoff Document
+### 1. Persist Durable Findings
 
-```typescript
-memory -
-  update({
-    file: "handoffs/YYYY-MM-DD-feature-name",
-    content: `# Session Handoff: [Feature Name]
+Write key findings and decisions to the appropriate repo files:
 
-## Context
-[Why this session started, what was the goal]
+- `.codex/context/session-context.md` — exact stop point and first next action
+- `.codex/memory/project/state.md` — durable current state and blockers
+- `.codex/context/worklog.md` — milestone summary
+- `.codex/context/decision-log.md` — architecture/workflow decisions with rationale
+- `.codex/memory/research/*.md` — deep investigation notes
 
-## Completed Work
-[What was done, files changed, decisions made]
+### 2. Create Handoff Summary
 
-## Current State
-[Where things stand right now]
+Use `/prompts:handoff` or write directly to `session-context.md`:
 
-## Remaining Work
-[What still needs to be done]
-
-## Key Decisions
-[Important choices made and why]
-
-## Files Modified
-[List of all files changed with brief description]
-
-## Gotchas
-[Things the next session should know]
-  `,
-    mode: "replace",
-  });
-```
+```markdown
+## Resume: [task-id]
 
-### 2. Save Key Observations
-
-```typescript
-observation({
-  type: "decision",
-  title: "Auth implementation approach",
-  narrative: "Chose JWT with Redis sessions because...",
-  facts: "JWT 15min expiry, Redis 24h TTL, bcrypt 12 rounds",
-  concepts: "authentication, sessions, tokens",
-  confidence: "high",
-});
+- Branch: [branch]
+- Commit: [short hash]
+- Stop point: [exact step in progress]
+- First next action: [single best next action]
+- Blockers: [none or short list]
 ```
 
 ### 3. Resume in New Session
 
-```typescript
-// In new session:
-memory - read({ file: "handoffs/YYYY-MM-DD-feature-name" });
-memory - search({ query: "auth implementation" });
-```
+```bash
+# Native Codex resume (thread-based):
+codex resume
 
-## Integration with DCP Plugin
-
-This project uses DCP-style context management for always-on context discipline:
-
-- **compress**: Phase-level conversation compression (primary DCP tool in the installed beta)
-- **/dcp sweep**: Cleanup command for stale/noisy content after a phase is complete
-- **Prunable-tools list**: Auto-injected into messages with token estimates
-- **Nudge system**: Reminders every N tool calls + critical limit warnings
-
-**Division of responsibility:**
-
-- **DCP plugin**: Context budget rules, tool guidance, prunable-tools list, nudges (always present via system prompt)
-- **Compaction workflow** (`.codex/context/session-context.md` + handoff/resume prompts): Session continuity, beads state, handoff recovery, post-compaction protocol
+# Or file-based resume via Codexkit:
+/prompts:resume [task-id]
+```
 
 ## Anti-Patterns
 
-### ❌ Premature Compaction
-
-```
-// DON'T compress a file you're about to edit
-compress({ ... })  // Loses exact line numbers you need
-edit({ ... })      // Now you can't find the right location
-```
+### Premature Compaction
 
-**Fix**: Keep raw content while actively editing. Compress AFTER the edit phase.
+Don't compact a file you're about to edit — you'll lose exact line numbers. Keep raw content while actively editing. Compact AFTER the edit phase.
 
-### ❌ Compressing Active Work
+### Compacting Active Work
 
-```
-// DON'T compress a conversation phase you might return to
-compress({ summary: "Explored auth options" })
-// Later: "Wait, which options did we consider?"
-```
+Don't compact a conversation phase you might return to. Only compact CLOSED chapters where findings are crystallized.
 
-**Fix**: Only compress CLOSED chapters where findings are crystallized.
+### Ignoring Context Growth
 
-### ❌ Ignoring Context Growth
+Don't let context grow unchecked until hitting limits. By the time you notice, emergency compaction loses information. Monitor regularly and compact at natural breakpoints.
 
-```
-// DON'T let context grow unchecked until hitting limits
-// By the time you notice, emergency compaction loses information
-```
+### Persisting Only to Session Memory
 
-**Fix**: Monitor regularly. Compress at natural breakpoints and use `/dcp sweep` after closed phases.
+Don't rely on session history for durable findings. Write important decisions and state to repo-visible files before compacting, so they survive session boundaries.
 
 ## Checklist
 
 Before compacting:
 
 - [ ] Identified what type of content is consuming context
-- [ ] Chosen appropriate strategy (compress/sweep/handoff)
+- [ ] Chosen appropriate strategy (/compact, manual summary, or handoff)
 - [ ] Verified raw content is no longer needed for active work
-- [ ] Captured all key details in the compression summary or handoff
-- [ ] Saved important decisions as observations
+- [ ] Persisted key findings to durable repo files
 - [ ] Created handoff document if switching sessions
 
 During long sessions:
 
-- [ ] Compressing completed phases at natural breakpoints
-- [ ] Sweeping stale/noisy outputs after phase completion
+- [ ] Running `/compact` at natural phase boundaries
+- [ ] Writing durable findings to context/memory files before they leave the window
 - [ ] Monitoring context usage trends
 - [ ] Planning session handoff if approaching limits