@tenkara/afm-linux-arm64 0.0.0-stage → 4.0.0-alpha.11

package/content/patterns/adapter.md

@@ -0,0 +1,46 @@
+---
+type: pattern
+description: Wraps a vendor SDK type or payload shape at the boundary so domain and lib code depend on an owned interface instead of the vendor's.
+load: cold
+smell: 'a vendor SDK type (a Stripe object, an S3 response, an ORM row) is imported and used directly inside domain or lib code, past the boundary it arrived at'
+when_to_use: the vendor type crosses more than one file, or it is expected to change independently of the domain model that consumes it
+when_not_to_use: the vendor call happens in exactly one file and its result is consumed nowhere else
+---
+
+# Pattern — Adapter
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues DIP in `rubrics/solid-triggers.md` (domain must not import infra) and
+`rubrics/validation-boundary.md` (the parser lives at exactly 2 places). Adapter is what sits at
+that same boundary for a *type*, not a schema: it converts the vendor's shape to an owned one on
+the way in, once.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| `Stripe.Customer` (or equivalent) is read in 2+ files | Adapter: one function maps it to an owned `Customer` type at the boundary, everything past that line uses the owned type | Passing the SDK type through domain and re-reading its fields in each consumer |
+| The SDK's field names or nesting are unstable across major versions (checked: it has broken before) | Adapter absorbs the next breaking change in 1 file | The breaking change ships and touches every call site that read the SDK type directly |
+| The SDK call and its one consumer live in the same file, never exported | No adapter yet — see `when-to-create-lib.md`, one caller does not earn extraction | A `StripeCustomerAdapter` class for a value read once and discarded |
+| The domain needs to call back into the vendor (not just read its output) | Wrap the vendor client behind a port your domain defines (this is DIP, Adapter's usual partner) | Domain importing the vendor SDK client directly to make the call itself |
+
+## Why this works
+
+A vendor's shape is out of your control; a domain model is not. Every field of the vendor type
+read directly in domain code is a place a vendor upgrade can break — with the adapter, an upgrade
+that renames or restructures the vendor type is absorbed in the 1 function that does the mapping,
+never in the N places that use the resulting owned type.
+
+## Anti-patterns
+
+- ❌ An adapter that just renames fields 1:1 and adds no real translation, guarding a type used in
+  exactly one place. That's indirection with no boundary to protect — see `when-to-create-lib.md`.
+- ❌ The adapter returns the vendor's own error type unchanged. Errors need the same translation as
+  data — see `error-classification.md` for what the domain-facing shape should be.
+- ❌ Two adapters for the same vendor type, one per module, silently drifting. Vendor type → owned
+  type is a boundary fact, not a per-module preference; it belongs in one shared place.
+- ❌ Calling the adapter function conditionally, so some call sites still see the raw vendor type.
+  A boundary that is optional is not a boundary.

package/content/patterns/facade.md

@@ -0,0 +1,47 @@
+---
+type: pattern
+description: Bundles a repeated sequence of calls across 3 or more collaborators, that always represents one business step, behind a single function.
+load: cold
+smell: 'a call site wires 3 or more collaborators in the same order, in more than one place, to carry out one coherent business step'
+when_to_use: the same sequence of calls across 3+ collaborators repeats at 2+ call sites and always represents one step
+when_not_to_use: the collaborators are used independently at each call site — a different subset, or a different order, each time
+---
+
+# Pattern — Facade
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues ISP in `rubrics/solid-triggers.md`, from the other direction: ISP narrows what a single
+function receives; Facade narrows what a *caller* must know to perform one step, by hiding the
+fan-out to several collaborators behind one call.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| 2+ call sites each wire the same 3+ collaborators, in the same order, for the same outcome | Extract a facade function; the call sites call it once and stop knowing the collaborators exist | Each call site re-derives the correct order, one of them getting it wrong under time pressure |
+| One of the wired collaborators is itself a vendor SDK crossing a boundary | Apply Adapter to that one collaborator first, then wrap the sequence in the Facade | The Facade re-exports the raw vendor type through its own return value, leaking the boundary it should hide |
+| The call sites use *different* subsets or orders of the same collaborators | Do not extract — that variation is the actual logic, and a facade would hide it, not simplify it | A facade with a boolean flag per caller's variant — the flags are the switch this pattern was meant to avoid |
+| Only one call site exists | No facade yet — inline the sequence until a 2nd real caller needs the same one | A `CheckoutFacade` built for a single call site "to keep the handler short" |
+
+## Why this works
+
+A caller wiring C collaborators must know all C APIs, their call order, and how errors from each
+propagate — that knowledge is repeated at every call site that performs the same step. A facade
+moves it to 1 place: each call site's coupling drops from C collaborators to 1 function, and a
+change to the internal wiring (a 4th collaborator added, the order changed) touches that 1 place.
+
+## Anti-patterns
+
+- ❌ A facade over collaborators that are each already simple to call alone. If wiring them takes
+  1 line each, the facade adds a name to remember without reducing real complexity.
+- ❌ A "God facade" that grows to wrap every collaborator in the module, becoming the module's only
+  entry point for unrelated steps. Facade wraps *one* coherent business step, not the whole module
+  — see `rubrics/solid-triggers.md` § SRP if it starts doing 2+ things.
+- ❌ Swallowing or generically catching every collaborator's error inside the facade. Each
+  collaborator's failure still needs its own classification — see `error-classification.md`;
+  a facade changes who calls, not how errors are represented.
+- ❌ Building the facade before the 2nd call site exists, on the belief the sequence will repeat.
+  That is the same premature-extraction risk `when-to-create-lib.md` names for helpers in general.

package/content/patterns/factory.md

@@ -0,0 +1,46 @@
+---
+type: pattern
+description: Centralizes a multi-step object construction that is copy-pasted at 2 or more call sites into one named function.
+load: cold
+smell: 'the same multi-step construction (apply defaults, validate, wire 2+ collaborators) is copy-pasted at 2 or more call sites to build the same kind of object'
+when_to_use: constructing the object takes more than one step, and that construction already repeats at 2+ call sites
+when_not_to_use: the value is a single-field object literal, or only one call site builds it today
+---
+
+# Pattern — Factory
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues the Rule-of-Three trigger already used in `rubrics/when-to-create-lib.md`: that rubric
+extracts a helper on the 3rd caller. Factory is the same threshold applied specifically to
+*construction* logic — defaults, validation, wiring 2+ collaborators into one object.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| 2+ call sites build the same kind of object with the same defaults and the same wiring steps | Extract a `create<X>()` factory function; call sites pass only what varies | Each call site re-applies the same defaults, one of them drifting when a default changes |
+| The object needs 1+ collaborator injected (a clock, an id generator, a config) to be testable | Factory takes the collaborators as parameters, with production defaults | The object reaches for `Date.now()` or a singleton internally — untestable without mocking modules |
+| Construction is a single field literal (`{ id, name }`) | No factory. A function that returns its own argument is ceremony | `createUser({ id, name })` that does nothing `{ id, name }` didn't already do |
+| Only one call site exists today | No factory yet — wait for the 2nd real caller, per `when-to-create-lib.md` | A `UserFactory` class built ahead of the 2nd caller, on the promise it is coming |
+
+## Why this works
+
+Construction logic duplicated at K call sites means a changed default, a new required field, or a
+new invariant must be applied K times — and K-1 of those edits are typically missed. A factory
+collapses that to 1 place: the invariant is enforced once, and every call site that changes still
+compiles because they pass arguments to a function, not fields to a literal.
+
+## Anti-patterns
+
+- ❌ A factory with a config object with 12 optional fields, most unused by every caller. That is
+  the object's own complexity leaking into the factory's signature — fix the object first.
+- ❌ A factory that also performs I/O (saves to the DB, calls an API) as a side effect of
+  "constructing." Construction builds a value; persistence is a separate step the caller invokes.
+- ❌ A factory function per call site (`createUserForSignup`, `createUserForAdmin`) that each
+  duplicate 90% of the same logic. That is the smell this pattern exists to remove, reintroduced
+  one layer down — collapse them into one factory with a parameter for the 10% that differs.
+- ❌ Naming it `UserFactory.getInstance()` to imitate a singleton when nothing requires only one
+  instance to exist. A plain exported function is the smaller design (KISS).

package/content/patterns/null-object.md

@@ -0,0 +1,55 @@
+---
+type: pattern
+description: Replaces a null guard repeated at 3 or more call sites with a default implementation that behaves like the absent case's known, safe outcome.
+load: cold
+smell: 'the same `if (x == null) { ...default behavior... }` guard, followed by using `x`, is repeated at 3 or more call sites'
+when_to_use: the absent case has one well-known default behavior and every caller currently branches on null to reach it
+when_not_to_use: callers must react differently to absence, or must distinguish absent from present-but-default
+---
+
+# Pattern — Null Object
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+A narrower cousin of Strategy in this same library: instead of one implementation per real case,
+it adds exactly one extra implementation standing in for "nothing here" — so the caller's `switch`
+or `if (x == null)` collapses to zero branches, not one fewer.
+
+## Decision
+
+- ✅ 3+ call sites do `if (x == null) return fallbackValue` (or an equivalent guard) right before
+  using `x`, and `fallbackValue` is the same at every one → give the absent case a real
+  implementation of the same interface (an empty cart, a no-op logger, a zero-total invoice) and
+  stop returning `null` in the first place.
+- ✅ The type already has a real interface with 1+ methods (a `Logger`, a `Cart`) → the Null Object
+  implements that interface with safe, inert behavior (`NullLogger.log()` does nothing).
+- ❌ Fewer than 3 call sites guard the same way, or two callers want a *different* fallback → a
+  shared Null Object would force one fallback where callers legitimately need their own; keep the
+  guards local, or pass the fallback in per caller instead.
+- ❌ The caller must tell "absent" apart from "present with the default value" (e.g. a form field
+  the user explicitly cleared vs. one never touched) → collapsing both into one Null Object erases
+  that distinction; `Result`/`Option` is the honest fit — see `result-vs-exception.md`.
+
+## Why this works
+
+Every `if (x == null)` guard is a branch a reader and the compiler must both track; N call sites
+with the same guard is N places that branch identically and N places a future change to the
+fallback must be kept in sync. A Null Object moves the branch inside the 1 place that decides
+"use the real thing or the null thing" (usually the factory or lookup that produces `x`), so the
+N call sites go back to unconditional code — 1 branch total instead of N.
+
+## Anti-patterns
+
+- ❌ A Null Object that throws when any of its methods is called. That is not a null object, it is
+  a differently-shaped exception — it defeats the purpose, which is *safe* default behavior.
+- ❌ Using Null Object where the caller actually needs to know absence happened (an audit log that
+  must record "no discount was found," not silently apply a $0 discount and look identical to a
+  real $0 discount). Prefer an explicit `Option`/`Result` there instead.
+- ❌ A Null Object with mutable shared state (`NullCart` that collects items across unrelated
+  calls). The point of the pattern is a stateless, inert stand-in — shared mutable state turns it
+  into a hidden singleton bug.
+- ❌ Silently swapping `null` for a Null Object across a serialization boundary (DB, API response).
+  Null Object is an in-process convenience; a stored `null` still means "absent" to every reader
+  outside this process, so translate at that boundary instead of upstream.

package/content/patterns/result-vs-exception.md

@@ -0,0 +1,52 @@
+---
+type: pattern
+description: Replaces a thrown exception for an expected, listable failure with a typed Result value the immediate caller must handle.
+load: cold
+smell: 'a function throws for an outcome the caller already anticipates and branches on (validation failure, not-found, conflict), and the caller wraps the call in try/catch to recover that one branch'
+when_to_use: the failure modes are known, finite, and the immediate caller needs to react differently to each one
+when_not_to_use: the failure is unexpected or unrecoverable — a network drop, a timeout, a bug
+---
+
+# Pattern — Result / Either over exception-as-control-flow
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+`rubrics/error-classification.md` already prescribes the shape (`Result<T, E>` with a literal
+`as const` code) for the Domain layer specifically. This pattern generalizes the same call: apply
+it to *any* function, domain or not, where a `try { } catch { }` exists only to recover one
+specific, anticipated branch — not to handle a genuine surprise.
+
+## Decision
+
+- ✅ The function has 2 or more named, expected outcomes (`EMAIL_TAKEN`, `NOT_FOUND`,
+  `WEAK_PASSWORD`) → return `Result<T, E>` with `E` a literal union, and force the caller to
+  `switch` with an exhaustive `never` default (see `error-classification.md`).
+- ✅ Today's code throws a custom error class only to `catch (e) { if (e instanceof X) }` one line
+  above the call → that `catch` is the tell; replace both sides with `Result`.
+- ❌ The failure is a bug, a timeout, or anything the immediate caller cannot meaningfully act on
+  → let it rise. Wrapping every infra call in `Result` just relocates the `try/catch`, it does not
+  remove it — see `error-classification.md`'s Infra-error row.
+- ❌ The function is called in exactly one place and that place already has a correct
+  `try/catch` → converting it buys nothing; the try/catch already IS the handling.
+
+## Why this works
+
+An exception's type is invisible at the call site — nothing in a function's signature says it can
+throw, so the caller either wraps every call defensively or misses a case entirely. A `Result<T,
+E>` return type puts the failure in the signature: TypeScript's exhaustiveness check on the
+`switch` (the `never` default) then makes an unhandled case a compile error instead of a runtime
+surprise, at zero added `try/catch` blocks.
+
+## Anti-patterns
+
+- ❌ Wrapping infra failures (DB down, network drop) in `Result` "for consistency." Those are not
+  anticipated outcomes — see `error-classification.md`: infra errors rise and get caught once at
+  the process boundary, they do not become a case in every caller's switch.
+- ❌ A `Result<T, string>` with a free-text message instead of a literal code. The caller cannot
+  `switch` on a string; the whole benefit (exhaustiveness) is gone. The code must be `as const`.
+- ❌ Mixing `Result` and exceptions in the same function — return `Result` for the expected branch,
+  then also `throw` for another branch of the same function. Callers must handle two mechanisms.
+- ❌ A generic `try/catch` around a `Result`-returning call "just in case." If the function no
+  longer throws for its expected failures, the surrounding `try` should not exist either.

package/content/patterns/strategy.md

@@ -0,0 +1,45 @@
+---
+type: pattern
+description: Replaces a branching conditional keyed on a kind, type, or provider field with one interface and one implementation per case, selected through a registry.
+load: cold
+smell: 'a `switch` or `if`/`else if` chain keyed on a kind, type, or provider field, duplicated across 2+ files or functions'
+when_to_use: a new case of the same kind arrives on a predictable cadence and every case can share one call shape
+when_not_to_use: only one implementation exists today, or the cases would return incompatible shapes
+---
+
+# Pattern — Strategy
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Continues the OCP trigger in `rubrics/solid-triggers.md`: that rubric tells you a `switch` on a
+provider is a problem the moment a 2nd `switch` on the same field appears elsewhere. Strategy is
+the concrete extraction once that trigger fires.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| A `switch(kind)` selects behavior, and a second `switch(kind)` on the same field lives in another function or file | Apply Strategy: one file per case implementing a shared interface, wired through a lookup table | Adding a 4th `case` to both switches and hoping they stay in sync |
+| Every case already returns the same shape (LSP, see `solid-triggers.md`) | Safe to extract now — the interface is exactly that shared shape | Extracting before the shapes agree — the interface degrades to `any` or a union of incompatibles |
+| Only one case exists and no second is concretely planned | Do not extract. A single `if` is not a smell | A `StrategyRegistry` with one entry — OCP paid for a case that never happened |
+| The active case is fixed for the process lifetime (an env-driven backend chosen once at boot) | Plain dependency injection of the one active implementation | A registry of N strategies when exactly 1 is ever selected at runtime |
+
+## Why this works
+
+A `switch` on a variant duplicates its list of cases every time the branch is copy-pasted into a
+new function: N call sites × M cases means up to N×M places that drift when case M+1 arrives.
+Strategy collapses that to N call sites each holding one lookup, plus M single-purpose files —
+adding case M+1 then touches exactly 1 new file and 1 registry line, never the N call sites.
+
+## Anti-patterns
+
+- ❌ A `StrategyRegistry` holding one entry "for when we add the second provider." Inline the one
+  implementation. Extract on the second real case, not the imagined one.
+- ❌ Interfaces that leak the framework in the port (`RegistryAdapter.publish(ctx: TRPCContext)`).
+  The port must be as narrow as ISP allows — see `solid-triggers.md` § ISP.
+- ❌ A registry keyed by a raw `string` instead of the closed literal union of kinds. A typo in the
+  key then fails at runtime instead of at compile time.
+- ❌ Keeping the old `switch` alongside the new registry "just in case." Delete it in the same
+  change — two selection mechanisms for the same kind is worse than the one you started with.

package/content/patterns/template-method-vs-composition.md

@@ -0,0 +1,50 @@
+---
+type: pattern
+description: Chooses between an inherited algorithm skeleton with overridable steps and a plain function that takes the varying step as a parameter.
+load: cold
+smell: 'two or more functions or classes repeat the same ordered sequence of steps, differing only in 1-2 of those steps'
+when_to_use: the skeleton has 3+ fixed steps and only 1-2 vary across callers
+when_not_to_use: the varying step is the only step, or fewer than 3 callers share the skeleton
+---
+
+# Pattern — Template Method vs. composition
+
+> Suggestion only. This pattern does not become project convention by existing here — it
+> materializes into `code-style/`, `ach.md`, or an ADR only when the operator accepts it for
+> this codebase.
+
+Shares the Rule-of-Three threshold from `rubrics/when-to-create-lib.md`, applied to a *sequence*
+of steps instead of a single helper — and it decides between two ways to remove the duplication,
+not just whether to remove it.
+
+## Decision
+
+| Situation | Verdict | Anti-pattern |
+| --- | --- | --- |
+| 3+ callers share an ordered skeleton (validate → transform → persist → notify), 1-2 steps vary, and the language has first-class functions | Composition: one function takes the varying step(s) as parameters/callbacks | Copy-pasting the whole skeleton per caller so the 1 varying line can differ |
+| Same skeleton, but the varying steps need to read or mutate protected state shared across steps (a running total, an accumulator built up across the sequence) | Template Method: a base class fixes the sequence, subclasses override only the varying steps | Threading that shared state through 4 separate callback parameters to fake what inheritance gives for free |
+| Only 1-2 callers share the skeleton today | Do not extract either way — inline duplication for 2 callers costs less than an abstraction (Rule of Three, `when-to-create-lib.md`) | A base class with exactly one subclass, built ahead of the 2nd real caller |
+| The "skeleton" is actually just the 1 step that varies, wrapped in ceremony | There is no skeleton to extract — this is a Strategy situation instead, see `strategy.md` | Template Method with a base class whose every method is abstract — nothing is actually shared |
+
+## Why this works
+
+A skeleton with S total steps where V of them vary means V×N points of difference across N
+callers when duplicated in full. Extracting the skeleton — either way — reduces that to N call
+sites providing only the V varying steps, plus 1 shared definition of the S−V fixed ones.
+Composition and Template Method both hit that number; the choice between them is only about
+where the shared state between steps needs to live — a closure (composition) or `this`
+(inheritance).
+
+## Anti-patterns
+
+- ❌ Reaching for inheritance by default. Composition is the smaller design (KISS) whenever no
+  step needs shared mutable state across the sequence — prefer it, and use Template Method only
+  when composition would require threading that state through every callback.
+- ❌ A Template Method base class with a step marked `abstract` that every subclass overrides
+  identically. That step isn't varying — fold it back into the fixed skeleton.
+- ❌ Composition where the "varying step" callback secretly depends on 3+ pieces of the caller's
+  outer scope. At that point the callback IS the logic and the shared skeleton is the smaller
+  part — question whether extracting the skeleton was the right cut at all.
+- ❌ Extracting the skeleton before the 3rd caller exists. Two callers sharing steps can be
+  coincidence, not a real pattern — the same Rule-of-Three reasoning `when-to-create-lib.md` uses
+  for helpers applies here.

package/content/questions/adr.questions.yaml

@@ -0,0 +1,14 @@
+questions:
+  - id: status
+    prompt: What is the status of this decision?
+    header: Status
+    recommended: Accepted
+    options:
+      - label: Proposed
+        description: Written down, not yet in force. Pass it as --status proposed.
+      - label: Accepted
+        description: In force today. Pass it as --status accepted.
+      - label: Superseded by ADR-NNNN
+        description: A later decision replaced it; write the new ADR with --supersedes N.
+      - label: Deprecated
+        description: No longer in force and nothing replaced it. Pass it as --status deprecated.

package/content/questions/analyze.questions.yaml

@@ -0,0 +1,12 @@
+questions:
+  - id: remediation
+    prompt: Do you want concrete edits for the top findings?
+    header: Remediation
+    recommended: top-5
+    options:
+      - label: top-5
+        description: Apply the edits for the top 5 findings in severity order, then report what changed and where.
+      - label: top-10
+        description: Same as top-5, for the top 10 findings.
+      - label: report-only
+        description: The report is enough. Nothing is edited and the findings are addressed manually.

package/content/questions/bootstrap-mapping.questions.yaml

@@ -0,0 +1,14 @@
+questions:
+  - id: mapping
+    prompt: Does the component-type to stack mapping drafted for the architecture doc make sense?
+    header: Mapping
+    recommended: All match
+    options:
+      - label: All match
+        description: Materializes the mapping as drafted.
+      - label: Adjust
+        description: One or two entries change; the operator points them out.
+      - label: Some do not apply
+        description: The operator lists the component types the project does not have.
+      - label: Rewrite
+        description: The operator dictates the mapping again.

package/content/questions/bootstrap-rules.questions.yaml

@@ -0,0 +1,10 @@
+questions:
+  - id: rules
+    prompt: Does any inherited hard rule not fit this project? Inalienable rules are never offered.
+    header: Rules
+    recommended: Keep all
+    options:
+      - label: Keep all
+        description: Every opt-out-able rule stays in force.
+      - label: Opt out of some
+        description: The operator names each rule and why; each becomes N/A with that reason.

package/content/questions/bootstrap-stack.questions.yaml

@@ -0,0 +1,23 @@
+questions:
+  - id: stack
+    prompt: Is the stack that afm init reported, layer by layer with its evidence, right?
+    header: Stack
+    recommended: Confirm
+    options:
+      - label: Confirm
+        description: Records every reported layer as decided.
+      - label: Adjust
+        description: Some layers are wrong or missing; the operator names them and the answer is recorded as given.
+      - label: Leave as TBD
+        description: Records [TBD] for the layers; a recommendation works better once the operator also knows what they do not want.
+  - id: modules
+    prompt: Apply every opt-in module detected for the stack? A module is applied whole, so the default is to opt out only what does not fit.
+    header: Modules
+    recommended: All
+    options:
+      - label: All
+        description: Merges each detected module's architecture and rule patches.
+      - label: Some
+        description: Applies all but the modules the operator names; those simply stay out.
+      - label: None
+        description: No module is applied.

package/content/questions/clarify.questions.yaml

@@ -0,0 +1,10 @@
+questions:
+  - id: underspecified
+    prompt: Most categories are Missing and many markers are open. How should clarify proceed?
+    header: Thin spec
+    recommended: respecify
+    options:
+      - label: respecify
+        description: Re-run specify with new input. A spec this thin needs rewriting, not a long question loop.
+      - label: continue
+        description: Keep clarifying anyway, within the limit of 5 questions for this session.

package/content/questions/code-style.questions.yaml

@@ -0,0 +1,12 @@
+questions:
+  - id: code-style
+    prompt: The listed code-style files are house conventions one project observed, not facts of the stack. Apply any? An unmarked item is written nowhere.
+    header: Code style
+    recommended: None
+    options:
+      - label: None
+        description: Nothing applies. The default, because a silent opt-in is the defect this question corrects.
+      - label: Some
+        description: The operator names the files; each is copied verbatim as the project's rule.
+      - label: All
+        description: Every listed file is copied verbatim as the project's rule.

package/content/questions/confirm.questions.yaml

@@ -0,0 +1,12 @@
+questions:
+  - id: restated
+    prompt: Is the restatement above correct?
+    header: Confirmation
+    recommended: Yes, exact
+    options:
+      - label: Yes, exact
+        description: Materializes it as restated.
+      - label: Almost
+        description: A small adjustment; the operator describes the fix.
+      - label: No, rewrite
+        description: The operator dictates it again.

package/content/questions/deliver.questions.yaml

@@ -0,0 +1,23 @@
+questions:
+  - id: outcome
+    prompt: The plan is drafted and verified. What should the delivery do now?
+    header: Outcome
+    recommended: run-to-completion
+    options:
+      - label: run-to-completion
+        description: Approve the plan and execute every task, stopping only at a halt or the push boundary.
+      - label: pause-per-phase
+        description: Approve the plan, execute it, and stop after each phase to ask whether to continue.
+      - label: materialize-only
+        description: Keep the drafted spec, plan and tasks on disk and execute nothing.
+      - label: adjust-or-cancel
+        description: Record no approval. Say what to change in the drafts, or stop here.
+  - id: phase-continue
+    prompt: The phase is done. Continue to the next phase?
+    header: Next phase
+    recommended: continue
+    options:
+      - label: continue
+        description: Run the next phase.
+      - label: stop
+        description: Stop here; re-running deliver resumes at the first open task.

package/content/questions/evolve.questions.yaml

@@ -0,0 +1,15 @@
+# One question per (b) item of the evolve package. Run it once per item:
+#   afm ask evolve --scope <item-slug> --recommend <label>
+# The item's evidence, its recommendation and "what changes if this is wrong" sit in the package the
+# agent shows before asking; the answer applies to that one item only.
+questions:
+  - id: apply
+    prompt: Apply this proposed change to the docs?
+    header: Apply
+    options:
+      - label: Apply
+        description: Apply the change after the gate, exactly as itemized in the package.
+      - label: Skip
+        description: Reject it; the report records the rejection as attempt memory, so it is not proposed again without new evidence.
+      - label: Stage
+        description: Defer it to the next cycle; the report records it as staged.

package/content/questions/export-template-apply.questions.yaml

@@ -0,0 +1,11 @@
+questions:
+  - id: apply
+    prompt: Delete the listed files and write the template marker?
+    header: Apply
+    options:
+      - label: Apply
+        description: Runs the same command with --yes. The deletion is not reversible outside git.
+      - label: Adjust
+        description: Go back to the keep question and review the plan again.
+      - label: Cancel
+        description: Nothing is touched.

package/content/questions/export-template.questions.yaml

@@ -0,0 +1,23 @@
+questions:
+  - id: keep
+    prompt: Which of the artifacts a template normally drops should STAY? Leave empty to keep none.
+    header: Keep
+    multiSelect: true
+    options:
+      - label: prd
+        description: prd.md is product-specific; a template usually drops it.
+      - label: ust
+        description: ust.md holds the product's stories; a template usually drops it.
+      - label: features
+        description: docs/features/ is product work; its tasks are first induced into a reusable shape.
+      - label: afm-version
+        description: A template is not an instance, so the version pin is dropped unless kept.
+  - id: research
+    prompt: What happens to docs/research/, which may hold reusable technical research?
+    header: Research
+    recommended: Keep
+    options:
+      - label: Keep
+        description: The research stays in the template.
+      - label: Delete
+        description: The research goes with the product content.

package/content/questions/gates.questions.yaml

@@ -0,0 +1,27 @@
+questions:
+  - id: dod
+    prompt: Which checks must pass to merge? Pre-check the ones the scan reported as gating merge.
+    header: Merge DoD
+    multiSelect: true
+    options:
+      - label: Test runner
+        description: The project's tests.
+      - label: Type check
+        description: The type checker with no emit.
+      - label: Lint
+        description: The linter or formatter check.
+      - label: Build
+        description: A production build.
+  - id: pre-push
+    prompt: Which checks run before a push? Pre-check the ones the scan reported in a pre-push hook.
+    header: Pre-push
+    multiSelect: true
+    options:
+      - label: Test runner
+        description: The project's tests.
+      - label: Type check
+        description: The type checker with no emit.
+      - label: Lint
+        description: The linter or formatter check.
+      - label: Build
+        description: A production build.

package/content/questions/generalize.questions.yaml

@@ -0,0 +1,13 @@
+# One question per merge of gotchas into an abstract rule:
+#   afm ask generalize --scope <rule-slug>
+questions:
+  - id: merge
+    prompt: Merge the batch of gotchas into the proposed rule and archive the members with tombstones?
+    header: Merge
+    options:
+      - label: Merge as a rule
+        description: Write a hard rule in afm.md section 3 with its 0/1 trigger, then archive the merged gotchas with tombstones.
+      - label: Merge as a principle
+        description: Write the abstraction in afm.md section 1.3 (guidance only, no executable trigger), then archive the merged gotchas with tombstones.
+      - label: Keep separate
+        description: The abstraction loses too much; keep the gotchas as they are and report "not generalizable without loss".

package/content/questions/gotcha.questions.yaml

@@ -0,0 +1,11 @@
+questions:
+  - id: basis
+    prompt: Does this behavior qualify for registration?
+    header: Qualify
+    options:
+      - label: bitten-twice
+        description: Confirmed to have bitten a developer at least twice.
+      - label: documented-sdk
+        description: Documented behavior of a known external SDK or runtime that surprises its users.
+      - label: neither
+        description: No second incidence and no external documentation; nothing is registered.

package/content/questions/init-template.questions.yaml

@@ -0,0 +1,10 @@
+questions:
+  - id: branch
+    prompt: This project comes from an architectural template (docs/.template). How should the interview run?
+    header: Interview
+    recommended: Product only
+    options:
+      - label: Product only
+        description: Runs only product, flows, a short validation step and gotchas. Stack, data model, mapping and rules are inherited.
+      - label: Full interview
+        description: Ignores the marker for this session and runs all seven steps. The marker stays on disk.