@ksuchoi216/ahe 0.1.2 → 0.1.7

package/.codex/ahe-shared/config.yaml

@@ -0,0 +1,8 @@
+agent_md: 80
+product_md: 180
+instructions_md: 180
+feature_list_json: 180
+progress_md: 180
+session_handoff_md: 180
+todo_md: 180
+total: 750

package/.codex/hooks/ahe-hook.js

@@ -1,137 +1,195 @@
 #!/usr/bin/env node
 const AHE_DIRECTIVE_MARKER = "<ahe-mode>";
+
+const STATUS_TABLE_LINES = [
+  "   - Start the response with a concise status report table.",
+  "   - Use this consistent Markdown table format:",
+  "     | Item | Content |",
+  "     |---|---|",
+  "     | AGENTS.md | Exists/missing, purpose status, and any obvious issue. |",
+  "     | PRODUCT.md | Exists/missing, completion state, and whether product scope needs work. |",
+  "     | INSTRUCTIONS.md | Exists/missing, and whether instruction boundaries need work. |",
+  "     | feature-list.json | Valid/missing/invalid, unfinished feature summary, and all-done status. |",
+  "     | PROGRESS.md | Exists/missing and current session state. |",
+  "   - Keep the table short and readable.",
+  "   - Do not include the next step inside the table.",
+];
+
+const COMMON_ROUTING_LINES = [
+  "1. Run CodeGraph preflight before inspecting harness status:",
+  "   - Check whether the CodeGraph CLI is installed with `command -v codegraph`.",
+  "   - If the `codegraph` command is not installed, report `NOT INSTALLATION of codegraph`, skip `codegraph init` and `codegraph sync`, and continue with normal repo inspection.",
+  "   - If `.codegraph/` does not exist, run `codegraph init` before reviewing code.",
+  "   - If `.codegraph/` exists, run `codegraph sync` before reviewing code.",
+  "",
+  "2. Inspect current harness state before choosing a workflow:",
+  "   - Check `AGENTS.md`.",
+  "   - Check `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the product/specification source of truth.",
+  "   - Check `feature-list.json` as a derived tracker.",
+  "   - Check `PROGRESS.md`.",
+  "   - Use `ahe-thinker` as the internal decision layer before choosing the next action.",
+  "   - Before reading large harness files wholesale, let `ahe-thinker` run the `ahe-compression` size detector and call `ahe-compression` if compression is required.",
+  "",
+  "3. Review code through CodeGraph when available:",
+  "   - Prefer CodeGraph MCP or CodeGraph exploration for code review and impact context after the preflight command succeeds.",
+  "   - If CodeGraph is not installed, skip CodeGraph review and rely on normal repo inspection.",
+  "",
+  "4. Make the first response a simple harness engineering status report table before proceeding:",
+  ...STATUS_TABLE_LINES,
+];
+
 const AHE_PROGRESS_DIRECTIVE = [
+  AHE_DIRECTIVE_MARKER,
+  "AHE automatic operation activated.",
+  "",
+  "The user sent the exact AHE command. Operate as the Awesome Harness Engineering router:",
+  "",
+  ...COMMON_ROUTING_LINES,
+  "",
+  "5. Decide the next AHE workflow with `ahe-thinker`:",
+  "   - If no harness files exist, route to `$ahe-init`.",
+  "   - If `docs/PRODUCT.md` or `docs/INSTRUCTIONS.md` is missing or empty, classify the state as `harness engineering not enough`.",
+  "   - If `feature-list.json` is missing or invalid, generating an empty one from template is allowed, but do not write specific features until `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` are created and organized.",
+  "   - If any feature in `feature-list.json` has a status other than `done`, classify the state as `in the middle of building features` and continue the first unfinished feature whose dependencies are satisfied.",
+  "   - If all features are `done` and no obvious harness gap remains, classify the state as `completed all` and ask the user for the next task.",
+  "   - Call `ahe-reviewer` when repo or code understanding is needed.",
+  "   - Call `ahe-conversator` when the next safe step is blocked on user input.",
+  "   - Call `ahe-harness` when product docs, instructions, tracking, todo sync, or compression-aware harness maintenance must change.",
+  "   - Call `ahe-solver` when the next job is solving or planning a feature.",
+  "",
+  "6. After the table, classify the harness into exactly one state.",
+  "   - Use exactly one state: `harness engineering not enough`, `in the middle of building features`, or `completed all`.",
+  "   - Do not include the next step inside the table.",
+  "   - Continue automatically after classification.",
+];
+
+const AHE_INIT_DIRECTIVE = [
+  AHE_DIRECTIVE_MARKER,
+  "AHE automatic operation activated.",
+  "",
+  "The user sent the exact AHE init command. Treat this as a possible new start request:",
+  "",
+  "1. Route to `$ahe-init` first.",
+  "2. If no AHE-managed harness files exist, start initialization normally.",
+  "3. If any AHE-managed harness file exists, read the existing files, summarize the current project purpose and product specification state, and ask what restart scope the user wants.",
+  "4. Do not remove, overwrite, or refresh existing harness files before the user answers the restart-scope question.",
+  "5. If the chosen restart scope replaces prior harness history, summarize that replaced state in the refreshed tracking artifacts instead of creating backup copies.",
+  "6. Interpret the restart scope from the user's free-form answer; examples like `purpose` and `product` are not a closed list.",
+  "7. Product/instructions specification details belong in `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md`, not `AGENTS.md`.",
+  "8. After setup, call `ahe-harness` to build the initial product, instructions, and tracking state.",
+  "9. Use `ahe-thinker` before clarification when the next setup step is uncertain.",
+  "10. If clarification is needed, call `ahe-conversator` for the exact missing detail.",
+].join("\n");
+
+function getQueryDirective(prompt) {
+  return [
     AHE_DIRECTIVE_MARKER,
     "AHE automatic operation activated.",
     "",
-    "The user sent the exact AHE command. Operate as the Awesome Harness Engineering router:",
+    `Original prompt: "${prompt}"`,
     "",
-    "1. Run CodeGraph preflight before inspecting harness status:",
-    "   - Check whether the CodeGraph CLI is installed with `command -v codegraph`.",
-    "   - If the `codegraph` command is not installed, report `NOT INSTALLATION of codegraph`, skip `codegraph init` and `codegraph sync`, and continue with normal repo inspection.",
-    "   - If `.codegraph/` does not exist, run `codegraph init` before reviewing code.",
-    "   - If `.codegraph/` exists, run `codegraph sync` before reviewing code.",
+    "The user sent an explicit AHE query. Route it through `ahe-thinker`:",
     "",
-    "2. Inspect current harness state before choosing a workflow:",
-    "   - Check `AGENTS.md`.",
-    "   - Check `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the product/specification source of truth.",
-    "   - Check `feature-list.json` as a derived tracker.",
-    "   - Check `PROGRESS.md`.",
-    "   - Use `ahe-thinking` as the internal decision layer before choosing the next action.",
+    ...COMMON_ROUTING_LINES,
     "",
-    "3. Review code through CodeGraph when available:",
-    "   - Prefer CodeGraph MCP or CodeGraph exploration for code review and impact context after the preflight command succeeds.",
-    "   - If CodeGraph is not installed, skip CodeGraph review and rely on normal repo inspection.",
+    "5. Decide the next AHE workflow with `ahe-thinker` based on the original prompt:",
+    "   - Use `ahe-reviewer` for code or harness review work.",
+    "   - Use `ahe-harness` for product, instructions, progress, feature-list, todo, or compression maintenance.",
+    "   - For `ahe compress feature-list`, replace old completed feature entries with one summarized done feature, preserve unfinished details, and reconcile `feature-list.json` against `docs/PRODUCT.md`.",
+    "   - If no new feature can be derived from `docs/PRODUCT.md`, call `ahe-conversator` to ask what next feature, product direction, or goal should be tracked.",
+    "   - Use `ahe-solver` for feature-solving work.",
+    "   - If multiple plausible next steps remain, use `ahe-conversator` to ask the minimum question needed.",
     "",
-    "4. Make the first response a simple harness engineering status report table before proceeding:",
-    "   - Start the response with a concise status report table.",
-    "   - Use this consistent Markdown table format:",
-    "     | Item | Content |",
-    "     |---|---|",
-    "     | AGENTS.md | Exists/missing, purpose status, and any obvious issue. |",
-    "     | PRODUCT.md | Exists/missing, completion state, and whether product scope needs work. |",
-    "     | INSTRUCTIONS.md | Exists/missing, and whether instruction boundaries need work. |",
-    "     | feature-list.json | Valid/missing/invalid, unfinished feature summary, and all-done status. |",
-    "     | PROGRESS.md | Exists/missing and current session state. |",
-    "   - Keep the table short and readable.",
-    "   - Do not include the next step inside the table.",
-    "",
-    "5. Decide the next AHE workflow with `ahe-thinking`:",
-    "   - If no harness files exist, route to `$ahe-init`.",
-    "   - If `docs/PRODUCT.md` or `docs/INSTRUCTIONS.md` is missing or empty, classify the state as `harness engineering not enough` and prioritize product/instructions specification.",
-    "   - If `feature-list.json` is missing or invalid, generating an empty one from template is allowed, but do not write specific features until `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` are created and organized.",
-    "   - If any feature in `feature-list.json` has a status other than `done`, classify the state as `in the middle of building features` and continue the first unfinished feature whose dependencies are satisfied.",
-    "   - Respect dependencies listed in `feature-list.json`; do not start a dependent feature before prerequisites are done.",
-    "   - If all features are `done` and no obvious harness gap remains, classify the state as `completed all` and ask the user for the next task.",
-    "   - Judge the active `project`, `feature`, or `sub-feature` before moving forward.",
-    "   - For a `project`, require `Why`, `What`, and `How` by default.",
-    "   - For a `feature` or `sub-feature`, require only the minimum of `Why`, `What`, and `How` needed to proceed safely.",
-    "",
-    "6. Ask for clarification instead of guessing:",
-    "   - If multiple plausible next steps exist, feature data conflicts, dependencies are unclear, or CodeGraph review points to several valid directions, use `ahe-thinking` to judge the missing detail.",
-    "   - If clarity is missing, call `ahe-conversation` for the exact missing `Why`, `What`, or `How`.",
-    "   - Continue only after one safe next step is clear.",
-    "",
-    "7. After the table, classify the harness into exactly one state.",
+    "6. After the table, classify the harness into exactly one state.",
     "   - Use exactly one state: `harness engineering not enough`, `in the middle of building features`, or `completed all`.",
     "   - Do not include the next step inside the table.",
     "   - Continue automatically after classification.",
-    "   - Follow this loop: `thinking -> conversation if needed -> execution -> thinking`.",
-].join("\\n");
+  ].join("\n");
+}
 
-const AHE_INIT_DIRECTIVE = [
-    AHE_DIRECTIVE_MARKER,
-    "AHE automatic operation activated.",
-    "",
-    "The user sent the exact AHE init command. Treat this as a possible new start request:",
-    "",
-    "1. Route to `$ahe-init` first.",
-    "2. If no AHE-managed harness files exist, start initialization normally.",
-    "3. If any AHE-managed harness file exists, read the existing files, summarize the current project purpose and product specification state, and ask what restart scope the user wants.",
-    "4. Do not back up, remove, overwrite, or refresh existing harness files before the user answers the restart-scope question.",
-    "5. Interpret the restart scope from the user's free-form answer; examples like `purpose` and `product` are not a closed list.",
-    "6. Product/instructions specification details belong in `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md`, not `AGENTS.md`.",
-    "7. Use `ahe-thinking` before clarification when the next setup step is uncertain.",
-    "8. If clarification is needed, call `ahe-conversation` for the exact missing detail.",
-    "9. Continue through initialization work until the new start path is clear.",
-].join("\\n");
+function normalizePrompt(prompt) {
+  return prompt.trim().toLowerCase();
+}
 
 function isExactAheCommand(prompt) {
-    return normalizePrompt(prompt) === "ahe";
+  return normalizePrompt(prompt) === "ahe";
 }
 
 function isExactAheInitCommand(prompt) {
-    const normalizedPrompt = normalizePrompt(prompt);
-    return (
-        normalizedPrompt === "ahe init" ||
-        normalizedPrompt === "ahe-init" ||
-        normalizedPrompt === "$ahe-init"
-    );
+  const normalizedPrompt = normalizePrompt(prompt);
+  return (
+    normalizedPrompt === "ahe init" ||
+    normalizedPrompt === "ahe-init" ||
+    normalizedPrompt === "$ahe-init"
+  );
 }
 
-function normalizePrompt(prompt) {
-    return prompt.trim().toLowerCase();
+function isExplicitAheQuery(prompt) {
+  const normalizedPrompt = normalizePrompt(prompt);
+  if (isExactAheCommand(prompt) || isExactAheInitCommand(prompt)) {
+    return false;
+  }
+  return normalizedPrompt.startsWith("ahe ");
 }
 
 async function main() {
-    let raw = "";
-    process.stdin.setEncoding("utf8");
-    for await (const chunk of process.stdin) {
-        raw += chunk;
-    }
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) {
+    raw += chunk;
+  }
+
+  if (!raw.trim()) {
+    return;
+  }
 
-    if (!raw.trim()) return;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  if (
+    parsed &&
+    parsed.hook_event_name === "UserPromptSubmit" &&
+    typeof parsed.prompt === "string"
+  ) {
+    if (isExactAheCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_PROGRESS_DIRECTIVE.join("\n"),
+          },
+        }) + "\n"
+      );
+      return;
+    }
 
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    } catch (e) {
-        return;
+    if (isExactAheInitCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_INIT_DIRECTIVE,
+          },
+        }) + "\n"
+      );
+      return;
     }
 
-    if (
-        parsed &&
-        parsed.hook_event_name === "UserPromptSubmit" &&
-        typeof parsed.prompt === "string"
-    ) {
-        if (isExactAheCommand(parsed.prompt)) {
-            const output = {
-                hookSpecificOutput: {
-                    hookEventName: "UserPromptSubmit",
-                    additionalContext: AHE_PROGRESS_DIRECTIVE
-                }
-            };
-            process.stdout.write(JSON.stringify(output) + "\n");
-        } else if (isExactAheInitCommand(parsed.prompt)) {
-            const output = {
-                hookSpecificOutput: {
-                    hookEventName: "UserPromptSubmit",
-                    additionalContext: AHE_INIT_DIRECTIVE
-                }
-            };
-            process.stdout.write(JSON.stringify(output) + "\n");
-        }
+    if (isExplicitAheQuery(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: getQueryDirective(parsed.prompt),
+          },
+        }) + "\n"
+      );
     }
+  }
 }
 
 main().catch(() => {});

package/.codex/skills/ahe-compression/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: ahe-compression
+description: Internal AHE compression workflow for detecting oversized harness-engineering files and compacting them before AHE thinker or harness routing reads large context. Use when AGENTS.md, docs/PRODUCT.md, docs/INSTRUCTIONS.md, feature-list.json, PROGRESS.md, SESSION-HANDOFF.md, docs/todo.md, or other AHE harness artifacts have too many lines or waste context.
+---
+
+# AHE Compression
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-compression` as a user command.
+Use it after `ahe-thinker` or `ahe-harness` decides that harness context is too large to read
+efficiently.
+
+## Size Detection
+
+Run the deterministic line-count preflight before reading full harness files:
+
+```bash
+sh .codex/skills/ahe-compression/scripts/check-harness-size.sh
+```
+
+The script checks these AHE-managed files when they exist:
+
+- `AGENTS.md`
+- `docs/PRODUCT.md`
+- `docs/INSTRUCTIONS.md`
+- `feature-list.json`
+- `PROGRESS.md`
+- `SESSION-HANDOFF.md`
+- `docs/todo.md`
+
+Default thresholds are configured in `.codex/ahe-shared/config.yaml`:
+
+- `agent_md`: 80
+- `product_md`: 180
+- `instructions_md`: 180
+- `feature_list_json`: 180
+- `progress_md`: 180
+- `session_handoff_md`: 180
+- `todo_md`: 180
+- `total`: 750 (combined harness context limit)
+
+Override thresholds only when the workspace has an explicit local rule using environment variables (e.g., `AHE_AGENT_MD_LIMIT`, `AHE_FILE_LINE_LIMIT`, `AHE_TOTAL_LINE_LIMIT`):
+
+```bash
+AHE_AGENT_MD_LIMIT=100 AHE_TOTAL_LINE_LIMIT=900 sh .codex/skills/ahe-compression/scripts/check-harness-size.sh
+```
+
+Exit code meanings:
+
+- `0`: no compression needed.
+- `2`: compression needed.
+- Output ending in `COMPRESSION_REQUIRED`: compression needed.
+- Any other nonzero code: detector failed; fall back to `wc -l` on the same
+  file set and continue the decision manually.
+
+## Compression Decision
+
+- If the detector exits `2`, compress before normal AHE routing continues.
+- If only one file exceeds the per-file threshold, compress that file first.
+- If total harness context exceeds the total threshold, compress the largest
+  AHE-managed files until the total is under the threshold.
+- If `AGENTS.md` is oversized, obey the local `AGENTS.md` instructions before
+  editing it. Compress only sections that local rules allow. If no section is
+  safely editable, report the blocker and compress other harness files instead.
+- Do not read an oversized file wholesale after detection. Read headings,
+  current-status sections, JSON keys, or bounded line ranges needed to preserve
+  behavior.
+
+## Compression Rules
+
+- Preserve active requirements, current decisions, incomplete work, blockers,
+  dependencies, and verification evidence.
+- Preserve required headers and file formats for `PROGRESS.md`,
+  `SESSION-HANDOFF.md`, `feature-list.json`, and `AGENTS.md`.
+- Keep `feature-list.json` valid JSON. Replace stale completed-feature history
+  with one summarized done feature, preserve its `id`, `name`, `description`,
+  `dependencies`, `status`, and short evidence, and keep current unfinished
+  details as-is.
+- Keep `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the current harness
+  contract. Remove duplicate historical wording only when the active contract
+  remains clear.
+- Keep `PROGRESS.md` focused on current status, recent completed work,
+  decisions that still matter, blockers, and latest verification.
+- Keep `SESSION-HANDOFF.md` focused on the startup path for the next session,
+  important files, open questions, and current verification status.
+- Do not create backup copies when compressing harness history. Preserve useful
+  context through concise summaries in the refreshed harness files instead.
+
+## Completion
+
+- Re-run the size detector after compression.
+- Run JSON validation when `feature-list.json` changed.
+- Run the repository's normal harness verification command when compression
+  changed tracked harness files.
+- Update `PROGRESS.md` and `SESSION-HANDOFF.md` with the compression evidence
+  when they changed or when compression affects the active workflow.

package/.codex/skills/ahe-compression/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "AHE Compression"
+  short_description: "Compress oversized harness context"
+  default_prompt: "Use $ahe-compression to compact oversized AHE harness files before continuing."
+policy:
+  allow_implicit_invocation: false

package/.codex/skills/ahe-compression/scripts/check-harness-size.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env sh
+set -eu
+
+limit_agent_md=180
+limit_product_md=180
+limit_instructions_md=180
+limit_feature_list_json=180
+limit_progress_md=180
+limit_session_handoff_md=180
+limit_todo_md=180
+limit_total=750
+
+config_file=".codex/ahe-shared/config.yaml"
+if [ -f "${config_file}" ]; then
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    case "$line" in
+      "" | \#*) continue ;;
+    esac
+    
+    key="${line%%:*}"
+    val="${line#*:}"
+    key="${key%"${key##*[![:space:]]}"}"
+    val="${val#"${val%%[![:space:]]*}"}"
+    
+    case "$val" in
+      ''|*[!0-9]*) continue ;;
+    esac
+
+    case "$key" in
+      agent_md) limit_agent_md="$val" ;;
+      product_md) limit_product_md="$val" ;;
+      instructions_md) limit_instructions_md="$val" ;;
+      feature_list_json) limit_feature_list_json="$val" ;;
+      progress_md) limit_progress_md="$val" ;;
+      session_handoff_md) limit_session_handoff_md="$val" ;;
+      todo_md) limit_todo_md="$val" ;;
+      total) limit_total="$val" ;;
+    esac
+  done < "${config_file}"
+fi
+
+limit_agent_md="${AHE_AGENT_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_agent_md}}"
+limit_product_md="${AHE_PRODUCT_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_product_md}}"
+limit_instructions_md="${AHE_INSTRUCTIONS_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_instructions_md}}"
+limit_feature_list_json="${AHE_FEATURE_LIST_JSON_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_feature_list_json}}"
+limit_progress_md="${AHE_PROGRESS_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_progress_md}}"
+limit_session_handoff_md="${AHE_SESSION_HANDOFF_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_session_handoff_md}}"
+limit_todo_md="${AHE_TODO_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_todo_md}}"
+total_limit="${AHE_TOTAL_LINE_LIMIT:-$limit_total}"
+
+total_lines=0
+compression_required=0
+
+if [ "$#" -eq 0 ]; then
+  set -- \
+    "AGENTS.md" \
+    "docs/PRODUCT.md" \
+    "docs/INSTRUCTIONS.md" \
+    "feature-list.json" \
+    "PROGRESS.md" \
+    "SESSION-HANDOFF.md" \
+    "docs/todo.md"
+fi
+
+for file_path in "$@"; do
+  if [ ! -f "${file_path}" ]; then
+    continue
+  fi
+
+  line_count="$(wc -l < "${file_path}")"
+  line_count="${line_count#"${line_count%%[![:space:]]*}"}"
+  line_count="${line_count%"${line_count##*[![:space:]]}"}"
+  total_lines=$((total_lines + line_count))
+
+  current_limit=180
+  case "${file_path}" in
+    "AGENTS.md") current_limit="${limit_agent_md}" ;;
+    "docs/PRODUCT.md") current_limit="${limit_product_md}" ;;
+    "docs/INSTRUCTIONS.md") current_limit="${limit_instructions_md}" ;;
+    "feature-list.json") current_limit="${limit_feature_list_json}" ;;
+    "PROGRESS.md") current_limit="${limit_progress_md}" ;;
+    "SESSION-HANDOFF.md") current_limit="${limit_session_handoff_md}" ;;
+    "docs/todo.md") current_limit="${limit_todo_md}" ;;
+    *) current_limit="${AHE_FILE_LINE_LIMIT:-180}" ;;
+  esac
+
+  if [ "${line_count}" -ge "${current_limit}" ]; then
+    compression_required=1
+    printf 'COMPRESS\t%s\t%s\tlimit=%s\n' "${file_path}" "${line_count}" "${current_limit}"
+  else
+    printf 'OK\t%s\t%s\tlimit=%s\n' "${file_path}" "${line_count}" "${current_limit}"
+  fi
+done
+
+if [ "${total_lines}" -ge "${total_limit}" ]; then
+  compression_required=1
+  printf 'COMPRESS_TOTAL\t%s\tlimit=%s\n' "${total_lines}" "${total_limit}"
+else
+  printf 'OK_TOTAL\t%s\tlimit=%s\n' "${total_lines}" "${total_limit}"
+fi
+
+if [ "${compression_required}" -eq 1 ]; then
+  printf 'COMPRESSION_REQUIRED\n'
+  exit 2
+fi
+
+printf 'COMPRESSION_NOT_REQUIRED\n'

package/.codex/skills/ahe-conversator/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ahe-conversator
+description: Internal AHE conversation protocol for recursive clarification, conversation state, and resume-aware workflow guidance.
+---
+
+# AHE Conversator
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-conversator` as a user command.
+Use it after `ahe-thinker` or another AHE agent identifies a missing decision or
+missing `Why`, `What`, or `How`.
+
+## When To Converse
+
+- Ask one question at a time.
+- Use conversation state when multiple answers are needed across turns.
+- Clarify product intent, instructions, next feature, restart scope, or any
+  decision that materially changes the workflow.
+- If the answer can be derived safely from repo state, do that instead of
+  asking.
+
+## Conversation Protocol
+
+- Inspect relevant files before asking.
+- Explain the blocked decision briefly.
+- Use a Codex-supported structured response request when it helps.
+- Ask exactly one focused question at a time.
+- Continue recursively until the answer is specific enough to unblock the
+  calling workflow.
+
+## State Persistence
+
+- Update `.ahe/process_status.json` before pausing for user input.
+- Preserve the current command, current_step, workflow_complete, and files map.
+- Update `PROGRESS.md` and `SESSION-HANDOFF.md` when the pending question
+  changes the workflow state.
+
+## Resume Protocol
+
+- Read `.ahe/process_status.json` and the relevant workflow artifacts.
+- Summarize the current state briefly.
+- Ask the next focused question or return control to the caller when the answer
+  resolves the missing detail.