gabbe-kit 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +42 -3
  2. package/agents/AGENTS.md +3 -2
  3. package/agents/guides/00-index.md +4 -4
  4. package/agents/guides/ai/agent-only-cognition.md +10 -2
  5. package/agents/guides/ai/agent-only-swarms.md +4 -4
  6. package/agents/guides/ai/agent-operating-ergonomics.md +1 -1
  7. package/agents/guides/ai/beyond-llms.md +12 -2
  8. package/agents/guides/architecture/api-standards.md +9 -7
  9. package/agents/guides/architecture/critical-systems-arch.md +10 -4
  10. package/agents/guides/architecture/microservices.md +2 -2
  11. package/agents/guides/architecture/orchestration.md +3 -3
  12. package/agents/guides/architecture/systems-architecture.md +6 -0
  13. package/agents/guides/ops/cost-optimization.md +1 -1
  14. package/agents/guides/patterns/agentic-patterns.md +12 -40
  15. package/agents/guides/patterns/ai-native-scenarios.md +2 -2
  16. package/agents/guides/patterns/design-patterns.md +11 -65
  17. package/agents/guides/patterns/software-design-patterns.md +4 -2
  18. package/agents/guides/principles/clean-code-standards.md +1 -1
  19. package/agents/guides/principles/evaluation-strategy.md +18 -13
  20. package/agents/guides/principles/future-tech.md +1 -1
  21. package/agents/guides/principles/human-agent-collaboration.md +4 -3
  22. package/agents/guides/principles/legacy-tech.md +7 -3
  23. package/agents/guides/principles/testing-strategy.md +5 -3
  24. package/agents/guides/processes/loki-sdlc-phases.md +1 -1
  25. package/agents/guides/security/api-security.md +1 -1
  26. package/agents/guides/security/cryptography-standards.md +8 -2
  27. package/agents/guides/security/privacy-data-protection.md +2 -2
  28. package/agents/guides/security/secure-architecture.md +1 -1
  29. package/agents/skills/00-index.md +16 -16
  30. package/agents/skills/brain/active-inference.skill.md +1 -1
  31. package/agents/skills/brain/brain-mode.skill.md +9 -2
  32. package/agents/skills/brain/cost-benefit-router.skill.md +20 -8
  33. package/agents/skills/brain/loki-mode.skill.md +13 -10
  34. package/agents/skills/brain/sequential-thinking.skill.md +1 -1
  35. package/agents/skills/coding/mobile-dev.skill.md +1 -0
  36. package/agents/skills/coding/tdd-cycle.skill.md +1 -1
  37. package/agents/skills/coding/testing-strategy.skill.md +1 -1
  38. package/agents/skills/coding/visual-design.skill.md +1 -0
  39. package/agents/skills/coordination/agent-interop.skill.md +5 -4
  40. package/agents/skills/coordination/meta-optimize.skill.md +2 -2
  41. package/agents/skills/coordination/multi-agent-orch.skill.md +1 -1
  42. package/agents/skills/coordination/persona-selector.skill.md +1 -1
  43. package/agents/skills/coordination/self-optimize.skill.md +1 -1
  44. package/agents/skills/coordination/swarm-consensus.skill.md +10 -0
  45. package/agents/skills/core/audit-trail.skill.md +1 -1
  46. package/agents/skills/core/emerging-tech.skill.md +1 -1
  47. package/agents/skills/core/integrity-check.skill.md +1 -1
  48. package/agents/skills/core/knowledge-connect.skill.md +1 -0
  49. package/agents/skills/core/preflight.skill.md +8 -0
  50. package/agents/skills/core/sdlc-checkpoint.skill.md +7 -2
  51. package/agents/skills/core/self-heal.skill.md +17 -4
  52. package/agents/skills/core/session-resume.skill.md +8 -3
  53. package/agents/skills/core/state-portability.skill.md +3 -2
  54. package/agents/skills/ops/incident-response.skill.md +1 -0
  55. package/agents/skills/ops/production-health.skill.md +1 -0
  56. package/agents/skills/ops/release-management.skill.md +1 -0
  57. package/agents/skills/ops/system-benchmark.skill.md +1 -0
  58. package/agents/skills/product/spec-writer.skill.md +6 -3
  59. package/agents/skills/security/ai-safety-guardrails.skill.md +12 -3
  60. package/agents/skills/security/legal-review.skill.md +1 -0
  61. package/agents/skills/security/reliability-engineering.skill.md +4 -3
  62. package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +1 -1
  63. package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +7 -0
  64. package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +1 -1
  65. package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +2 -2
  66. package/agents/templates/coordination/AGENTS_TEMPLATE.md +108 -15
  67. package/agents/templates/core/MCP_CONFIG_TEMPLATE.json +12 -0
  68. package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +3 -3
  69. package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +1 -1
  70. package/agents/templates/product/PRD_TEMPLATE.md +8 -2
  71. package/agents/templates/product/SPEC_TEMPLATE.md +9 -3
  72. package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +1 -1
  73. package/docs/FEATURES_AND_INNOVATIONS.md +208 -0
  74. package/docs/MCP_CONFIGURATIONS.md +44 -1
  75. package/docs/POST_INSTALL.md +2 -1
  76. package/docs/QUICK_GUIDE.md +1 -0
  77. package/docs/README_FULL.md +4 -2
  78. package/docs/ROADMAP.md +98 -0
  79. package/docs/adr/0002-brain-active-inference-runtime.md +29 -8
  80. package/docs/assets/GABBE.png +0 -0
  81. package/package.json +2 -1
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
  ## What is this?
9
9
 
10
10
  - Agentic code development and governance via capability layers and software development cycle gates verifications and alignment (including best practices for security and human-in-the-loop, complete framework).
11
- - The first published open-source project world-wide that features a complete agentic coding kit/framework with cognitive brain loop, skills, SDLC workflow, etc.
11
+ - An open-source project that features a complete agentic coding kit/framework with cognitive brain loop, skills, SDLC workflow, etc.
12
12
  - Universal kit for Software and AI coding agents: Claude Code, Cursor, Windsurf, Cline, Aider, Devin, Gemini, **Antigravity**, **OpenCode**, **Zed**, **Continue**, **Roo Code**, **Kilo Code**, OpenAI/Codex, GitHub Copilot, VS Code.
13
13
  - Drop-in context kit that turns any AI coding agent into a governed engineering team for developing software.
14
14
  - Based on Software Engineering & Architecture Practices and Procedures.
@@ -34,7 +34,7 @@ It contains:
34
34
 
35
35
  ---
36
36
 
37
- *Full documentation: [README_FULL.md](docs/README_FULL.md) · Full quick guide: [QUICK_GUIDE.md](docs/QUICK_GUIDE.md) · Quick commands: [QUICK_COMMANDS.md](docs/QUICK_COMMANDS.md) · CLI reference: [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) · MCP servers: [MCP_CONFIGURATIONS.md](docs/MCP_CONFIGURATIONS.md) · Platform Controls: [PLATFORM_CONTROLS.md](docs/PLATFORM_CONTROLS.md) · Verification Guide: [VERIFICATION_GUIDE.md](docs/VERIFICATION_GUIDE.md)*
37
+ *Full documentation: [README_FULL.md](docs/README_FULL.md) · Full quick guide: [QUICK_GUIDE.md](docs/QUICK_GUIDE.md) · Quick commands: [QUICK_COMMANDS.md](docs/QUICK_COMMANDS.md) · CLI reference: [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) · MCP servers: [MCP_CONFIGURATIONS.md](docs/MCP_CONFIGURATIONS.md) · Platform Controls: [PLATFORM_CONTROLS.md](docs/PLATFORM_CONTROLS.md) · Verification Guide: [VERIFICATION_GUIDE.md](docs/VERIFICATION_GUIDE.md) · Roadmap: [ROADMAP.md](docs/ROADMAP.md)*
38
38
 
39
39
  ---
40
40
 
@@ -57,7 +57,7 @@ It contains:
57
57
  | **Shell bootstrap** | `curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh \| sh` | picks the best available installer |
58
58
  | **Git checkout** | `git clone https://github.com/andreibesleaga/GABBE && cd GABBE && python3 scripts/init.py` | the interactive wizard |
59
59
 
60
- > On npm the package is **`gabbe-kit`** (npm refuses the unscoped `gabbe`); on PyPI it is **`gabbe`**. The installed command is `gabbe` either way. After installing, run `gabbe doctor` for an environment + install report. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
60
+ > On npm the package is **`gabbe-kit`** (npm refuses the unscoped `gabbe`); on PyPI it is **`gabbe`**; the npm package is additionally mirrored on GitHub Packages as `@andreibesleaga/gabbe-kit` (npmjs stays canonical). The installed command is `gabbe` either way. After installing, run `gabbe doctor` for an environment + install report. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
61
61
 
62
62
  **Universal, Python-independent (one command):**
63
63
  ```bash
@@ -124,6 +124,44 @@ cp -r GABBE/agents .
124
124
  chmod +x agents/setup-context.sh && agents/setup-context.sh
125
125
  ```
126
126
 
127
+ ### Install as a Claude Code plugin
128
+
129
+ The skills also ship as Claude Code plugins in one marketplace, so Claude Code can use
130
+ them without installing the kit into the project:
131
+
132
+ ```bash
133
+ claude plugin marketplace add andreibesleaga/GABBE
134
+ claude plugin install gabbe@gabbe
135
+ ```
136
+
137
+ `gabbe` holds the core skills (every skill in `agents/skills/core/` and every skill
138
+ marked `core: true`). The other skills come as topic plugins from the same marketplace:
139
+ `gabbe-ai`, `gabbe-architecture`, `gabbe-brain`, `gabbe-coding`, `gabbe-coordination`,
140
+ `gabbe-data`, `gabbe-industry`, `gabbe-ops`, `gabbe-product` and `gabbe-security`
141
+ (for example `claude plugin install gabbe-security@gabbe`). Claude Code keeps every
142
+ installed skill's name and description in context, within about 1% of the context
143
+ window. All 214 skills would need far more than that; the core plugin alone costs about
144
+ 2,700 tokens per session (`claude plugin details gabbe`), a little over the ~2,000-token
145
+ budget of a 200k context and well within that of a 1M context. Over budget, Claude Code
146
+ drops the descriptions of the least-used skills; nothing fails. Install only the topics
147
+ you use.
148
+
149
+ The same skills install one by one with the skills CLI ([skills.sh](https://skills.sh)):
150
+
151
+ ```bash
152
+ npx skills add andreibesleaga/GABBE -a claude-code
153
+ ```
154
+
155
+ Plugin skills are namespaced (`/gabbe:code-review`, `/gabbe:debug`). The skills CLI
156
+ instead writes them to `.claude/skills/` in the project, where GABBE's `code-review` and
157
+ `debug` take the place of Claude Code's built-in `/code-review` and `/debug` in that
158
+ project; skip those two there if you want the built-ins.
159
+
160
+ The plugins are content only (Markdown skills and the templates they name: no hooks,
161
+ no MCP servers, no executables). They are generated from `agents/skills/`; after
162
+ editing a skill run `python scripts/build_claude_plugin.py` (CI checks the tree is in
163
+ sync).
164
+
127
165
  ### 🌍 Cross-Platform Support
128
166
  - **Linux / macOS / WSL:** Native support.
129
167
  - **Windows (Native):**
@@ -609,6 +647,7 @@ Full catalog: `agents/templates/00-index.md` *(generated by `init.py`)*
609
647
  | **Context-7** | Up-to-date SDK docs (prevents hallucination) |
610
648
  | **Sequential Thinking** | Chain-of-thought reasoning |
611
649
  | **GitHub MCP** | PR review, code search |
650
+ | **GitHits** | Navigate open-source dependency source/docs (no clone, no key) |
612
651
  | **PostgreSQL MCP** | Live schema introspection |
613
652
  | **Playwright MCP** | Browser automation / visual TDD |
614
653
  | **Brave Search** | Authoritative web research |
package/agents/AGENTS.md CHANGED
@@ -124,7 +124,7 @@ every task (episodic, semantic, AUDIT_LOG, CONTINUITY, PROJECT_STATE, RESUME_POI
124
124
  **CRITICAL MANDATES (always apply):**
125
125
 
126
126
  - **Optimal skill/guide/MCP selection** — analyze the task and select (or ask the user to confirm) the best skills/guides/templates; never default to generic execution when a specialized one exists. Recommend enabling any MCP server that would materially help.
127
- - **Cost & budget by default** — minimize tokens/context/API cost; never use swarms or SOTA models for simple work, and **ask the human before any expensive/SOTA/high-cost approach** (with a one-line cost-benefit). Four levers (`guides/ops/cost-optimization.md`): prompt caching (stable context first), context budgeting (load minimum, prefer `context_cost: low`), model tiering (`gabbe route`), batching. Never weaken the gates, the 10-phase SDLC, or HITL to save cost.
127
+ - **Cost & budget by default** — minimize tokens/context/API cost; never use swarms or SOTA models for simple work, and **ask the human before any expensive/SOTA/high-cost approach** (with a one-line cost-benefit). Four levers (`guides/ops/cost-optimization.md`): prompt caching (stable context first), context budgeting (load minimum, prefer `context_cost: low`), model tiering (`gabbe route`), batching. Never weaken the gates, the SDLC lifecycle, or HITL to save cost.
128
128
  - **Spec-driven (first-class)** — `spec → evals → test → code`, never code-first. Non-trivial features start from an **EARS** spec (`product/spec-writer.skill`, `templates/product/SPEC_TEMPLATE.md`, `guides/planning/product-requirements.md`); keep a **golden thread** (requirement → spec → test → code → audit). No requirement without a test (Article I); resolve ambiguity in the spec via `clarify.skill`.
129
129
  - **Observability (first-class)** — every run/decision/model+tool call is traced with token usage + **per-step cost attribution** (`core/audit-trail.skill`, `core/agent-analytics.skill`; OTel GenAI conventions `gen_ai.usage.*`; span tree root→plan→discover→execute→retrieve). Redact content by default (Article IV); `AUDIT_LOG.md` is authoritative without the CLI.
130
130
  - **Human–agent collaboration (manager, not operator)** — the human delegates → observes → intervenes on exceptions. Keep three questions always answerable: **Purpose** (scope/non-goals via spec), **Transparency** (legible reasoning/tools/cost via observability), **Control** (pause/correct/approve via HITL). Prefer an async, observable surface; "done" only when all three hold (`guides/principles/human-agent-collaboration.md`).
@@ -559,7 +559,8 @@ restating them here, to prevent drift):
559
559
  - **🧠 Brain Mode** (`brain/brain-mode.skill.md`) — the Strategist (System 2): meta-cognitive
560
560
  planner/router/optimizer (Active Inference + dynamic cost routing). Trigger: `gabbe brain activate`, `supermode`.
561
561
  - **⚡ Loki Mode** (`brain/loki-mode.skill.md`) — the Executor (System 1): the deterministic
562
- 10-phase SDLC (S01→S10) with human-in-the-loop gates. Trigger: `loki`, `orchestrate`.
562
+ SDLC state machine — a 14-phase lifecycle (10-phase core build loop S01–S10, plus
563
+ Day-0 S00 and Day-2 S11–S13) with human-in-the-loop gates (S00/S01/S02/S07/S08). Trigger: `loki`, `orchestrate`.
563
564
 
564
565
  Brain Mode **wraps** Loki: it receives the request, routes by complexity/budget, runs Loki for
565
566
  the SDLC, and monitors — intervening if cost spikes, errors loop, or requirements drift. Both use
@@ -87,12 +87,12 @@
87
87
  ### 6. Implementation Patterns (`patterns/`)
88
88
  | Guide | File | Purpose |
89
89
  |---|---|---|
90
- | Agentic Patterns| `patterns/agentic-patterns.md` | Implementation paths for swarms |
91
- | Agentic Design Patterns | `patterns/agentic-design-patterns.md` | Full pattern catalog: reasoning/planning/workflow/multi-agent/memory/safety |
92
- | Software Design Patterns | `patterns/software-design-patterns.md` | Classical catalog: GoF + architectural + DDD + enterprise/distributed |
90
+ | Agentic Design Patterns | `patterns/agentic-design-patterns.md` | **Canonical** agentic catalog: reasoning/planning/workflow/multi-agent/memory/safety |
91
+ | Agentic Patterns| `patterns/agentic-patterns.md` | Pointer → `agentic-design-patterns.md` |
92
+ | Software Design Patterns | `patterns/software-design-patterns.md` | **Canonical** classical catalog: GoF + architectural + DDD + enterprise/distributed |
93
+ | Design Patterns | `patterns/design-patterns.md` | Pointer → `software-design-patterns.md` |
93
94
  | AI Scenarios | `patterns/ai-native-scenarios.md` | Real-world AI integrations |
94
95
  | Autonomous Swarm| `patterns/autonomous-swarm-patterns.md` | Inter-agent negotiation |
95
- | Design Patterns | `patterns/design-patterns.md` | GoF and modern code patterns |
96
96
  | Ent. Migration | `patterns/enterprise-migration-scenario.md` | Legacy to modern code paths |
97
97
  | Ent. Patterns | `patterns/enterprise-patterns.md` | CQRS, Saga, and bounded contexts |
98
98
  | Time Complexity | `patterns/time-complexity-analysis.md` | Big-O detection and remediation |
@@ -17,7 +17,11 @@ This guide explains how to manually trigger:
17
17
 
18
18
  ## 1. Manual Brain Mode (Active Inference)
19
19
 
20
- If you have a massive feature to build and want the agent to use "System 2" Free Energy logic (thinking before typing), you can explicitly ask it to load the `brain-mode` skill.
20
+ If you have a massive feature to build and want the agent to use "System 2" deliberation (thinking before typing), you can explicitly ask it to load the `brain-mode` skill.
21
+
22
+ > **Framing vs. implementation.** "Active Inference" and "Free Energy" are *framing words* for
23
+ > the observe → decide → act loop in the brain prompt — no variational free-energy math is
24
+ > computed. See `ai/self-evolving-skills.md` for the honest accounting.
21
25
 
22
26
  ### The Agent Prompt
23
27
  > "Activate Brain Mode for this session by reading `agents/skills/brain/brain-mode.skill.md`. Your goal is to [build X feature]. Follow the Observe -> Orient -> Decide -> Act loop in that document before you write any code."
@@ -34,6 +38,10 @@ Because `brain-mode.skill.md` contains strict procedural logic, the LLM will:
34
38
 
35
39
  If your agent is consistently failing at a specific task (e.g., repeatedly generating outdated React components), you don't need the CLI to fix it. You can order the agent to "evolve" its own rulebook.
36
40
 
41
+ > **Framing vs. implementation.** "Genetic Evolution" is a metaphor. GABBE's real mechanism is a
42
+ > single-parent **LLM-driven rewrite** of a skill selected by an **epsilon-greedy bandit** — there
43
+ > is no crossover and no population culling. See `ai/self-evolving-skills.md`.
44
+
37
45
  ### The Agent Prompt
38
46
  > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/ui-gen.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
39
47
 
@@ -61,7 +69,7 @@ Agents often fail silently or give up when a test breaks. You can manually force
61
69
 
62
70
  ## 4. Manual Cost-Benefit Routing
63
71
 
64
- If you are using a local LLM or a cheaper model on Copilot and encounter a hyper-complex visual diagram or massive refactor, you can prompt the agent to "route" the task context to you, the human, to paste into a frontier model (like Claude 3.5 Sonnet or OpenAI o1).
72
+ If you are using a local LLM or a cheaper model on Copilot and encounter a hyper-complex visual diagram or massive refactor, you can prompt the agent to "route" the task context to you, the human, to paste into a frontier model.
65
73
 
66
74
  ### The Agent Prompt
67
75
  > "Evaluate my request to [refactor the legacy COBOL module] using `cost-benefit-router.skill.md`. Provide a Complexity Score. If the score is > 50, do not attempt to solve it. Instead, generate a `REMOTE_PAYLOAD.md` containing exactly the context I need to copy-paste into an external AI interface."
@@ -10,7 +10,7 @@ However, **all GABBE swarm coordination protocols are defined in Markdown.** Thi
10
10
 
11
11
  There are two primary ways to operate Swarms in "Agent-Only" mode:
12
12
  1. **In-Context Simulation**: The LLM adopts multiple personas sequentially within the same chat thread.
13
- 2. **True Subagent Delegation (A2A)**: You act as the "Router," taking instructions from the Master Orchestrator and spinning up true, parallel LLM instances (like Gemini 1.5 Pro or Claude 3.5 Sonnet) to do isolated work.
13
+ 2. **True Subagent Delegation (A2A)**: You act as the "Router," taking instructions from the Master Orchestrator and spinning up true, parallel LLM instances (each running a frontier model) to do isolated work.
14
14
 
15
15
  ---
16
16
 
@@ -49,13 +49,13 @@ Use this for simple projects where context window limits are not a concern. The
49
49
  > "Execute the next 3 tasks using **In-Context Simulation**. Act as the `eng-backend` persona to write the code, then immediately adopt the `eng-qa` persona in the next paragraph to test it."
50
50
 
51
51
  ### Tactic B: True Subagent Delegation A2A (For Massive Scale)
52
- Use this when you need true isolation, zero context-pollution, or want to utilize different frontier models for different tasks (e.g., Cursor for coding, OpenAI o1 for Architecture review).
52
+ Use this when you need true isolation, zero context-pollution, or want to utilize different frontier models for different tasks (e.g., one tool for coding, another frontier model for architecture review).
53
53
 
54
54
  > "For the next task, use **True Subagent Delegation**. Do not write the code yourself. Instead, generate a `delegation-payload.md` file. Include the specific `persona` file to load, the exact task context, and the expected output format. I will copy-paste this file into a separate AI model and return the result to you here."
55
55
 
56
56
  **Your Workflow:**
57
57
  1. The Orchestrator generates `delegation-payload.md`.
58
- 2. You open a new browser tab for an advanced model (e.g., Gemini Advanced).
58
+ 2. You open a new browser tab for a frontier model.
59
59
  3. You paste the payload: *"You are now adopting the GABBE `eng-qa` persona based on the following payload..."*
60
60
  4. The Subagent works in isolation and gives you the final test suite.
61
61
  5. You paste the test suite back to the Orchestrator in Cursor: *"Here is the output from the `eng-qa` subagent. Proceed to S06."*
@@ -64,7 +64,7 @@ Use this when you need true isolation, zero context-pollution, or want to utiliz
64
64
 
65
65
  ## 4. Ad-Hoc Swarm Debate (No SDLC)
66
66
 
67
- You don't need the 10 phases to use Swarms. You can invoke a specific matrix of personas to debate a complex architecture decision.
67
+ You don't need the full 14-phase lifecycle (the 10-phase core build loop S01–S10, plus Day-0 S00 and Day-2 S11–S13) to use Swarms. You can invoke a specific matrix of personas to debate a complex architecture decision.
68
68
 
69
69
  ### The Agent Prompt
70
70
  > "Invoke `agents/skills/coordination/multi-agent-orch.skill.md`. I need to decide between PostgreSQL and MongoDB. Load the `prod-architect`, `eng-database`, and `ops-cost` personas. Facilitate a sequential debate simulating their perspectives. Synthesize their arguments into a final recommendation."
@@ -12,7 +12,7 @@
12
12
  | **Context efficiency** | The context window is finite; every token spent on irrelevant text is a token not spent on the task. | `00-index.md` summaries + `context_cost` tags + `preflight.skill` (load summaries, then bodies on demand — progressive disclosure). |
13
13
  | **A clear operating loop** | Ambiguity about "what do I do next" wastes turns and invites drift. | `AGENTS.md` §5 Step 0–7 (preflight → plan → test → implement → verify → refactor → log). |
14
14
  | **Durable memory** | A token/time cutoff or an agent switch must not lose progress. | `state-preserve.skill` (continuous + pre-cutoff checkpoint) + `RESUME_POINTER.md` + `state-portability.skill` (move to any agent). |
15
- | **Knowing when to ask vs act** | Acting on a wrong interpretation is expensive; asking on the obvious is annoying. | `clarify.skill` (uncertainty-aware) + `GABBE_AUTONOMY` levels (L0–L3). |
15
+ | **Knowing when to ask vs act** | Acting on a wrong interpretation is expensive; asking on the obvious is annoying. | `clarify.skill` (uncertainty-aware) + the autonomy posture `GABBE_AUTONOMY = ask \| auto \| hybrid` (default **hybrid**). |
16
16
  | **Fast feedback** | Verifying late means debugging a big surface; verifying early localizes the error. | Test-first mandate + run the test/lint/gate now, not at the end + `verify_all.sh`. |
17
17
  | **Self-correction** | The first attempt is often wrong; a bounded recovery loop beats giving up or thrashing. | `self-heal.skill` (≤5 attempts, cost-gated) + `final-review.skill`. |
18
18
  | **Cost awareness** | Cheap and expensive paths often produce the same result; defaulting to expensive burns budget. | Cost levers (cache/context-budget/model-tier/batch) + `budget.reserve()` + `cost-benefit-router`. |
@@ -9,7 +9,7 @@ This guide explores paradigms that extend beyond pure Large Language Models, off
9
9
  ## 1. Neuro-Symbolic AI (Hybrid)
10
10
  **The Best of Both Worlds:**
11
11
  * **Neural (System 1):** Fast, intuitive, handles fuzzy data (Images, Text).
12
- * **Symbolic (System 2):** Slow, logical, guarantees correctness (Logic, Math, Rules).
12
+ * **Symbolic (System 2):** Slow, logical, can establish correctness within its formal model (Logic, Math, Rules).
13
13
 
14
14
  ### Application in Engineering
15
15
  * **Formal Verification:** LLM translates code to Formal Logic (TLA+ / Coq). Symbolic Prover verifies it.
@@ -29,6 +29,11 @@ Instead of "one-shot" generation, use "Population-based" improvement.
29
29
  4. **Crossover/Mutation:** Ask LLM to "Mix strategy A and B" or "Mutate parameter X".
30
30
  5. **Repeat:** Until optimal.
31
31
 
32
+ > **Framing vs. implementation.** This is the *evolutionary metaphor*, not what GABBE
33
+ > actually runs. GABBE's real mechanism is a single-parent **LLM-driven rewrite** of a
34
+ > skill steered by an **epsilon-greedy multi-armed bandit** — there is **no crossover and
35
+ > no population culling**. See `ai/self-evolving-skills.md` for the honest accounting.
36
+
32
37
  *See `brain/learning-adaptation.skill.md` and `brain/self-improvement.skill.md`.*
33
38
 
34
39
  ---
@@ -38,9 +43,14 @@ Instead of "one-shot" generation, use "Population-based" improvement.
38
43
  Based on Karl Friston's work. Agents act to confirm their predictions about the world.
39
44
  *See `brain/active-inference.skill.md`.*
40
45
 
46
+ > **Framing vs. implementation.** In GABBE, "Active Inference" and "minimize free energy/surprise"
47
+ > are *framing words* placed in the brain's system prompt to bias the observe → decide → act loop —
48
+ > there is no variational free energy or generative-model math being computed. See
49
+ > `ai/self-evolving-skills.md` for the honest accounting.
50
+
41
51
  * **Generative Model:** The Agent maintains a belief state of the Project.
42
52
  * **Prediction Error:** The difference between "Expected State" (All tests pass) and "Sensed State" (Build failed).
43
- * **Action:** The Agent codes *solely* to minimize this Prediction Error.
53
+ * **Action:** The Agent codes to *reduce* this Prediction Error (as a goal, not a computed objective).
44
54
  * **Epistemic Exploration:** Agent acts not just to fix, but to *learn* ("I will add a log to see what's happening").
45
55
 
46
56
  ---
@@ -38,14 +38,16 @@ Consistency allows shared client libraries.
38
38
  }
39
39
  ```
40
40
 
41
- ### Error (RFC 7807)
41
+ ### Error (RFC 9457 Problem Details)
42
+ Use the standardized **Problem Details** media type `application/problem+json` (RFC 9457, which obsoletes RFC 7807) for HTTP error responses:
42
43
  ```json
43
44
  {
44
- "error": {
45
- "code": "resource_not_found",
46
- "message": "User 123 not found",
47
- "traceId": "abc-123"
48
- }
45
+ "type": "https://example.com/probs/resource-not-found",
46
+ "title": "Resource not found",
47
+ "status": 404,
48
+ "detail": "User 123 not found",
49
+ "instance": "/users/123",
50
+ "traceId": "abc-123"
49
51
  }
50
52
  ```
51
53
 
@@ -53,7 +55,7 @@ Consistency allows shared client libraries.
53
55
  - **Authentication**: Bearer Token (JWT) in Header.
54
56
  - **Rate Limiting**: Return `429 Too Many Requests` with `Retry-After` header.
55
57
  - **Idempotency**: `POST` requests should accept `Idempotency-Key` header to prevent double-billing on network retry.
56
- - **Documentation**: OpenAPI 3.0+ required for ALL APIs.
58
+ - **Documentation**: OpenAPI 3.1+ required for ALL APIs (3.1 aligns with JSON Schema 2020-12).
57
59
 
58
60
  ## 6. Deprecation Policy
59
61
  1. Mark endpoint `Deprecated: true` in OpenAPI.
@@ -22,7 +22,7 @@ This guide details how to apply **Agentic Engineering** to domains governed by s
22
22
  You cannot trust an AI Agent to control a plane directly ("The Black Box Problem").
23
23
  **Solution:** **Runtime Assurance (RTA)** arch.
24
24
  * **Complex Channel (AI):** Optimizes flight path (High Performance, Low Trust).
25
- * **Safety Monitor (Deterministic):** Checks limits ($$ G < 4.0 $$, $$ Alt > 500 $$).
25
+ * **Safety Monitor (Deterministic):** Checks limits (`G < 4.0`, `Alt > 500`).
26
26
  * **Switch:** If Monitor triggers, revert to distinct "Safe Core" code.
27
27
 
28
28
  ### 2.2 Integration with Domain-Driven Design (DDD)
@@ -47,17 +47,23 @@ In a regulated environment, the Agent's primary job is **Evidence Generation**.
47
47
  2. **Segregation Verification:**
48
48
  * Agent analyzes import graphs.
49
49
  * Alerts if "Class C" (Critical) code imports "Class A" (UI) code.
50
- 3. **Hazard Analysis (FMEA/STPA):**
51
- * Agent brainstorms "What if?" scenarios ("What if the GPS sensor sends NaN?").
50
+ 3. **Hazard Analysis (STPA / FTA):**
51
+ * For *hazard* analysis use system-theoretic methods — **STPA** (Systems-Theoretic Process Analysis) and **FTA** (Fault Tree Analysis) — to reason top-down from unsafe control actions and hazards.
52
+ * **FMEA** (Failure Mode and Effects Analysis) is a *failure-mode* analysis, not a hazard analysis: it works bottom-up from component failure modes to their effects. Use it alongside, not as a substitute for, STPA/FTA.
53
+ * Agent brainstorms "What if?" scenarios ("What if the GPS sensor sends NaN?") to seed both.
52
54
 
53
55
  ---
54
56
 
55
- ## 4. The "Lethal Trifecta" in Critical Ops
57
+ ## 4. Forbidden Constructs in Hard-Real-Time Code
56
58
  Avoid these three at all costs:
57
59
  1. **Unbounded Loops:** Control loops must be deterministic.
58
60
  2. **Dynamic Memory Allocation:** Critical C/C++ often forbids `malloc` after init.
59
61
  3. **Deadlocks:** Actors/Agents must have proven liveness.
60
62
 
63
+ > Note: "Lethal Trifecta" is a term of art for the *prompt-injection* risk
64
+ > (private data + untrusted content + exfiltration channel in one agent) — see the
65
+ > security guides; it does not refer to the real-time constructs above.
66
+
61
67
  ---
62
68
 
63
69
  ## 5. References
@@ -12,11 +12,11 @@
12
12
  - Organization is large enough to support operational overhead
13
13
 
14
14
  **Do NOT use microservices when:**
15
- - Team < 10 engineers (start with modular monolith)
15
+ - Team is below ~50 engineers and you have not hit a concrete scaling-pain trigger (start with a modular monolith)
16
16
  - Domain is not well understood yet (boundaries will be wrong)
17
17
  - Operational maturity is not there (monitoring, tracing, CI/CD)
18
18
 
19
- **Start with a modular monolith. Extract services when boundaries are proven.**
19
+ **Start with a modular monolith. Extract services when boundaries are proven** — the rule of thumb is ~50 engineers or a clear scaling-pain trigger (independent deploy cadence, divergent scaling needs), matching `architecture/monolith.md`.
20
20
 
21
21
  ---
22
22
 
@@ -9,7 +9,7 @@ This directory contains the **High-Level Orchestrators** for the Agentic Enginee
9
9
 
10
10
  - **Role**: Meta-Cognitive Orchestrator.
11
11
  - **Function**: Plans, Routes, and Optimizes.
12
- - **Logic**: Active Inference (Free Energy Principle).
12
+ - **Logic**: Active Inference (Free Energy Principle) — used here as conceptual *framing* for the observe → decide → act loop, not implemented variational math. See `ai/self-evolving-skills.md` for the honest accounting.
13
13
  - **Use Case**: Complex, ambiguous, or high-stakes projects.
14
14
  - **Key Feature**: **Dynamic Cost Routing** (Local vs Remote).
15
15
 
@@ -21,8 +21,8 @@ This directory contains the **High-Level Orchestrators** for the Agentic Enginee
21
21
  > **The Executor (System 1)**
22
22
 
23
23
  - **Role**: SDLC Orchestrator.
24
- - **Function**: Executes the 10-Phase Engineering Lifecycle.
25
- - **Logic**: Deterministic Workflow (S01 -> S10).
24
+ - **Function**: Executes the 14-phase lifecycle (10-phase core build loop S01–S10, plus Day-0 S00 and Day-2 S11–S13).
25
+ - **Logic**: Deterministic Workflow (core build loop S01 -> S10).
26
26
  - **Use Case**: Building software with strict process requirements.
27
27
  - **Key Feature**: **Human-in-the-Loop Gates**.
28
28
 
@@ -46,6 +46,12 @@ If you don't know the quality priorities → you cannot make good architecture d
46
46
 
47
47
  ### ISO 25010 Quality Attributes
48
48
 
49
+ > **Authoritative model:** the canonical, complete characteristic set is the
50
+ > **ISO/IEC 25010:2023 (Ed. 2)** nine-characteristic model in
51
+ > [`system-qualities.md`](system-qualities.md) (which adds Functional Suitability,
52
+ > Compatibility, and the new **Safety** characteristic). The list below is an
53
+ > illustrative subset of the sub-characteristics, not the full model.
54
+
49
55
  ```
50
56
  Performance Efficiency
51
57
  Time behavior: How fast (response time, throughput)
@@ -47,7 +47,7 @@ Match model power to task difficulty. `gabbe route` decides LOCAL (free/cheap lo
47
47
  For non-latency-sensitive bulk work, async batch APIs run at **−50%** (e.g. Anthropic Message Batches). Schedule large non-interactive runs (audits, migrations, regen) as batches.
48
48
 
49
49
  ### Hard guardrails (never disabled)
50
- `GABBE_MAX_COST_USD`, token/iteration/wall-time budgets, and hard stops bound a runaway loop regardless of the optimizations above — cost control must never weaken the quality gates, the 10-phase SDLC, or human-in-the-loop escalation.
50
+ `GABBE_MAX_COST_USD`, token/iteration/wall-time budgets, and hard stops bound a runaway loop regardless of the optimizations above — cost control must never weaken the quality gates, the 10-phase core SDLC (S01–S10), or human-in-the-loop escalation.
51
51
 
52
52
  ## Automation & Agentic Checks
53
53
  Use the `cost-optimization.skill.md` to autonomously:
@@ -1,43 +1,15 @@
1
- # Advanced Agentic Systems Guide
1
+ # Agentic Patterns — see the canonical catalog
2
2
 
3
- Building AI that can act, plan, and self-correct.
3
+ > **Single source of truth.** The full agentic-pattern catalog — reasoning (ReAct,
4
+ > Reflection/self-correction, Chain-of-Thought/Plan-and-Solve), planning, workflow,
5
+ > multi-agent orchestration (orchestrator-worker, consensus), memory/context, tools &
6
+ > function calling, and reliability/safety — now lives in one place:
7
+ >
8
+ > **→ [`agentic-design-patterns.md`](agentic-design-patterns.md)**
4
9
 
5
- ## 1. The Core Loop: ReAct
6
- **Reason + Act**. The fundamental pattern for autonomous agents.
7
- 1. **Thought**: The model reasons about the current state.
8
- 2. **Action**: The model decides to call a tool.
9
- 3. **Observation**: The tool output is fed back to the model.
10
- 4. **Repeat**: Until the goal is met.
10
+ For multi-agent topologies and how GABBE wires personas together, see
11
+ [`../ai/multi-agent-systems.md`](../ai/multi-agent-systems.md) and
12
+ [`autonomous-swarm-patterns.md`](autonomous-swarm-patterns.md).
11
13
 
12
- ## 2. Reflection & Self-Correction
13
- Models are prone to hallucination. Reflection mitigates this.
14
- - **The Pattern**: `Draft` -> `Critique` -> `Refine`.
15
- - **Implementation**:
16
- - Generate a solution.
17
- - Prompt the model: "Review the solution above for errors in logic or syntax."
18
- - Prompt the model: "Based on the critique, generate a fixed version."
19
-
20
- ## 3. Memory Architecture
21
- Agents need context beyond the immediate prompt.
22
- - **Short-Term (Working Memory)**: The current context window. Summary management is key here.
23
- - **Long-Term (Episodic)**: Vector Database (RAG). Stores past interactions.
24
- - **Semantic (Knowledge)**: Knowledge Graph. Stores facts and relationships.
25
-
26
- ## 4. Planning (Chain of Thought)
27
- For complex tasks, "winging it" fails.
28
- - **Plan-and-Solve**:
29
- 1. Ask model to generate a step-by-step plan.
30
- 2. Execute step 1.
31
- 3. Feed result back.
32
- 4. Update plan if needed.
33
-
34
- ## 5. Tools & Function Calling
35
- The agent's hands.
36
- - **Safety**: Always validate tool inputs with JSON Schema (Zod/Pydantic).
37
- - **Granularity**: Atomic tools (`readFile`, `writeFile`) are better than god-tools (`doEverything`).
38
- - **Feedback**: Tool outputs must be descriptive. "Error: File not found" is better than "Error".
39
-
40
- ## 6. Multi-Agent Orchestration
41
- (See `guides/ai/multi-agent-systems.md` for details)
42
- - **Orchestrator-Worker**: Delegating sub-tasks.
43
- - **Consensus**: Multiple agents voting on an answer.
14
+ For the classical (non-agentic) code/architecture patterns these sit on top of, see
15
+ [`software-design-patterns.md`](software-design-patterns.md).
@@ -12,7 +12,7 @@ This guide explores advanced "in the wild" use cases where GABBE 2.0 excels, lev
12
12
  2. **Key Steps:**
13
13
  - **Extract Logic:** The agent separates UI-only "vibe" code from business logic.
14
14
  - **Apply Types:** Moving from `any` or loose JS to strict TypeScript.
15
- - **Add Gates:** Setting up `ESLint` and `Pretier` to enforce the style discovered during the "vibe" phase.
15
+ - **Add Gates:** Setting up `ESLint` and `Prettier` to enforce the style discovered during the "vibe" phase.
16
16
 
17
17
  ---
18
18
 
@@ -46,7 +46,7 @@ This guide explores advanced "in the wild" use cases where GABBE 2.0 excels, lev
46
46
 
47
47
  ## 4. Multi-Agent Competitive Design (Brain Mode)
48
48
 
49
- **The Scenario:** You have a high-stakes architectural decision (e.g., GraphQL vs REST for a high-traffic API) and want the agent to simulate a debate between two विशेषज्ञ (specialist) personas.
49
+ **The Scenario:** You have a high-stakes architectural decision (e.g., GraphQL vs REST for a high-traffic API) and want the agent to simulate a debate between two specialist personas.
50
50
 
51
51
  ### Workflow:
52
52
  1. **Prompt:**
@@ -1,68 +1,14 @@
1
- # Modern Design Patterns Guide (2025 Edition)
1
+ # Design Patterns — see the canonical catalog
2
2
 
3
- This guide covers essential software design patterns, updated for modern distributed and cloud-native contexts.
3
+ > **Single source of truth.** The classical (non-agentic) design-pattern catalog —
4
+ > GoF creational/structural/behavioral patterns, architectural patterns, DDD, and
5
+ > enterprise/distributed patterns (Circuit Breaker, Sidecar, Backend-for-Frontend,
6
+ > Saga, Strangler Fig, …) — now lives in one place:
7
+ >
8
+ > **→ [`software-design-patterns.md`](software-design-patterns.md)**
4
9
 
5
- ## 1. Creational Patterns
6
- **Focus**: Object creation mechanisms.
10
+ That guide includes a smell-to-pattern map, a selection cheat-sheet, and the GABBE
11
+ skill that implements each family (`design-patterns.skill`, `enterprise-patterns.skill`, …).
7
12
 
8
- ### Factory Method / Abstract Factory
9
- - **Concept**: Create objects without specifying the exact class.
10
- - **Modern Use**: LLM Client factories (OpenAI vs Anthropic clients), Cloud SDK initialization.
11
- - **When to use**: When the implementation needs to be swappable at runtime based on config.
12
-
13
- ### Builder
14
- - **Concept**: Construct complex objects step-by-step.
15
- - **Modern Use**: Constructing complex HTTP requests, prompt chains, or Kubernetes manifests.
16
- - **When to use**: When an object has >3 optional constructor parameters.
17
-
18
- ### Singleton
19
- - **Concept**: Ensure a class has only one instance.
20
- - **Modern Use**: Database connection pools, Configuration managers, Logging services.
21
- - **Warning**: Avoid for stateful business logic; it makes testing hard.
22
-
23
- ## 2. Structural Patterns
24
- **Focus**: Class and object composition.
25
-
26
- ### Adapter
27
- - **Concept**: Make incompatible interfaces work together.
28
- - **Modern Use**: Standardizing different 3rd party APIs (e.g., Stripe vs PayPal) behind a single `PaymentProvider` interface.
29
-
30
- ### Facade
31
- - **Concept**: Simple interface to a complex sub-system.
32
- - **Modern Use**: A `CloudStorage` class that wraps the complexity of S3/GCS SDKs.
33
-
34
- ### Proxy
35
- - **Concept**: A placeholder for another object to control access.
36
- - **Modern Use**: Caching proxies, Lazy loading large datasets, Security/Auth gates.
37
-
38
- ## 3. Behavioral Patterns
39
- **Focus**: Communication between objects.
40
-
41
- ### Strategy (The #1 Pattern)
42
- - **Concept**: Define a family of algorithms, put each in a separate class, and make them interchangeable.
43
- - **Modern Use**: Search algorithms (Exact vs Vector), Authentication strategies (OAuth vs API Key).
44
- - **Why strict?**: It eliminates massive `if/else` or `switch` statements.
45
-
46
- ### Observer / Pub-Sub
47
- - **Concept**: Notify subscribers of state changes.
48
- - **Modern Use**: Event-Driven Architecture (receiving logic), UI Reactivity (Redux/MobX).
49
-
50
- ### Command
51
- - **Concept**: Turn a request into a stand-alone object.
52
- - **Modern Use**: Job queues (Sidekiq/Celery tasks), Undo/Redo functionality.
53
-
54
- ## 4. Cloud & Microservices Patterns
55
-
56
- ### Circuit Breaker
57
- - **Problem**: Cascading failures in distributed systems.
58
- - **Solution**: Stop calling a failing service for a timeout period.
59
- - **Library**: `Polly` (.NET), `Resilience4j` (Java), `opossum` (Node).
60
-
61
- ### Sidecar
62
- - **Problem**: Application logic polluted with infra concerns (logging, mTLS).
63
- - **Solution**: Run a helper process alongside the main app container.
64
- - **Example**: Envoy, Istio.
65
-
66
- ### Backend for Frontend (BFF)
67
- - **Problem**: One API doesn't fit Mobile, Web, and IoT needs equally.
68
- - **Solution**: Create separate API gateways for each client type.
13
+ For the *agentic* patterns that sit on top of these (reasoning, planning, workflow,
14
+ multi-agent, memory, safety), see [`agentic-design-patterns.md`](agentic-design-patterns.md).
@@ -63,11 +63,13 @@ tech) is the hard part. → `domain-model.skill`
63
63
 
64
64
  - **Saga** — manage a distributed transaction as a sequence of local steps + compensations.
65
65
  - **Outbox / Inbox** — reliable event publishing alongside a DB write.
66
- - **Circuit Breaker** — stop calling a failing dependency; fail fast and recover.
66
+ - **Circuit Breaker** — stop calling a failing dependency for a timeout period; fail fast and recover. Avoids cascading failures. Libraries: `Resilience4j` (Java), `Polly` (.NET), `opossum` (Node).
67
67
  - **Bulkhead** — isolate resource pools so one failure can't sink the whole system.
68
68
  - **Retry with backoff + jitter**, **Timeout**, **Rate Limiting**, **Idempotency key**.
69
69
  - **Strangler Fig** — incrementally replace a legacy system. → `enterprise-migration-scenario.skill`, `legacy-modernization.skill`
70
- - **API Gateway**, **Backend-for-Frontend**, **Sidecar**, **Anti-Corruption Layer**, **Service Mesh**.
70
+ - **API Gateway**, **Anti-Corruption Layer**, **Service Mesh**.
71
+ - **Backend-for-Frontend (BFF)** — separate API/gateway per client type (Mobile/Web/IoT) when one API can't serve all equally.
72
+ - **Sidecar** — run a helper process alongside the main app container to keep infra concerns (logging, mTLS, telemetry) out of application logic. Example: Envoy/Istio.
71
73
  - Implemented by `enterprise-patterns.skill`, `error-handling-strategy.skill`, `middleware-design.skill`, `api-design.skill`.
72
74
 
73
75
  ---
@@ -20,7 +20,7 @@ Code is read 10x more than it is written. Optimize for readability and maintaina
20
20
 
21
21
  ### DRY (Don't Repeat Yourself)
22
22
  - Every piece of knowledge needs a single, unambiguous representation.
23
- - **Nuance**: duplication of *code* is sometimes verified to avoid coupling. Duplication of *business logic* is always bad.
23
+ - **Nuance**: incidental duplication of *code* is sometimes tolerable — and even preferable — when removing it would force premature coupling between otherwise-independent modules. Duplication of *business logic* (a single rule encoded in two places) is always bad.
24
24
 
25
25
  ### KISS (Keep It Simple, Stupid)
26
26
  - Avoid "clever" one-liners.
@@ -24,19 +24,24 @@ or reasoning).
24
24
 
25
25
  ## 2. The Eval Pyramid
26
26
 
27
- Like the testing pyramid, push work down to the cheapest, most-deterministic layer that
28
- can express the check. Climb only when you must.
29
-
30
- 1. **Deterministic assertions (base)** — exact match, regex, JSON-schema validation, set
31
- membership. Cheap, instant, 100% reproducible. Most "quality" checks are secretly
32
- deterministic — catch them here.
33
- 2. **Semantic similarity** — embedding cosine similarity against a reference answer, with
34
- a threshold. Tolerates wording differences while still being mostly reproducible.
35
- 3. **LLM-as-judge** — a model scores the output against a rubric. Expensive, subjective,
36
- non-deterministic; use for quality dimensions no formula captures (clarity, helpfulness).
37
- 4. **Human review (tip)** — the gold standard and the calibration anchor for everything
38
- below it. Slowest and most expensive; reserve for high-stakes output and for keeping the
39
- judges honest.
27
+ This is the **authoritative eval taxonomy** for GABBE (the testing taxonomy lives in
28
+ `testing-strategy.md`; its "Level 5: Evaluation-Driven" defers here). Like the testing
29
+ pyramid, push work down to the cheapest, most-deterministic layer that can express the
30
+ check. Climb only when you must. The four layers are referred to elsewhere as **Tier-1**
31
+ through **Tier-4**:
32
+
33
+ 1. **Tier-1 — Deterministic assertions (base)** — exact match, regex, JSON-schema
34
+ validation, set membership. Cheap, instant, 100% reproducible. Most "quality" checks are
35
+ secretly deterministic — catch them here.
36
+ 2. **Tier-2 — Semantic similarity** — embedding cosine similarity against a reference
37
+ answer, with a threshold. Tolerates wording differences while still being mostly
38
+ reproducible.
39
+ 3. **Tier-3 — LLM-as-judge** — a model scores the output against a rubric. Expensive,
40
+ subjective, non-deterministic; use for quality dimensions no formula captures (clarity,
41
+ helpfulness).
42
+ 4. **Tier-4 — Human review (tip)** — the gold standard and the calibration anchor for
43
+ everything below it. Slowest and most expensive; reserve for high-stakes output and for
44
+ keeping the judges honest.
40
45
 
41
46
  Each layer up costs more and is less reproducible. A good eval suite is fat at the base.
42
47
 
@@ -32,4 +32,4 @@ Software engineering moves fast. In 2026, we are building the foundations for 20
32
32
 
33
33
  ## 6. Post-Quantum Cryptography (PQC)
34
34
  - **Threat**: Quantum computers (2030+) will break RSA/ECC encryption.
35
- - **Action**: Start adopting NIST-approved PQC algorithms (CRYSTALS-Kyber) for long-term data storage.
35
+ - **Action**: Start adopting NIST-approved PQC algorithms (ML-KEM (FIPS 203, formerly CRYSTALS-Kyber)) for long-term data storage.
@@ -44,11 +44,12 @@ of the collaboration are:
44
44
  architect persona bounds what the agent is and is *not* to do.
45
45
  - **Transparency** → observability is non-negotiable (every run traced; see the
46
46
  Observability mandate in AGENTS.md §5 and CONSTITUTION Article VI).
47
- - **Control** → HITL gates + autonomy levels (L0–L3, `self-optimize.skill`) scale
48
- intervention frequency to the autonomy the human has granted.
47
+ - **Control** → HITL gates + the autonomy posture (`GABBE_AUTONOMY = ask | auto | hybrid`,
48
+ default **hybrid**; see `clarify.skill` / `preflight.skill`) scale intervention
49
+ frequency to the autonomy the human has granted.
49
50
 
50
51
  ## Final-review checklist (apply at integrity-check / S08)
51
52
  A change is only "done" when all three facets hold:
52
53
  - [ ] **Purpose** — scope/non-goals are explicit; the work maps to a spec/requirement.
53
54
  - [ ] **Transparency** — the run is traced and legible (decisions, tools, cost) — no black box.
54
- - [ ] **Control** — the right HITL gates fired for the autonomy level; high-stakes/irreversible actions were human-approved.
55
+ - [ ] **Control** — the right HITL gates fired for the autonomy posture; high-stakes/irreversible actions were human-approved.