pi-aia-asf 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-08-14
+
+### Added
+
+- **Mandatory modularity & maintainability standard** (`references/06c-code-quality.md`) — 8 rules distilled from Bruno's Tunnel-project philosophy (small well-readable modules plugged in where needed; one authoritative implementation for shared functionality with a single escalation path; no hardcoding — config-driven; fully testable outside the host then integrated verbatim, same modules in tests and production; refactor what is too complex to understand; layered with clear one-way boundaries and an architecture writeup; full I/O debug logging with replay of stored data; nothing may break existing functionality) and reinforced by external research (SSOT, testability as design property, ports-and-adapters seams).
+
+### Changed
+
+- **Phase 6** now requires reading `06c-code-quality.md` before structuring code; **Phase 7** verification includes the modularity DoD (no duplicated shared logic, no hardcoded config values, standalone-tested modules, architecture writeup, existing functionality green).
+- **Phase 4** adversarial analysis gains a code-quality lens (duplication, single escalation path, standalone testability, hardcoded values); **Phase 5** PLAN.md architecture section now requires the SSOT map, layering rules, and standalone-testability notes.
+- Anti-patterns extended: god-objects, copy-pasted shared logic, test copies of modules, hardcoding, per-caller escalation logic, untestable-standalone modules, behavior-breaking refactors.
+
+
+## [0.2.1] - 2026-08-14
+
+### Added
+
+- **Scale-based flow.** Every ASF activation is now classified **small** or **large**:
+  - **Small** (small features, minor bugfixes, small refactors) — runs **automatically**: no intake question barrage (at most one clarifying question), no research, no adversarial gate, no PLAN.md, no approval. State the intent, capture specs silently, implement test-first, verify, deliver.
+  - **Large** (new projects, significant features, major bugfixes, architectural refactors) — full gated flow unchanged: intake → research → specs → adversarial → PLAN.md → **explicit approval** → implementation → verification.
+  - When in doubt, **default to small and start working**; re-classify upward if the work grows.
+- **`/asf small`** command — starts a small session directly in implementation phase. `/asf status` now shows the scale (`automatic — no gates` for small).
+
+### Changed
+
+- All gates (1–5) explicitly apply to large work only; Phase 2 (research) and Phase 5 (PLAN.md + approval) are skipped entirely for small work.
+- References `01-intake`, `04-adversarial`, `05-plan` annotated with the scale rule.
+- Anti-patterns: no question barrage or PLAN.md/approval demand for small work; when in doubt, start small.
+
+
 ## [0.2.0] - 2026-08-14
 
 ### Added

package/index.ts

@@ -30,8 +30,11 @@ type AsfPhase =
   | "implementation"
   | "verification";
 
+type AsfScale = "small" | "large";
+
 interface AsfState {
   workType?: "new-project" | "feature" | "major-bugfix" | "refactor";
+  scale?: AsfScale;
   phase: AsfPhase;
   planApproved?: boolean;
   startedAt?: string;
@@ -160,7 +163,7 @@ export default function register(pi: ExtensionAPI): void {
   // Startup check: warn once per session if deps are missing (unless disabled)
   // The extension loads at startup; log to console so it surfaces in logs.
 
-  const setPhase = async (ctx: ExtensionCommandContext, phase: AsfPhase, workType?: AsfState["workType"]): Promise<string> => {
+  const setPhase = async (ctx: ExtensionCommandContext, phase: AsfPhase, workType?: AsfState["workType"], scale?: AsfScale): Promise<string> => {
     const project = projectName();
     const state = await loadState(project);
     const now = new Date().toISOString();
@@ -183,6 +186,7 @@ export default function register(pi: ExtensionAPI): void {
         };
       }
       if (workType) state.current.workType = workType;
+      if (scale) state.current.scale = scale;
       state.current.phase = phase;
       state.current.updatedAt = now;
     }
@@ -196,13 +200,15 @@ export default function register(pi: ExtensionAPI): void {
 
     switch (sub) {
       case "new":
-        return await setPhase(ctx, "intake", "new-project");
+        return await setPhase(ctx, "intake", "new-project", "large");
       case "feature":
-        return await setPhase(ctx, "intake", "feature");
+        return await setPhase(ctx, "intake", "feature", "large");
       case "bugfix":
-        return await setPhase(ctx, "intake", "major-bugfix");
+        return await setPhase(ctx, "intake", "major-bugfix", "large");
       case "refactor":
-        return await setPhase(ctx, "intake", "refactor");
+        return await setPhase(ctx, "intake", "refactor", "large");
+      case "small":
+        return await setPhase(ctx, "implementation", undefined, "small");
       case "status": {
         const project = projectName();
         const state = await loadState(project);
@@ -210,6 +216,7 @@ export default function register(pi: ExtensionAPI): void {
         return (
           `ASF status (${project}):\n` +
           `  work type: ${state.current.workType || "unset"}\n` +
+          `  scale: ${state.current.scale || "unset"}${state.current.scale === "small" ? " (automatic — no gates)" : ""}\n` +
           `  phase: ${state.current.phase}\n` +
           `  plan approved: ${state.current.planApproved ? "yes" : "no"}\n` +
           `  started: ${state.current.startedAt || "?"}\n` +
@@ -236,10 +243,11 @@ export default function register(pi: ExtensionAPI): void {
       default:
         return (
           "ASF commands:\n" +
-          "  /asf new        — start a new software project\n" +
-          "  /asf feature    — add a feature to an existing project\n" +
-          "  /asf bugfix     — major bugfix\n" +
-          "  /asf refactor   — architectural refactor\n" +
+          "  /asf new        — start a new software project (large, gated)\n" +
+          "  /asf feature    — add a feature to an existing project (large, gated)\n" +
+          "  /asf bugfix     — major bugfix (large, gated)\n" +
+          "  /asf refactor   — architectural refactor (large, gated)\n" +
+          "  /asf small      — small change, automatic (no gates)\n" +
           "  /asf status     — show current phase\n" +
           "  /asf verify     — run the definition-of-done QA gate\n" +
           "  /asf abort      — end the current session\n\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",

package/skills/aia-asf/SKILL.md

@@ -4,15 +4,17 @@ description: >-
   Agentic Software Factory — run a complete, disciplined software development
   cycle. Use when the user wants to start a NEW software project, add a
   SIGNIFICANT FEATURE to an existing project, perform a MAJOR BUGFIX, or do an
-  ARCHITECTURAL REFACTOR. The flow classifies the work, asks questions until the
-  intent is clear, researches SOTA and existing packages, captures hard
-  specifications (via capture_spec, shared with pi-vigilant), runs adversarial
-  analysis, produces a PLAN.md and gets explicit user approval, then implements
-  test-first with strict codebase isolation and mandatory browser testing of any
-  web interfaces (pi-aia-browser). Do NOT activate for simple Q&A, one-line
-  fixes, casual conversation, content writing, or non-software tasks. When in
-  doubt about whether work qualifies as a project/feature/bugfix/refactor, ask
-  the user.
+  ARCHITECTURAL REFACTOR — and also for SMALL software changes (small features,
+  minor bugfixes, small refactors), which run AUTOMATICALLY with no intake
+  questions, no PLAN.md, and no approval. LARGE work (new projects, significant
+  features, major bugfixes, architectural refactors) runs the full gated flow:
+  classify, ask until intent is clear, research SOTA and packages, capture hard
+  specifications (via capture_spec, shared with pi-vigilant), run adversarial
+  analysis, produce a PLAN.md and get explicit user approval, then implement
+  test-first with strict codebase isolation and mandatory browser testing of web
+  interfaces (pi-aia-browser). Do NOT activate for simple Q&A, one-line fixes,
+  casual conversation, content writing, or non-software tasks. When in doubt,
+  ask the user.
 ---
 
 # AIA Agentic Software Factory (ASF)
@@ -28,24 +30,35 @@ You are running the **Ai Applied Agentic Software Factory**. This skill codifies
 
 ## Phase 0 — Classify the work (gate)
 
-Determine the work type. If it is not ASF work, **do not run the factory** — just help normally.
+Determine the work type **and scale**. If it is not ASF work, **do not run the factory** — just help normally.
 
-| Work type | ASF? |
-|---|---|
-| New software project | ✅ yes — full flow |
-| Significant feature in an existing project | ✅ yes — full flow (research: medium depth) |
-| Major bugfix (multi-file, behavior change, needs tests) | ✅ yes — lighter flow (research optional) |
-| Architectural refactor | ✅ yes — full flow (research: low depth) |
-| Simple Q&A, one-liner fix, casual talk, docs-only | ❌ no |
-| Non-software tasks (LinkedIn, research-only, writing) | ❌ no |
+| Work type | ASF? | Scale | Flow |
+|---|---|---|---|
+| New software project | ✅ | **large** | full flow |
+| Significant feature | ✅ | **large** | full flow (research: medium) |
+| Small feature | ✅ | **small** | automatic |
+| Major bugfix (multi-file, behavior change, needs tests) | ✅ | **large** | lighter flow (research optional) |
+| Minor bugfix (one area, no contract change) | ✅ | **small** | automatic |
+| Architectural refactor | ✅ | **large** | full flow (research: low) |
+| Small refactor (renames, restructure of one module) | ✅ | **small** | automatic |
+| Simple Q&A, one-liner fix, casual talk, docs-only | ❌ | — | — |
+| Non-software tasks (LinkedIn, research-only, writing) | ❌ | — | — |
+
+**Scale rule — the core behavior difference:**
+
+- **Large work** runs the full gated flow: intake questions → research → specs → adversarial → PLAN.md → **explicit approval** → implementation → verification.
+- **Small work runs automatically**: no intake question barrage (at most ONE clarifying question, only if truly ambiguous), no research, no PLAN.md, no approval gate. State the intent in one or two sentences, capture specs, implement test-first, verify, deliver. Do not ask permission to start; do not stop for sign-off. If it turns out to be larger than expected mid-way, re-classify, say so, and switch to the full flow with approval.
+- When in doubt about scale, **default to small and start working** — the user prefers action over questions. Re-classify upward if the work grows.
 
 If the user's request is ambiguous, **ask** before starting. State the classification explicitly:
-`ASF: <new-project|feature|major-bugfix|refactor> — starting Phase 1 (intake).`
+`ASF: <new-project|feature|major-bugfix|refactor> <large|small> — starting Phase 1 (intake).`
 
 ---
 
 ## Phase 1 — Intake: ask until it's clear (gate)
 
+> **Scale check — applies to LARGE work only.** For **small** work: skip the question bank. If the request is clear enough to act, state your understanding in one or two sentences and proceed immediately. Ask at most ONE clarifying question, and only when genuinely ambiguous.
+
 The factory **keeps asking until all is clear**. Never start planning or implementation on guesses.
 
 Minimum intake checklist (ask anything not yet known, one question at a time or a short batch):
@@ -60,12 +73,14 @@ Minimum intake checklist (ask anything not yet known, one question at a time or
 
 For each answer, **capture hard requirements immediately with `capture_spec`** (requirement, area, priority). Specs are the shared contract with pi-vigilant — it will re-verify them at the end.
 
-**Gate 1**: You may only leave intake when the user has confirmed the summary of intent (restate it back in 3–5 bullet points and ask "is this correct?").
+**Gate 1** (large only): You may only leave intake when the user has confirmed the summary of intent (restate it back in 3–5 bullet points and ask "is this correct?"). Small work does not pass through this gate.
 
 ---
 
 ## Phase 2 — Research: SOTA and packages (adaptive depth)
 
+> **Small work skips research entirely.** If implementation needs a library you don't know, a single quick search is enough — no research summary, no Gate 2.
+
 | Work type | Research depth |
 |---|---|
 | New project | **Mandatory, full** — SOTA approaches, frameworks, existing packages, reference implementations |
@@ -80,7 +95,7 @@ Research method (use `web_search` + `web_fetch`/`batch_web_fetch`):
 4. **Cite sources** in the research summary — every claim about a package/library gets a URL
 5. Summarize findings + a **recommendation** (which approach, which packages, with rationale)
 
-**Gate 2**: present the research summary + recommendation to the user. Ask: "proceed with this approach, or adjust?" Do not enter planning until the approach is agreed.
+**Gate 2** (large only): present the research summary + recommendation to the user. Ask: "proceed with this approach, or adjust?" Do not enter planning until the approach is agreed.
 
 ---
 
@@ -94,12 +109,14 @@ Turn the intake answers + research into the authoritative spec set.
 4. Default priority is `must`; use `should` only when the user says "nice to have".
 5. Areas: functionality, ui-ux, performance, security, error-handling, testing, documentation, compatibility, constraints, format, data, deployment, other.
 
-**Gate 3**: show the full spec tree (`get_task_specs`) and get user sign-off: "specs correct — proceed to adversarial analysis?"
+**Gate 3** (large only): show the full spec tree (`get_task_specs`) and get user sign-off: "specs correct — proceed to adversarial analysis?" Small work: capture specs silently, no sign-off needed.
 
 ---
 
 ## Phase 4 — Adversarial analysis (gate)
 
+> **Small work:** skip the formal gate. Do a quick mental pass over edge cases and failure modes while implementing; if something real surfaces, fix it or capture a spec. No user checkpoint.
+
 Challenge the plan like a hostile reviewer before committing to it. For each spec and the overall design, ask and resolve:
 
 - **Edge cases** — empty input, zero users, max load, missing data, concurrency
@@ -112,12 +129,14 @@ Challenge the plan like a hostile reviewer before committing to it. For each spe
 
 For each finding: either capture a new spec, refine an existing one (supersede), or record the decision to accept the risk. **Ask the user about anything that changes scope.**
 
-**Gate 4**: summarize adversarial findings + resolutions, get user confirmation.
+**Gate 4** (large only): summarize adversarial findings + resolutions, get user confirmation.
 
 ---
 
 ## Phase 5 — Plan + approval gate
 
+> **Small work: SKIP this phase entirely.** No PLAN.md, no approval — go straight to Phase 6 (implementation).
+
 Write `PLAN.md` in the project root (repo root, or cwd if no repo). Structure:
 
 ```markdown
@@ -136,10 +155,10 @@ Write `PLAN.md` in the project root (repo root, or cwd if no repo). Structure:
 
 Keep the plan **implementation-ready**: any competent engineer (or agent) can execute the task list without re-deriving decisions.
 
-**Gate 5 — MANDATORY user approval**: present the plan and ask explicitly:
+**Gate 5 — MANDATORY user approval (large only)**: present the plan and ask explicitly:
 > "Plan ready. Do you approve starting implementation? (yes / changes needed)"
 
-**Never start implementing before Gate 5 passes.** If the user says "go" without reading, still show the plan and confirm.
+**Never start implementing before Gate 5 passes — for LARGE work.** If the user says "go" without reading, still show the plan and confirm. Small work never reaches this gate.
 
 ---
 
@@ -153,6 +172,14 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > **read the actual error before editing**; **verify clean-room** (caches serve stale
 > builds); **add a regression test for every bug fixed**.
 
+> **Read `references/06c-code-quality.md` before structuring code.** It is the mandatory
+> modularity & maintainability standard: small well-readable modules plugged in where
+> needed; **one implementation for shared functionality** (single escalation path,
+> SSOT); no hardcoding (config-driven); **testable outside the host then integrated
+> verbatim** (same modules in tests and production); refactor what is too complex to
+> understand; layered with clear boundaries and an architecture writeup; full I/O debug
+> logging with replay; nothing breaks existing functionality.
+
 Execute the task list milestone by milestone. Discipline rules:
 
 1. **Test-first**: write/update tests before or with implementation; run them; only commit green.
@@ -171,6 +198,8 @@ Execute the task list milestone by milestone. Discipline rules:
 
 Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule 10). Every box must hold.
 
+Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7 section): no duplicated shared logic, no hardcoded config values, every module tested standalone with the same calls it gets in the host, architecture writeup exists, existing functionality still green.
+
 1. Run the full test suite (all of it, not a subset); fix failures; re-run until green.
 2. **Verify the artifact a user would actually get**: inspect the packaged file list
    (`npm pack` → `tar tzf`), install/load it clean-room in a fresh dir with caches
@@ -201,6 +230,17 @@ Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule
 - ❌ Guessing at a fix before reading the actual error message
 - ❌ Fixing a bug without adding a regression test
 - ❌ Claiming something was verified when it was assumed
+- ❌ Asking a barrage of intake questions for small work — small runs automatically
+- ❌ Writing PLAN.md / demanding approval for small work — that's the large-work gate only
+- ❌ Waiting for sign-off when the work is small; when in doubt, default to small and start
+- ❌ One giant file / god-object that "does everything" — small well-readable modules, plugged in
+- ❌ Copy-pasting shared logic instead of importing the one authoritative module (SSOT)
+- ❌ A "test copy" of a module that differs from the production version — same modules everywhere
+- ❌ Hardcoding values (model names, thresholds, URLs) that config should drive
+- ❌ Escalation/fallback logic re-implemented per caller instead of one shared escalation path
+- ❌ Shipping a module that cannot run/test standalone outside the host
+- ❌ Refactoring without the architecture writeup (see `references/06c-code-quality.md`)
+- ❌ Breaking existing functionality during a refactor — refactoring preserves behavior
 
 ## References
 
@@ -210,4 +250,5 @@ Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule
 - `references/05-plan.md` — PLAN.md template with examples
 - `references/06-implementation.md` — coding discipline details
 - `references/06b-testing-qa.md` — **mandatory testing & QA standard** (11 rules + definition of done)
+- `references/06c-code-quality.md` — **mandatory modularity & maintainability standard** (8 rules, SSOT, testable-standalone, single escalation path)
 - `references/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)

package/skills/aia-asf/references/01-intake.md

@@ -1,5 +1,9 @@
 # Phase 1 — Intake: Question Bank
 
+> **Scale note: this bank is for LARGE work.** Small work (small features, minor
+> bugfixes, small refactors) skips the questions — state understanding in 1–2
+> sentences and start. At most ONE clarifying question, only if genuinely ambiguous.
+
 Keep asking until the user confirms. One question at a time is fine; short batches (3–5) are faster. Do not proceed on guesses.
 
 ## Starter questions
@@ -32,3 +36,5 @@ Every concrete requirement the user states → `capture_spec` immediately, befor
 ## Intake gate
 
 Restate intent in 3–5 bullets, then ask: **"Is this correct?"** Only proceed on an explicit yes.
+
+> Large work only. Small work has no intake gate.

package/skills/aia-asf/references/04-adversarial.md

@@ -1,9 +1,19 @@
 # Phase 4 — Adversarial Analysis Checklist
 
+> **Scale note: the full checklist and gate apply to LARGE work.** Small work does
+> a quick mental pass on edge cases and failure modes while implementing — no
+> formal review, no user checkpoint.
+
 Challenge every spec and design decision like a hostile reviewer. For each item, determine: capture a new spec / supersede an existing one / accept the risk (recorded).
 
 ## Per-spec questions
 
+> **Code-quality lens (always applied):** for every module/design under review,
+> also ask the `references/06c-code-quality.md` questions — is shared logic
+> duplicated anywhere? Is the single escalation path identifiable? Is the module
+> testable standalone with the same calls? Any hardcoded values that belong in
+> config?
+
 - **Edge cases**: empty input, zero data, max load, missing fields, concurrent access, duplicate input, unicode, huge payloads
 - **Failure modes**: what breaks first? Is failure loud or silent? Can we recover automatically?
 - **Security**: authentication, authorization, injection (SQL/XSS), data exposure, secrets, abuse/rate-limiting, supply chain

package/skills/aia-asf/references/05-plan.md

@@ -1,5 +1,8 @@
 # Phase 5 — PLAN.md Template
 
+> **Scale note: this phase is for LARGE work only.** Small work skips PLAN.md and
+> the approval gate entirely — implement directly.
+
 Write `PLAN.md` in the project root. It must be executable by any competent engineer without re-deriving decisions.
 
 ```markdown
@@ -18,10 +21,13 @@ Existing system, repo layout, relevant prior work. Links to research sources.
 Decided approach with rationale. Cite the research (package names, URLs).
 
 ## Architecture / Design
-- Components and their responsibilities
+- Modules and their responsibilities (small, single-purpose — see `references/06c-code-quality.md`)
 - Data model / schema (if any)
 - Key flows (request lifecycle, event flow)
 - Interfaces / contracts between components
+- **Where shared truth lives** (single source of truth map: which module owns each shared capability)
+- **Layering**: one-way dependency rules between layers; what each layer may/may not import
+- **Standalone testability**: how each module is exercised outside the host with the same calls
 
 ## Milestones
 | # | Milestone | Exit criteria |
@@ -54,7 +60,7 @@ From adversarial analysis. Each risk: likelihood, impact, mitigation, owner.
 Explicitly cut items (so nobody re-adds them).
 ```
 
-## Approval gate (MANDATORY)
+## Approval gate (MANDATORY — large work only)
 
 Present the plan and ask:
 

package/skills/aia-asf/references/06-implementation.md

@@ -1,5 +1,11 @@
 # Phase 6 — Implementation Discipline
 
+> **Also read `references/06c-code-quality.md`** — the modularity & maintainability
+> standard. Structure code as small modules with one responsibility, keep shared
+> functionality in exactly one implementation (SSOT, single escalation path),
+> never hardcode what config should drive, and keep every module testable
+> standalone outside the host.
+
 ## Test-first
 
 1. Write the failing test for the next behavior

package/skills/aia-asf/references/06c-code-quality.md

@@ -0,0 +1,170 @@
+# Modularity & Maintainability Standard (MANDATORY)
+
+Distilled from Bruno's own development philosophy — honed on the Tunnel project
+and its modules (smart-router, autoroute, feature-extractor, heuristic-engine) —
+and reinforced by established software-engineering research: **Single Source of
+Truth (SSOT)**, **testability as a design property**, and **ports-and-adapters
+(hexagonal) seams**.
+
+These rules exist because violating them caused real pain in those sessions:
+code "thrown on a heap", duplicated logic, hardcoded model attributes, modules
+that could not be tested outside the server, and regressions that broke
+existing functionality. Each rule below carries the lesson.
+
+---
+
+## Rule 1 — Small, well-readable modules, plugged in where needed
+
+> *"You throw a bunch of code and functionality on a heap, instead of making
+> smaller, well-readable modules and plugging them in where needed."* — Tunnel sessions
+
+- One module = one responsibility. If a file does two unrelated things, split it.
+- A module must be **readable top to bottom** by someone new: clear names,
+  short functions, no 500-line god-files.
+- **Plug in, don't embed**: the host system imports and wires modules; it does
+  not copy their logic inline.
+- Extraction triggers (any of these → extract a module):
+  - a function/concern exceeds ~100 lines or 3 levels of nesting
+  - the same logic is needed by two call sites
+  - you cannot explain what the file does in one sentence
+  - you are about to debug the same area a second time
+
+## Rule 2 — One implementation for shared functionality (single escalation path)
+
+> *"Make a separate module for ... communication and use IT instead of having
+> that function integrated in there."* — Tunnel sessions
+
+- **Every shared capability lives in exactly one authoritative module.**
+  Everything else imports it. No copies, no re-implementations, no
+  "parallel systems working side by side" (*"I want an integrated system, not a
+  dual system working side by side"*).
+- This is the **Single Source of Truth** (SSOT) principle: every piece of
+  knowledge exists in exactly one place; every other reference *points* to it.
+- SSOT checklist before shipping (from research on SSOT):
+  - Is any value/logic defined in more than one place?
+  - If this changes tomorrow, how many files do I touch? (Answer: **one**.)
+  - Would a new developer know where the authoritative version lives?
+- Escalation paths included: if a request can escalate (to a stronger model,
+  a fallback, a retry, an admin), there is **one** escalation path module that
+  every caller routes through — not ad-hoc escalation logic scattered per
+  caller.
+
+## Rule 3 — No hardcoding; config drives behavior
+
+> *"DO NOT hard-code attributes of models ... stuff in the brackets is specific
+> to opus, but not necessarily to any model we will add."* — Tunnel sessions
+
+- Model names, thresholds, limits, timeouts, URLs, feature flags: all load from
+  config, never literal in logic.
+- If you hardcode a value that another system (or a future system) might share,
+  you have created a second source of truth — see Rule 2.
+- The module must behave the same for any config input; its logic is
+  config-agnostic.
+
+## Rule 4 — Testable outside the host, then integrated verbatim
+
+> *"MAKE IT TIGHT AND MODULAR AND FULLY TESTABLE OUTSIDE OF THE SERVER. TEST
+> EVERYTHING 100% ANALOGOUS TO HOW IT WORKS ON THE SERVER ... THEN INTEGRATE
+> BACK INTO THE SERVER."* — Tunnel sessions
+
+- A module must run standalone: a test script imports and primes it **with the
+  exact same calls** the host would make.
+- **Same modules in tests and production** — never a "test copy" of logic.
+  Tests import the production module; the host imports the same module.
+  (*"It should be imported in [the host] and used there with no changes — a
+  separate test script importing and priming the module can be created for
+  testing."*)
+- **Testability is a design property, not a testing task** (research): if a
+  business rule needs a running server + real DB to validate, the architecture
+  is wrong. Core logic should run as plain functions with injected fakes.
+- Build **seams** (ports-and-adapters): core logic depends on interfaces
+  (clock, IDs, persistence, external calls, message publishing), not on
+  concrete infrastructure. Adapters live at the edge.
+- Verification flow: develop → test standalone (100% analogous) → **integrate
+  into the host verbatim** → re-test in place.
+
+## Rule 5 — Refactor what is too complex to understand
+
+> *"REFACTOR WHAT IS TOO COMPLEX FOR YOU TO UNDERSTAND!"* — Tunnel sessions
+
+- Complexity you cannot explain is a defect, not a badge of honor.
+- When you find yourself running "rounds like a moron" debugging something,
+  **stop and refactor the module** instead of patching blind.
+- Refactor gate (when to invest): only refactor when it makes debugging and
+  individual component testing easier and faster, with the data you already
+  have. Not refactoring for its own sake; refactoring for **testability and
+  clarity**.
+- Refactoring techniques that directly serve this (research-validated):
+  **Extract Method** (break long functions into named steps), **Extract Class/
+  Module** (group related logic), **Replace Conditional with Polymorphism**
+  (turn nested conditionals into modular dispatch), **Remove Duplication**
+  (collapse copies into one implementation).
+
+## Rule 6 — Layer with clear boundaries, and document them
+
+> *"Refactor the layering for readability completely, test everything in
+> detail, and do a writeup for the layered system."* — Tunnel sessions
+
+- Define layers (e.g., handler → router → modules → backends) with one-way
+  dependency rules. No layer reaches across another.
+- **Do a writeup**: a short architecture doc (in the repo) stating what each
+  module is, what it uses, how and why, and where truth lives (the SSOT map).
+  (*"Properly document the modules and the main scaffolding to always have a
+  clear idea what is happening where."*)
+- Research on architecture fitness: keep the "core" boring and deterministic
+  (no framework/IO inside); edges translate to and from infrastructure.
+
+## Rule 7 — Debug observability: full I/O logging, replayable
+
+> *"Shouldn't you also log somewhere the FULL input and outputs of the whole
+> chain (during debug only) including headers and bodies ... and then
+> comparing, since the lateral test just works?"* — Tunnel sessions
+
+- During debug: log the **full input and output of the whole chain** (headers,
+  bodies, intermediate steps) to disk — not just errors.
+- Side tests must log identically, so you can **compare** a passing lateral
+  test against a failing production call and see the divergence.
+- Keep captured real traffic and **replay it through the structure**
+  (*"using stored message data and replaying it through the structure"*) to
+  reproduce and fix without the live host.
+- Logging must be enough that long-term debugging works from log files and the
+  stored corpus alone.
+
+## Rule 8 — Nothing may break existing functionality
+
+> *"Nothing may break already existing functionality in the server."* — Tunnel sessions
+
+- Modularity changes and refactors are **behavior-preserving**: same inputs,
+  same outputs, same side effects.
+- After any restructuring, run the existing tests + a regression pass over the
+  previous behavior before declaring done.
+- This is the SSOT/refactor safety net: refactoring restructures *structure*,
+  never *behavior*.
+
+---
+
+## Where this applies in ASF
+
+- **Phase 4 (adversarial)**: challenge the design — is there duplication?
+  Where is the single source of truth? Is the module testable outside the
+  host? What breaks if a config value changes?
+- **Phase 5 (PLAN.md)**: the Architecture/Design section must name the modules,
+  their boundaries, the one-way dependencies, where shared truth lives, and
+  how each module is tested standalone.
+- **Phase 6 (implementation)**: apply Rules 1–8 as you build; extract modules
+  when triggers fire; write the architecture doc alongside the code.
+- **Phase 7 (verification)**: the DoD checklist includes: no duplicated shared
+  logic (Rule 2), no hardcoded config values (Rule 3), every module tested
+  standalone with the same calls (Rule 4), architecture doc written (Rule 6),
+  existing functionality still green (Rule 8).
+
+## Anti-patterns
+
+- ❌ One giant file / god-object that "does everything"
+- ❌ Copy-pasting shared logic instead of importing the one module
+- ❌ A "test version" of a module that differs from the production version
+- ❌ Hardcoded model names, thresholds, URLs in logic instead of config
+- ❌ Escalation/fallback logic re-implemented per caller instead of one path
+- ❌ Refactoring "for fun" without the testability/debugging payoff
+- ❌ Shipping a module that cannot run outside the host
+- ❌ Skipping the architecture writeup ("the code is self-documenting")