feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SihaoLiu merged 12 commits into from
Jan 16, 2026
Merged

feat(cli): add --plan-file and --track-plan-file options with comprehensive validation #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
16c6b6b
[command] fix bash command exec format
SihaoLiu Jan 15, 2026
dcf7cbf
impl(cli) init implementation effort to add CLI to track plan file
SihaoLiu Jan 15, 2026
c83c416
fix(hooks): address critical issues from code review
SihaoLiu Jan 15, 2026
f1ca666
test(hooks): add stop hook plan file integrity tests
SihaoLiu Jan 15, 2026
9e21520
refactor(loop): unify loop directory and state management concepts
SihaoLiu Jan 15, 2026
5261ecc
refactor(hooks): consolidate state parsing and fix pipefail issues
SihaoLiu Jan 15, 2026
76982ea
fix(plan-file): fix YAML injection and add space validation
SihaoLiu Jan 15, 2026
e93a1b0
fix(security): harden injection prevention and add comprehensive tests
SihaoLiu Jan 15, 2026
0d87b6f
fix(plan-file): address code review issues for plan file CLI
SihaoLiu Jan 16, 2026
b49dad6
fix(security): address code review issues for plan file CLI
SihaoLiu Jan 16, 2026
c3165b6
fix(tests): use dynamic branch name instead of hardcoded main
SihaoLiu Jan 16, 2026
90e7c52
fix(security): verify plan content matches backup even for tracked files
SihaoLiu Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
"name": "humanize",
"source": "./",
"description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
"version": "1.1.1"
"version": "1.1.2"
}
]
}
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
"name": "humanize",
"description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
"version": "1.1.1",
"version": "1.1.2",
"author": {
"name": "humania-org"
},
Expand Down
51 changes: 51 additions & 0 deletions .github/workflows/plan-file-test.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
push:
paths:
- 'scripts/setup-rlcr-loop.sh'
- 'hooks/loop-plan-file-validator.sh'
- 'hooks/loop-codex-stop-hook.sh'
- 'hooks/loop-write-validator.sh'
- 'hooks/loop-edit-validator.sh'
- 'hooks/loop-bash-validator.sh'
- 'hooks/lib/loop-common.sh'
- 'tests/test-plan-file-*.sh'
- 'tests/test-state-exit-naming.sh'
pull_request:
paths:
- 'scripts/setup-rlcr-loop.sh'
- 'hooks/loop-plan-file-validator.sh'
- 'hooks/loop-codex-stop-hook.sh'
- 'hooks/loop-write-validator.sh'
- 'hooks/loop-edit-validator.sh'
- 'hooks/loop-bash-validator.sh'
- 'hooks/lib/loop-common.sh'
- 'tests/test-plan-file-*.sh'
- 'tests/test-state-exit-naming.sh'

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y jq

- name: Run plan file validation tests
run: |
chmod +x tests/test-plan-file-validation.sh
./tests/test-plan-file-validation.sh

- name: Run plan file hook tests
run: |
chmod +x tests/test-plan-file-hooks.sh
./tests/test-plan-file-hooks.sh

- name: Run state exit naming tests
run: |
chmod +x tests/test-state-exit-naming.sh
./tests/test-state-exit-naming.sh
3 changes: 2 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down
25 changes: 17 additions & 8 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
- `round-N-codex-run.cmd` - Command invoked
Expand Down
29 changes: 20 additions & 9 deletions commands/cancel-rlcr-loop.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
- Read the state file to get the current round number
- Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
- Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
- Read the state file to get the current round number and max iterations
- Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
- Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.
2 changes: 1 addition & 1 deletion commands/start-rlcr-loop.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down
10 changes: 10 additions & 0 deletions hooks/hooks.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
"description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
}
]
}
],
"PreToolUse": [
{
"matcher": "Write",
Expand Down
40 changes: 40 additions & 0 deletions hooks/lib/loop-common.sh
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

local patterns=(
">[[:space:]]*[^[:space:]]*${file_pattern}"
">>[[:space:]]*[^[:space:]]*${file_pattern}"
"tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
"sed[[:space:]]+-i[^|]*${file_pattern}"
"awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
"perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
"(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
"rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
"dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
"truncate[[:space:]]+[^|]*${file_pattern}"
"printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
"exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
)

for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
"CURRENT_ROUND=$current_round" \
"SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
local loop_dir="$1"
local state_file="$2"
local reason="$3" # complete, cancel, maxiter, stop, unexpected

# Validate reason
case "$reason" in
complete|cancel|maxiter|stop|unexpected)
;;
*)
echo "Error: Invalid end_loop reason: $reason" >&2
return 1
;;
esac

local target_name="${reason}-state.md"

if [[ -f "$state_file" ]]; then
mv "$state_file" "$loop_dir/$target_name"
echo "Loop ended: $reason" >&2
echo "State preserved as: $loop_dir/$target_name" >&2
return 0
else
echo "Warning: State file not found, cannot end loop" >&2
return 1
fi
}
13 changes: 13 additions & 0 deletions hooks/loop-bash-validator.sh
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
echo "$REASON" >&2
exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

SihaoLiu
merged 12 commits into

from

Jan 16, 2026
 Merged


feat(cli): add --plan-file and --track-plan-file options with comprehensive validation
#8
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
16c6b6b

[command] fix bash command exec format


SihaoLiu Jan 15, 2026
dcf7cbf

impl(cli) init implementation effort to add CLI to track plan file


SihaoLiu Jan 15, 2026
c83c416

fix(hooks): address critical issues from code review


SihaoLiu Jan 15, 2026
f1ca666

test(hooks): add stop hook plan file integrity tests


SihaoLiu Jan 15, 2026
9e21520

refactor(loop): unify loop directory and state management concepts


SihaoLiu Jan 15, 2026
5261ecc

refactor(hooks): consolidate state parsing and fix pipefail issues


SihaoLiu Jan 15, 2026
76982ea

fix(plan-file): fix YAML injection and add space validation


SihaoLiu Jan 15, 2026
e93a1b0

fix(security): harden injection prevention and add comprehensive tests


SihaoLiu Jan 15, 2026
0d87b6f

fix(plan-file): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
b49dad6

fix(security): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
c3165b6

fix(tests): use dynamic branch name instead of hardcoded main


SihaoLiu Jan 16, 2026
90e7c52

fix(security): verify plan content matches backup even for tracked files


SihaoLiu Jan 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
.claude-plugin/marketplace.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
 "name": "humanize",
 "source": "./",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1"
 "version": "1.1.2"
 }
 ]
}

2 changes: 1 addition & 1 deletion
.claude-plugin/plugin.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
 "name": "humanize",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1",
 "version": "1.1.2",
 "author": {
 "name": "humania-org"
 },
Expand Down

51 changes: 51 additions & 0 deletions
.github/workflows/plan-file-test.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
 push:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'
 pull_request:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install dependencies
 run: |
 sudo apt-get update
 sudo apt-get install -y jq

 - name: Run plan file validation tests
 run: |
 chmod +x tests/test-plan-file-validation.sh
 ./tests/test-plan-file-validation.sh

 - name: Run plan file hook tests
 run: |
 chmod +x tests/test-plan-file-hooks.sh
 ./tests/test-plan-file-hooks.sh

 - name: Run state exit naming tests
 run: |
 chmod +x tests/test-state-exit-naming.sh
 ./tests/test-state-exit-naming.sh

3 changes: 2 additions & 1 deletion
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down

25 changes: 17 additions & 8 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
 - `round-N-codex-run.cmd` - Command invoked
Expand Down

29 changes: 20 additions & 9 deletions
commands/cancel-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
 - Read the state file to get the current round number
 - Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
 - Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
 - Read the state file to get the current round number and max iterations
 - Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
 - Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.

2 changes: 1 addition & 1 deletion
commands/start-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down

10 changes: 10 additions & 0 deletions
hooks/hooks.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
 "description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
 "hooks": {
 "UserPromptSubmit": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Write",
Expand Down

40 changes: 40 additions & 0 deletions
hooks/lib/loop-common.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

 local patterns=(
 ">[[:space:]]*[^[:space:]]*${file_pattern}"
 ">>[[:space:]]*[^[:space:]]*${file_pattern}"
 "tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "sed[[:space:]]+-i[^|]*${file_pattern}"
 "awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
 "perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
 "(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
 "rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
 "truncate[[:space:]]+[^|]*${file_pattern}"
 "printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
 "exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
 )

 for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
 "CURRENT_ROUND=$current_round" \
 "SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
 local loop_dir="$1"
 local state_file="$2"
 local reason="$3" # complete, cancel, maxiter, stop, unexpected

 # Validate reason
 case "$reason" in
 complete|cancel|maxiter|stop|unexpected)
 ;;
 *)
 echo "Error: Invalid end_loop reason: $reason" >&2
 return 1
 ;;
 esac

 local target_name="${reason}-state.md"

 if [[ -f "$state_file" ]]; then
 mv "$state_file" "$loop_dir/$target_name"
 echo "Loop ended: $reason" >&2
 echo "State preserved as: $loop_dir/$target_name" >&2
 return 0
 else
 echo "Warning: State file not found, cannot end loop" >&2
 return 1
 fi
}

13 changes: 13 additions & 0 deletions
hooks/loop-bash-validator.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
 exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
 FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
 REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
 echo "$REASON" >&2
 exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

SihaoLiu
merged 12 commits into

from

Jan 16, 2026
 Merged


feat(cli): add --plan-file and --track-plan-file options with comprehensive validation
#8
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
16c6b6b

[command] fix bash command exec format


SihaoLiu Jan 15, 2026
dcf7cbf

impl(cli) init implementation effort to add CLI to track plan file


SihaoLiu Jan 15, 2026
c83c416

fix(hooks): address critical issues from code review


SihaoLiu Jan 15, 2026
f1ca666

test(hooks): add stop hook plan file integrity tests


SihaoLiu Jan 15, 2026
9e21520

refactor(loop): unify loop directory and state management concepts


SihaoLiu Jan 15, 2026
5261ecc

refactor(hooks): consolidate state parsing and fix pipefail issues


SihaoLiu Jan 15, 2026
76982ea

fix(plan-file): fix YAML injection and add space validation


SihaoLiu Jan 15, 2026
e93a1b0

fix(security): harden injection prevention and add comprehensive tests


SihaoLiu Jan 15, 2026
0d87b6f

fix(plan-file): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
b49dad6

fix(security): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
c3165b6

fix(tests): use dynamic branch name instead of hardcoded main


SihaoLiu Jan 16, 2026
90e7c52

fix(security): verify plan content matches backup even for tracked files


SihaoLiu Jan 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
.claude-plugin/marketplace.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
 "name": "humanize",
 "source": "./",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1"
 "version": "1.1.2"
 }
 ]
}

2 changes: 1 addition & 1 deletion
.claude-plugin/plugin.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
 "name": "humanize",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1",
 "version": "1.1.2",
 "author": {
 "name": "humania-org"
 },
Expand Down

51 changes: 51 additions & 0 deletions
.github/workflows/plan-file-test.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
 push:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'
 pull_request:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install dependencies
 run: |
 sudo apt-get update
 sudo apt-get install -y jq

 - name: Run plan file validation tests
 run: |
 chmod +x tests/test-plan-file-validation.sh
 ./tests/test-plan-file-validation.sh

 - name: Run plan file hook tests
 run: |
 chmod +x tests/test-plan-file-hooks.sh
 ./tests/test-plan-file-hooks.sh

 - name: Run state exit naming tests
 run: |
 chmod +x tests/test-state-exit-naming.sh
 ./tests/test-state-exit-naming.sh

3 changes: 2 additions & 1 deletion
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down

25 changes: 17 additions & 8 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
 - `round-N-codex-run.cmd` - Command invoked
Expand Down

29 changes: 20 additions & 9 deletions
commands/cancel-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
 - Read the state file to get the current round number
 - Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
 - Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
 - Read the state file to get the current round number and max iterations
 - Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
 - Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.

2 changes: 1 addition & 1 deletion
commands/start-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down

10 changes: 10 additions & 0 deletions
hooks/hooks.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
 "description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
 "hooks": {
 "UserPromptSubmit": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Write",
Expand Down

40 changes: 40 additions & 0 deletions
hooks/lib/loop-common.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

 local patterns=(
 ">[[:space:]]*[^[:space:]]*${file_pattern}"
 ">>[[:space:]]*[^[:space:]]*${file_pattern}"
 "tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "sed[[:space:]]+-i[^|]*${file_pattern}"
 "awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
 "perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
 "(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
 "rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
 "truncate[[:space:]]+[^|]*${file_pattern}"
 "printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
 "exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
 )

 for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
 "CURRENT_ROUND=$current_round" \
 "SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
 local loop_dir="$1"
 local state_file="$2"
 local reason="$3" # complete, cancel, maxiter, stop, unexpected

 # Validate reason
 case "$reason" in
 complete|cancel|maxiter|stop|unexpected)
 ;;
 *)
 echo "Error: Invalid end_loop reason: $reason" >&2
 return 1
 ;;
 esac

 local target_name="${reason}-state.md"

 if [[ -f "$state_file" ]]; then
 mv "$state_file" "$loop_dir/$target_name"
 echo "Loop ended: $reason" >&2
 echo "State preserved as: $loop_dir/$target_name" >&2
 return 0
 else
 echo "Warning: State file not found, cannot end loop" >&2
 return 1
 fi
}

13 changes: 13 additions & 0 deletions
hooks/loop-bash-validator.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
 exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
 FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
 REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
 echo "$REASON" >&2
 exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

SihaoLiu
merged 12 commits into

from

Jan 16, 2026
 Merged


feat(cli): add --plan-file and --track-plan-file options with comprehensive validation
#8
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
16c6b6b

[command] fix bash command exec format


SihaoLiu Jan 15, 2026
dcf7cbf

impl(cli) init implementation effort to add CLI to track plan file


SihaoLiu Jan 15, 2026
c83c416

fix(hooks): address critical issues from code review


SihaoLiu Jan 15, 2026
f1ca666

test(hooks): add stop hook plan file integrity tests


SihaoLiu Jan 15, 2026
9e21520

refactor(loop): unify loop directory and state management concepts


SihaoLiu Jan 15, 2026
5261ecc

refactor(hooks): consolidate state parsing and fix pipefail issues


SihaoLiu Jan 15, 2026
76982ea

fix(plan-file): fix YAML injection and add space validation


SihaoLiu Jan 15, 2026
e93a1b0

fix(security): harden injection prevention and add comprehensive tests


SihaoLiu Jan 15, 2026
0d87b6f

fix(plan-file): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
b49dad6

fix(security): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
c3165b6

fix(tests): use dynamic branch name instead of hardcoded main


SihaoLiu Jan 16, 2026
90e7c52

fix(security): verify plan content matches backup even for tracked files


SihaoLiu Jan 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
.claude-plugin/marketplace.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
 "name": "humanize",
 "source": "./",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1"
 "version": "1.1.2"
 }
 ]
}

2 changes: 1 addition & 1 deletion
.claude-plugin/plugin.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
 "name": "humanize",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1",
 "version": "1.1.2",
 "author": {
 "name": "humania-org"
 },
Expand Down

51 changes: 51 additions & 0 deletions
.github/workflows/plan-file-test.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
 push:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'
 pull_request:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install dependencies
 run: |
 sudo apt-get update
 sudo apt-get install -y jq

 - name: Run plan file validation tests
 run: |
 chmod +x tests/test-plan-file-validation.sh
 ./tests/test-plan-file-validation.sh

 - name: Run plan file hook tests
 run: |
 chmod +x tests/test-plan-file-hooks.sh
 ./tests/test-plan-file-hooks.sh

 - name: Run state exit naming tests
 run: |
 chmod +x tests/test-state-exit-naming.sh
 ./tests/test-state-exit-naming.sh

3 changes: 2 additions & 1 deletion
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down

25 changes: 17 additions & 8 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
 - `round-N-codex-run.cmd` - Command invoked
Expand Down

29 changes: 20 additions & 9 deletions
commands/cancel-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
 - Read the state file to get the current round number
 - Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
 - Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
 - Read the state file to get the current round number and max iterations
 - Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
 - Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.

2 changes: 1 addition & 1 deletion
commands/start-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down

10 changes: 10 additions & 0 deletions
hooks/hooks.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
 "description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
 "hooks": {
 "UserPromptSubmit": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Write",
Expand Down

40 changes: 40 additions & 0 deletions
hooks/lib/loop-common.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

 local patterns=(
 ">[[:space:]]*[^[:space:]]*${file_pattern}"
 ">>[[:space:]]*[^[:space:]]*${file_pattern}"
 "tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "sed[[:space:]]+-i[^|]*${file_pattern}"
 "awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
 "perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
 "(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
 "rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
 "truncate[[:space:]]+[^|]*${file_pattern}"
 "printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
 "exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
 )

 for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
 "CURRENT_ROUND=$current_round" \
 "SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
 local loop_dir="$1"
 local state_file="$2"
 local reason="$3" # complete, cancel, maxiter, stop, unexpected

 # Validate reason
 case "$reason" in
 complete|cancel|maxiter|stop|unexpected)
 ;;
 *)
 echo "Error: Invalid end_loop reason: $reason" >&2
 return 1
 ;;
 esac

 local target_name="${reason}-state.md"

 if [[ -f "$state_file" ]]; then
 mv "$state_file" "$loop_dir/$target_name"
 echo "Loop ended: $reason" >&2
 echo "State preserved as: $loop_dir/$target_name" >&2
 return 0
 else
 echo "Warning: State file not found, cannot end loop" >&2
 return 1
 fi
}

13 changes: 13 additions & 0 deletions
hooks/loop-bash-validator.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
 exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
 FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
 REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
 echo "$REASON" >&2
 exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

SihaoLiu
merged 12 commits into

from

Jan 16, 2026
 Merged


feat(cli): add --plan-file and --track-plan-file options with comprehensive validation
#8
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
16c6b6b

[command] fix bash command exec format


SihaoLiu Jan 15, 2026
dcf7cbf

impl(cli) init implementation effort to add CLI to track plan file


SihaoLiu Jan 15, 2026
c83c416

fix(hooks): address critical issues from code review


SihaoLiu Jan 15, 2026
f1ca666

test(hooks): add stop hook plan file integrity tests


SihaoLiu Jan 15, 2026
9e21520

refactor(loop): unify loop directory and state management concepts


SihaoLiu Jan 15, 2026
5261ecc

refactor(hooks): consolidate state parsing and fix pipefail issues


SihaoLiu Jan 15, 2026
76982ea

fix(plan-file): fix YAML injection and add space validation


SihaoLiu Jan 15, 2026
e93a1b0

fix(security): harden injection prevention and add comprehensive tests


SihaoLiu Jan 15, 2026
0d87b6f

fix(plan-file): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
b49dad6

fix(security): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
c3165b6

fix(tests): use dynamic branch name instead of hardcoded main


SihaoLiu Jan 16, 2026
90e7c52

fix(security): verify plan content matches backup even for tracked files


SihaoLiu Jan 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
.claude-plugin/marketplace.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
 "name": "humanize",
 "source": "./",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1"
 "version": "1.1.2"
 }
 ]
}

2 changes: 1 addition & 1 deletion
.claude-plugin/plugin.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
 "name": "humanize",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1",
 "version": "1.1.2",
 "author": {
 "name": "humania-org"
 },
Expand Down

51 changes: 51 additions & 0 deletions
.github/workflows/plan-file-test.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
 push:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'
 pull_request:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install dependencies
 run: |
 sudo apt-get update
 sudo apt-get install -y jq

 - name: Run plan file validation tests
 run: |
 chmod +x tests/test-plan-file-validation.sh
 ./tests/test-plan-file-validation.sh

 - name: Run plan file hook tests
 run: |
 chmod +x tests/test-plan-file-hooks.sh
 ./tests/test-plan-file-hooks.sh

 - name: Run state exit naming tests
 run: |
 chmod +x tests/test-state-exit-naming.sh
 ./tests/test-state-exit-naming.sh

3 changes: 2 additions & 1 deletion
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down

25 changes: 17 additions & 8 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
 - `round-N-codex-run.cmd` - Command invoked
Expand Down

29 changes: 20 additions & 9 deletions
commands/cancel-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
 - Read the state file to get the current round number
 - Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
 - Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
 - Read the state file to get the current round number and max iterations
 - Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
 - Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.

2 changes: 1 addition & 1 deletion
commands/start-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down

10 changes: 10 additions & 0 deletions
hooks/hooks.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
 "description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
 "hooks": {
 "UserPromptSubmit": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Write",
Expand Down

40 changes: 40 additions & 0 deletions
hooks/lib/loop-common.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

 local patterns=(
 ">[[:space:]]*[^[:space:]]*${file_pattern}"
 ">>[[:space:]]*[^[:space:]]*${file_pattern}"
 "tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "sed[[:space:]]+-i[^|]*${file_pattern}"
 "awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
 "perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
 "(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
 "rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
 "truncate[[:space:]]+[^|]*${file_pattern}"
 "printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
 "exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
 )

 for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
 "CURRENT_ROUND=$current_round" \
 "SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
 local loop_dir="$1"
 local state_file="$2"
 local reason="$3" # complete, cancel, maxiter, stop, unexpected

 # Validate reason
 case "$reason" in
 complete|cancel|maxiter|stop|unexpected)
 ;;
 *)
 echo "Error: Invalid end_loop reason: $reason" >&2
 return 1
 ;;
 esac

 local target_name="${reason}-state.md"

 if [[ -f "$state_file" ]]; then
 mv "$state_file" "$loop_dir/$target_name"
 echo "Loop ended: $reason" >&2
 echo "State preserved as: $loop_dir/$target_name" >&2
 return 0
 else
 echo "Warning: State file not found, cannot end loop" >&2
 return 1
 fi
}

13 changes: 13 additions & 0 deletions
hooks/loop-bash-validator.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
 exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
 FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
 REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
 echo "$REASON" >&2
 exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

SihaoLiu
merged 12 commits into

from

Jan 16, 2026
 Merged


feat(cli): add --plan-file and --track-plan-file options with comprehensive validation
#8
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
16c6b6b

[command] fix bash command exec format


SihaoLiu Jan 15, 2026
dcf7cbf

impl(cli) init implementation effort to add CLI to track plan file


SihaoLiu Jan 15, 2026
c83c416

fix(hooks): address critical issues from code review


SihaoLiu Jan 15, 2026
f1ca666

test(hooks): add stop hook plan file integrity tests


SihaoLiu Jan 15, 2026
9e21520

refactor(loop): unify loop directory and state management concepts


SihaoLiu Jan 15, 2026
5261ecc

refactor(hooks): consolidate state parsing and fix pipefail issues


SihaoLiu Jan 15, 2026
76982ea

fix(plan-file): fix YAML injection and add space validation


SihaoLiu Jan 15, 2026
e93a1b0

fix(security): harden injection prevention and add comprehensive tests


SihaoLiu Jan 15, 2026
0d87b6f

fix(plan-file): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
b49dad6

fix(security): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
c3165b6

fix(tests): use dynamic branch name instead of hardcoded main


SihaoLiu Jan 16, 2026
90e7c52

fix(security): verify plan content matches backup even for tracked files


SihaoLiu Jan 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
.claude-plugin/marketplace.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
 "name": "humanize",
 "source": "./",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1"
 "version": "1.1.2"
 }
 ]
}

2 changes: 1 addition & 1 deletion
.claude-plugin/plugin.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
 "name": "humanize",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1",
 "version": "1.1.2",
 "author": {
 "name": "humania-org"
 },
Expand Down

51 changes: 51 additions & 0 deletions
.github/workflows/plan-file-test.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
 push:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'
 pull_request:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install dependencies
 run: |
 sudo apt-get update
 sudo apt-get install -y jq

 - name: Run plan file validation tests
 run: |
 chmod +x tests/test-plan-file-validation.sh
 ./tests/test-plan-file-validation.sh

 - name: Run plan file hook tests
 run: |
 chmod +x tests/test-plan-file-hooks.sh
 ./tests/test-plan-file-hooks.sh

 - name: Run state exit naming tests
 run: |
 chmod +x tests/test-state-exit-naming.sh
 ./tests/test-state-exit-naming.sh

3 changes: 2 additions & 1 deletion
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down

25 changes: 17 additions & 8 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
 - `round-N-codex-run.cmd` - Command invoked
Expand Down

29 changes: 20 additions & 9 deletions
commands/cancel-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
 - Read the state file to get the current round number
 - Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
 - Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
 - Read the state file to get the current round number and max iterations
 - Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
 - Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.

2 changes: 1 addition & 1 deletion
commands/start-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down

10 changes: 10 additions & 0 deletions
hooks/hooks.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
 "description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
 "hooks": {
 "UserPromptSubmit": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Write",
Expand Down

40 changes: 40 additions & 0 deletions
hooks/lib/loop-common.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

 local patterns=(
 ">[[:space:]]*[^[:space:]]*${file_pattern}"
 ">>[[:space:]]*[^[:space:]]*${file_pattern}"
 "tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "sed[[:space:]]+-i[^|]*${file_pattern}"
 "awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
 "perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
 "(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
 "rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
 "truncate[[:space:]]+[^|]*${file_pattern}"
 "printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
 "exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
 )

 for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
 "CURRENT_ROUND=$current_round" \
 "SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
 local loop_dir="$1"
 local state_file="$2"
 local reason="$3" # complete, cancel, maxiter, stop, unexpected

 # Validate reason
 case "$reason" in
 complete|cancel|maxiter|stop|unexpected)
 ;;
 *)
 echo "Error: Invalid end_loop reason: $reason" >&2
 return 1
 ;;
 esac

 local target_name="${reason}-state.md"

 if [[ -f "$state_file" ]]; then
 mv "$state_file" "$loop_dir/$target_name"
 echo "Loop ended: $reason" >&2
 echo "State preserved as: $loop_dir/$target_name" >&2
 return 0
 else
 echo "Warning: State file not found, cannot end loop" >&2
 return 1
 fi
}

13 changes: 13 additions & 0 deletions
hooks/loop-bash-validator.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
 exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
 FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
 REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
 echo "$REASON" >&2
 exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

SihaoLiu
merged 12 commits into

from

Jan 16, 2026
 Merged


feat(cli): add --plan-file and --track-plan-file options with comprehensive validation
#8
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
16c6b6b

[command] fix bash command exec format


SihaoLiu Jan 15, 2026
dcf7cbf

impl(cli) init implementation effort to add CLI to track plan file


SihaoLiu Jan 15, 2026
c83c416

fix(hooks): address critical issues from code review


SihaoLiu Jan 15, 2026
f1ca666

test(hooks): add stop hook plan file integrity tests


SihaoLiu Jan 15, 2026
9e21520

refactor(loop): unify loop directory and state management concepts


SihaoLiu Jan 15, 2026
5261ecc

refactor(hooks): consolidate state parsing and fix pipefail issues


SihaoLiu Jan 15, 2026
76982ea

fix(plan-file): fix YAML injection and add space validation


SihaoLiu Jan 15, 2026
e93a1b0

fix(security): harden injection prevention and add comprehensive tests


SihaoLiu Jan 15, 2026
0d87b6f

fix(plan-file): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
b49dad6

fix(security): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
c3165b6

fix(tests): use dynamic branch name instead of hardcoded main


SihaoLiu Jan 16, 2026
90e7c52

fix(security): verify plan content matches backup even for tracked files


SihaoLiu Jan 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
.claude-plugin/marketplace.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
 "name": "humanize",
 "source": "./",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1"
 "version": "1.1.2"
 }
 ]
}

2 changes: 1 addition & 1 deletion
.claude-plugin/plugin.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
 "name": "humanize",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1",
 "version": "1.1.2",
 "author": {
 "name": "humania-org"
 },
Expand Down

51 changes: 51 additions & 0 deletions
.github/workflows/plan-file-test.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
 push:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'
 pull_request:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install dependencies
 run: |
 sudo apt-get update
 sudo apt-get install -y jq

 - name: Run plan file validation tests
 run: |
 chmod +x tests/test-plan-file-validation.sh
 ./tests/test-plan-file-validation.sh

 - name: Run plan file hook tests
 run: |
 chmod +x tests/test-plan-file-hooks.sh
 ./tests/test-plan-file-hooks.sh

 - name: Run state exit naming tests
 run: |
 chmod +x tests/test-state-exit-naming.sh
 ./tests/test-state-exit-naming.sh

3 changes: 2 additions & 1 deletion
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down

25 changes: 17 additions & 8 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
 - `round-N-codex-run.cmd` - Command invoked
Expand Down

29 changes: 20 additions & 9 deletions
commands/cancel-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
 - Read the state file to get the current round number
 - Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
 - Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
 - Read the state file to get the current round number and max iterations
 - Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
 - Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.

2 changes: 1 addition & 1 deletion
commands/start-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down

10 changes: 10 additions & 0 deletions
hooks/hooks.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
 "description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
 "hooks": {
 "UserPromptSubmit": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Write",
Expand Down

40 changes: 40 additions & 0 deletions
hooks/lib/loop-common.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

 local patterns=(
 ">[[:space:]]*[^[:space:]]*${file_pattern}"
 ">>[[:space:]]*[^[:space:]]*${file_pattern}"
 "tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "sed[[:space:]]+-i[^|]*${file_pattern}"
 "awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
 "perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
 "(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
 "rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
 "truncate[[:space:]]+[^|]*${file_pattern}"
 "printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
 "exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
 )

 for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
 "CURRENT_ROUND=$current_round" \
 "SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
 local loop_dir="$1"
 local state_file="$2"
 local reason="$3" # complete, cancel, maxiter, stop, unexpected

 # Validate reason
 case "$reason" in
 complete|cancel|maxiter|stop|unexpected)
 ;;
 *)
 echo "Error: Invalid end_loop reason: $reason" >&2
 return 1
 ;;
 esac

 local target_name="${reason}-state.md"

 if [[ -f "$state_file" ]]; then
 mv "$state_file" "$loop_dir/$target_name"
 echo "Loop ended: $reason" >&2
 echo "State preserved as: $loop_dir/$target_name" >&2
 return 0
 else
 echo "Warning: State file not found, cannot end loop" >&2
 return 1
 fi
}

13 changes: 13 additions & 0 deletions
hooks/loop-bash-validator.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
 exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
 FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
 REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
 echo "$REASON" >&2
 exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat(cli): add --plan-file and --track-plan-file options with comprehensive validation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

SihaoLiu
merged 12 commits into

from

Jan 16, 2026
 Merged


feat(cli): add --plan-file and --track-plan-file options with comprehensive validation
#8
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


12 commits


Select commit
Hold shift + click to select a range
16c6b6b

[command] fix bash command exec format


SihaoLiu Jan 15, 2026
dcf7cbf

impl(cli) init implementation effort to add CLI to track plan file


SihaoLiu Jan 15, 2026
c83c416

fix(hooks): address critical issues from code review


SihaoLiu Jan 15, 2026
f1ca666

test(hooks): add stop hook plan file integrity tests


SihaoLiu Jan 15, 2026
9e21520

refactor(loop): unify loop directory and state management concepts


SihaoLiu Jan 15, 2026
5261ecc

refactor(hooks): consolidate state parsing and fix pipefail issues


SihaoLiu Jan 15, 2026
76982ea

fix(plan-file): fix YAML injection and add space validation


SihaoLiu Jan 15, 2026
e93a1b0

fix(security): harden injection prevention and add comprehensive tests


SihaoLiu Jan 15, 2026
0d87b6f

fix(plan-file): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
b49dad6

fix(security): address code review issues for plan file CLI


SihaoLiu Jan 16, 2026
c3165b6

fix(tests): use dynamic branch name instead of hardcoded main


SihaoLiu Jan 16, 2026
90e7c52

fix(security): verify plan content matches backup even for tracked files


SihaoLiu Jan 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 1 addition & 1 deletion
.claude-plugin/marketplace.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@
 "name": "humanize",
 "source": "./",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1"
 "version": "1.1.2"
 }
 ]
}

2 changes: 1 addition & 1 deletion
.claude-plugin/plugin.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
{
 "name": "humanize",
 "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
 "version": "1.1.1",
 "version": "1.1.2",
 "author": {
 "name": "humania-org"
 },
Expand Down

51 changes: 51 additions & 0 deletions
.github/workflows/plan-file-test.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
name: Plan File Validation Tests

on:
 push:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'
 pull_request:
 paths:
 - 'scripts/setup-rlcr-loop.sh'
 - 'hooks/loop-plan-file-validator.sh'
 - 'hooks/loop-codex-stop-hook.sh'
 - 'hooks/loop-write-validator.sh'
 - 'hooks/loop-edit-validator.sh'
 - 'hooks/loop-bash-validator.sh'
 - 'hooks/lib/loop-common.sh'
 - 'tests/test-plan-file-*.sh'
 - 'tests/test-state-exit-naming.sh'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install dependencies
 run: |
 sudo apt-get update
 sudo apt-get install -y jq

 - name: Run plan file validation tests
 run: |
 chmod +x tests/test-plan-file-validation.sh
 ./tests/test-plan-file-validation.sh

 - name: Run plan file hook tests
 run: |
 chmod +x tests/test-plan-file-hooks.sh
 ./tests/test-plan-file-hooks.sh

 - name: Run state exit naming tests
 run: |
 chmod +x tests/test-state-exit-naming.sh
 ./tests/test-state-exit-naming.sh

3 changes: 2 additions & 1 deletion
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
wip
# Scratchpad
temp

# Humanize loop state directory (used by start-rlcr-loop)
.humanize-loop.local/
Expand Down

25 changes: 17 additions & 8 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
# Humanize

**Current Version: 1.1.1**
**Current Version: 1.1.2**

> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.

Expand DownExpand Up@@ -113,19 +113,20 @@ This provides a real-time dashboard showing:

**The loop is fully interruptible** - you can exit Claude Code at any time and resume later:

- **Loop state**: Controlled solely by the presence of `.humanize-loop.local/*/state.md`
- **Loop state**: Controlled solely by the presence of `state.md` in the current loop directory (newest timestamp in `.humanize-loop.local/`)
- **Resume**: Simply restart Claude Code in the same directory - the loop continues automatically
- **Cancel**: Remove the state file to stop the loop permanently
- **Cancel**: Rename `state.md` to `cancel-state.md` to stop the loop permanently

```bash
# Cancel the active loop
# Cancel the active loop (recommended)
/humanize:cancel-rlcr-loop

# Or manually remove state file
rm .humanize-loop.local/*/state.md
# Or manually rename state file (find newest loop directory first)
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ | sort -r | head -1)
mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"
```

The loop directory with all summaries and review results is preserved for reference.
The loop directory with all summaries, review results, and state information is preserved for reference.

## Goal Tracker System

Expand DownExpand Up@@ -243,13 +244,21 @@ humanize/
When loop is active, creates: `.humanize-loop.local/<TIMESTAMP>/`

**Files Created**:
- `state.md` - Current round, config (YAML frontmatter)
- `state.md` - Current round, config (YAML frontmatter). Presence indicates active loop.
- `plan.md` - Backup copy of the plan file (for integrity verification)
- `goal-tracker.md` - Immutable (goals/AC) + Mutable (active tasks, deferred, etc.)
- `round-N-prompt.md` - Instructions FROM Codex TO Claude
- `round-N-summary.md` - Work summary written BY Claude
- `round-N-review-prompt.md` - Prompt sent to Codex
- `round-N-review-result.md` - Codex's review output

**Exit State Files** (state.md renamed on loop end):
- `complete-state.md` - Loop completed successfully (Codex confirmed all goals met)
- `cancel-state.md` - User cancelled via `/humanize:cancel-rlcr-loop`
- `maxiter-state.md` - Reached maximum iteration limit
- `stop-state.md` - Codex triggered circuit breaker
- `unexpected-state.md` - Schema/integrity issues or abnormal termination

**Cache Directory** (not in project):
- `$HOME/.cache/humanize/<sanitized-project-path>/<timestamp>/`
 - `round-N-codex-run.cmd` - Command invoked
Expand Down

29 changes: 20 additions & 9 deletions
commands/cancel-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
---
description: "Cancel active RLCR loop"
allowed-tools: ["Bash(ls .humanize-loop.local/*/state.md:*)", "Bash(rm .humanize-loop.local/*/state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
allowed-tools: ["Bash(ls -1d .humanize-loop.local/*/)", "Bash(mv .humanize-loop.local/*/state.md .humanize-loop.local/*/cancel-state.md)", "Bash(cat .humanize-loop.local/*/state.md)", "Read"]
hide-from-slash-command-tool: "true"
---

# Cancel RLCR Loop

To cancel the active loop:

1. Check if any loop is active by looking for state files:
1. Find the current loop directory (newest timestamp):

```bash
ls .humanize-loop.local/*/state.md 2>/dev/null || echo "NO_LOOP"
LOOP_DIR=$(ls -1d .humanize-loop.local/*/ 2>/dev/null | sort -r | head -1)
echo "Loop dir: ${LOOP_DIR:-NONE}"
```

2. **If NO_LOOP**: Say "No active RLCR loop found."
2. **If NONE**: Say "No active RLCR loop found."

3. **If state file(s) found**:
 - Read the state file to get the current round number
 - Remove the state file(s) using: `rm .humanize-loop.local/*/state.md`
 - Report: "Cancelled RLCR loop (was at round N of M)"
3. Check if the current loop is active (state.md exists):

The loop directory with summaries and review results will be preserved for reference.
```bash
ls "${LOOP_DIR}state.md" 2>/dev/null || echo "NO_ACTIVE_LOOP"
```

4. **If NO_ACTIVE_LOOP**: Say "No active RLCR loop found. (Loop directory exists but no state.md)"

5. **If state.md found**:
 - Read the state file to get the current round number and max iterations
 - Rename state.md to cancel-state.md: `mv "${LOOP_DIR}state.md" "${LOOP_DIR}cancel-state.md"`
 - Report: "Cancelled RLCR loop (was at round N of M). State preserved as cancel-state.md"

**Key principle**: The current loop directory is always the one with the newest timestamp. A loop is active only if `state.md` exists in that directory.

The loop directory with summaries, review results, and state information will be preserved for reference.

2 changes: 1 addition & 1 deletion
commands/start-rlcr-loop.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ hide-from-slash-command-tool: "true"

Execute the setup script to initialize the loop:

```!
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh" $ARGUMENTS
```

Expand Down

10 changes: 10 additions & 0 deletions
hooks/hooks.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
{
 "description": "Humanize Plugin Hooks - Validation hooks and Stop hooks for /start-rlcr-loop",
 "hooks": {
 "UserPromptSubmit": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/hooks/loop-plan-file-validator.sh"
 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Write",
Expand Down

40 changes: 40 additions & 0 deletions
hooks/lib/loop-common.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -161,12 +161,17 @@ command_modifies_file() {

 local patterns=(
 ">[[:space:]]*[^[:space:]]*${file_pattern}"
 ">>[[:space:]]*[^[:space:]]*${file_pattern}"
 "tee[[:space:]]+(-a[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "sed[[:space:]]+-i[^|]*${file_pattern}"
 "awk[[:space:]]+-i[[:space:]]+inplace[^|]*${file_pattern}"
 "perl[[:space:]]+-[^[:space:]]*i[^|]*${file_pattern}"
 "(mv|cp)[[:space:]]+[^[:space:]]+[[:space:]]+[^[:space:]]*${file_pattern}"
 "rm[[:space:]]+(-[rfv]+[[:space:]]+)?[^[:space:]]*${file_pattern}"
 "dd[[:space:]].*of=[^[:space:]]*${file_pattern}"
 "truncate[[:space:]]+[^|]*${file_pattern}"
 "printf[[:space:]].*>[[:space:]]*[^[:space:]]*${file_pattern}"
 "exec[[:space:]]+[0-9]*>[[:space:]]*[^[:space:]]*${file_pattern}"
 )

 for pattern in "${patterns[@]}"; do
Expand All@@ -190,3 +195,38 @@ After Round 0, only Codex can modify the Goal Tracker. Include a Goal Tracker Up
 "CURRENT_ROUND=$current_round" \
 "SUMMARY_FILE=$summary_file"
}

# End the loop by renaming state.md to indicate exit reason
# Usage: end_loop "$loop_dir" "$state_file" "complete|cancel|maxiter|stop|unexpected"
# Arguments:
# $1 - loop_dir: Path to the loop directory
# $2 - state_file: Path to the state.md file
# $3 - reason: One of complete, cancel, maxiter, stop, unexpected
# Returns: 0 on success, 1 on failure
end_loop() {
 local loop_dir="$1"
 local state_file="$2"
 local reason="$3" # complete, cancel, maxiter, stop, unexpected

 # Validate reason
 case "$reason" in
 complete|cancel|maxiter|stop|unexpected)
 ;;
 *)
 echo "Error: Invalid end_loop reason: $reason" >&2
 return 1
 ;;
 esac

 local target_name="${reason}-state.md"

 if [[ -f "$state_file" ]]; then
 mv "$state_file" "$loop_dir/$target_name"
 echo "Loop ended: $reason" >&2
 echo "State preserved as: $loop_dir/$target_name" >&2
 return 0
 else
 echo "Warning: State file not found, cannot end loop" >&2
 return 1
 fi
}

13 changes: 13 additions & 0 deletions
hooks/loop-bash-validator.sh

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -74,6 +74,19 @@ if command_modifies_file "$COMMAND_LOWER" "state\.md"; then
 exit 2
fi

# ========================================
# Block Plan Backup Modifications (All Rounds)
# ========================================
# Plan backup is read-only - protects plan integrity during loop
# Use command_modifies_file helper for consistent pattern matching

if command_modifies_file "$COMMAND_LOWER" "\.humanize-loop\.local(/[^/]+)?/plan\.md"; then
 FALLBACK="Writing to plan.md backup is not allowed during RLCR loop."
 REASON=$(load_and_render_safe "$TEMPLATE_DIR" "block/plan-backup-protected.md" "$FALLBACK")
 echo "$REASON" >&2
 exit 2
fi

# ========================================
# Block Goal Tracker Modifications (All Rounds)
# ========================================
Expand Down
Loading