v0.1.3 — Structured Handoff Classifier Output

v0.1.3 — Structured Handoff Classifier Output

RU

Этот релиз усиливает UserPromptSubmit handoff classifier: LLM-путь теперь работает через строгий typed JSON contract, а deterministic logic остаётся fallback/offline guard.

Что добавлено

• LLM classifier переведён на Responses API Structured Outputs через text.format + json_schema + strict=true.
• Добавлен canonical JSON Schema contract для classifier output:
  • intent с enum;
  • typed booleans: should_edit, should_plan, should_use_task_ledger, subagents_authorized, requires_worktree_gate, requires_release_flow, requires_gitnexus_impact;
  • score/confidence;
  • reason, task_brief, architecture_terms, verification_commands, policy_notes.
• Plain JSON parsing оставлен только как compatibility fallback, если structured output не поддержан API/моделью.
• Итоговый hook context теперь рендерится компактно на английском: Flags, Policy, Task brief, Terms, Suggested verification, Policy notes.
• auto и always теперь используют LLM при наличии credentials; HANDOFF_CLASSIFIER_LLM=off включает deterministic-only offline mode.
• Default timeout увеличен до 6.0, чтобы strict structured output не уходил в fallback из-за короткого окна.

Исправления поведения

• Release-запросы вроде пуш на гит и делай новый релиз с информацией об обновлениях теперь классифицируются как:
  • intent=implementation;
  • edit=true;
  • ledger=true;
  • release_flow=true.
• Release-only запросы больше не требуют gitnexus_impact; GitNexus impact поднимается только когда есть code-change intent и проектные правила GitNexus в repo profile.
• Suggested verification commands фильтруются от опасных/нежелательных команд вроде force/reset/rm/shell chaining.
• Previous follow-up state теперь хранит compact typed snapshot (intent, flags, task brief, terms), а не весь длинный rendered context.
• LLM input получает deterministic repo profile, чтобы модель видела project stack, scripts и project rules до генерации structured output.

Не включено

• Plain text / loose JSON mode не переводился в default. Мы оставили strict schema как основной контракт, а loose JSON только как compatibility fallback.
• 5-7 повторных LLM проверок не добавлялись, чтобы не увеличивать latency и стоимость.

Проверка

• python3 -m py_compile hooks/handoff-intake-classifier.py scripts/validate-pack.py
• python3 scripts/validate-pack.py
• git diff --check
• manual release prompt test: intent=implementation, release_flow=true
• manual question-only prompt test: intent=question_only, edit=false
• manual follow-up prompt test with previous context
• deterministic fallback release test

EN

This release strengthens the UserPromptSubmit handoff classifier. The LLM path now uses a strict typed JSON contract while deterministic logic remains the fallback/offline guard.

Added

• The LLM classifier now uses Responses API Structured Outputs through text.format + json_schema + strict=true.
• Added a canonical JSON Schema contract for classifier output:
  • enum-backed intent;
  • typed booleans: should_edit, should_plan, should_use_task_ledger, subagents_authorized, requires_worktree_gate, requires_release_flow, requires_gitnexus_impact;
  • score/confidence;
  • reason, task_brief, architecture_terms, verification_commands, policy_notes.
• Plain JSON parsing remains only as a compatibility fallback when structured output is unsupported by the API/model.
• Rendered hook context is now compact English: Flags, Policy, Task brief, Terms, Suggested verification, Policy notes.
• auto and always now use the LLM whenever credentials are available; HANDOFF_CLASSIFIER_LLM=off enables deterministic-only offline mode.
• Default timeout is now 6.0 to reduce unnecessary fallback from strict structured output.

Behavior fixes

• Release requests such as пуш на гит и делай новый релиз с информацией об обновлениях now classify as:
  • intent=implementation;
  • edit=true;
  • ledger=true;
  • release_flow=true.
• Release-only requests no longer require gitnexus_impact; GitNexus impact is raised only when there is code-change intent and the repo profile contains GitNexus rules.
• Suggested verification commands are filtered to remove unsafe/unwanted commands such as force/reset/rm/shell chaining.
• Previous follow-up state now stores a compact typed snapshot (intent, flags, task brief, terms) instead of the full rendered context.
• LLM input now includes the deterministic repo profile so the model sees project stack, scripts, and project rules before generating structured output.

Not included

• Plain text / loose JSON mode was not made the default. Strict schema remains the primary contract; loose JSON is only a compatibility fallback.
• 5-7 repeated LLM checks were not added, to avoid extra latency and cost.

Verification

• python3 -m py_compile hooks/handoff-intake-classifier.py scripts/validate-pack.py
• python3 scripts/validate-pack.py
• git diff --check
• manual release prompt test: intent=implementation, release_flow=true
• manual question-only prompt test: intent=question_only, edit=false
• manual follow-up prompt test with previous context
• deterministic fallback release test