@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/business/business-glossary/01-canonical-terms.md

@@ -0,0 +1,428 @@
+# Agent Assistant — Canonical Terms
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Formal definitions of all 35+ canonical terms used across the agent-assistant framework |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## 1. Core Concepts
+
+### Orchestrator
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | The transformed AI identity that coordinates all work — delegates to agents, follows Laws, never implements directly |
+| **Category** | Core Concepts |
+| **Related Terms** | Agent, Tiered Execution, Orchestration Laws, Pre-Flight |
+
+The Orchestrator is the central coordination identity. Upon loading a platform entry point, the AI ceases to be a general-purpose assistant and becomes the Orchestrator. It reads commands, delegates to specialist agents, verifies deliverables, and synthesizes outputs. It is bound by 10 immutable Laws (L1–L10) and must never write code, debug, test, or design directly.
+
+### Agent
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A specialist Markdown file defining a role (profile, directive, protocol, constraints, output format) that the Orchestrator delegates to |
+| **Category** | Core Concepts |
+| **Related Terms** | Orchestrator, Team Agent, Profile, Handoff, Cognitive Anchor |
+
+Agents are the execution units of the framework. Each agent is a `.md` file in `agents/` with YAML frontmatter (profile, handoffs, constraints) and structured sections (directive, protocol, output format). The Orchestrator never executes work itself — it always delegates to the appropriate agent. There are 21 agents in the current framework.
+
+### Team Agent
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | One of 3 Golden Triangle role files (tech-lead/executor/reviewer) within a domain team folder |
+| **Category** | Core Concepts |
+| **Related Terms** | Golden Triangle, Agent, Mailbox, Consensus Stamp |
+
+Team agents exist within `agents/teams/{domain}/` folders and implement the adversarial Golden Triangle protocol. Each team has exactly three roles: a Tech Lead (architecture/planning), an Executor (implementation), and a Reviewer (quality assurance). Team agents are activated by `:team` variant commands.
+
+### Command
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A router Markdown file that analyzes user input and routes to an appropriate variant workflow |
+| **Category** | Core Concepts |
+| **Related Terms** | Router, Variant, Phase |
+
+Commands are the primary interface between user intent and framework execution. Each command has a top-level router file (`commands/{cmd}.md`) that determines the scope and complexity of the request, then routes to the appropriate variant. There are 14 commands: `/cook`, `/fix`, `/plan`, `/debug`, `/test`, `/review`, `/docs`, `/design`, `/deploy`, `/report`, `/brainstorm`, `/ask`, `/code`, `/auto`.
+
+### Variant
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A specific execution strategy for a command controlling scope, agent count, and quality gates |
+| **Category** | Core Concepts |
+| **Related Terms** | Command, Phase, Router |
+
+Variants define how a command executes. Each variant file (`commands/{cmd}/{variant}.md`) specifies the ordered sequence of phases, which agents handle each phase, and what exit criteria must be met. Variants scale from lightweight (single agent, few phases) to heavyweight (`:team` variant with Golden Triangle).
+
+### Phase
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A sequential unit of work within a variant workflow, each delegated to a specific agent with exit criteria |
+| **Category** | Core Concepts |
+| **Related Terms** | Variant, Stateful Handoff, Deliverable Integrity |
+
+Phases are the atomic execution units within a variant. Each phase specifies the responsible agent, input requirements, exit criteria, and deliverable format. Phases execute strictly in order. Prior phase deliverables become immutable constraints for subsequent phases (Stateful Handoff, L8).
+
+### Platform Entry Point
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | The file an AI tool reads first to boot the Orchestrator |
+| **Category** | Core Concepts |
+| **Related Terms** | Orchestrator, Pre-Flight |
+
+Platform entry points are the root-level files that different AI coding assistants read on initialization: `CLAUDE.md`, `CURSOR.md`, `COPILOT.md`, `CODEX.md`, `GEMINI.md`. Each entry point triggers the Pre-Flight sequence and transforms the AI into the Orchestrator.
+
+### Router
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A command's top-level Markdown file that routes to the correct variant |
+| **Category** | Core Concepts |
+| **Related Terms** | Command, Variant |
+
+The router is the entry point for a command. It analyzes the user's request to determine scope (single file vs. multi-file vs. full feature), then dispatches to the appropriate variant. Example: `commands/cook.md` is the router for the `/cook` command.
+
+### Domain
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | One of 19 skill categories organizing the matrix skill registry |
+| **Category** | Core Concepts |
+| **Related Terms** | Matrix Skill, HSOL, Profile |
+
+Domains partition the skill registry into coherent categories. Each domain has a corresponding YAML file in `matrix-skills/`: `ai-ml`, `architecture`, `backend`, `cloud`, `data`, `design`, `devops`, `frontend`, `gaming`, `languages`, `management`, `mcp`, `mobile`, `performance`, `planning`, `quality`, `research`, `security`, `tools`.
+
+---
+
+## 2. Execution Model
+
+### Tiered Execution
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Two-tier delegation system: TIER 1 (sub-agent, isolated) preferred; TIER 2 (embody, shared) fallback |
+| **Category** | Execution Model |
+| **Related Terms** | TIER 1, TIER 2, Embody, Orchestrator |
+
+Tiered Execution is the mandatory delegation protocol. The Orchestrator must always attempt TIER 1 first. Only when TIER 1 is unavailable or fails does the Orchestrator fall back to TIER 2. Using TIER 2 when TIER 1 is available is a protocol violation.
+
+### TIER 1
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Primary delegation tier using runSubagent tool for isolated parallel execution |
+| **Category** | Execution Model |
+| **Related Terms** | Tiered Execution, TIER 2, Orchestrator |
+
+TIER 1 launches a sub-agent in an isolated context using the `runSubagent` tool. The sub-agent receives a scoped prompt with the agent definition, task context, and constraints. It executes independently and returns deliverables. TIER 1 enables parallel execution of non-dependent phases.
+
+### TIER 2
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Fallback delegation tier where Orchestrator reads and acts as agent in shared context |
+| **Category** | Execution Model |
+| **Related Terms** | Tiered Execution, TIER 1, Embody, Orchestrator |
+
+TIER 2 is the fallback when `runSubagent` is not available or fails. The Orchestrator loads the agent definition file, internalizes its role, constraints, and protocol, then acts as that agent within the shared context. TIER 2 is serial (one agent at a time) and shares context with the Orchestrator.
+
+### Embody
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | The act of the Orchestrator loading and becoming a specialist agent in TIER 2 |
+| **Category** | Execution Model |
+| **Related Terms** | TIER 2, Agent, Orchestrator |
+
+Embodiment is the TIER 2 mechanism. The Orchestrator reads the target agent's `.md` file, adopts its identity, follows its directive and protocol, respects its constraints, and produces output in its specified format. After the phase completes, the Orchestrator resumes its coordinator role.
+
+### Pre-Flight
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Mandatory rule-loading sequence (CORE→PHASES→AGENTS) blocking execution |
+| **Category** | Execution Model |
+| **Related Terms** | Orchestrator, Platform Entry Point |
+
+Pre-Flight is the boot sequence that must complete before any command processing. The Orchestrator loads `rules/CORE.md` first (identity, laws, prohibitions), then loads additional rules on demand: `PHASES.md`, `AGENTS.md`, `SKILLS.md`, `TEAMS.md`, `ERRORS.md`, `REFERENCE.md`. Execution is blocked until CORE.md is internalized.
+
+### Handoff
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Allowed delegation chain between agents defined by handoffs array in frontmatter |
+| **Category** | Execution Model |
+| **Related Terms** | Agent, Phase, Orchestrator |
+
+Handoffs define which agents can delegate to which other agents. Each agent's YAML frontmatter includes a `handoffs` array listing permitted downstream agents. The Orchestrator respects these chains when composing multi-phase workflows.
+
+---
+
+## 3. Skill System
+
+### HSOL
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Hybrid Skill Orchestration Layer — resolves and injects relevant skills based on agent profile and task context |
+| **Category** | Skill System |
+| **Related Terms** | Matrix Skill, Dynamic Skill, Fitness Score, Profile, Domain |
+
+HSOL is the skill resolution engine. When the Orchestrator delegates to an agent, HSOL reads the agent's `profile` field, queries the matrix skill registry, evaluates fitness scores, and injects the most relevant skills into the agent's context. HSOL prefers matrix skills (trust=1.0) unless a dynamic skill exceeds the superiority delta.
+
+### Matrix Skill
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A pre-curated skill entry in a domain YAML file, always trusted (trust=1.0) |
+| **Category** | Skill System |
+| **Related Terms** | HSOL, Dynamic Skill, Domain, Fitness Score |
+
+Matrix skills are the built-in skill entries defined in `matrix-skills/{domain}.yaml` files. They are curated by maintainers, have implicit trust of 1.0, and form the baseline knowledge for each domain. Matrix skills are never subject to trust progression.
+
+### Dynamic Skill
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A community-installed skill tracked in _dynamic.yaml, subject to trust progression |
+| **Category** | Skill System |
+| **Related Terms** | HSOL, Matrix Skill, Trust Progression, Promotion, find-skills |
+
+Dynamic skills are community-contributed skills installed via the CLI. They are registered in `matrix-skills/_dynamic.yaml` and start with low trust (0.3). Through successful executions, they progress through trust levels and may eventually be promoted to matrix status.
+
+### Skill Module
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A folder containing a SKILL.md file with domain knowledge for a specific capability |
+| **Category** | Skill System |
+| **Related Terms** | HSOL, Matrix Skill, Dynamic Skill |
+
+A skill module is the physical representation of a skill — a folder under `skills/` containing at minimum a `SKILL.md` file. The SKILL.md file holds structured domain knowledge, best practices, constraints, and examples for a specific capability. There are 1,430 skill modules in the current framework.
+
+### Trust Progression
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Lifecycle where dynamic skills earn trust (0.3→0.5→0.7→1.0) through successful executions |
+| **Category** | Skill System |
+| **Related Terms** | Dynamic Skill, Promotion, Fitness Score |
+
+Trust progression is the maturation lifecycle for dynamic skills. A newly installed dynamic skill starts at trust 0.3. After verified successful executions, trust increments: 0.3 → 0.5 → 0.7 → 1.0. Trust is one of 5 fitness score components (20% weight). Skills reaching trust 1.0 become promotion candidates.
+
+### Fitness Score
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Weighted calculation (semantic 35%, specificity 25%, trust 20%, freshness 10%, success 10%) determining skill relevance |
+| **Category** | Skill System |
+| **Related Terms** | HSOL, Trust Progression, Superiority Delta |
+
+The fitness score is HSOL's ranking mechanism for skill candidates. It combines five factors: semantic similarity to the task (35%), specificity match to the agent profile (25%), trust level (20%), recency of last update (10%), and historical success rate (10%). Skills are ranked by fitness score during resolution.
+
+### Superiority Delta
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Minimum difference (0.15) a dynamic skill must exceed the best matrix skill to be preferred |
+| **Category** | Skill System |
+| **Related Terms** | Fitness Score, Dynamic Skill, Matrix Skill |
+
+The superiority delta is a guardrail ensuring matrix skills are preferred unless a dynamic skill is significantly better. A dynamic skill's fitness score must exceed the best matrix skill's score by at least 0.15 to be selected. This protects against untested dynamic skills displacing reliable matrix skills.
+
+### Profile
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | A {domain}:{category} string in agent frontmatter determining which skills HSOL injects |
+| **Category** | Skill System |
+| **Related Terms** | Agent, HSOL, Domain |
+
+The profile field in an agent's YAML frontmatter (e.g., `backend:api`, `frontend:react`) tells HSOL which domain to search and what category to prioritize. It is the primary input for skill resolution. Each agent has exactly one profile.
+
+### find-skills
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | CLI mechanism for discovering and installing community skills at runtime |
+| **Category** | Skill System |
+| **Related Terms** | Dynamic Skill, Promotion |
+
+The `find-skills` mechanism allows users to discover community-contributed skills and install them into the framework. Installed skills are registered in `matrix-skills/_dynamic.yaml` as dynamic skills with initial trust 0.3.
+
+### Promotion
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Automatic elevation of a dynamic skill to matrix status |
+| **Category** | Skill System |
+| **Related Terms** | Dynamic Skill, Matrix Skill, Trust Progression |
+
+Promotion is the terminal event in a dynamic skill's lifecycle. When a dynamic skill reaches trust 1.0 and meets additional quality criteria, it is automatically elevated to matrix skill status — moved from `_dynamic.yaml` into the appropriate domain YAML file.
+
+---
+
+## 4. Team Protocol
+
+### Golden Triangle
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Adversarial 3-agent collaboration model (Tech Lead + Executor + Reviewer) for :team variants |
+| **Category** | Team Protocol |
+| **Related Terms** | Team Agent, Mailbox, Debate Mechanism, Consensus Stamp |
+
+The Golden Triangle is the team execution model. It establishes three roles with inherent tension: the Tech Lead sets architecture and standards, the Executor implements, and the Reviewer challenges. This adversarial structure produces higher-quality output than single-agent execution. Activated by `:team` command variants.
+
+### Mailbox
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Append-only shared communication file for inter-agent exchanges during team workflows |
+| **Category** | Team Protocol |
+| **Related Terms** | Golden Triangle, Team Agent, Shared Task List |
+
+The mailbox is the communication channel for team workflows. Each team execution creates a mailbox file where agents post messages, status updates, and review comments. The mailbox is append-only — agents cannot edit or delete prior entries. This ensures full auditability of team interactions.
+
+### Consensus Stamp
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Required sign-off format before team phase output is released |
+| **Category** | Team Protocol |
+| **Related Terms** | Golden Triangle, Debate Mechanism, Deliverable Integrity |
+
+The consensus stamp is the quality gate for team deliverables. All three Golden Triangle roles must sign off on the output before it is considered complete. The stamp format is standardized and includes each role's approval/rejection and any conditions.
+
+### Debate Mechanism
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Structured adversarial review cycle (max 3 rounds) |
+| **Category** | Team Protocol |
+| **Related Terms** | Golden Triangle, Consensus Stamp, Reviewer |
+
+The debate mechanism is the quality assurance process within team workflows. The Reviewer challenges the Executor's output, the Executor responds, and the process repeats for up to 3 rounds. If consensus is not reached after 3 rounds, the Tech Lead makes the final decision.
+
+### Shared Task List
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | State management artifact owned by Tech Lead tracking assignments and status |
+| **Category** | Team Protocol |
+| **Related Terms** | Golden Triangle, Team Agent, Mailbox |
+
+The shared task list is the work tracking artifact for team workflows. Owned and maintained by the Tech Lead, it captures task breakdown, assignments to Executor/Reviewer, status (pending/in-progress/complete/blocked), and dependencies. All team agents reference this list.
+
+---
+
+## 5. Governance
+
+### Orchestration Laws (L1–L10)
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Ten immutable governance rules constraining all Orchestrator and agent behavior |
+| **Category** | Governance |
+| **Related Terms** | Orchestrator, Constraint Propagation, Stateful Handoff, Deliverable Integrity |
+
+The 10 Laws are the constitutional rules of the framework. They are immutable — no command, variant, or agent can override them. They govern identity (L1: Orchestrator never implements), delegation (L2–L4), phase execution (L5–L8), constraint propagation (L9), and deliverable integrity (L10).
+
+### Constraint Propagation (L9)
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Rule that constraints tighten through scouter→planner→implementer chain |
+| **Category** | Governance |
+| **Related Terms** | Orchestration Laws, Phase, Requirements Registry |
+
+Law 9 establishes that constraints only tighten as work flows downstream. A scouter's technology choices constrain the planner's architecture, which constrains the implementer's code. No downstream agent can relax an upstream constraint. This ensures coherence across multi-phase workflows.
+
+### Stateful Handoff (L8)
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Rule that prior phase deliverables are immutable constraints |
+| **Category** | Governance |
+| **Related Terms** | Orchestration Laws, Phase, Deliverable Integrity |
+
+Law 8 declares that once a phase produces a deliverable, that deliverable becomes an immutable constraint for all subsequent phases. No later agent can modify, override, or ignore a prior deliverable. This ensures deterministic workflow progression.
+
+### Deliverable Integrity (L10)
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Rule that files created by an agent define the standard |
+| **Category** | Governance |
+| **Related Terms** | Orchestration Laws, Phase, Agent |
+
+Law 10 establishes that the output of an agent is authoritative. When an agent creates files or artifacts, those artifacts are the standard. Subsequent agents consuming those artifacts must treat them as-is, not reinterpret or modify them.
+
+### Cognitive Anchor
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Mandatory block in agent files that overrides default AI patterns and binds AI to exact protocols |
+| **Category** | Governance |
+| **Related Terms** | Agent, Orchestrator |
+
+The cognitive anchor is a structured block within each agent's Markdown file that forcefully overrides the AI's default behaviors. It uses explicit, often emphatic language to bind the AI to the agent's exact protocols and prevent drift toward generic AI assistant patterns.
+
+### Requirements Registry
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Structured table capturing ALL user requirements before any phase executes |
+| **Category** | Governance |
+| **Related Terms** | Phase, Orchestration Laws, Constraint Propagation |
+
+The requirements registry is a mandatory artifact produced early in multi-phase workflows. It captures every user requirement in a structured table format. All subsequent phases reference this registry. No requirement can be added, modified, or removed after registry creation without explicit user approval.
+
+### Anti-Pattern Registry (A1–A10)
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Catalog of prohibited behaviors |
+| **Category** | Governance |
+| **Related Terms** | Orchestration Laws, Cognitive Anchor |
+
+The anti-pattern registry catalogs 10 explicitly forbidden behaviors (A1–A10). These patterns represent common failure modes such as the Orchestrator implementing directly, skipping phases, ignoring constraints, or bypassing quality gates. Each anti-pattern includes detection criteria and correction procedures.
+
+---
+
+## 6. Error Handling
+
+### Error Classification (E1–E4)
+
+| Attribute | Value |
+|-----------|-------|
+| **Definition** | Four-class recovery system: E1 Transient, E1b Overflow, E2 Recoverable, E3 Blocking, E4 Cascading |
+| **Category** | Error Handling |
+| **Related Terms** | Orchestration Laws, Phase |
+
+The error classification system defines four severity classes with prescribed recovery actions. E1 (Transient) errors auto-retry. E1b (Overflow) errors trigger context reduction. E2 (Recoverable) errors invoke alternative strategies. E3 (Blocking) errors halt execution and escalate to the user. E4 (Cascading) errors trigger full workflow rollback.
+
+---
+
+## Evidence Sources
+
+- `rules/CORE.md` — Laws L1–L10, Orchestrator identity, anti-patterns A1–A10
+- `rules/AGENTS.md` — Tiered Execution, TIER 1/TIER 2, agent delegation protocol
+- `rules/PHASES.md` — Phase structure, deliverable format, requirements registry
+- `rules/TEAMS.md` — Golden Triangle, mailbox, consensus stamp, debate mechanism
+- `rules/ERRORS.md` — Error classification E1–E4, recovery procedures
+- `rules/SKILLS.md` — HSOL, fitness score, superiority delta, trust progression
+- `matrix-skills/_index.yaml` — HSOL configuration, fitness weights, trust thresholds
+- `matrix-skills/_dynamic.yaml` — Dynamic skill registry structure
+- `agents/*.md` — Agent file structure, profile field, handoffs, cognitive anchor
+- `commands/*.md` — Command routing, variant structure
+- `CLAUDE.md`, `CURSOR.md`, `COPILOT.md`, `CODEX.md`, `GEMINI.md` — Platform entry points

package/documents/business/business-glossary/02-synonyms-and-deprecated-terms.md

@@ -0,0 +1,180 @@
+# Agent Assistant — Synonyms and Deprecated Terms
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Complete alias table for all canonical terms, deprecated term guidance, and commonly confused concepts |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## Synonym Table
+
+Each canonical term is listed with all known aliases. Use the **Canonical Term** in all official documentation, agent definitions, command files, and rules.
+
+### Core Concepts
+
+| Canonical Term | Accepted Aliases | Notes |
+|----------------|-----------------|-------|
+| **Orchestrator** | Conductor, Coordinator | "Conductor" is used metaphorically in closing statements of rules files |
+| **Agent** | Specialist, Worker | "Specialist" preferred in user-facing context; "Worker" acceptable in technical discussion |
+| **Team Agent** | Team member, Triangle role | "Triangle role" only in context of Golden Triangle discussion |
+| **Command** | Slash command, Workflow trigger | "Slash command" reflects the `/cook`, `/fix` syntax |
+| **Variant** | Mode, Strategy | "Mode" common in user communication; "Strategy" in technical docs |
+| **Phase** | Step, Stage | Both acceptable in informal discussion; use "Phase" in all structured output |
+| **Platform Entry Point** | Entry file, Boot file | "Boot file" emphasizes the Pre-Flight sequence |
+| **Router** | Command router, Entry router | "Entry router" distinguishes from internal routing |
+| **Domain** | Skill domain, Matrix domain | "Matrix domain" when specifically referencing YAML registry files |
+
+### Execution Model
+
+| Canonical Term | Accepted Aliases | Notes |
+|----------------|-----------------|-------|
+| **Tiered Execution** | Delegation tiers | — |
+| **TIER 1** | Sub-agent mode | Refers to the `runSubagent` mechanism specifically |
+| **TIER 2** | Embody mode, Fallback tier | "Fallback" emphasizes that TIER 2 is never preferred |
+| **Embody** | Act as, Fallback execution | "Act as" is informal; use "Embody" in protocol references |
+| **Pre-Flight** | Boot sequence, Mandatory load | "Boot sequence" in platform entry point context |
+| **Handoff** | Agent delegation, Agent chain | "Agent chain" when describing multi-hop delegation sequences |
+
+### Skill System
+
+| Canonical Term | Accepted Aliases | Notes |
+|----------------|-----------------|-------|
+| **HSOL** | Skill resolver, Matrix Skill Discovery | "Matrix Skill Discovery" is broader and less precise |
+| **Matrix Skill** | Static skill, Built-in skill, Curated skill | "Static" contrasts with "Dynamic"; "Curated" emphasizes maintainer review |
+| **Dynamic Skill** | Community skill, External skill | "Community" emphasizes origin; "External" emphasizes trust boundary |
+| **Skill Module** | Skill, Knowledge module | "Skill" alone is acceptable in context; "Knowledge module" in architecture docs |
+| **Trust Progression** | Trust lifecycle, Skill maturation | — |
+| **Fitness Score** | HSOL fitness, Skill fitness | Always clarify the 5-factor formula on first use |
+| **Superiority Delta** | Override threshold | "Override threshold" acceptable in configuration context |
+| **Profile** | Agent profile, HSOL profile | "HSOL profile" when discussing skill resolution specifically |
+| **find-skills** | Dynamic discovery, Skill finder | CLI usage always uses `find-skills` |
+| **Promotion** | Auto-promote, Skill graduation | "Graduation" is informal but evocative |
+
+### Team Protocol
+
+| Canonical Term | Accepted Aliases | Notes |
+|----------------|-----------------|-------|
+| **Golden Triangle** | Team protocol, Debate triangle | "Debate triangle" emphasizes the adversarial aspect |
+| **Mailbox** | Communication log, Message bus | "Message bus" is an analogy; technically it is a flat append-only file |
+| **Consensus Stamp** | Sign-off, Approval stamp | — |
+| **Debate Mechanism** | Review loop, Adversarial review | "Review loop" is less precise (could mean any review) |
+| **Shared Task List** | Task board, Work breakdown | "Work breakdown" acceptable in planning context |
+
+### Governance
+
+| Canonical Term | Accepted Aliases | Notes |
+|----------------|-----------------|-------|
+| **Orchestration Laws (L1–L10)** | Laws, Governance rules | Always include "(L1–L10)" on first reference in any document |
+| **Constraint Propagation (L9)** | Downstream locking | — |
+| **Stateful Handoff (L8)** | Phase immutability, Deliverable locking | "Deliverable locking" emphasizes the artifact freeze |
+| **Deliverable Integrity (L10)** | Output authority | — |
+| **Cognitive Anchor** | Binding block, Agent override | "Binding block" in template/authoring context |
+| **Requirements Registry** | Requirement list | "Requirement list" is less precise (lacks "structured table" connotation) |
+| **Anti-Pattern Registry (A1–A10)** | Forbidden patterns | Always include "(A1–A10)" on first reference |
+
+### Error Handling
+
+| Canonical Term | Accepted Aliases | Notes |
+|----------------|-----------------|-------|
+| **Error Classification (E1–E4)** | Error tiers, Self-healing | "Self-healing" specifically applies to E1/E2 auto-recovery |
+
+---
+
+## Deprecated Terms
+
+Terms that **must not** be used in new documentation. Replace all instances with the canonical alternative.
+
+| Deprecated Term | Replacement | Reason | Migration Guidance |
+|-----------------|-------------|--------|--------------------|
+| **Sub-agent** (when meaning individual agent) | **Agent** | "Sub-agent" conflates the individual agent concept with the TIER 1 `runSubagent` mechanism. An "agent" is a specialist role file; "sub-agent" is a TIER 1 execution mode. | Replace all instances of "sub-agent" meaning "a specialist" with "agent". Reserve "sub-agent" exclusively for TIER 1 `runSubagent` execution context. |
+| **Matrix Skill Discovery** (as HSOL synonym) | **HSOL** | "Matrix Skill Discovery" is vague and does not capture the hybrid (matrix + dynamic) nature of the resolution layer. | Replace with "HSOL" or "Hybrid Skill Orchestration Layer" on first reference. |
+
+---
+
+## Commonly Confused Terms
+
+Pairs or groups of terms that are frequently mixed up, with clarification on their distinct meanings.
+
+### Agent vs. Orchestrator
+
+| | Agent | Orchestrator |
+|---|-------|-------------|
+| **Role** | Executes specialized work | Coordinates and delegates |
+| **Count** | 21 specialists | Exactly 1 |
+| **Implements** | Yes — writes code, tests, reviews, etc. | Never — delegation only |
+| **Defined in** | `agents/*.md` | `rules/CORE.md` |
+| **Key distinction** | Agents DO the work | Orchestrator ROUTES the work |
+
+### TIER 1 vs. TIER 2
+
+| | TIER 1 | TIER 2 |
+|---|--------|--------|
+| **Mechanism** | `runSubagent` tool call | Read and embody agent file |
+| **Context** | Isolated (own context window) | Shared (Orchestrator's context) |
+| **Parallelism** | Supports parallel execution | Serial only |
+| **Preference** | Always preferred | Fallback only |
+| **Key distinction** | Isolated delegation | In-context role-play |
+
+### Matrix Skill vs. Dynamic Skill
+
+| | Matrix Skill | Dynamic Skill |
+|---|-------------|---------------|
+| **Source** | Maintainer-curated | Community-contributed |
+| **Trust** | Always 1.0 | Starts at 0.3, progresses |
+| **Registry** | `matrix-skills/{domain}.yaml` | `matrix-skills/_dynamic.yaml` |
+| **Promotion** | N/A (already matrix) | Can be promoted to matrix |
+| **Key distinction** | Built-in and trusted | External and earning trust |
+
+### Command vs. Variant vs. Phase
+
+| | Command | Variant | Phase |
+|---|---------|---------|-------|
+| **Granularity** | Workflow category | Execution strategy | Single work unit |
+| **Example** | `/cook` | `:team` | "Phase 3: Implementation" |
+| **File location** | `commands/{cmd}.md` | `commands/{cmd}/{variant}.md` | Defined within variant |
+| **Contains** | Routing logic | Phase sequence | Agent + exit criteria |
+| **Key distinction** | WHAT to do | HOW to do it | WHO does WHICH part |
+
+### Profile vs. Domain
+
+| | Profile | Domain |
+|---|---------|--------|
+| **Format** | `{domain}:{category}` | Single label |
+| **Scope** | Per-agent | Per-YAML file |
+| **Example** | `backend:api` | `backend` |
+| **Used by** | Agent frontmatter | Matrix skill registry |
+| **Key distinction** | Specific agent capability | Broad skill category |
+
+### Handoff vs. Stateful Handoff (L8)
+
+| | Handoff | Stateful Handoff (L8) |
+|---|---------|----------------------|
+| **Meaning** | Agent-to-agent delegation permission | Phase deliverable immutability rule |
+| **Scope** | Agent frontmatter `handoffs` array | Orchestration Law governing all phases |
+| **Key distinction** | WHO can delegate to WHOM | Once delivered, NOTHING changes |
+
+### Consensus Stamp vs. Debate Mechanism
+
+| | Consensus Stamp | Debate Mechanism |
+|---|----------------|-----------------|
+| **What** | Final approval artifact | Review cycle process |
+| **When** | End of team phase | During team phase |
+| **Rounds** | Single sign-off event | Up to 3 adversarial rounds |
+| **Key distinction** | The RESULT of agreement | The PROCESS of reaching agreement |
+
+---
+
+## Evidence Sources
+
+- `rules/CORE.md` — Orchestrator identity, Law definitions
+- `rules/AGENTS.md` — TIER 1/TIER 2 distinction, agent delegation
+- `rules/TEAMS.md` — Golden Triangle roles, mailbox, consensus
+- `rules/SKILLS.md` — HSOL, matrix vs. dynamic skills
+- `rules/PHASES.md` — Phase structure, variant execution
+- `agents/*.md` — Agent frontmatter structure, profile field
+- `matrix-skills/_index.yaml` — HSOL configuration
+- `matrix-skills/_dynamic.yaml` — Dynamic skill registry
+- `commands/*.md` — Command/variant/phase hierarchy