ahead-pi 0.2.1 → 0.3.1

package/src/storage.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import type { Actor, Run } from "./types.js";
 
@@ -11,9 +11,11 @@ interface CurrentRunPointer {
 
 export class RunStore {
   readonly aheadDirectory: string;
+  readonly projectRoot: string;
 
-  constructor(readonly projectRoot: string) {
-    this.aheadDirectory = join(projectRoot, ".ahead");
+  constructor(rootPath: string) {
+    this.projectRoot = rootPath;
+    this.aheadDirectory = join(rootPath, ".ahead");
   }
 
   newRunId(): string {
@@ -23,19 +25,20 @@ export class RunStore {
 
   async loadCurrent(): Promise<Run | undefined> {
     try {
-      const pointer = JSON.parse(await readFile(join(this.aheadDirectory, "current.json"), "utf8")) as CurrentRunPointer;
-      if (pointer.api_version !== "ahead.current/v0" || !pointer.run_id) {
-        throw new Error("invalid .ahead/current.json");
-      }
+      const pointer = parseCurrentRunPointer(
+        await readFile(join(this.aheadDirectory, "current.json"), "utf8"),
+      );
       return this.load(pointer.run_id);
     } catch (error) {
-      if (isMissing(error)) return undefined;
+      if (isMissing(error)) {
+        return undefined;
+      }
       throw error;
     }
   }
 
   async load(runId: string): Promise<Run> {
-    return JSON.parse(await readFile(this.runPath(runId), "utf8")) as Run;
+    return parseRun(await readFile(this.runPath(runId), "utf8"));
   }
 
   async save(run: Run, makeCurrent = true): Promise<void> {
@@ -46,9 +49,48 @@ export class RunStore {
     }
   }
 
+  async listRunIds(): Promise<string[]> {
+    try {
+      const entries = await readdir(join(this.aheadDirectory, "runs"), { withFileTypes: true });
+      return entries
+        .filter((entry) => entry.isDirectory() && isSafeRunId(entry.name))
+        .map((entry) => entry.name)
+        .toSorted((left, right) => right.localeCompare(left));
+    } catch (error) {
+      if (isMissing(error)) {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  async saveCurrentForResume(runId: string): Promise<void> {
+    await this.load(runId);
+    await this.clearCurrent(runId);
+  }
+
+  async resume(runId: string): Promise<Run> {
+    const run = await this.load(runId);
+    const pointer: CurrentRunPointer = { api_version: "ahead.current/v0", run_id: runId };
+    await atomicJson(join(this.aheadDirectory, "current.json"), pointer);
+    return run;
+  }
+
+  async discardCurrent(runId: string): Promise<void> {
+    const directory = this.runDirectory(runId);
+    await this.clearCurrent(runId);
+    await rm(directory, { recursive: true, force: false });
+  }
+
   artifactPath(run: Run, phase: string, kind: string): { absolute: string; relative: string } {
     const sequence = String(run.events.length + 1).padStart(4, "0");
-    const absolute = join(this.aheadDirectory, "runs", run.id, "artifacts", `${sequence}-${phase}-${kind}.md`);
+    const absolute = join(
+      this.aheadDirectory,
+      "runs",
+      run.id,
+      "artifacts",
+      `${sequence}-${phase}-${kind}.md`,
+    );
     return { absolute, relative: relative(this.projectRoot, absolute) };
   }
 
@@ -62,15 +104,51 @@ export class RunStore {
     await writeFile(resolved, `${content.trim()}\n`, { encoding: "utf8", flag: "wx" });
   }
 
+  async readArtifact(path: string): Promise<string> {
+    const resolved = resolve(this.projectRoot, path);
+    const artifactsRoot = resolve(this.aheadDirectory, "runs");
+    if (!resolved.startsWith(`${artifactsRoot}/`)) {
+      throw new Error("artifact path escaped .ahead/runs");
+    }
+    return readFile(resolved, "utf8");
+  }
+
   private runPath(runId: string): string {
-    if (!/^[A-Za-z0-9._-]+$/.test(runId)) throw new Error("unsafe AHEAD run id");
-    return join(this.aheadDirectory, "runs", runId, "run.json");
+    return join(this.runDirectory(runId), "run.json");
+  }
+
+  private runDirectory(runId: string): string {
+    if (!isSafeRunId(runId)) {
+      throw new Error("unsafe AHEAD run id");
+    }
+    return join(this.aheadDirectory, "runs", runId);
+  }
+
+  private async clearCurrent(expectedRunId: string): Promise<void> {
+    const path = join(this.aheadDirectory, "current.json");
+    let pointer: CurrentRunPointer;
+    try {
+      pointer = parseCurrentRunPointer(await readFile(path, "utf8"));
+    } catch (error) {
+      if (isMissing(error)) {
+        return;
+      }
+      throw error;
+    }
+    if (pointer.run_id !== expectedRunId) {
+      throw new Error(
+        `active AHEAD run changed from ${expectedRunId} to ${pointer.run_id}; stop or resume again`,
+      );
+    }
+    await unlink(path);
   }
 }
 
 export function humanActor(cwd: string): Actor {
   const explicit = process.env.AHEAD_HUMAN_IDENTITY?.trim();
-  if (explicit) return { kind: "human", identity: explicit };
+  if (explicit) {
+    return { kind: "human", identity: explicit };
+  }
   for (const key of ["user.email", "user.name"]) {
     try {
       const value = execFileSync("git", ["config", key], {
@@ -78,7 +156,9 @@ export function humanActor(cwd: string): Actor {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"],
       }).trim();
-      if (value) return { kind: "human", identity: value };
+      if (value) {
+        return { kind: "human", identity: value };
+      }
     } catch {
       // Fall through to the next local identity source.
     }
@@ -93,7 +173,9 @@ export function projectRoot(cwd: string): string {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
-    if (root) return root;
+    if (root) {
+      return root;
+    }
   } catch {
     // AHEAD can also persist beside work that is not yet in Git.
   }
@@ -110,3 +192,45 @@ async function atomicJson(path: string, value: unknown): Promise<void> {
 function isMissing(error: unknown): boolean {
   return !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
 }
+
+function isSafeRunId(runId: string): boolean {
+  return runId !== "." && runId !== ".." && /^[A-Za-z0-9._-]+$/.test(runId);
+}
+
+function parseCurrentRunPointer(content: string): CurrentRunPointer {
+  const value: unknown = JSON.parse(content);
+  if (
+    !isRecord(value) ||
+    value.api_version !== "ahead.current/v0" ||
+    typeof value.run_id !== "string" ||
+    value.run_id.length === 0
+  ) {
+    throw new Error("invalid .ahead/current.json");
+  }
+  return { api_version: value.api_version, run_id: value.run_id };
+}
+
+function parseRun(content: string): Run {
+  const value: unknown = JSON.parse(content);
+  if (!isRun(value)) {
+    throw new Error("invalid AHEAD run record");
+  }
+  return value;
+}
+
+function isRun(value: unknown): value is Run {
+  return (
+    isRecord(value) &&
+    typeof value.api_version === "string" &&
+    typeof value.id === "string" &&
+    typeof value.title === "string" &&
+    typeof value.workflow_id === "string" &&
+    typeof value.workflow_version === "string" &&
+    typeof value.owner === "string" &&
+    Array.isArray(value.events)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/types.ts

@@ -13,6 +13,7 @@ export interface ArtifactDefinition {
   actor: ActorRule;
   required: boolean;
   independent_of?: string;
+  same_as?: string;
 }
 
 export interface PhaseDefinition {

package/generated/reference/docs/design/debugging-and-operations.md

@@ -1,119 +0,0 @@
-# Debugging and Operational Investigation
-
-Status: design discussion, not an approved workflow specification
-
-The minimal [corrective-debugging](../workflows/corrective-debugging.md) and [operational-stabilization](../workflows/operational-stabilization.md) profiles translate this discussion into pilotable flows. This document retains the reasoning and unresolved questions behind them.
-
-## Human ownership
-
-Debugging is human-owned. AI may help collect and organize evidence, suggest hypotheses and tests, identify contradictions, explain systems, and challenge conclusions. The human chooses what to investigate, performs or authorizes tests, interprets the evidence, selects interventions, and accepts the conclusion or remaining uncertainty.
-
-There is no “AI investigation” phase. Investigation is a human engineering activity in which AI may participate.
-
-## Shared reasoning loop
-
-```text
-Observation
-→ Characterize
-→ Build or update the mental model
-→ Generate hypotheses
-→ Human selects a discriminating test
-→ Predict expected results
-→ Run the test
-→ Record evidence
-→ Update or refute hypotheses
-→ Repeat
-```
-
-The process distinguishes:
-
-- **Fact:** directly observed and linked to evidence.
-- **Inference:** an interpretation derived from facts.
-- **Hypothesis:** a falsifiable proposed explanation.
-- **Test:** an experiment or observation capable of changing confidence in a hypothesis.
-- **Result:** what the test actually produced.
-- **Conclusion:** a human-accepted explanation with confidence, limits, and remaining uncertainty.
-
-Predictions should be recorded before a test when practical. This reduces hindsight interpretation of ambiguous results.
-
-## Bug debugging
-
-A bug is a defect where observed software behavior conflicts with intended behavior.
-
-```text
-Observe → Reproduce or establish
-→ Characterize
-→ Human-led investigation loop
-→ Human accepts diagnosis or uncertainty
-→ Choose fix → Plan → Implement → Validate locally
-→ AI review → Independent human review
-→ Human-authorized deploy or release when applicable
-→ Verify the original failure and observe the outcome
-→ Audit assumptions → Human outcome
-```
-
-Reproduction is valuable but not universally required. A failure may be intermittent, historical, production-only, environment-specific, or already mitigated.
-
-## Operational investigation
-
-An operational issue is undesirable system behavior that may not be a software defect. Examples include reconciliation storms, configuration drift, capacity exhaustion, cloud-provider behavior, dependency failures, identity or certificate failures, resource contention, bad rollout sequencing, and emergent controller interactions.
-
-```text
-Observed condition
-→ Desired state versus actual state
-→ Impact and scope
-→ Timeline
-→ System and control-loop model
-→ Recent changes and external events
-→ Evidence/hypothesis/test loop
-→ Intervention decision
-→ Verify convergence and user-visible behavior
-→ Monitor recurrence
-→ Corrective actions
-```
-
-The initial cause classification must remain tentative. Labeling an issue a code bug, configuration error, or provider failure before collecting evidence can bias the investigation.
-
-## Incident mode
-
-“Incident” describes impact and urgency rather than cause. An incident may be caused by a bug, configuration, capacity, provider behavior, a security event, data, or an interaction that remains partially unexplained.
-
-Incident mode adds parallel concerns:
-
-```text
-Response:       assess impact → contain → recover → monitor
-Investigation:  evidence → model → hypotheses → tests → conclusion
-Coordination:   ownership → decisions → communications → timeline
-```
-
-Mitigation and recovery must not be blocked on completing a full diagnosis. Risky interventions still require explicit human authorization. After recovery, unresolved causal analysis and prevention work may continue as a linked bug, operational investigation, security issue, or technical-debt item.
-
-## Current design direction
-
-- Treat bug debugging and operational investigation as separate work types.
-- Treat incident mode as an overlay that may apply to several work types.
-- Keep the evidence and hypothesis loop flexible rather than gating every iteration.
-- Reserve hard gates for human accountability, risky tests, consequential interventions, accepted conclusions, implementation plans, reviews, and verified outcomes.
-- Distinguish hypothesis testing, fix validation, and post-deployment outcome verification.
-- Allow causal conclusions to include a failure mechanism, trigger, enabling conditions, and detection or containment gaps instead of insisting on one root cause.
-
-## Open questions
-
-- What minimum evidence is needed before a human may accept a diagnosis?
-- When may a team remediate while explicitly accepting that the cause is unknown?
-- Which tests require approval based on environment, reversibility, or blast radius?
-- How should AHEAD represent multiple interacting causes and confidence changes?
-- When does an operational anomaly become incident mode?
-- Which incident records must be produced during response, and which may be reconstructed afterward?
-- How should follow-up work remain linked without keeping the incident itself permanently open?
-
-## Evidence basis
-
-The current reasoning loop is supported by direct empirical software-engineering research, though the exact AHEAD recording requirements are not yet validated:
-
-- [Li and Coblenz, *A Grounded Theory of Debugging in Professional Software Engineering Practice*](https://arxiv.org/abs/2602.11435) observed professional developers and describes debugging as iterative mental-model construction that guides information gathering.
-- [Alaboudi and LaToza, *Using Hypotheses as a Debugging Aid*](https://doi.org/10.1109/VL/HCC50065.2020.9127273) found that early correct hypotheses predicted success and that supplying potential hypotheses helped more than supplying fault locations in their controlled experiment.
-- [Sillito and Kutomi, *Failures and Fixes*](https://doi.org/10.1109/ICSME46990.2020.00027) analyzed 30 incidents and identified distinct investigative and mitigative strategies.
-- [Ghosh et al., *How to Fight Production Incidents?*](https://doi.org/10.1145/3542929.3563482) studied hundreds of high-severity cloud incidents, including non-code causes, across detection, diagnosis, and mitigation.
-
-These studies support the shape of the process. They do not prove that requiring engineers to record every fact, hypothesis, or test improves results. AHEAD must test the minimum useful structure and remove requirements that interrupt investigation without improving reasoning, handoff, or learning.

package/generated/reference/docs/design/executable-workflows.md

@@ -1,110 +0,0 @@
-# Executable AHEAD Workflows
-
-Status: initial vertical slice v0.1
-
-## Purpose
-
-The executable layer makes AHEAD workflow state durable and makes selected human/AI boundaries enforceable across integrations. It does not turn judgment into a checklist or make workflow artifacts proof of understanding.
-
-The first vertical slice implements the Product Change workflow. The other five pilot workflows remain manual profiles until dogfooding provides evidence about the reusable state model.
-
-## Architecture
-
-```text
-CONSTITUTION / ACCEPTABLE-AI-USE
-                 │
-                 ▼
-CANONICAL WORKFLOW SPEC + POLICY FRAGMENTS
-                 │
-        ┌────────┴────────┐
-        ▼                 ▼
-RUST WORKFLOW CORE   GENERATED INSTRUCTIONS
-        │                 │
-        └────────┬────────┘
-                 ▼
-         INTEGRATION ADAPTER
-        (Pi first; others later)
-                 │
-        ┌────────┴─────────┐
-        ▼                  ▼
-HOST TOOLS / MODEL     DURABLE RUN FILES
-```
-
-The Rust core owns workflow semantics. It is deterministic and has no filesystem, network, clock, model-provider, or editor dependency. Hosts supply identity and timestamps, persist returned runs, and map their tools to canonical capabilities.
-
-The initial WebAssembly boundary is a small versioned JSON ABI. This avoids coupling the core to one JavaScript binding generator and lets a later editor or CI integration load the same state machine.
-
-## Sources of truth
-
-| Concern | Canonical source |
-|---|---|
-| Durable principles | `CONSTITUTION.md` |
-| AI authority | `docs/acceptable-ai-use.md` |
-| Human-readable Product Change flow | `docs/workflows/product-change.md` |
-| Executable phases, artifacts, gates, transitions, and capabilities | `spec/workflows/product-change-v0.1.json` |
-| Compact binding agent profile and shared AI behavior | `policy/common.md` |
-| Phase AI behavior | `policy/product-change/*.md` |
-| State transition enforcement | `crates/ahead-core` |
-| Host mapping, storage, and UI | `integrations/pi` |
-
-Generated integration instructions are build artifacts. They include the compact agent profile, active phase policy, enforced contract, workflow version, and a source hash and must not be edited directly.
-
-The Pi package also copies the canonical Constitution and `docs/**/*.md` into a generated reference catalog. These full documents are not injected into every prompt. The adapter recommends references applicable to the active phase, lets humans read them through `/ahead-guide`, and lets AI retrieve a specific source through `ahead_get_reference`. This keeps the binding prompt small while making the framework, rationale, evidence, and original page-level provenance available on demand.
-
-## State and evidence
-
-A run is an append-only event log. Events record an actor kind and identity, host-supplied timestamp, sequence, and one action:
-
-- start the run;
-- record an artifact;
-- accept a human gate;
-- advance or return between phases;
-- close the run.
-
-State is derived by replay. The core rejects invalid history rather than trusting a cached phase field. A return transition creates a new visit to the target phase. Earlier evidence remains in history, but only evidence recorded during the current visit satisfies its gate.
-
-Pi stores state under the work's Git root:
-
-```text
-.ahead/
-├── current.json
-└── runs/
-    └── <run-id>/
-        ├── run.json
-        └── artifacts/
-            └── <sequence>-<phase>-<kind>.md
-```
-
-These are intended to be inspectable, diffable repository artifacts. A team can decide which records belong in Git, while CI and GitHub enforcement are later adapters over the same run contract.
-
-## Enforced boundaries in v0.1
-
-- Only a human actor can start a run, accept a gate, transition a phase, return work, or close a run.
-- Artifact definitions state whether a human, AI, or either may record them.
-- Human-first option and plan artifacts unlock AI assistance in those phases.
-- Required current-visit artifacts must exist before gate acceptance.
-- Advancement requires the current human gate.
-- Independent human review must be recorded by an identity other than the latest changeset implementer, and that reviewer must accept the review gate.
-- The Product Change flow distinguishes implementation, deployment, observation, audit, and human outcome.
-- Model-invoked host tools require an explicit adapter mapping to an allowed canonical capability.
-
-Instructions explain these boundaries to the model. The Rust core enforces the transition, actor, artifact, identity, and capability decisions even if instructions are ignored.
-
-During implementation, instructions explicitly permit questions, explanation, debugging help, and bounded suggestions while keeping the engineer first. If the engineer has not supplied a current model, attempted approach, or intended behavior, AI asks for it before proposing a solution. A request for help does not authorize AI to take over the implementation.
-
-## Trust boundaries and limits
-
-The Pi adapter is an engineering workflow control, not a security sandbox.
-
-- Local human identity comes from `AHEAD_HUMAN_IDENTITY`, then Git email/name, then the local user. It is self-attested. GitHub review identity and protected-branch rules will provide a stronger boundary later.
-- Pi's direct `!` shell is a human action and is not intercepted. Model-invoked `bash` is intercepted.
-- Unknown model tools are denied until the adapter classifies them. This prevents a newly installed effectful tool from silently acquiring authority.
-- Artifact and run writes are atomic, but v0.1 has no multi-process lock. One writer should operate a run at a time.
-- Workflow files can prove that a named action was recorded, not that a person genuinely understood it. Human review and organizational accountability remain necessary.
-- No GitHub checks, PR gates, migration engine, signature scheme, or backwards-compatible workflow upgrade exists yet.
-
-## Reuse path
-
-The reusable boundary is the engine API, not a CLI. Pi is the first adapter. A VS Code extension, GitHub check, or future WASM-capable editor can reuse the same compiled core and canonical fragments while providing its own UI, storage transport, identity strength, and tool-capability map.
-
-Dogfooding should test whether phase visits, artifacts, gates, returns, capability vocabulary, and identity rules generalize before the remaining five workflow profiles are encoded.

package/generated/reference/docs/design/process-taxonomy.md

@@ -1,144 +0,0 @@
-# AHEAD Process Taxonomy
-
-Status: proposed design
-Last reviewed: 2026-08-12
-
-## Why classify by outcome
-
-AHEAD should not create a workflow for every issue label. “Security,” “performance,” “data,” “incident,” and “technical debt” often describe risk, domain, urgency, or cause—not the kind of reasoning needed to complete the work.
-
-The primary workflow should be selected by the **dominant outcome** the human is trying to produce. Variants and overlays then adapt that workflow to context.
-
-This gives AHEAD six proposed process families. All six now have minimal [pilot workflow profiles](../workflows/README.md) for use and evaluation; that does not yet validate the taxonomy or justify automated enforcement.
-
-## The six process families
-
-| Process family | Dominant question | Terminal outcome | Examples | Status |
-|---|---|---|---|---|
-| 1. [Product change](../workflows/product-change.md) | What behavior or capability should exist, and how should we deliver it? | Verified intended behavior | Feature, API change, integration, migration, dependency adaptation, decommission | Pilot v0.1 |
-| 2. [Corrective debugging](../workflows/corrective-debugging.md) | Why does observed behavior differ from intended behavior, and how should we correct it? | Verified correction or explicitly accepted uncertainty | Deterministic bug, flaky failure, regression, incorrect data processing | Pilot v0.1 |
-| 3. [Operational stabilization](../workflows/operational-stabilization.md) | Why is a live system outside an acceptable operating state, and how do we restore and stabilize it? | Demonstrated recovery/convergence and follow-up disposition | Reconciliation storm, capacity exhaustion, configuration drift, dependency outage | Pilot v0.1 |
-| 4. [Decision](../workflows/decision.md) | Which course should humans choose, given goals, evidence, constraints, and tradeoffs? | Approved decision and rationale | Architecture decision, buy/build, technology selection, policy or platform choice | Pilot v0.1 |
-| 5. [Investigation](../workflows/investigation.md) | What is true, feasible, or likely when no intervention has yet been selected? | Bounded conclusion, confidence, evidence, and remaining unknowns | Technical spike, feasibility study, causal follow-up, capacity study, vendor evaluation | Pilot v0.1 |
-| 6. [Internal improvement](../workflows/internal-improvement.md) | How can we improve system qualities while preserving an explicit behavioral contract? | Verified invariants plus improved target qualities | Refactor, preventive maintenance, maintainability debt, performance optimization without semantic change | Pilot v0.1 |
-
-Six is a working taxonomy, not a sacred number. The threshold for adding a seventh family is deliberately high.
-
-## Selection test
-
-```text
-Is the primary outcome new or changed externally meaningful behavior?
-  → Product change
-
-Is an observed behavior wrong and the main work is causal diagnosis plus correction?
-  → Corrective debugging
-
-Is a live system unhealthy, unstable, or failing to converge, with restoration as the immediate outcome?
-  → Operational stabilization
-
-Is the deliverable an accountable choice among alternatives?
-  → Decision
-
-Is the deliverable knowledge or reduced uncertainty, without a predetermined change?
-  → Investigation
-
-Must behavior remain invariant while internal qualities improve?
-  → Internal improvement
-```
-
-A large effort may link several runs. An architecture decision can lead to a product change. An incident can create an operational investigation, a corrective bug, and an internal-improvement follow-up. A technical spike can end in a decision without pretending that knowledge production and option selection are the same activity.
-
-## Why the additional three differ
-
-### Decision
-
-A feature includes decisions, but some engineering work ends with a decision rather than code. Its quality depends on framing, option coverage, evidence, tradeoffs, consequences, reversibility, and accountable approval. Forcing it through implementation and deployment creates meaningless states.
-
-### Investigation
-
-An investigation begins with a question, not an assumed defect or desired change. It may conclude that no action is needed, evidence is insufficient, a vendor owns the behavior, or several interventions remain viable. Its terminal quality is epistemic: evidence, confidence, limitations, and unknowns.
-
-### Internal improvement
-
-Refactoring and preventive work are judged differently from feature work. They begin by specifying invariants and target qualities. Success means that required behavior was preserved while maintainability, performance, safety, comprehensibility, or another quality improved. Treating this as a feature encourages invented product outcomes; treating it as a bug assumes a failure that may not exist.
-
-## Overlays, not primary processes
-
-### Incident mode
-
-Incident mode represents urgency, impact, coordination, containment, communication, and recovery. It can overlay corrective debugging, operational stabilization, a security event, or a data issue. It relaxes nonessential documentation during response but strengthens action authorization and decision logging.
-
-### Security
-
-Security adds confidentiality, evidence preservation, threat modeling, restricted AI access, disclosure, and security approval. A vulnerability may use corrective debugging; proactive hardening may use internal improvement; an active compromise may use incident-mode operational stabilization; a threat assessment may use investigation.
-
-### Safety, regulatory, and compliance
-
-These overlays strengthen traceability, independence, evidence retention, required reviewers, and non-waivable gates. They do not change whether the underlying work is a change, correction, operation, decision, investigation, or improvement.
-
-### Emergency
-
-Emergency handling changes sequencing and permits explicitly governed deferrals. It does not erase human accountability or evidence requirements; it moves some reconstruction and learning after stabilization.
-
-## Labels and modifiers
-
-Context belongs in typed modifiers rather than new workflow definitions:
-
-```yaml
-process: operational-stabilization
-urgency: incident
-domain: infrastructure
-assurance: standard
-failure_character: intermittent
-environment: production
-data_classification: internal
-```
-
-Useful modifiers may include:
-
-- urgency: normal, expedited, incident, emergency;
-- assurance: standard, security, safety-critical, regulated;
-- environment: local, test, staging, production, external provider;
-- failure character: deterministic, intermittent, performance, data, distributed, unknown;
-- change character: additive, adaptive, migration, retirement;
-- reversibility and blast radius;
-- evidence sensitivity.
-
-## Where common work maps
-
-| Work label | Primary process or routing rule |
-|---|---|
-| Feature | Product change |
-| Bug | Corrective debugging |
-| Production reconciliation storm | Operational stabilization; add incident mode when impact/urgency warrants it |
-| Architecture decision | Decision; link resulting implementation separately |
-| Technical debt | Internal improvement when preserving behavior; product change when behavior changes; corrective debugging when it represents a known defect |
-| Refactor | Internal improvement |
-| Performance regression | Corrective debugging |
-| Proactive performance optimization | Internal improvement or product change, depending on whether performance is a new product outcome |
-| Security vulnerability | Corrective debugging plus security overlay |
-| Active security compromise | Operational stabilization plus incident and security overlays |
-| Security hardening | Internal improvement or product change plus security overlay |
-| Research spike | Investigation |
-| Compliance audit | Investigation plus compliance overlay; corrective or improvement runs handle findings |
-| Dependency or platform upgrade | Product change with adaptive-change modifier |
-| Service retirement | Product change with retirement and risk modifiers |
-
-## Test for adding another family
-
-A new primary process family should be added only when all of these are true:
-
-1. It has a distinct terminal outcome.
-2. It has a distinct central reasoning loop.
-3. It requires materially different human decisions or gates.
-4. It cannot be represented clearly as a variant, overlay, modifier, or linked combination of existing families.
-5. Evidence or repeated practice shows that using an existing family creates confusion, unsafe behavior, or process theater.
-6. The additional cognitive and tooling cost is justified.
-
-## Evidence basis and limits
-
-[ISO/IEC/IEEE 12207:2026](https://standards.ieee.org/ieee/12207/11416/) covers development, operation, maintenance, support, and retirement and allows processes to operate concurrently, iteratively, and recursively. [ISO/IEC/IEEE 14764:2022](https://www.iso.org/standard/80710.html) separately establishes software-maintenance types. These standards support broad coverage and composition, but they do not validate this six-family taxonomy.
-
-Empirical debugging research supports a mental-model and hypothesis-testing process distinct from planned change. Empirical production-incident research distinguishes code and non-code causes and separates detection, investigation, and mitigation. Those findings support keeping corrective debugging and operational stabilization separate.
-
-The proposed six-family classification itself remains an AHEAD design hypothesis. The pilot profiles should be tested against a diverse sample of real engineering work by asking whether teams can route work consistently, whether important states or gates differ, which records improve reasoning or handoff, and whether any family is rarely used or routinely misclassified.