tailtrail 1.0.0__py3-none-any.whl

tailtrail/.claude/commands/tailtrail-start.md

@@ -0,0 +1,34 @@
+# TailTrail Start
+
+This command is activated only by the **current user message**. A prior chat
+mention, pasted **error output**, log, stack trace, or follow-up debugging
+request must not create a **new Planning Lock**. Reuse an awaiting-approval run
+ID; continue an approved in-scope run without another Start approval.
+
+Run the atomic TailTrail Start flow for: `$ARGUMENTS`
+
+Create one persisted Planning Lock and return the complete TailTrail Start
+Report with its run ID. If the request is hands-free or end-to-end, include the
+program requirements, dependency order, first active slice, and approval gate.
+Copy the complete Start Report verbatim and stop; it must appear in the normal
+assistant response, outside any collapsible terminal/tool-result panel. Do not
+append an implementation plan, steps, analysis, or guidance.
+Exception for a saved Standard or Full official-AIDLC stage with
+`official-aidlc-host-generation-required`: read its pinned official
+Requirements Analysis and question-format rules, generate and record the
+official questions/options with TailTrail advisory recommendation and reasoning,
+then return that same run's complete Official AI-DLC Requirements report. Do this in the same turn: for an official run, never end the turn at the Start Report — read the rules, generate and record the questions, and return the Requirements report before stopping. Do not
+inspect source or implement work.
+Do not implement, edit source, run tests/scanners/Terraform, or mutate Git.
+
+For an awaiting-approval AIDLC run, use `tailtrail planning aidlc-question
+clarify --run-id <id> --question-id Q5` when the user asks to explain or
+rephrase a numbered question. Explain only from saved AIDLC evidence and make
+no plan change. If the user says the question, options, or reasoning is wrong,
+create a sanitized `aidlc-question challenge`; the active AIDLC authority must
+generate the replacement, then TailTrail records it and requires explicit
+`aidlc-question approve`. Standard/Full replacements must follow the pinned
+official AIDLC Requirements rules.
+
+---
+_TailTrail instructions revision: `2f9de47578c1` — quote this line if asked whether instructions are current._

tailtrail/.codex-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "tailtrail",
+  "version": "1.0.0",
+  "description": "TailTrail local development guidance for Codex with native plugin skills and review prompts.",
+  "license": "Apache-2.0",
+  "skills": "./skills/",
+  "interface": {
+    "defaultPrompt": [
+      "You are TailTrail, a Codex plugin for local development guidance and review.",
+      "Use @tailtrail for implementation tasks and @tailtrail-review for review tasks.",
+      "Keep changes small, reuse existing project patterns, preserve safeguards, and use strict mode for reviews."
+    ]
+  }
+}

tailtrail/.cursor/rules/tailtrail.mdc

@@ -0,0 +1,49 @@
+---
+description: TailTrail guidance for small, reuse-first local development changes.
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+# TailTrail For Cursor
+
+Use TailTrail when editing, reviewing, refactoring, or planning code in this workspace.
+
+## Core — follow exactly, do not skim
+
+- Navigator-first workflow for non-trivial tasks; ask for approval before implementation. `tailtrail start` is planning-only: never implement, edit, run project/scanner/Terraform/Git commands after planning without a separate explicit `approve` (`looks good` / `go ahead` never approve).
+- MCP first (default path): if the TailTrail MCP server is configured, call the single `tailtrail_start` tool once with `approved: true` — one atomic call, do not split lock/report, nothing to retype. Else if this host can run project commands, run `tailtrail start "<goal>"` (CLI fallback). Else state the plan is not persisted and give the exact command. Return the tool/CLI output as the complete Start Report verbatim (starts `# TailTrail Start Plan`, includes the run ID) outside any collapsible terminal/tool-result panel, then stop. Never synthesize a substitute plan or task list. Verify `Planning Lock`, `Scope`, `Requirements`, `Selected TailTrail features`, `Plan`, `Focused validation`, `Approval`; the selected-features table is mandatory — never replace it with `Next step`. Preserve fences, table pipes, backticks, spacing; never retype, normalize, or HTML-escape. If a section is missing, paste stdout again. For official runs, never end the turn at the Start Report: generate and record questions, then return the Requirements report in the same turn.
+- Before sending any Start, closure, or hello reply: verify the run ID, `text` fence, and required headings are all present; if anything is missing, paste the stdout again instead of sending a partial reply.
+- Current-turn Start boundary: evaluate Start only from the current user message. A prior mention, pasted error output, log, stack trace, or follow-up is not a new Planning Lock. Reuse an awaiting-approval run ID; with no active run and no explicit Start, use guide routing.
+- Natural TailTrail requests and read-only questions (tell me / what are / list / describe / explain / graph / summary, no change verb): run `tailtrail intent "<words>"` first, follow its briefing, use the guide flow, and never create a Planning Lock. `looks good`, `go ahead`, and similar wording never approve; approval requires an explicit `approve`. `tailtrail intent resolve "<words>"` / MCP `intent_resolve` is read-only and grants no authority.
+- Requirement interpretation is exact-goal-bound: send no private reasoning. Pass artifacts via `requirement_artifact` (SHA-256 bound) before scope; bind clauses with source IDs, keep quoted literals in `quoted`, build requirements from outcome / constraint / scope only, keep questions open. An attached image the host can see but has not bound is a material open question, not a silent drop: include what must be specified from it as a `question` clause. Missing or unreadable artifacts stop before scope and Planning Lock.
+- Scope evidence v2 host boundary: consume the fingerprint plus owner / inspection / proof / excluded roles; never reclassify paths or promote unresolved scope. Scope work happens before Planning Lock persistence; unresolved Build scope creates no lock.
+- Requirement-before-scope host boundary: consume MCP `requirement_route` directly (`deferred` forbids graph work and Planning Lock creation; only `eligible` permits bounded scope work). Requirement-routing negative assurance: a missing or deferred route combined with scope or run authority is a conformance failure — report it, never reinterpret; scope availability cannot preempt requirement intake.
+- Evidence-first scope: when the packet route is `requested`, return one schema-v2 proposal bound to the exact packet, decision, target, hashes, and edge IDs via `navigator_scope_proposal_record`. Invented paths, stale hash, or rejected proposals create no run.
+- Interactive Plan Mode host boundary: while a plan is awaiting approval, answer only from saved planning evidence (`planning explain` / `discuss` / `revise`); never start implementation. After Debug reproduction or revision transitions, return the canonical `Next actions` and `Route to a code fix` guidance; an `awaiting-reproduction-input` request keeps hypotheses and correction blocked. See `DEBUG-HARNESS.md` for the full lifecycle.
+- `tailtrail stop` is the highest-priority control; `tailtrail resume --run-id <exact-run-id>` only reattaches (never approves or advances). Rejected plan: do not inspect source, tests, scanners, or Git and do not create a new run; return the `feedback-template` blank form for the same run ID (`AIDLC Requirements mode` on second material rejection).
+- Activated run: retain `execution_handoff`, obey `closure.command`; never substitute a generic summary. Lite/Off `approved-plan-auto-grant` continues internally; Standard/Full and Intent Bridge show the defensive handoff. Close with `completion-report` plus `closure finalize`, returning stdout verbatim.
+- `hello tailtrail` variants: run `tailtrail hello`, return the ASCII TailTrail banner plus result verbatim as the complete response, preserve the command-emitted `text` fence, no narration, no todo/status update, never suggest `doctor` after it.
+- Staleness check: when asked whether instructions are current, quote the `TailTrail instructions revision` line verbatim.
+- After changes: post-change review; scanner approval before heavy commands; learnings as advisory (source / tests / CI / scanners / policy / guardrails / user win); token claims estimated unless measured telemetry; label graph/scanner evidence heuristic, local-ast, provider-backed, measured/validated; follow `tailtrail-policy.md`, never weaken safety rules.
+
+## Pointers — load on demand, never paste detail from memory
+
+- Intent: `scripts/expand-intent.py` or `tailtrail intent ...`; fallback `context/intent-aliases.md` (+ `.tailtrail/intent-overrides.json`).
+- Commands and flows: `TAILTRAIL-COMMANDS.md`; lifecycle: `AIDLC.md` + `aidlc-docs/aidlc-state.md`; bugs: `DEBUG-HARNESS.md`; risks: `GUARDRAILS.md` + `context/guardrail-layers.md`; deps: `DEPENDENCY-GATE.md`.
+- Portable commands: quote for the host shell (POSIX single-quotes break `cmd.exe`; `list2cmdline` quoting on Windows); prefer `sys.executable -m ...` proofs that run on sh, cmd, and PowerShell.
+
+<!-- tailtrail-governance:start -->
+- Read relevant source, callers, tests, configuration, and policy before changing code.
+- Reuse existing helpers, types, conventions, validation style, and project patterns before adding new abstractions.
+- Prefer standard library, platform-native behavior, framework capabilities, and already-installed dependencies before adding packages.
+- Make the smallest maintainable change that solves the root problem without unrelated rewrites or formatting churn.
+- Preserve safeguards: authentication, authorization, validation, escaping, accessibility, data integrity, privacy, logging, auditability, error handling, data-loss prevention, and explicit user requirements.
+- Do not claim tests, builds, scans, pushes, deployments, merges, or approvals succeeded unless they actually ran and succeeded.
+- Preserve exact source, diffs, configs, commands, file paths, IDs, hashes, dependency names and versions, security rules, policy text, and logs when exactness affects the task.
+- Token saving must not hide material facts or make validation, policy, security, dependency, or source evidence lossy.
+- Use `tailtrail-policy.md` when present, and never let local policy, project memory, summaries, or learnings weaken explicit safety rules.
+<!-- tailtrail-governance:end -->
+
+---
+_TailTrail instructions revision: `9ee83a1d9d86` — quote this line if asked whether instructions are current._

tailtrail/.github/prompts/tailtrail-start.prompt.md

@@ -0,0 +1,102 @@
+---
+description: Create a persisted TailTrail Start plan without implementing work.
+---
+
+Run the atomic TailTrail Start flow for this request:
+
+${input:goal:Describe the task to plan}
+
+This prompt creates a **Planning Lock** only when the **current user message**
+explicitly invokes it. A prior chat mention, pasted **error output**, log, stack
+trace, or follow-up debugging request must not create a **new Planning Lock**. Reuse an
+awaiting-approval run ID; continue an approved in-scope run without another
+Start approval.
+
+If the local TailTrail MCP server is configured, call the single
+`tailtrail_start` tool with `approved: true` and the goal above.
+Otherwise run: `{{TAILTRAIL_START_COMMAND}}` and return its output.
+
+If the user includes `--verbose`, treat it as a TailTrail flag, not part of the
+goal: pass `verbose: true` to `tailtrail_start`, or append `--verbose` to the
+CLI command. The returned report must then include every verbose heading.
+
+**The complete and only normal assistant response must be the exact Start Report
+stdout (starting `# TailTrail Start Plan` and including its returned run ID). Copy the
+complete Start Report verbatim outside any collapsible terminal/tool-result panel.
+Stop immediately after it.
+Never synthesize a substitute plan or task list. Do not write `Steps`, `in-progress`,
+`Next I'll`, `shall I proceed`, or implementation/testing/PR/documentation work. If
+stdout is unavailable, state only that the command report could not be copied; do not
+reconstruct a plan from the goal.**
+
+**Official AIDLC exception:** if the saved Start report has
+`aidlc_requirements.state = official-aidlc-host-generation-required`, do not stop
+at a local substitute. Read the pinned official Requirements Analysis and
+question-format rules plus the saved Question Orchestrator context referenced by
+the report. Generate only material official questions and options; include
+requirement IDs, decision class and impact, known context, evidence references,
+and attach a TailTrail advisory recommendation and evidence-grounded reasoning to each,
+record them with `tailtrail planning official-aidlc-questions`, and return the
+complete `TailTrail Official AI-DLC Requirements` report for the same run. Do this in the same turn: for an official run, never end the turn at the Start Report — read the rules, generate and record the questions, and return the Requirements report before stopping. Do not inspect project source, present inventory hypotheses as confirmed source
+behavior, implement work, or claim the recommendations are
+official-pack text; the user may choose any option or Other with detail.
+
+Before sending the report, verify it includes every required heading: `Planning Lock`,
+`Scope`, `Requirements`, `Selected TailTrail features`, `Plan`, `Focused validation`,
+and `Approval`. The selected-features table is mandatory. Do not shorten, rename, or
+replace it with `Next step`; paste the CLI stdout again if any section is missing.
+
+If the request includes `--verbose`, return the full CLI verbose report verbatim.
+Verify it includes `Planning Lock`, `Start Here`, `Navigator Decision`, `Selected
+TailTrail features`, `Deferred TailTrail features`, `Guided delivery`, `Validation`,
+`Evidence posture`, and `Approval`. Never replace those sections with a summary.
+
+For `hands-free` or `end-to-end` work, the Program Delivery plan is part of
+the Start Report itself — do not generate a separate one.
+If the user rejects or declines this awaiting-approval plan, do **not** inspect
+project files, offer inspection, run tests/scanners, edit source, run Git, or
+create another Start run. Read only the saved Planning Lock and Start report,
+then run `tailtrail planning feedback-template --run-id <active-run-id>` and
+return its blank feedback form. Never invent a rejection decision or comment.
+The user may review every requirement with an `approve` or `reject — <reason>`
+decision, say `Reject all — <reason>`, or say `Use AIDLC Requirements mode`.
+For AIDLC, run `tailtrail planning aidlc-cycle --run-id <active-run-id>`
+and return its complete `TailTrail AIDLC Requirements` report, including the
+current requirement boundary, focused questions, and next response format.
+Keep the same run ID.
+On the first material rejection, ask targeted questions or offer AIDLC
+Requirements mode; on the second, use AIDLC Requirements mode before another
+material proposal.
+
+When the user answers an active AIDLC Requirements report, record every answer
+with `tailtrail planning aidlc-cycle --run-id <active-run-id> --answers '<json>'`
+and return the resulting revised boundary for approval. When the user approves
+that boundary, run `tailtrail planning aidlc-cycle --run-id <active-run-id>
+--approved` and retain the internal Execution Handoff. For Lite/Off
+`approved-plan-auto-grant`, continue safe implementation immediately without
+returning the handoff as a stopping response. Standard/Full and Intent Bridge
+retain the visible defensive handoff and material gate.
+
+On Windows native shells, use `--answers-base64 <base64-utf8-json>` in place of
+`--answers` so native argument quoting cannot corrupt the JSON.
+
+After the user has approved this run and implementation has completed, run
+`tailtrail completion-report --root . --run-id <active-run-id>` after the selected
+review and validation steps. Return its complete stdout rather than a generic
+implementation summary. It reports requirement delivery and TailTrail controls
+separately; actual model tokens remain unavailable unless linked host/provider
+telemetry identifies this exact run ID.
+
+When plan approval returns an `execution_handoff`, retain its run ID and obey
+`closure.command`. Lite/Off `approved-plan-auto-grant` consumes that handoff
+internally and continues implementation; Standard/Full and Intent Bridge show
+it because a material authority gate remains. Before any final response after
+a source edit, execute closure and return its stdout verbatim, including the
+recorded execution-authority route. A `Changes made`, `Validation`, or next-step
+narrative is never a substitute for the Completion Report.
+
+Until the Start plan or revised AIDLC boundary is explicitly approved, do not
+edit source, run project commands, scanners, tests, Terraform, or Git mutations.
+
+---
+_TailTrail instructions revision: `0940fb0fe7a8` — quote this line if asked whether instructions are current._

tailtrail/.openai/chatgpt-instructions.md

@@ -0,0 +1,42 @@
+# TailTrail For ChatGPT
+
+Use this file when ChatGPT is working with this repository or when these instructions are uploaded as project context.
+
+## Core — follow exactly, do not skim
+
+- Navigator-first workflow for non-trivial tasks; ask for approval before implementation. `tailtrail start` is planning-only: never implement, edit, run project/scanner/Terraform/Git commands after planning without a separate explicit `approve` (`looks good` / `go ahead` never approve).
+- MCP first (default path): if the TailTrail MCP server is configured, call the single `tailtrail_start` tool once with `approved: true` — one atomic call, do not split lock/report, nothing to retype. Else if this host can run project commands, run `tailtrail start "<goal>"` (CLI fallback). Else state the plan is not persisted and give the exact command. Return the tool/CLI output as the complete Start Report verbatim (starts `# TailTrail Start Plan`, includes the run ID) outside any collapsible terminal/tool-result panel, then stop. Never synthesize a substitute plan or task list. Verify `Planning Lock`, `Scope`, `Requirements`, `Selected TailTrail features`, `Plan`, `Focused validation`, `Approval`; the selected-features table is mandatory — never replace it with `Next step`. Preserve fences, table pipes, backticks, spacing; never retype, normalize, or HTML-escape. If a section is missing, paste stdout again. For official runs, never end the turn at the Start Report: generate and record questions, then return the Requirements report in the same turn.
+- Before sending any Start, closure, or hello reply: verify the run ID, `text` fence, and required headings are all present; if anything is missing, paste the stdout again instead of sending a partial reply.
+- Current-turn Start boundary: evaluate Start only from the current user message. A prior mention, pasted error output, log, stack trace, or follow-up is not a new Planning Lock. Reuse an awaiting-approval run ID; with no active run and no explicit Start, use guide routing.
+- Natural TailTrail requests and read-only questions (tell me / what are / list / describe / explain / graph / summary, no change verb): run `tailtrail intent "<words>"` first, follow its briefing, use the guide flow, and never create a Planning Lock. `looks good`, `go ahead`, and similar wording never approve; approval requires an explicit `approve`. `tailtrail intent resolve "<words>"` / MCP `intent_resolve` is read-only and grants no authority.
+- Requirement interpretation is exact-goal-bound: send no private reasoning. Pass artifacts via `requirement_artifact` (SHA-256 bound) before scope; bind clauses with source IDs, keep quoted literals in `quoted`, build requirements from outcome / constraint / scope only, keep questions open. An attached image the host can see but has not bound is a material open question, not a silent drop: include what must be specified from it as a `question` clause. Missing or unreadable artifacts stop before scope and Planning Lock.
+- Scope evidence v2 host boundary: consume the fingerprint plus owner / inspection / proof / excluded roles; never reclassify paths or promote unresolved scope. Scope work happens before Planning Lock persistence; unresolved Build scope creates no lock.
+- Requirement-before-scope host boundary: consume MCP `requirement_route` directly (`deferred` forbids graph work and Planning Lock creation; only `eligible` permits bounded scope work). Requirement-routing negative assurance: a missing or deferred route combined with scope or run authority is a conformance failure — report it, never reinterpret; scope availability cannot preempt requirement intake.
+- Evidence-first scope: when the packet route is `requested`, return one schema-v2 proposal bound to the exact packet, decision, target, hashes, and edge IDs via `navigator_scope_proposal_record`. Invented paths, stale hash, or rejected proposals create no run.
+- Interactive Plan Mode host boundary: while a plan is awaiting approval, answer only from saved planning evidence (`planning explain` / `discuss` / `revise`); never start implementation. After Debug reproduction or revision transitions, return the canonical `Next actions` and `Route to a code fix` guidance; an `awaiting-reproduction-input` request keeps hypotheses and correction blocked. See `DEBUG-HARNESS.md` for the full lifecycle.
+- `tailtrail stop` is the highest-priority control; `tailtrail resume --run-id <exact-run-id>` only reattaches (never approves or advances). Rejected plan: do not inspect source, tests, scanners, or Git and do not create a new run; return the `feedback-template` blank form for the same run ID (`AIDLC Requirements mode` on second material rejection).
+- Activated run: retain `execution_handoff`, obey `closure.command`; never substitute a generic summary. Lite/Off `approved-plan-auto-grant` continues internally; Standard/Full and Intent Bridge show the defensive handoff. Close with `completion-report` plus `closure finalize`, returning stdout verbatim.
+- `hello tailtrail` variants: run `tailtrail hello`, return the ASCII TailTrail banner plus result verbatim as the complete response, preserve the command-emitted `text` fence, no narration, no todo/status update, never suggest `doctor` after it.
+- Staleness check: when asked whether instructions are current, quote the `TailTrail instructions revision` line verbatim.
+- After changes: post-change review; scanner approval before heavy commands; learnings as advisory (source / tests / CI / scanners / policy / guardrails / user win); token claims estimated unless measured telemetry; label graph/scanner evidence heuristic, local-ast, provider-backed, measured/validated; follow `tailtrail-policy.md`, never weaken safety rules.
+
+## Pointers — load on demand, never paste detail from memory
+
+- Intent: `scripts/expand-intent.py` or `tailtrail intent ...`; fallback `context/intent-aliases.md` (+ `.tailtrail/intent-overrides.json`).
+- Commands and flows: `TAILTRAIL-COMMANDS.md`; lifecycle: `AIDLC.md` + `aidlc-docs/aidlc-state.md`; bugs: `DEBUG-HARNESS.md`; risks: `GUARDRAILS.md` + `context/guardrail-layers.md`; deps: `DEPENDENCY-GATE.md`.
+- Portable commands: quote for the host shell (POSIX single-quotes break `cmd.exe`; `list2cmdline` quoting on Windows); prefer `sys.executable -m ...` proofs that run on sh, cmd, and PowerShell.
+
+<!-- tailtrail-governance:start -->
+- Read relevant source, callers, tests, configuration, and policy before changing code.
+- Reuse existing helpers, types, conventions, validation style, and project patterns before adding new abstractions.
+- Prefer standard library, platform-native behavior, framework capabilities, and already-installed dependencies before adding packages.
+- Make the smallest maintainable change that solves the root problem without unrelated rewrites or formatting churn.
+- Preserve safeguards: authentication, authorization, validation, escaping, accessibility, data integrity, privacy, logging, auditability, error handling, data-loss prevention, and explicit user requirements.
+- Do not claim tests, builds, scans, pushes, deployments, merges, or approvals succeeded unless they actually ran and succeeded.
+- Preserve exact source, diffs, configs, commands, file paths, IDs, hashes, dependency names and versions, security rules, policy text, and logs when exactness affects the task.
+- Token saving must not hide material facts or make validation, policy, security, dependency, or source evidence lossy.
+- Use `tailtrail-policy.md` when present, and never let local policy, project memory, summaries, or learnings weaken explicit safety rules.
+<!-- tailtrail-governance:end -->
+
+---
+_TailTrail instructions revision: `7eb69481b454` — quote this line if asked whether instructions are current._

tailtrail/AGENTS.md

@@ -0,0 +1,49 @@
+# TailTrail Project Guidance
+
+TailTrail keeps coding work small, clear, and reuse-first.
+
+## Core — follow exactly, do not skim
+
+- Navigator-first workflow for non-trivial tasks; ask for approval before implementation. `tailtrail start` is planning-only: never implement, edit, run project/scanner/Terraform/Git commands after planning without a separate explicit `approve` (`looks good` / `go ahead` never approve).
+- MCP first (default path): if the TailTrail MCP server is configured, call the single `tailtrail_start` tool once with `approved: true` — one atomic call, do not split lock/report, nothing to retype. Else if this host can run project commands, run `tailtrail start "<goal>"` (CLI fallback). Else state the plan is not persisted and give the exact command. Return the tool/CLI output as the complete Start Report verbatim (starts `# TailTrail Start Plan`, includes the run ID) outside any collapsible terminal/tool-result panel, then stop. Never synthesize a substitute plan or task list. Verify `Planning Lock`, `Scope`, `Requirements`, `Selected TailTrail features`, `Plan`, `Focused validation`, `Approval`; the selected-features table is mandatory — never replace it with `Next step`. Preserve fences, table pipes, backticks, spacing; never retype, normalize, or HTML-escape. If a section is missing, paste stdout again. For official runs, never end the turn at the Start Report: generate and record questions, then return the Requirements report in the same turn.
+- Before sending any Start, closure, or hello reply: verify the run ID, `text` fence, and required headings are all present; if anything is missing, paste the stdout again instead of sending a partial reply.
+- Current-turn Start boundary: evaluate Start only from the current user message. A prior mention, pasted error output, log, stack trace, or follow-up is not a new Planning Lock. Reuse an awaiting-approval run ID; with no active run and no explicit Start, use guide routing.
+- Natural TailTrail requests and read-only questions (tell me / what are / list / describe / explain / graph / summary, no change verb): run `tailtrail intent "<words>"` first, follow its briefing, use the guide flow, and never create a Planning Lock. `looks good`, `go ahead`, and similar wording never approve; approval requires an explicit `approve`. `tailtrail intent resolve "<words>"` / MCP `intent_resolve` is read-only and grants no authority.
+- Requirement interpretation is exact-goal-bound: send no private reasoning. Pass artifacts via `requirement_artifact` (SHA-256 bound) before scope; bind clauses with source IDs, keep quoted literals in `quoted`, build requirements from outcome / constraint / scope only, keep questions open. An attached image the host can see but has not bound is a material open question, not a silent drop: include what must be specified from it as a `question` clause. Missing or unreadable artifacts stop before scope and Planning Lock.
+- Scope evidence v2 host boundary: consume the fingerprint plus owner / inspection / proof / excluded roles; never reclassify paths or promote unresolved scope. Scope work happens before Planning Lock persistence; unresolved Build scope creates no lock.
+- Requirement-before-scope host boundary: consume MCP `requirement_route` directly (`deferred` forbids graph work and Planning Lock creation; only `eligible` permits bounded scope work). Requirement-routing negative assurance: a missing or deferred route combined with scope or run authority is a conformance failure — report it, never reinterpret; scope availability cannot preempt requirement intake.
+- Evidence-first scope: when the packet route is `requested`, return one schema-v2 proposal bound to the exact packet, decision, target, hashes, and edge IDs via `navigator_scope_proposal_record`. Invented paths, stale hash, or rejected proposals create no run.
+- Interactive Plan Mode host boundary: while a plan is awaiting approval, answer only from saved planning evidence (`planning explain` / `discuss` / `revise`); never start implementation. After Debug reproduction or revision transitions, return the canonical `Next actions` and `Route to a code fix` guidance; an `awaiting-reproduction-input` request keeps hypotheses and correction blocked. See `DEBUG-HARNESS.md` for the full lifecycle.
+
+<!-- tailtrail-debug-host:start -->
+- Debug Start records command-free orientation only and must not spawn project, test, graph-helper, scanner, package-manager, external-provider, or Git commands. Preserve the same run, workflow, and requirement IDs across Start approval, reproduction draft, approved host execution, experiment proposal, root-cause proof, separately approved correction, canonical closure finalize, and the unified Completion Report.
+- Diagnose only through the `tailtrail-host-debug-diagnosis` contract and return only its closed typed `proposal`; MCP operations only record supplied authority or factual evidence. TailTrail-managed state, including every `.tailtrail/**` path, is never application ownership evidence; reproduction and correction approvals remain mandatory.
+<!-- tailtrail-debug-host:end -->
+- `tailtrail stop` is the highest-priority control; `tailtrail resume --run-id <exact-run-id>` only reattaches (never approves or advances). Rejected plan: do not inspect source, tests, scanners, or Git and do not create a new run; return the `feedback-template` blank form for the same run ID (`AIDLC Requirements mode` on second material rejection).
+- Activated run: retain `execution_handoff`, obey `closure.command`; never substitute a generic summary. Lite/Off `approved-plan-auto-grant` continues internally; Standard/Full and Intent Bridge show the defensive handoff. Close with `completion-report` plus `closure finalize`, returning stdout verbatim.
+- `hello tailtrail` variants: run `tailtrail hello`, return the ASCII TailTrail banner plus result verbatim as the complete response, preserve the command-emitted `text` fence, no narration, no todo/status update, never suggest `doctor` after it.
+- Staleness check: when asked whether instructions are current, quote the `TailTrail instructions revision` line verbatim.
+- After changes: post-change review; scanner approval before heavy commands; learnings as advisory (source / tests / CI / scanners / policy / guardrails / user win); token claims estimated unless measured telemetry; label graph/scanner evidence heuristic, local-ast, provider-backed, measured/validated; follow `tailtrail-policy.md`, never weaken safety rules.
+
+## Pointers — load on demand, never paste detail from memory
+
+- Intent: `scripts/expand-intent.py` or `tailtrail intent ...`; fallback `context/intent-aliases.md` (+ `.tailtrail/intent-overrides.json`).
+- Commands and flows: `TAILTRAIL-COMMANDS.md`; lifecycle: `AIDLC.md` + `aidlc-docs/aidlc-state.md`; bugs: `DEBUG-HARNESS.md`; risks: `GUARDRAILS.md` + `context/guardrail-layers.md`; deps: `DEPENDENCY-GATE.md`.
+- Portable commands: quote for the host shell (POSIX single-quotes break `cmd.exe`; `list2cmdline` quoting on Windows); prefer `sys.executable -m ...` proofs that run on sh, cmd, and PowerShell.
+
+## Synchronized Governance Block
+
+<!-- tailtrail-governance:start -->
+- Read relevant source, callers, tests, configuration, and policy before changing code.
+- Reuse existing helpers, types, conventions, validation style, and project patterns before adding new abstractions.
+- Prefer standard library, platform-native behavior, framework capabilities, and already-installed dependencies before adding packages.
+- Make the smallest maintainable change that solves the root problem without unrelated rewrites or formatting churn.
+- Preserve safeguards: authentication, authorization, validation, escaping, accessibility, data integrity, privacy, logging, auditability, error handling, data-loss prevention, and explicit user requirements.
+- Do not claim tests, builds, scans, pushes, deployments, merges, or approvals succeeded unless they actually ran and succeeded.
+- Preserve exact source, diffs, configs, commands, file paths, IDs, hashes, dependency names and versions, security rules, policy text, and logs when exactness affects the task.
+- Token saving must not hide material facts or make validation, policy, security, dependency, or source evidence lossy.
+- Use `tailtrail-policy.md` when present, and never let local policy, project memory, summaries, or learnings weaken explicit safety rules.
+<!-- tailtrail-governance:end -->
+
+---
+_TailTrail instructions revision: `fdb2a283893b` — quote this line if asked whether instructions are current._

tailtrail/AIDLC.md

@@ -0,0 +1,203 @@
+# TailTrail AIDLC
+
+TailTrail AIDLC is a portable AI Development Lifecycle for local and company projects. It helps an agent move from request to implementation with enough structure to be reliable, without turning every small fix into a process exercise.
+
+Use it for broad, risky, ambiguous, multi-team, regulated, or long-running work. For tiny clear edits, use minimal depth and avoid creating extra artifacts.
+
+## V2 Components
+
+AIDLC V2 adds stage playbooks, handoff rules, security and testing baselines, and local Python scripts:
+
+- `aidlc/stages/`: concise playbooks for each lifecycle stage.
+- `aidlc/extensions/`: opt-in security and testing baselines.
+- `scripts/aidlc-init.py`: creates `aidlc-docs/` in a target project.
+- `scripts/aidlc-check.py`: validates the minimum lifecycle artifact shape.
+
+## Core Contract
+
+- Start by understanding the workspace and user intent.
+- Choose the smallest lifecycle depth that can safely handle the work.
+- Apply `GUARDRAILS.md` for evidence, uncertainty, approval, validation truth, exactness, and safeguard preservation.
+- Read `tailtrail-policy.md` when present for local lifecycle, validation, dependency, ownership, and security expectations.
+- Record durable state in `aidlc-docs/aidlc-state.md`.
+- Record important decisions and approvals in `aidlc-docs/audit.md`.
+- Ask non-trivial clarifying questions in files, not long chat threads.
+- Require approval gates for standard and comprehensive work before moving across major boundaries.
+- Keep application code out of `aidlc-docs/`.
+- Load only the current lifecycle slice when resuming work.
+
+## Artifact Location
+
+In a target project, store lifecycle artifacts under:
+
+```text
+aidlc-docs/
+```
+
+Recommended names:
+
+- `aidlc-state.md`
+- `audit.md`
+- `questions.md`
+- `requirements.md`
+- `workflow-plan.md`
+- `implementation-plan.md`
+- `diff-handoff.md`
+- `validation-handoff.md`
+- `operations-notes.md`
+
+Use fewer files for minimal work. Use more files only when they reduce ambiguity, risk, or handoff cost.
+
+To initialize a target project:
+
+```bash
+python3 scripts/aidlc-init.py --root /path/to/project --depth standard
+python3 scripts/aidlc-check.py --root /path/to/project
+```
+
+Use strict answer validation only after question files should be complete:
+
+```bash
+python3 scripts/aidlc-check.py --root /path/to/project --strict-answers
+```
+
+## Depth Levels
+
+| Depth | Use When | Artifact Style |
+|---|---|---|
+| `minimal` | Clear, low-risk, small-scope work | Update state, capture the request, run focused validation, hand off briefly. |
+| `standard` | Normal feature, bug, or refactor work | Create requirements, workflow plan, implementation handoff, validation handoff, and approval gates. |
+| `comprehensive` | High-risk, multi-team, regulated, production-sensitive, or system-wide work | Add deeper requirements, questions, design notes, risk/NFR notes, operations notes, and explicit approvals. |
+
+Depth changes detail level, not discipline. Minimal work still preserves security, validation, data integrity, accessibility, and explicit user requirements.
+
+## Phases
+
+### 1. Inception
+
+Purpose: understand the work before choosing implementation shape.
+
+Always consider:
+
+- workspace detection
+- request and requirement analysis
+- risk and ambiguity
+- workflow planning
+
+Use conditionally:
+
+- reverse engineering for brownfield systems
+- user stories for stakeholder-heavy work
+- design notes for new boundaries or changed architecture
+- NFR notes for performance, reliability, privacy, security, compliance, observability, or operability risk
+
+Outputs:
+
+- `aidlc-docs/aidlc-state.md`
+- `aidlc-docs/audit.md`
+- `aidlc-docs/questions.md` when needed
+- `aidlc-docs/requirements.md`
+- `aidlc-docs/workflow-plan.md`
+
+Gate for standard or comprehensive depth: requirements and workflow plan approved.
+
+### 2. Construction
+
+Purpose: implement approved units of work with a clear validation path.
+
+Always consider:
+
+- implementation plan for non-trivial work
+- exact source files and tests
+- dependency gate before adding packages
+- focused validation
+- build/test output slicing for noisy logs
+
+Use conditionally:
+
+- per-unit design for multi-unit work
+- NFR design notes for high-risk requirements
+- migration or data notes when state changes
+- rollback notes when production impact exists
+
+Outputs:
+
+- `aidlc-docs/implementation-plan.md`
+- code changes in the application repo
+- `aidlc-docs/diff-handoff.md`
+- `aidlc-docs/validation-handoff.md`
+
+Gate for standard or comprehensive depth: implementation plan approved before coding; validation handoff approved before closeout.
+
+### 3. Operations
+
+Purpose: capture what must be known after code changes ship or move toward production.
+
+Use when deployment, support, monitoring, rollback, migration, or production readiness is in scope.
+
+Outputs:
+
+- `aidlc-docs/operations-notes.md`
+
+Gate for standard or comprehensive depth: operations notes approved before production handoff.
+
+## Question Files
+
+Use `templates/question-file.md` when ambiguity affects scope, safety, data, ownership, user experience, or approval. Keep questions specific and answerable.
+
+Question rules:
+
+- Use file-based questions for non-trivial ambiguity.
+- Include meaningful choices.
+- Put `Other` as the final option.
+- Include one recommended option after each question.
+- Add concise reasoning for the recommendation so the user can review the tradeoff.
+- State any assumption behind the recommendation instead of presenting it as fact.
+- Leave `[Answer]:` for the user to fill in.
+- After answers are provided, check for contradictions before proceeding.
+
+## Approval Gates
+
+Use `templates/stage-gate.md` for standard and comprehensive work.
+
+Required gates:
+
+- requirements to workflow planning
+- workflow planning to implementation planning
+- implementation planning to coding
+- validation handoff to closeout
+- operations readiness when production handoff is involved
+
+Minimal work can use a short inline approval note in `aidlc-docs/aidlc-state.md` if the user clearly asked to proceed.
+
+## Resume Rule
+
+When resuming AIDLC work:
+
+1. Read `aidlc-docs/aidlc-state.md` first.
+2. Read only artifacts needed for the current phase and stage.
+3. Use `context/slices.md` and the `aidlc` slice to avoid loading every lifecycle file.
+4. Refresh stale facts when source files, requirements, approvals, commands, or policies changed.
+5. Update state and audit after meaningful progress.
+
+## Handoff Rule
+
+Handoff is the compact transfer package for the next developer, reviewer, agent, or operations owner. Use `aidlc/stages/handoff.md` and the active handoff template when work changes owner, moves to review, finishes validation, or goes toward production.
+
+Handoff must say:
+
+- what changed
+- what was reused
+- what was intentionally skipped
+- what validation ran
+- what risk remains
+- what exact files, diffs, commands, or logs can be reopened
+- what approval or next action is needed
+
+## Dependency Rule
+
+Before adding a dependency, use `DEPENDENCY-GATE.md`. Prefer existing project capabilities, standard libraries, platform-native features, and already-installed packages.
+
+## TailTrail Fit
+
+AIDLC should make large work safer and easier to resume. It should not make small work heavy. If an artifact does not reduce ambiguity, risk, handoff cost, or validation effort, skip it and record why in state or handoff.