@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/business/business-features/04-dependencies-and-release-sequencing.md

@@ -0,0 +1,313 @@
+# Agent Assistant — Dependencies and Release Sequencing
+
+> **Purpose**: Feature dependency graph, release history mapping, and recommended rollout order for new installations
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Feature Dependency Graph
+
+```mermaid
+graph TD
+    BF001["BF-001<br/>Global Installation"] --> BF002["BF-002<br/>Multi-Platform (5)"]
+    BF001 --> BF003["BF-003<br/>Orchestrator Pattern"]
+    BF001 --> BF023["BF-023<br/>CLI List ⏳"]
+    
+    BF003 --> BF004["BF-004<br/>21 Agents"]
+    BF003 --> BF005["BF-005<br/>14 Commands"]
+    BF003 --> BF008["BF-008<br/>Tiered Execution"]
+    BF003 --> BF009["BF-009<br/>10 Laws"]
+    
+    BF004 --> BF007["BF-007<br/>HSOL Skills"]
+    BF004 --> BF010["BF-010<br/>Cognitive Anchoring"]
+    BF004 --> BF011["BF-011<br/>17 Teams"]
+    BF004 --> BF015["BF-015<br/>Docs Generation"]
+    BF004 --> BF019["BF-019<br/>Deploy Workflows"]
+    BF004 --> BF020["BF-020<br/>Autonomous /auto"]
+    BF004 --> BF021["BF-021<br/>Reporting"]
+    
+    BF005 --> BF006["BF-006<br/>4 Variants"]
+    BF005 --> BF017["BF-017<br/>NL Detection"]
+    BF005 --> BF022["BF-022<br/>Plan Short-Circuit"]
+    BF005 --> BF020
+    
+    BF006 --> BF011
+    
+    BF007 --> BF013["BF-013<br/>Dynamic Discovery"]
+    BF013 --> BF014["BF-014<br/>Trust Lifecycle"]
+    
+    BF011 --> BF016["BF-016<br/>Debate Mailbox"]
+    
+    BF012["BF-012<br/>Error Healing"]
+    BF018["BF-018<br/>Language L6"]
+
+    classDef must fill:#1a7f37,stroke:#1a7f37,color:#fff
+    classDef should fill:#0969da,stroke:#0969da,color:#fff
+    classDef could fill:#8250df,stroke:#8250df,color:#fff
+    classDef pending fill:#d1242f,stroke:#d1242f,color:#fff
+
+    class BF001,BF002,BF003,BF004,BF005,BF006,BF007,BF008,BF009,BF010 must
+    class BF011,BF012,BF013,BF014,BF015,BF016,BF017,BF018 should
+    class BF019,BF020,BF021,BF022 could
+    class BF023 pending
+```
+
+**Legend**: 🟢 Must Have | 🔵 Should Have | 🟣 Could Have | 🔴 Pending
+
+---
+
+## Dependency Matrix
+
+| Feature | Depends On | Depended On By |
+|---------|-----------|----------------|
+| BF-001 | (none — root) | BF-002, BF-003, BF-023 |
+| BF-002 | BF-001 | (none) |
+| BF-003 | BF-001 | BF-004, BF-005, BF-008, BF-009 |
+| BF-004 | BF-003 | BF-007, BF-010, BF-011, BF-015, BF-019, BF-020, BF-021 |
+| BF-005 | BF-003, BF-004 | BF-006, BF-017, BF-020, BF-022 |
+| BF-006 | BF-005 | BF-011 |
+| BF-007 | BF-004 | BF-013 |
+| BF-008 | BF-003 | (none) |
+| BF-009 | BF-003 | (none) |
+| BF-010 | BF-004 | (none) |
+| BF-011 | BF-004, BF-006 | BF-016 |
+| BF-012 | (none — standalone) | (none) |
+| BF-013 | BF-007 | BF-014 |
+| BF-014 | BF-013 | (none) |
+| BF-015 | BF-004, BF-005 | (none) |
+| BF-016 | BF-011 | (none) |
+| BF-017 | BF-005 | (none) |
+| BF-018 | (none — standalone) | (none) |
+| BF-019 | BF-004 | (none) |
+| BF-020 | BF-004, BF-005 | (none) |
+| BF-021 | BF-004 | (none) |
+| BF-022 | BF-005 | (none) |
+| BF-023 | BF-001 | (none) |
+
+### Standalone Features (No Inbound Dependencies)
+
+- **BF-012** (Error Self-Healing) — Defined in `rules/ERRORS.md`; operates independently
+- **BF-018** (Language Compliance) — CORE.md law; no feature dependency
+
+### Critical Path
+
+The longest dependency chain determines the minimum sequential delivery order:
+
+```
+BF-001 → BF-003 → BF-004 → BF-007 → BF-013 → BF-014
+  (6 features deep)
+```
+
+All features on this chain must ship in order. Parallel branches (BF-005→BF-006→BF-011→BF-016 and BF-008, BF-009, BF-010) can ship concurrently once their immediate dependency is met.
+
+---
+
+## Release History — Features per Version
+
+### v1.0.0 (2026-01-26) — Foundation Release
+
+| Feature | Description |
+|---------|-------------|
+| BF-001 | One-Time Global Installation |
+| BF-002 | Multi-Platform Support (Cursor, Copilot, Claude, Antigravity — 4 platforms) |
+| BF-003 | Orchestrator Pattern |
+| BF-004 | 21 Specialist Agents |
+| BF-005 | 14 Structured Commands |
+| BF-006 | Variant Strategies (`:fast`, `:hard` — partial) |
+| BF-007 | Matrix Skill Discovery (HSOL v1) |
+| BF-008 | Tiered Execution |
+| BF-009 | 10 Orchestration Laws |
+| BF-010 | Cognitive Anchoring |
+| BF-012 | Error Self-Healing (E1–E4) |
+| BF-015 | Documentation Generation (/docs) |
+| BF-017 | Natural Language Command Detection |
+| BF-018 | Language Compliance (L6) |
+
+**14 features delivered. All 10 Must Have features shipped in v1.0.0.**
+
+---
+
+### v1.0.2 (2026-01-28) — Focus Variants
+
+| Feature | Description |
+|---------|-------------|
+| BF-006 | `:focus` variant added (cook:focus, fix:focus) |
+
+---
+
+### v1.0.3 (2026-01-30) — Reporter
+
+| Feature | Description |
+|---------|-------------|
+| BF-021 | Reporting System (/report command + reporter agent) |
+
+---
+
+### v1.0.4 (2026-01-30) — Autonomy & Optimization
+
+| Feature | Description |
+|---------|-------------|
+| BF-020 | Autonomous Execution (/auto command) |
+| BF-022 | Plan Short-Circuit (skip research when plan exists) |
+
+---
+
+### v1.1.0 (2026-02-03) — HSOL v2
+
+| Feature | Description |
+|---------|-------------|
+| BF-007 | Matrix Skills rewrite — 19 domains, HSOL v2 algorithm |
+
+**Major enhancement of existing feature, not a new feature.**
+
+---
+
+### v1.2.0 (2026-03-09) — Teams & Codex
+
+| Feature | Description |
+|---------|-------------|
+| BF-002 | 5th platform: Codex added |
+| BF-006 | `:team` variant added |
+| BF-011 | 17 Domain Teams (Golden Triangle) |
+| BF-016 | Debate Mechanism (Mailbox) |
+| BF-019 | Deployment Workflows (/deploy) |
+
+**5 features delivered/enhanced. Largest feature release since v1.0.0.**
+
+---
+
+### v1.3.0 (2026-03-23) — Smart Skills
+
+| Feature | Description |
+|---------|-------------|
+| BF-007 | 1,430+ skills (expanded from 310+) |
+| BF-013 | Dynamic Skill Discovery |
+| BF-014 | Trust Progression Lifecycle |
+
+---
+
+### Not Yet Released
+
+| Feature | Description | Blocker |
+|---------|------------|---------|
+| BF-023 | CLI List Command | No blocker — low priority (Could Have) |
+
+---
+
+## Release Timeline Visualization
+
+```mermaid
+gantt
+    title Feature Release Timeline
+    dateFormat YYYY-MM-DD
+    axisFormat %Y-%m-%d
+    
+    section Must Have
+    BF-001 Global Install          :done, 2026-01-26, 1d
+    BF-002 Multi-Platform (4)      :done, 2026-01-26, 1d
+    BF-003 Orchestrator            :done, 2026-01-26, 1d
+    BF-004 21 Agents               :done, 2026-01-26, 1d
+    BF-005 14 Commands             :done, 2026-01-26, 1d
+    BF-006 fast+hard Variants      :done, 2026-01-26, 1d
+    BF-007 HSOL v1                 :done, 2026-01-26, 1d
+    BF-008 Tiered Execution        :done, 2026-01-26, 1d
+    BF-009 10 Laws                 :done, 2026-01-26, 1d
+    BF-010 Cognitive Anchoring     :done, 2026-01-26, 1d
+    
+    section Must Have (enhanced)
+    BF-006 +focus Variant          :done, 2026-01-28, 1d
+    BF-007 HSOL v2 Rewrite         :done, 2026-02-03, 1d
+    BF-002 +Codex Platform         :done, 2026-03-09, 1d
+    BF-006 +team Variant           :done, 2026-03-09, 1d
+    BF-007 1430+ Skills            :done, 2026-03-23, 1d
+    
+    section Should Have
+    BF-012 Error Healing           :done, 2026-01-26, 1d
+    BF-015 Docs Generation         :done, 2026-01-26, 1d
+    BF-017 NL Detection            :done, 2026-01-26, 1d
+    BF-018 Language L6             :done, 2026-01-26, 1d
+    BF-011 17 Teams                :done, 2026-03-09, 1d
+    BF-016 Debate Mailbox          :done, 2026-03-09, 1d
+    BF-013 Dynamic Discovery       :done, 2026-03-23, 1d
+    BF-014 Trust Lifecycle         :done, 2026-03-23, 1d
+    
+    section Could Have
+    BF-021 Reporting               :done, 2026-01-30, 1d
+    BF-020 Autonomous /auto        :done, 2026-01-30, 1d
+    BF-022 Plan Short-Circuit      :done, 2026-01-30, 1d
+    BF-019 Deploy Workflows        :done, 2026-03-09, 1d
+    BF-023 CLI List                :active, 2026-03-26, 7d
+```
+
+---
+
+## Recommended Rollout Order for New Installations
+
+For teams adopting agent-assistant for the first time, the recommended rollout sequence introduces features in dependency-safe batches:
+
+### Phase 1 — Foundation (Day 1)
+
+| Feature | Reason |
+|---------|--------|
+| BF-001 | Install the framework |
+| BF-002 | Configure target platforms |
+| BF-003 | Orchestrator loads at first session |
+| BF-004 | All 21 agents available immediately |
+| BF-009 | Laws enforce governance from session 1 |
+| BF-010 | Cognitive anchoring active in every agent |
+
+**Result**: Users can delegate tasks to specialist agents. All Must Have foundations in place.
+
+### Phase 2 — Structured Workflows (Day 1–2)
+
+| Feature | Reason |
+|---------|--------|
+| BF-005 | Learn core commands (start with `/cook`, `/fix`, `/test`) |
+| BF-006 | Start with `:fast` variant; graduate to `:hard` |
+| BF-008 | Tiered execution auto-detected per platform |
+| BF-012 | Error handling active from first run |
+| BF-017 | Natural language reduces learning curve |
+| BF-018 | Language compliance for international teams |
+
+**Result**: Full command workflow available. Users productive with structured development.
+
+### Phase 3 — Knowledge Layer (Week 1)
+
+| Feature | Reason |
+|---------|--------|
+| BF-007 | HSOL skill injection enriches agent output |
+| BF-015 | Generate project documentation |
+| BF-022 | Use plans to skip redundant research |
+
+**Result**: Agents produce domain-specific, high-quality output. Documentation generated.
+
+### Phase 4 — Advanced Quality (Week 2+)
+
+| Feature | Reason |
+|---------|--------|
+| BF-011 | Introduce `:team` variant for critical features |
+| BF-016 | Debate mechanism ensures adversarial review |
+| BF-013 | Dynamic discovery extends skill coverage |
+| BF-014 | Trust lifecycle governs community skills |
+| BF-019 | Structured deployment for production releases |
+| BF-020 | Autonomous execution for experienced users |
+| BF-021 | Automated reporting for team visibility |
+
+**Result**: Full framework capability. Adversarial quality, ecosystem skills, deployment automation.
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| CHANGELOG (release history) | [../../CHANGELOG.md](../../CHANGELOG.md) |
+| Structured Business Pack | [../../reports/business-analysis/structured-business-pack.md](../../reports/business-analysis/structured-business-pack.md) |
+| Knowledge overview — features | [../knowledge-overview/03-features.md](../knowledge-overview/03-features.md) |
+| PRD — goals and scope | [../business-prd/02-problem-goals-and-scope.md](../business-prd/02-problem-goals-and-scope.md) |
+| CORE rules | [../../rules/CORE.md](../../rules/CORE.md) |
+| SKILLS rules | [../../rules/SKILLS.md](../../rules/SKILLS.md) |
+| TEAMS rules | [../../rules/TEAMS.md](../../rules/TEAMS.md) |
+| CLI installer | [../../cli/install.js](../../cli/install.js) |

package/documents/business/business-features/05-success-metrics.md

@@ -0,0 +1,290 @@
+# Agent Assistant — Success Metrics
+
+> **Purpose**: KPIs per feature with baselines, targets, measurement approach, and validation status
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Validation Status Legend
+
+| Status | Meaning |
+|--------|---------|
+| ✅ VALIDATED | Metric measured and confirmed through testing or production use |
+| ⚠️ SELF-REPORTED | Metric claimed in documentation but not independently verified |
+| ❌ UNVALIDATED | No measurement performed; target is aspirational |
+| 📐 STRUCTURAL | Metric is a count or structural check verifiable by inspection |
+
+---
+
+## Must Have Features — Metrics
+
+### BF-001 — One-Time Global Installation
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Installation success rate | N/A (new product) | 100% on all 5 platforms | Run `install --all` on clean systems per platform | 📐 STRUCTURAL |
+| Per-project config required | Manual setup per project | Zero (0 files per project) | Verify no project-level files needed after global install | 📐 STRUCTURAL |
+| Installation time | N/A | < 60 seconds | Time `npm run install:all` end-to-end | ❌ UNVALIDATED |
+| Platform file count | N/A | All framework files copied | Diff source vs installed directory | 📐 STRUCTURAL |
+
+---
+
+### BF-002 — Multi-Platform Support (5 Platforms)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Platforms supported | 0 | 5 (Cursor, Copilot, Claude, Codex, Antigravity) | Count entries in CLI `TOOLS` config | ✅ VALIDATED |
+| Command parity across platforms | N/A | 100% — identical command set on each | Execute all 14 commands on each platform; compare output structure | ❌ UNVALIDATED |
+| Placeholder resolution | Raw `{TOOL}` in files | Zero unresolved placeholders post-install | Grep installed files for `{TOOL}` pattern | 📐 STRUCTURAL |
+
+---
+
+### BF-003 — Orchestrator Pattern
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Direct implementation rate | AI writes code by default | 0% — Orchestrator always delegates | Audit session transcripts for Orchestrator-authored code | ⚠️ SELF-REPORTED |
+| Time-to-production improvement | Manual AI prompting baseline | 70% faster | Compare task completion time with/without framework | ⚠️ SELF-REPORTED |
+| Bug rate reduction | Manual AI prompting baseline | 70% reduction | Compare defect rate in outputs with/without framework | ⚠️ SELF-REPORTED |
+
+---
+
+### BF-004 — 21 Specialist Agents
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Agent count | 0 | 21 specialist + 51 team = 72 total | Count files in `agents/` and `agents/teams/` | ✅ VALIDATED |
+| Profile completeness | N/A | 100% — every agent has profile, directive, protocol, constraints | Parse agent files for required sections | 📐 STRUCTURAL |
+| Domain coverage | No specialization | 5 categories (implementation, architecture, quality, planning, support) | Map agents to categories | ✅ VALIDATED |
+
+---
+
+### BF-005 — 14 Structured Commands
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Command count | 0 | 14 | Count files in `commands/` | ✅ VALIDATED |
+| Routing accuracy | N/A | 100% — all commands route to correct variant | Test each command with each variant specification | ❌ UNVALIDATED |
+| Variant coverage | N/A | Up to 54 total variants | Count variant files across all command subdirectories | 📐 STRUCTURAL |
+
+---
+
+### BF-006 — 4 Variant Strategies
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Variants per command | 1 (no variants) | Up to 4 (fast, hard, focus, team) | Count variant files per command directory | ✅ VALIDATED |
+| Agent scaling | Fixed | `:fast` 2–3, `:hard` 5–8, `:team` 3 per team | Verify agent count in variant file phase definitions | 📐 STRUCTURAL |
+| Quality gate presence | None | `:hard` includes test + review + security gates | Parse `:hard` variant files for gate definitions | 📐 STRUCTURAL |
+
+---
+
+### BF-007 — Matrix Skill Discovery (HSOL)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Skill count | 0 | 1,430+ | Count directories in `skills/` | ✅ VALIDATED |
+| Domain count | 0 | 19 | Count YAML files in `matrix-skills/` (excluding meta files) | ✅ VALIDATED |
+| Token cost savings | Generic AI prompting | 85% savings | Compare prompt token usage with/without HSOL skill injection | ⚠️ SELF-REPORTED |
+| Fitness threshold | N/A | ≥ 0.8 for skill inclusion | Verify threshold in `rules/SKILLS.md` | 📐 STRUCTURAL |
+
+---
+
+### BF-008 — Tiered Execution
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| TIER 1 usage on capable platforms | N/A | 100% when `runSubagent` available | Verify TIER 1 mandatory rule in CORE.md | 📐 STRUCTURAL |
+| TIER 2 fallback reliability | N/A | 100% — execution succeeds when TIER 1 unavailable | Test on non-sub-agent platform | ❌ UNVALIDATED |
+| Parallel execution speedup | Sequential (1×) | Up to 3× on TIER 1 (3 parallel agents) | Time multi-agent tasks on TIER 1 vs TIER 2 | ❌ UNVALIDATED |
+
+---
+
+### BF-009 — 10 Orchestration Laws
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Law count | 0 | 10 | Count laws in `rules/CORE.md` | ✅ VALIDATED |
+| Enforcement rate | N/A | 100% — all laws active every session | Verify mandatory boot sequence loads CORE.md | 📐 STRUCTURAL |
+| Violation rate | N/A | 0 violations per session | Audit session transcripts for law violations | ❌ UNVALIDATED |
+
+---
+
+### BF-010 — Cognitive Anchoring
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Agents with anchor block | 0 | 21/21 (100%) | Parse agent files for cognitive anchor section | 📐 STRUCTURAL |
+| Role drift incidents | Unanchored AI drifts frequently | Zero drift per session | Audit long sessions for agent identity loss | ❌ UNVALIDATED |
+
+---
+
+## Should Have Features — Metrics
+
+### BF-011 — 17 Domain Teams (Golden Triangle)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Team count | 0 | 17 | Count directories in `agents/teams/` | ✅ VALIDATED |
+| Team agent count | 0 | 51 (17 × 3) | Count agent files in team directories | ✅ VALIDATED |
+| Defect detection improvement | Single-agent review baseline | Measurable improvement over `:hard` variant | Compare defect escape rate `:team` vs `:hard` | ❌ UNVALIDATED |
+
+---
+
+### BF-012 — Error Self-Healing (E1–E4)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Error classes defined | 0 | 4 (E1–E4) | Parse `rules/ERRORS.md` | ✅ VALIDATED |
+| Silent failure rate | Unknown | 0 — all errors surfaced | Audit sessions for unreported errors | ❌ UNVALIDATED |
+| Auto-recovery rate (E1+E2) | N/A | ≥ 80% of recoverable errors auto-resolved | Track E1/E2 recovery outcomes | ❌ UNVALIDATED |
+
+---
+
+### BF-013 — Dynamic Skill Discovery
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Discovery trigger threshold | N/A | Fitness < 0.8 | Verify in `rules/SKILLS.md` | 📐 STRUCTURAL |
+| Community skills discovered | 0 | Grows over time | Count entries in `matrix-skills/_dynamic.yaml` | ❌ UNVALIDATED |
+| Offline fallback success | N/A | 100% — graceful degradation | Test with network disabled | ❌ UNVALIDATED |
+
+---
+
+### BF-014 — Trust Progression Lifecycle
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Lifecycle stages | 0 | 4 (NEW → EVALUATING → VALIDATED → PROMOTED) | Verify in `rules/SKILLS.md` | 📐 STRUCTURAL |
+| Skills promoted | 0 | Grows with community usage | Count PROMOTED entries in `_dynamic.yaml` | ❌ UNVALIDATED |
+| False promotion rate | N/A | 0 — no skill promoted without successful validation | Audit promotion criteria | ❌ UNVALIDATED |
+
+---
+
+### BF-015 — Documentation Generation (/docs)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Doc folder types | 0 | 3 categories (Core 5, Business 4+, Audit 4) | Count generated folder structure | 📐 STRUCTURAL |
+| Generation completeness | Manual docs | All specified folders populated | Verify non-empty output per folder | ❌ UNVALIDATED |
+| Update idempotency | N/A | Re-running `/docs` updates, not duplicates | Run twice; compare output | ❌ UNVALIDATED |
+
+---
+
+### BF-016 — Debate Mechanism (Mailbox)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Message types | 0 | 6 (TASK_ASSIGNMENT, SUBMISSION, REVIEW, DEFENSE, ARBITRATION, DECISION) | Parse `rules/TEAMS.md` | ✅ VALIDATED |
+| Max debate rounds | Unlimited | 3 | Verify in `rules/TEAMS.md` | 📐 STRUCTURAL |
+| Convergence rate | N/A | ≥ 90% consensus within 3 rounds | Track round counts across team executions | ❌ UNVALIDATED |
+
+---
+
+### BF-017 — Natural Language Command Detection
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Intent mapping accuracy | N/A | ≥ 95% correct routing | Test corpus of natural language inputs | ❌ UNVALIDATED |
+| Supported intents | 0 | All 14 commands reachable via natural language | Verify mapping table in CORE.md | 📐 STRUCTURAL |
+
+---
+
+### BF-018 — Language Compliance (L6)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Response language match | English only | Matches user's language | Test with non-English prompts | ❌ UNVALIDATED |
+| Code language | N/A | Always English | Audit generated code for non-English content | ❌ UNVALIDATED |
+
+---
+
+## Could Have Features — Metrics
+
+### BF-019 — Deployment Workflows (/deploy)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Deploy variants | 0 | 4 (check, preview, production, rollback) | Count variant files in `commands/deploy/` | ✅ VALIDATED |
+| Pre-deployment check coverage | Manual checklists | Automated validation of environment, config, deps | Audit check variant output | ❌ UNVALIDATED |
+
+---
+
+### BF-020 — Autonomous Execution (/auto)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Classification accuracy | N/A | ≥ 90% correct command selection | Test with varied task descriptions | ❌ UNVALIDATED |
+| Human intervention rate | 100% (manual routing) | < 10% (only ambiguous cases) | Track fallback-to-user events in `/auto` | ❌ UNVALIDATED |
+
+---
+
+### BF-021 — Reporting System (/report)
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Report variants | 0 | 4 (auto, fast, hard, focus) | Count variant files | ✅ VALIDATED |
+| Report accuracy | Manual reports | Grounded in project state | Compare report assertions to actual codebase state | ❌ UNVALIDATED |
+
+---
+
+### BF-022 — Plan Short-Circuit
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Phases skipped | 0 | 3 (research, scout, brainstorm) when plan exists | Verify skip logic in code command files | 📐 STRUCTURAL |
+| Token savings | Full pipeline tokens | Measurable reduction when plan provided | Compare token usage with/without plan | ❌ UNVALIDATED |
+
+---
+
+### BF-023 — CLI List Command
+
+| KPI | Baseline | Target | Measurement | Status |
+|-----|----------|--------|-------------|--------|
+| Platforms detected | N/A | All 5 platforms accurately reported | Run CLI list; compare to filesystem state | ❌ UNVALIDATED |
+
+**Status**: NOT YET IMPLEMENTED — all metrics are targets for future validation.
+
+---
+
+## Metrics Summary by Validation Status
+
+| Status | Count | Features Affected |
+|--------|-------|-------------------|
+| ✅ VALIDATED | 12 | BF-002, BF-004, BF-005, BF-006, BF-007, BF-009, BF-011, BF-012, BF-016, BF-019, BF-021 |
+| ⚠️ SELF-REPORTED | 4 | BF-003 (70% faster, 70% bugs), BF-007 (85% tokens) |
+| 📐 STRUCTURAL | 22 | All features (structural checks always verifiable) |
+| ❌ UNVALIDATED | 28 | Most behavioral and performance metrics |
+
+### Key Observation
+
+The majority of **structural metrics** (counts, file presence, configuration values) are easily validated by script or inspection. The **behavioral metrics** (accuracy, speed, defect rates) require controlled experiments that have not been conducted. The three **self-reported performance claims** (70% time reduction, 70% bug reduction, 85% token savings) are the highest-risk metrics — they drive the product's value proposition but lack independent verification.
+
+### Recommended Measurement Plan
+
+| Priority | Action | Metrics Covered |
+|----------|--------|-----------------|
+| 1 | Build automated structural validation script | All 📐 STRUCTURAL metrics |
+| 2 | Design A/B test: framework vs manual prompting | BF-003 time/bug claims, BF-007 token claims |
+| 3 | Instrument `:team` sessions for debate round tracking | BF-016 convergence rate |
+| 4 | Create NL intent test corpus | BF-017 accuracy |
+| 5 | Run `/auto` classification tests | BF-020 accuracy |
+| 6 | Measure TIER 1 vs TIER 2 execution time | BF-008 parallel speedup |
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Structured Business Pack (metrics section) | [../../reports/business-analysis/structured-business-pack.md](../../reports/business-analysis/structured-business-pack.md) |
+| Knowledge overview — features and metrics | [../knowledge-overview/03-features.md](../knowledge-overview/03-features.md) |
+| README (performance claims) | [../../README.md](../../README.md) |
+| HSOL Assessment (skill metrics) | [../HSOL-ASSESSMENT.md](../HSOL-ASSESSMENT.md) |
+| CORE rules (laws, tiered execution) | [../../rules/CORE.md](../../rules/CORE.md) |
+| SKILLS rules (HSOL thresholds) | [../../rules/SKILLS.md](../../rules/SKILLS.md) |
+| TEAMS rules (debate protocol) | [../../rules/TEAMS.md](../../rules/TEAMS.md) |
+| ERRORS rules (classification) | [../../rules/ERRORS.md](../../rules/ERRORS.md) |
+| CHANGELOG | [../../CHANGELOG.md](../../CHANGELOG.md) |

package/documents/business/business-glossary/00-index.md

@@ -0,0 +1,89 @@
+# Agent Assistant — Business Glossary Index
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Master index for the canonical business glossary of the agent-assistant framework |
+| **Parent** | [../README.md](../README.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## Quick Summary
+
+This glossary establishes the **single source of truth** for all domain terminology used across the @namch/agent-assistant v1.3.0 framework. It canonicalizes 35+ terms spanning orchestration, agent delegation, skill resolution, team protocols, governance, and error handling. The glossary serves as the authoritative reference for documentation authors, agent definitions, command workflows, and platform integrations.
+
+---
+
+## Sub-Files
+
+| # | File | Description |
+|---|------|-------------|
+| 01 | [01-canonical-terms.md](01-canonical-terms.md) | All 35+ canonical terms with formal definitions organized by category |
+| 02 | [02-synonyms-and-deprecated-terms.md](02-synonyms-and-deprecated-terms.md) | Complete alias table, deprecated terms with replacement guidance, confused terms |
+| 03 | [03-domain-entities-and-events.md](03-domain-entities-and-events.md) | Entity vocabulary, event vocabulary, entity-event interaction matrix |
+| 04 | [04-api-term-mapping.md](04-api-term-mapping.md) | Domain term to technical implementation mapping (files, YAML fields, CLI args) |
+
+---
+
+## Key Facts
+
+| Metric | Value |
+|--------|-------|
+| Canonical Terms | 35+ |
+| Term Categories | 6 (Core Concepts, Execution Model, Skill System, Team Protocol, Governance, Error Handling) |
+| Domain Entities | 12 |
+| Domain Events | 11 |
+| Skill Domains | 19 |
+| Deprecated Terms | 2 |
+| Known Aliases | 70+ |
+| API Mappings | 9 primary + CLI + prompt + HSOL config |
+
+---
+
+## Cross-References
+
+| Glossary Area | Related Documents |
+|---------------|-------------------|
+| Orchestrator, Agent, Command | `rules/CORE.md`, `rules/AGENTS.md`, `rules/PHASES.md` |
+| HSOL, Matrix Skill, Dynamic Skill | `matrix-skills/_index.yaml`, `matrix-skills/_dynamic.yaml` |
+| Golden Triangle, Mailbox, Consensus | `rules/TEAMS.md`, `agents/teams/` |
+| Orchestration Laws (L1–L10) | `rules/CORE.md` |
+| Error Classification (E1–E4) | `rules/ERRORS.md` |
+| Commands, Variants, Phases | `commands/*.md`, `commands/{cmd}/*.md`, `rules/PHASES.md` |
+| Platform Entry Points | `CLAUDE.md`, `CURSOR.md`, `COPILOT.md`, `CODEX.md`, `GEMINI.md` |
+| Tiered Execution | `rules/AGENTS.md` |
+| Trust Progression, Promotion | `matrix-skills/_index.yaml` `hsol.trust` |
+| Requirements Registry | `rules/PHASES.md` |
+| Anti-Pattern Registry | `rules/CORE.md` |
+| Business Workflows | `documents/business/business-workflows/` |
+
+---
+
+## Known Gaps
+
+| Gap | Description | Priority |
+|-----|-------------|----------|
+| **CLI sub-commands** | `install`, `uninstall`, `list`, `update` sub-command terminology not yet canonicalized beyond `find-skills` | Medium |
+| **Platform-specific overrides** | Terminology differences across Claude, Cursor, Copilot, Codex, Gemini entry points not fully mapped | Medium |
+| **Skill metadata fields** | Not all YAML fields in SKILL.md files have been mapped to glossary terms (e.g., `tags`, `version`, `author`) | Low |
+| **Team variant naming** | Naming conventions for team folders under `agents/teams/` not formally defined | Low |
+| **Error recovery actions** | Specific recovery action vocabulary (retry, escalate, abort) not canonicalized | Low |
+| **Versioning terminology** | No canonical terms for version progression, breaking changes, or migration paths | Low |
+
+---
+
+## Evidence Sources
+
+- `rules/CORE.md` — Orchestration Laws, identity, prohibitions
+- `rules/AGENTS.md` — Tiered execution, agent delegation
+- `rules/PHASES.md` — Phase structure, deliverable format
+- `rules/TEAMS.md` — Golden Triangle, mailbox, consensus
+- `rules/ERRORS.md` — Error classification E1–E4
+- `rules/SKILLS.md` — HSOL resolution, fitness scoring
+- `matrix-skills/_index.yaml` — HSOL configuration, trust, fitness weights
+- `matrix-skills/_dynamic.yaml` — Dynamic skill registry
+- `agents/*.md` — Agent file structure, profile, handoffs
+- `commands/*.md` — Command routing, variant structure
+- `package.json` — Project metadata v1.3.0
+- `README.md` — Project overview, feature summary