ahead-pi 0.3.1 → 0.5.0

package/generated/product-change/deploy.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=deploy sha256=299a79a63024f2a0a012747b7f2ee7317a2a2eb3832f4f2d0f2210ef2825f3c2 -->
+<!-- workflow=product-change@0.2.0 phase=deploy sha256=b7f6d2e3844c8719ec01bc277ebdfb66b4501cb4f024ce5cdc5fb71ccdec78ba -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/human-review.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=human-review sha256=e94dd8e864afab324fadd3da464d5818df8df0bfb2671f3f609063b7b91b8bb7 -->
+<!-- workflow=product-change@0.2.0 phase=human-review sha256=ed70af1697f2a87fb3e7757b65f0dd3fa94bc6113da5c9e95862edfad37f20c2 -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/implement.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=implement sha256=c45eb2a3e2b83d5df27ee2dc3c5bda856486c57cbda0eefe6c950b6f2cb6815d -->
+<!-- workflow=product-change@0.2.0 phase=implement sha256=80c450e0f6487c32f5a8b4f4bc7338ab9eb13e5f54d78f1606a21f6d5c2e57bb -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/options.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=options sha256=f0a9f8f3936ed59a89c809e1e31546ca5e9ac3c3ab76ac656676586a9b7c4645 -->
+<!-- workflow=product-change@0.2.0 phase=options sha256=595c1fbecf433d64a4c8a647df372c3937006c101fcbe5235bb4975403f0c61a -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/outcome.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=outcome sha256=d6e1a73bbc2be8b5374464a6cb2f198bd1cb395b85db6ac84201d6dae95e2518 -->
+<!-- workflow=product-change@0.2.0 phase=outcome sha256=0c2a79dcb011adc8e99985e2add7ea90b12d7056839f0d746654f2dc34aa54ab -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/plan.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=plan sha256=c15a791eaff9639ce71c1fb08b865a1c8472ee68a25ecd529e1c40f75dd040c0 -->
+<!-- workflow=product-change@0.2.0 phase=plan sha256=9863c8de33161735bb3bf9ba146c4d520faa99ce617d974ae763be1ac7f0e266 -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/questions.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=questions sha256=c666b41866f716539f89e5518193e1fb26328ba0ba9b5c3ac0b31b29d499a13e -->
+<!-- workflow=product-change@0.2.0 phase=questions sha256=7960c7ed009449dfe17c6219890645066d6aa72dcee6c3059279dccc4386cee7 -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/research.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=research sha256=5d47cb0aa2a2e08600b0a8e3ed2efc062555cc525ec485b8e43f2b8657f0da48 -->
+<!-- workflow=product-change@0.2.0 phase=research sha256=871000313681366e424b39a987b9973edc7c03e82d68668d3fb49e5e3f56bdc5 -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/product-change/verify.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=verify sha256=f16d886eef6a02cdfa0dc0fbf89b19c8dfcd67c584b2e37b2c0f6ba54097b273 -->
+<!-- workflow=product-change@0.2.0 phase=verify sha256=69ad233303afbfe6de12aa14e50243c41955de7a5a56ebdecf4939adff9c20ec -->
 
 # AHEAD agent profile
 
@@ -8,10 +8,12 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 - Work only within the current phase and its allowed capabilities.
 - Treat the workflow state returned by `ahead_get_context` as authoritative.
 - Never claim human authorship, understanding, approval, review, authorization, or gate acceptance.
-- Never transition or close the workflow. Ask the human to use `/ahead` for the next guided action.
+- Never transition or close the workflow. Explain the next human action in normal conversation; the human may open `/ahead` when a recorded action or gate is needed.
 - Record only artifacts whose actor rule permits AI. Human-owned artifacts must be written and recorded by a human.
 - Distinguish observation, evidence, inference, hypothesis, and decision. Preserve uncertainty.
 - A tool denial is a workflow boundary, not a request to find a bypass.
+- Treat a linked work item as a coordination reference, not as a substitute for AHEAD evidence or human approval. Never create, replace, or claim a work item on the human's behalf.
+- Use `ahead_get_work_item` when the human-linked work item is relevant and a provider adapter can resolve it.
 - Do not imply that implementation means deployment, or that deployment means the intended outcome was verified.
 - Help humans understand and solve problems through questions, explanations, evidence, hints, and bounded suggestions. Do not turn a request for help into taking over human-owned work.
 - Where human-first reasoning is required, ask for the human's current model, first attempt, or intended behavior before generating a solution.

package/generated/reference/CONSTITUTION.md

@@ -43,3 +43,7 @@ The workflow engine, editor extensions, repository artifacts, and CI gates exist
 ## 10. Learning closes the loop
 
 Deployment or remediation is not the end. Teams observe outcomes, audit assumptions, capture learning, improve the system, and improve the way humans and AI work together.
+
+## 11. Quality is designed, bounded, and verified
+
+Relevant quality attributes are considered from the beginning rather than only during final inspection. Teams make material invariants, limits, resource budgets, fault models, and operational consequences explicit, apply defenses proportionate to the work, and verify assumptions against observed behavior. Specific techniques remain contextual and must not become rituals detached from the system's purpose.

package/generated/reference/docs/evidence/README.md

@@ -13,5 +13,6 @@ This library records why AHEAD makes its process choices and how strong the supp
 
 - [Pragmatic Programmer page index](sources/pragmatic-programmer-page-index.md) preserves edition-specific page locators.
 - [Submitted engineering notes](sources/submitted-engineering-notes.md) preserves the original tips and checklists behind the distilled practitioner guidance.
+- [TigerStyle practitioner source](sources/tigerstyle.md) records the provenance, systems context, selected adaptations, and limitations of TigerBeetle's documented engineering practice.
 
 Practitioners may consult this material when they need the basis or limitation of a rule. Framework maintainers use it when proposing, evaluating, or revising AHEAD policy.

package/generated/reference/docs/evidence/research-map.md

@@ -38,6 +38,18 @@ The evidence supports using AI and evaluating it contextually. It gives indirect
 
 The evidence supports substantial but bounded AI assistance and supports prototyping as a learning mechanism. It does not establish that AI-generated prototypes are production-ready or that vibe coding is safe outside the prototype boundary. AHEAD's acceptable-use rules combine direct evidence, risk guidance, and constitutional choices; the rules should be reevaluated as tools and work practices change.
 
+## Engineering quality and systems practice
+
+| AHEAD claim | Evidence | Class | What it supports | Important limitation |
+|---|---|---:|---|---|
+| Relevant quality attributes, material limits, fault models, and invariants should be considered while shaping a design. | [TigerStyle](https://tigerstyle.dev/) documents TigerBeetle's use of upfront design, explicit bounds, executable invariants, and layered verification in a distributed financial database. | E4 | Add risk-proportionate design and review prompts for limits, resource budgets, failure behavior, interfaces, and independent checks. | A self-reported practice from a specialized organization does not establish causation or make its concrete Zig and infrastructure rules universal. |
+| Early physical estimates can challenge performance assumptions before architecture hardens. | [TigerStyle](https://tigerstyle.dev/) describes back-of-the-envelope analysis across network, storage, memory, and compute, considering bandwidth and latency, followed by systems-specific optimization techniques. | E4 | Encourage rough estimates when performance is material and require later comparison with representative measurements. | The source does not independently measure estimate accuracy or show that its batching, allocation, cache, and data-layout techniques fit other workloads. |
+| Dependencies and tools should be judged by lifecycle costs, not only immediate authoring convenience. | [TigerStyle](https://tigerstyle.dev/) documents TigerBeetle's dependency-minimization and standardized-tooling rationale, including supply-chain, performance, installation, operational, and team-comprehension costs. | E4 | Make dependency and tooling costs explicit, especially when AI proposes additions casually. | TigerBeetle's zero-dependency and single-language policies are local choices, not general AHEAD requirements; alternatives may have lower total cost in other contexts. |
+
+### Current conclusion
+
+TigerStyle supplies a coherent practitioner example for designing safety, performance, and engineering experience together. AHEAD adapts its technology-neutral questions while keeping concrete prescriptions contextual. Whether any derived practice improves outcomes across AHEAD users remains a hypothesis to evaluate through direct evidence or pilot measurement. See the [source record](sources/tigerstyle.md) for provenance and detailed limitations.
+
 ## Feature and change work
 
 | AHEAD claim | Evidence | Class | What it supports | Important limitation |

package/generated/reference/docs/evidence/sources/tigerstyle.md

@@ -0,0 +1,65 @@
+# TigerStyle Practitioner Source
+
+Audience: AHEAD evidence readers and framework maintainers
+
+Status: reviewed practitioner source
+
+## Source and provenance
+
+[TigerStyle](https://tigerstyle.dev/) is TigerBeetle's published software-engineering methodology for advancing safety, performance, and developer experience in its distributed financial database. TigerBeetle is both the author of the source and the organization reporting the practice. The source describes a coherent operating philosophy and concrete coding rules; it is not an independent evaluation of their outcomes.
+
+Under the [AHEAD Evidence Standard](../evidence-standard.md), TigerStyle is **E4 — documented practitioner evidence**. It can demonstrate a feasible practice, supply design heuristics, and identify failure modes. It does not by itself establish that a rule causes better outcomes or generalizes beyond its environment.
+
+## Context
+
+TigerStyle is shaped by foundational infrastructure with demanding correctness, durability, predictability, and performance requirements. Its concrete prescriptions also reflect Zig, explicit memory management, distributed state-machine design, simulation testing, and tight control over the software stack.
+
+That context makes the source especially relevant to infrastructure, embedded, distributed, real-time, storage, networking, and other safety- or performance-sensitive systems. It also limits direct transfer to managed runtimes, user-interface code, ordinary business applications, scripts, prototypes, and systems with different fault models or economics.
+
+## Themes adapted by AHEAD
+
+AHEAD draws the following bounded practitioner lessons from TigerStyle:
+
+- consider relevant quality attributes while shaping a design rather than relying on final inspection;
+- make material limits, resource budgets, fault models, and invariants explicit;
+- use proportionate defenses in depth, including executable checks, without treating automation as a substitute for understanding;
+- examine both expected and invalid states and distinguish programmer errors from expected operating errors;
+- treat interface quality, failure semantics, defaults, state locality, and semantic distance as system concerns;
+- make rough performance estimates across network, storage, memory, and compute, considering latency and bandwidth, then validate them through measurement;
+- evaluate dependencies and tools by their lifecycle, operational, performance, comprehension, and supply-chain costs;
+- optimize names, rationale, documentation, and design for the people who will repeatedly read, review, operate, diagnose, and change the system;
+- address material design risks while context is fresh and keep accepted engineering debt visible and owned.
+
+These themes inform the [AHEAD Engineering Practice](../../guide/engineering-practice.md). The Constitution adopts only the durable, technology-neutral principle that relevant quality attributes should be designed, bounded, and verified.
+
+## Contextual techniques, not universal AHEAD rules
+
+AHEAD does not generalize TigerStyle's concrete requirements to all software. Examples that remain contextual include:
+
+- prohibiting recursion;
+- allocating all memory at startup and prohibiting later allocation;
+- preferring fixed-width integers over architecture-specific types in all cases;
+- requiring a fixed assertion density;
+- imposing exact function- or line-length limits;
+- scheduling reactions to external events at fixed intervals;
+- separating control and data planes through batching;
+- avoiding serialization, copying, or movable data structures;
+- requiring cache-line-aligned layouts;
+- prohibiting third-party dependencies;
+- standardizing all tooling on one language;
+- mandating TigerBeetle's naming and formatting conventions.
+
+These techniques may be excellent choices when justified by a system's risk, workload, language, hardware, fault model, and operating environment. AHEAD requires the reasoning and evidence to remain visible; it does not prescribe the answer in advance.
+
+## Important limitations and tensions
+
+- TigerStyle orders safety, performance, and developer experience for TigerBeetle. AHEAD treats quality priorities as contextual and human-owned.
+- TigerStyle advocates “zero technical debt” and doing work right the first time. AHEAD instead requires material debt to be explicit, owned, contained, and revisited; it preserves experimentation and revisable decisions.
+- TigerStyle often treats process termination as the correct response to a violated program invariant. AHEAD requires failure behavior to follow the system's fault model and blast radius.
+- Early performance sketches can expose architectural constraints but do not replace representative measurement.
+- Assertions, fuzzing, simulation, types, and tests can reveal defects but do not prove correctness or replace a maintained human mental model.
+- The source reports TigerBeetle's own practice and has not been evaluated here through controlled comparison or independent replication.
+
+## Resulting AHEAD decision
+
+AHEAD cites TigerStyle as an E4 practitioner source, adapts selected technology-neutral themes, and labels concrete systems techniques as contextual. Future claims that a particular TigerStyle-derived rule should become mandatory require direct evidence, strong professional consensus, or favorable AHEAD pilot results under the evidence standard.

package/generated/reference/docs/guide/README.md

@@ -11,7 +11,8 @@ This is the starting point for people applying AHEAD to engineering work. These
 3. [Acceptable AI use](acceptable-ai-use.md) defines binding authority boundaries.
 4. [Engineering practice](engineering-practice.md) describes the habits AHEAD asks engineers to cultivate.
 5. [Pilot workflows](workflows/README.md) explains how to choose and execute one of the six flows.
-6. [Recommended skills](recommended-skills.md) lists optional, reviewed third-party aids.
+6. [Work items and planning handoffs](work-items.md) explains provider-neutral links, configurable gates, and sprint-ahead preparation.
+7. [Recommended skills](recommended-skills.md) lists optional, reviewed third-party aids.
 
 ## Authority
 

package/generated/reference/docs/guide/engineering-practice.md

@@ -10,7 +10,7 @@ AHEAD is not only a sequence of AI gates. It is a way of practicing engineering.
 
 Many of these ideas come from practitioner literature rather than controlled experiments. The source type matters: a useful craft principle can guide work without being misrepresented as science.
 
-The submitted notes include page-level references to *The Pragmatic Programmer*. Those locators are preserved in the [edition-specific page index](../evidence/sources/pragmatic-programmer-page-index.md) and grouped below so the distillation remains traceable to its source. Additional submitted tips, complete checklists, and practices are retained in the [submitted engineering notes](../evidence/sources/submitted-engineering-notes.md); the practice guide condenses them without replacing that source record.
+The submitted notes include page-level references to *The Pragmatic Programmer*. Those locators are preserved in the [edition-specific page index](../evidence/sources/pragmatic-programmer-page-index.md) and grouped below so the distillation remains traceable to its source. Additional submitted tips, complete checklists, and practices are retained in the [submitted engineering notes](../evidence/sources/submitted-engineering-notes.md); the practice guide condenses them without replacing that source record. Selected systems-engineering practices are adapted from [TigerStyle](../evidence/sources/tigerstyle.md), with its infrastructure context and limits kept explicit.
 
 ## 1. Care about the craft and own the result
 
@@ -30,15 +30,15 @@ Basis: *The Pragmatic Programmer* tips 2 (p. xlx as submitted), 9 (p. 16), 27 (p
 
 Requirements are discovered and refined, not merely received. Work with users and domain experts, use their language, identify the desired outcome, and separate real constraints from inherited habits.
 
-Quality is contextual. Reliability, latency, accessibility, security, cost, maintainability, and delivery time do not have one universal ordering; accountable humans decide what the work requires.
+Quality is contextual. Reliability, latency, accessibility, security, cost, maintainability, and delivery time do not have one universal ordering; accountable humans decide what the work requires. Consider the relevant qualities while shaping the design, when foundational assumptions are still inexpensive to change, rather than relying on inspection at the end.
 
-Basis: requirements and traceability research, ISO/IEC/IEEE life-cycle standards, and *The Pragmatic Programmer* tips 7 (p. 11), 17 (p. 58), 51 (p. 202), 52 (p. 204), 54 (p. 210), and 55 (p. 213).
+Basis: requirements and traceability research, ISO/IEC/IEEE life-cycle standards, *The Pragmatic Programmer* tips 7 (p. 11), 17 (p. 58), 51 (p. 202), 52 (p. 204), 54 (p. 210), and 55 (p. 213), and TigerStyle's documented design practice. The priority and timing appropriate to one safety- and performance-sensitive system do not establish a universal ordering for other work.
 
 ## 4. Make reasoning visible
 
-Record important assumptions, options, decisions, tradeoffs, evidence, uncertainty, and changes in understanding. Link intent to implementation and verification without creating documents that nobody uses.
+Record important assumptions, options, decisions, tradeoffs, evidence, uncertainty, and changes in understanding. Link intent to implementation and verification without creating documents that nobody uses. Use domain-accurate names, include units and meaningful qualifiers where ambiguity would matter, and preserve the reasons behind non-obvious choices in durable repository artifacts.
 
-Traceability should help future engineers understand why and where—not become compliance theater.
+Traceability should help future engineers understand why and where—not become compliance theater. Optimize communication for the people who will repeatedly read, review, operate, diagnose, and change the system, not only for its first author.
 
 Basis: controlled evidence that requirements-to-code traceability can improve maintenance-task performance, AHEAD's evidence standard, and *The Pragmatic Programmer* tips 10 (p. 21), 18 (p. 64), 19 (p. 69), 20 (p. 74), and 23 (p. 88).
 
@@ -46,6 +46,8 @@ Basis: controlled evidence that requirements-to-code traceability can improve ma
 
 Choose designs that minimize the number of concepts a person must hold simultaneously. Keep unrelated concerns independently changeable. Make state explicit and contained. Keep policy distinct from mechanism. Prefer stable values, plain data, clear interfaces, and declarative rules when they fit the problem.
 
+Treat interface quality as a system property: minimize unnecessary surface area, define failure semantics and fault models, avoid ambiguous parameters and return states, and keep state close to where it is checked and used. Do not rely silently on call ordering, timing, or defaults whose change would alter correctness.
+
 Modularity is not automatically simplicity: separate modules can remain tightly coupled through hidden assumptions, timing, shared state, or required call order.
 
 Basis: Rich Hickey's *Simple Made Easy* and *The Pragmatic Programmer* tips 11 (p. 27), 13 (p. 35), 36 (p. 140), 41 (p. 156), and 42 (p. 161). These are design heuristics, not universal experimental laws.
@@ -56,7 +58,9 @@ Decisions can be revised, so record their rationale, reversibility, and review t
 
 Use a “rule of three” only as a prompt for judgment, not a mechanical law. Duplication of knowledge is more dangerous than superficially similar code; premature abstraction can couple cases that should evolve separately.
 
-Basis: *The Pragmatic Programmer* tips 4 (p. 5), 12 (p. 33), 14 (p. 46), 47 (p. 186), and 53 (p. 209). The precise abstraction threshold is context-dependent.
+Address material design risks while the context is fresh. This does not require “zero technical debt” or pretending every first decision is final. When debt is accepted, make its rationale, consequences, owner, containment, and review or removal trigger visible so it does not become invisible or ownerless.
+
+Basis: *The Pragmatic Programmer* tips 4 (p. 5), 12 (p. 33), 14 (p. 46), 47 (p. 186), and 53 (p. 209), plus TigerStyle's practitioner case for proactive design. The precise abstraction threshold and acceptable debt are context-dependent.
 
 ## 7. Prototype to learn
 
@@ -74,17 +78,29 @@ Use source control, shells, scripts, formatters, generators, CI, and other autom
 
 Do not automate a process you cannot evaluate. Judge tools by the long-lived artifacts and operational behavior they produce, not only authoring convenience or initial speed.
 
-Basis: *The Pragmatic Programmer* tips 21 (p. 80), 22 (p. 85), 28 (p. 100), 29 (p. 103), and 61 (p. 231), NIST secure-development guidance, and AHEAD's Toyota analogy.
+Dependencies and tools carry lifecycle costs: supply-chain exposure, build and installation behavior, performance, operational complexity, team comprehension, maintenance, upgrades, and abandonment risk. Evaluate those costs in proportion to the dependency's criticality. Neither zero dependencies nor one standardized tool for every task is a universal goal.
+
+Basis: *The Pragmatic Programmer* tips 21 (p. 80), 22 (p. 85), 28 (p. 100), 29 (p. 103), and 61 (p. 231), NIST secure-development guidance, AHEAD's Toyota analogy, and TigerStyle's documented dependency and tooling discipline.
 
 ## 9. Design for testing and failure
 
-Think about verification before implementation. Define observable behavior, invariants, boundaries, significant states, failure modes, resource exhaustion, recovery, and performance expectations.
+Think about verification before implementation. Define observable behavior, invariants, boundaries, significant states, failure modes, resource exhaustion, recovery, and performance expectations. Identify material limits on queues, retries, loops, concurrency, memory, storage, request sizes, and execution; a limit may be dynamic or operational, but the underlying resource is not infinite.
+
+Build a mental model first, then encode important expectations through types, contracts, assertions, tests, runtime checks, or other appropriate defenses. Distinguish expected operating errors, which need defined handling, from violated program invariants. Whether an invariant violation should stop a process, isolate work, reject input, or degrade service depends on the fault model and blast radius.
+
+Coverage is evidence about execution, not proof of correctness. Exercise expected and invalid states and transitions between them. Test the tests through mutation, fault injection, known negative cases, or other independent checks where proportionate. Assertions, fuzzing, static analysis, and types can expose defects; none substitutes for human understanding or proves their absence. When a defect is fixed, preserve a regression check when one can reliably express the failure.
+
+Basis: software-testing research, *The Pragmatic Programmer* tips 30–35 (pp. 107–129), 48–50 (pp. 192–199), and 62–66 (pp. 237–247), and TigerStyle's documented use of explicit limits, executable invariants, and layered verification. Evidence for specific methods such as strict test-driven development is mixed and context-dependent; AHEAD does not mandate one universal test-writing order, assertion density, or failure response.
+
+## 10. Estimate physical performance early and measure it later
+
+When performance is material, make rough design-time estimates across network, storage, memory, and compute, considering both latency and bandwidth. Sketches are inexpensive ways to expose impossible assumptions, likely bottlenecks, and order-of-magnitude opportunities before architecture hardens.
 
-Coverage is evidence about execution, not proof of correctness. Test the tests through mutation, fault injection, or known negative cases where proportionate. When a defect is fixed, preserve a regression check when one can reliably express the failure.
+Use the estimate to identify a relevant constraint, implement proportionately, and then measure in a representative environment. Revise the model when observations disagree. Batching, control- and data-plane separation, static allocation, cache-aware layout, and reduced copying or serialization are contextual techniques, not default AHEAD requirements.
 
-Basis: software-testing research and *The Pragmatic Programmer* tips 30–35 (pp. 107–129), 48–50 (pp. 192–199), and 62–66 (pp. 237–247). Evidence for specific methods such as strict test-driven development is mixed and context-dependent; AHEAD does not mandate one universal test-writing order.
+Basis: *The Pragmatic Programmer* tips 18 (p. 64), 45 (p. 180), and 46 (p. 182), and TigerStyle's documented performance-sketch practice. TigerStyle is a practitioner source from a specialized systems context, not controlled evidence that its techniques generalize to every system.
 
-## 10. Debug with evidence, not confidence or blame
+## 11. Debug with evidence, not confidence or blame
 
 Do not panic, guess from the loudest log, or assume the platform is broken. Establish the observation, characterize it, build a mental model, generate hypotheses, predict discriminating results, test safely, and update the model.
 
@@ -92,7 +108,7 @@ Treat application code, dependencies, infrastructure, configuration, data, opera
 
 Basis: direct empirical debugging and incident-response studies, plus *The Pragmatic Programmer* tips 24–27 (pp. 91–97) and debugging checklist (p. 98).
 
-## 11. Review independently and communicate honestly
+## 12. Review independently and communicate honestly
 
 Review is a reasoning activity, not an approval button. Review the current artifact against intended behavior, architecture, risks, tests, operations, and maintainability. Automated and AI review add coverage; they do not replace accountable human judgment. A lasting engineering change requires review by a person other than the implementer; implementer self-review is still necessary, but it does not satisfy that independent gate.
 
@@ -100,7 +116,7 @@ Technical communication should be clear, audience-aware, and grounded in the aut
 
 Basis: empirical code-review research, NIST generative-AI risk guidance, and *The Pragmatic Programmer* tips 3 (p. 3), 10 (p. 21), and 67–70 (pp. 248–258).
 
-## 12. Learn continuously and measure the tools
+## 13. Learn continuously and measure the tools
 
 Build breadth by learning new languages, paradigms, ecosystems, tools, and operational models. Reimplementing a small system in contrasting languages can reveal how type systems, concurrency models, package managers, and idioms change design choices.
 
@@ -117,6 +133,8 @@ Before implementation:
 - What is the simplest model of the problem?
 - Which concerns can vary independently?
 - What must remain invariant?
+- Which limits, resource budgets, and fault-model assumptions are material?
+- If performance matters, what do rough network, storage, memory, and compute estimates predict?
 - How will we know the change works and fails safely?
 - Are we prototyping to learn or building production code?
 - If this is a disposable prototype, what is its learning question, isolation boundary, and disposal date?
@@ -126,6 +144,7 @@ Before accepting AI-assisted work:
 - Can the responsible engineer explain and change it?
 - Did the AI define behavior that a human should own?
 - Are claims, sources, dependencies, and commands verified?
+- Were added dependencies and tools evaluated for lifecycle and supply-chain cost?
 - Did AI-generated tests inherit the implementation's assumptions?
 - Was sensitive context authorized for the selected tool?
 - Has a person other than the implementer independently reviewed every lasting engineering change, with additional specialist review proportionate to risk?
@@ -135,6 +154,8 @@ Before merge or delivery:
 - Does the change trace to the approved problem and decision?
 - Are tests meaningful, current, and capable of failing?
 - Are failure, rollback, observation, and recovery understood?
+- Are material limits and invariants implemented and independently exercised?
+- Were relevant performance assumptions compared with representative measurements?
 - Did review examine system behavior rather than only style?
 - Is the documentation close enough to the system to remain accurate?
 - What accepted uncertainty or follow-up remains?
@@ -148,6 +169,7 @@ These are recommended practitioner sources, not scientific proof of AHEAD:
 - Luca Palmieri, [*Zero To Production In Rust*](https://www.zero2prod.com/), ISBN 9798847211437. This is a concrete production-backend learning path rather than a general philosophy source.
 - Richard Hamming, [*The Art of Doing Science and Engineering: Learning to Learn*](https://press.stripe.com/the-art-of-doing-science-and-engineering), ISBN 9781732265172.
 - Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+- TigerBeetle, [*TigerStyle*](https://tigerstyle.dev/). AHEAD adapts selected systems-engineering practices while keeping their specialized context and limitations explicit in the [source record](../evidence/sources/tigerstyle.md).
 
 ## Research sources
 

package/generated/reference/docs/guide/work-items.md

@@ -0,0 +1,65 @@
+# Work Items and Planning Handoffs
+
+Audience: AHEAD practitioners
+
+Status: pilot v0.1
+
+## Purpose
+
+A work item is the team's coordination surface: a GitHub issue, Jira issue, Azure Boards item, Linear issue, or another durable URL. AHEAD owns the workflow state, evidence chain, human gates, and resumable handoff. Linking the two avoids making either system pretend to be the other.
+
+A work item is optional unless the repository's AHEAD configuration requires one. Labels and issue templates may inform workflow selection, but the human still chooses the flow by its dominant outcome.
+
+## Existing and new work items
+
+An AHEAD run may link an existing work-item URL at startup or later. The link is provider-neutral and visible in the active header. Pi can also create a GitHub issue in the current repository after a human reviews its body, including any available approved plan, and explicitly confirms the external write. Creating, replacing, or linking a work item is always a human-attributed action.
+
+The work item may summarize or link the approved outcome, decision, and plan. It does not replace the AHEAD run record, and AHEAD does not silently rewrite it as the workflow changes.
+
+## Configurable boundary
+
+A repository may add `.ahead/config.json` and require a work item before a selected phase in each workflow:
+
+```json
+{
+  "api_version": "ahead.config/v0",
+  "work_items": {
+    "required_before_phase": {
+      "product-change": "implement",
+      "corrective-debugging": "implement",
+      "internal-improvement": "implement",
+      "decision": "publish",
+      "investigation": "conclude",
+      "operational-stabilization": "outcome"
+    }
+  }
+}
+```
+
+The map is deliberately explicit. A team may configure only the flows it uses, choose a different phase, or omit the file entirely. Operational teams should place the boundary after urgent stabilization if creating a work item first could delay safe recovery.
+
+The resolved requirement is copied into each new run. Later configuration changes do not silently change an active or saved run's gates.
+
+## Project setup and configuration changes
+
+When Pi starts new AHEAD work in a project with no `.ahead/config.json`, it offers to run a setup wizard or continue without project policy. Run `/ahead-config` at any time to:
+
+- choose AHEAD's recommended planning boundaries;
+- choose a different boundary for each workflow;
+- explicitly make work items optional for every workflow;
+- view the current configuration; or
+- rerun the wizard to replace an existing or unsupported configuration.
+
+Replacement is deliberate and confirmed. Before writing the current schema, AHEAD copies the exact prior file to `.ahead/backups/`, including an invalid file or one with an unsupported API version. This provides a recoverable configuration-migration path without guessing how old policy should map to new semantics. Existing and explicitly saved runs keep their original policy snapshot.
+
+## Sprint-ahead planning
+
+For work planned before implementation:
+
+1. Start AHEAD with the work-item URL, or link/create the item during the run.
+2. Complete the selected workflow through its human-approved plan.
+3. Satisfy the configured work-item boundary and enter `implement`.
+4. Save the ready-to-implement handoff instead of beginning implementation.
+5. In the later sprint, the implementing engineer resumes the same run and inherits the approved evidence, decisions, plan, link, and open implementation gate.
+
+Saving this handoff is an explicit human choice. It is not workflow completion, and it does not claim that implementation, review, deployment, or verification occurred.

package/generated/reference/docs/guide/workflows/README.md

@@ -75,6 +75,7 @@ modifiers:
   assurance: standard | security | regulated | safety-critical
   environment: local | test | staging | production | external
 links: []
+work_item: optional provider-neutral URL
 ```
 
 The body records only the sections required by the selected flow. Evidence may remain in its native system and be linked rather than copied.

package/generated/reference/index.json

@@ -7,11 +7,13 @@
     "docs/evidence/research-map.md",
     "docs/evidence/sources/pragmatic-programmer-page-index.md",
     "docs/evidence/sources/submitted-engineering-notes.md",
+    "docs/evidence/sources/tigerstyle.md",
     "docs/guide/README.md",
     "docs/guide/acceptable-ai-use.md",
     "docs/guide/engineering-practice.md",
     "docs/guide/rationale.md",
     "docs/guide/recommended-skills.md",
+    "docs/guide/work-items.md",
     "docs/guide/workflows/README.md",
     "docs/guide/workflows/corrective-debugging.md",
     "docs/guide/workflows/decision.md",
@@ -111,6 +113,19 @@
         "*"
       ]
     },
+    {
+      "id": "evidence:sources:tigerstyle",
+      "path": "docs/evidence/sources/tigerstyle.md",
+      "title": "TigerStyle Practitioner Source",
+      "summary": "[TigerStyle](https://tigerstyle.dev/) is TigerBeetle's published software-engineering methodology for advancing safety, performance, and developer experience in its distributed financial database. TigerBeetle is both the author of the sourc",
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
+    },
     {
       "id": "guide",
       "path": "docs/guide/README.md",
@@ -184,6 +199,19 @@
         "*"
       ]
     },
+    {
+      "id": "work-items",
+      "path": "docs/guide/work-items.md",
+      "title": "Work Items and Planning Handoffs",
+      "summary": "A work item is the team's coordination surface: a GitHub issue, Jira issue, Azure Boards item, Linear issue, or another durable URL. AHEAD owns the workflow state, evidence chain, human gates, and resumable handoff. Linking the two avoids m",
+      "audience": "practitioner",
+      "authority": "guidance",
+      "distribution": "agent-and-human",
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
+    },
     {
       "id": "workflows",
       "path": "docs/guide/workflows/README.md",