@zigrivers/scaffold 3.8.0 → 3.9.1

package/content/knowledge/ml/ml-testing.md

@@ -0,0 +1,301 @@
+---
+name: ml-testing
+description: Unit tests for data transforms, tolerance-based model tests, pipeline integration tests, and regression tests for ML systems
+topics: [ml, testing, unit-tests, model-tests, pipeline-tests, regression-tests, tdd]
+---
+
+ML code is tested less rigorously than traditional software because "the model is probabilistic" feels like an excuse for skipping tests. It is not. The vast majority of ML code — data transforms, preprocessing, feature engineering, postprocessing, and serving logic — is deterministic and must be unit tested. The probabilistic parts — model weights and accuracy — require tolerance-based tests and regression baselines. Untested ML pipelines fail silently in ways that are expensive to diagnose in production.
+
+## Summary
+
+Test ML systems at four levels: unit tests for deterministic components (transforms, metrics, preprocessing), model tests using tolerance-based assertions (output shape, value range, basic accuracy on canonical examples), pipeline tests (end-to-end training and inference on small data), and regression tests (compare new model against production baseline). Use `pytest` with `torch.testing` and `numpy.testing` for numerical assertions. Run tests in CI on every commit.
+
+## Deep Guidance
+
+### What to Test in ML
+
+**Always unit test**:
+- Data loading and preprocessing transforms
+- Feature engineering functions
+- Custom loss functions
+- Metric computation functions
+- Postprocessing logic (thresholding, calibration)
+- Model architecture components (custom layers, attention mechanisms)
+
+**Always model test** (tolerance-based):
+- Model output shape matches expected shape
+- Output values are in valid range (probabilities sum to 1, logits are finite)
+- Model forward pass runs without error
+- Model handles edge cases (empty input, max-length input, all-zero input)
+- Basic sanity check: model achieves above-chance accuracy on a canonical small dataset
+
+**Always pipeline test**:
+- Full training pipeline runs on a tiny dataset without error
+- Checkpoint save and load produces identical predictions
+- Inference pipeline produces output in the correct format
+
+**Always regression test**:
+- New model version's accuracy on held-out test set does not regress beyond a threshold vs. the current production baseline
+
+### Unit Tests for Data Transforms
+
+```python
+# tests/test_transforms.py
+import pytest
+import numpy as np
+import torch
+from src.data.transforms import (
+    Normalizer,
+    TextTokenizer,
+    ImageAugmenter,
+)
+
+class TestNormalizer:
+    def test_zero_mean(self):
+        """Normalized features should have near-zero mean on training data."""
+        X = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
+        norm = Normalizer()
+        norm.fit(X)
+        X_norm = norm.transform(X)
+        np.testing.assert_allclose(X_norm.mean(axis=0), 0.0, atol=1e-6)
+
+    def test_unit_std(self):
+        """Normalized features should have unit standard deviation."""
+        X = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
+        norm = Normalizer()
+        norm.fit(X)
+        X_norm = norm.transform(X)
+        np.testing.assert_allclose(X_norm.std(axis=0), 1.0, atol=1e-6)
+
+    def test_transform_without_fit_raises(self):
+        """Transform before fit must raise a clear error."""
+        norm = Normalizer()
+        with pytest.raises(RuntimeError, match="fit"):
+            norm.transform(np.array([[1.0, 2.0]]))
+
+    def test_inverse_transform_roundtrip(self):
+        """fit + transform + inverse_transform should return original values."""
+        X = np.random.rand(100, 5) * 10.0
+        norm = Normalizer()
+        norm.fit(X)
+        X_rt = norm.inverse_transform(norm.transform(X))
+        np.testing.assert_allclose(X_rt, X, rtol=1e-5)
+
+    def test_no_fit_leakage_to_test_data(self):
+        """Test data stats must not affect normalisation parameters."""
+        X_train = np.array([[1.0], [2.0], [3.0]])
+        X_test = np.array([[100.0], [200.0]])  # Very different distribution
+        norm = Normalizer()
+        norm.fit(X_train)
+        X_test_norm = norm.transform(X_test)
+        # Test data should be normalised using TRAINING stats only
+        assert np.all(np.abs(X_test_norm) > 1.0)  # Large because distribution is different
+
+
+class TestTextTokenizer:
+    def test_output_shape(self):
+        """Tokenizer must produce correct sequence length."""
+        tokenizer = TextTokenizer(max_length=128)
+        result = tokenizer("Hello world, this is a test.")
+        assert result["input_ids"].shape == (128,)
+        assert result["attention_mask"].shape == (128,)
+
+    def test_truncation(self):
+        """Long inputs must be truncated to max_length."""
+        tokenizer = TextTokenizer(max_length=8)
+        long_text = " ".join(["word"] * 100)
+        result = tokenizer(long_text)
+        assert result["input_ids"].shape == (8,)
+
+    def test_empty_input(self):
+        """Empty string must not raise an exception."""
+        tokenizer = TextTokenizer(max_length=128)
+        result = tokenizer("")
+        assert result["input_ids"].shape == (128,)
+        # All tokens after CLS should be PAD
+        assert result["attention_mask"].sum() <= 2  # Only CLS and/or SEP attended
+```
+
+### Model Tests
+
+```python
+# tests/test_model.py
+import pytest
+import torch
+import torch.nn.functional as F
+from src.models.classifier import TextClassifier
+
+@pytest.fixture
+def model():
+    return TextClassifier(vocab_size=1000, hidden_dim=64, num_classes=3)
+
+@pytest.fixture
+def batch():
+    return {
+        "input_ids": torch.randint(0, 1000, (4, 128)),
+        "attention_mask": torch.ones(4, 128, dtype=torch.long),
+    }
+
+class TestTextClassifier:
+    def test_output_shape(self, model, batch):
+        """Model output shape must match (batch_size, num_classes)."""
+        output = model(**batch)
+        assert output.shape == (4, 3)
+
+    def test_output_finite(self, model, batch):
+        """Model output must not contain NaN or Inf."""
+        output = model(**batch)
+        assert torch.all(torch.isfinite(output)), "Model output contains NaN or Inf"
+
+    def test_probabilities_sum_to_one(self, model, batch):
+        """Softmax probabilities must sum to 1."""
+        logits = model(**batch)
+        probs = F.softmax(logits, dim=-1)
+        torch.testing.assert_close(
+            probs.sum(dim=-1),
+            torch.ones(4),
+            atol=1e-5,
+            rtol=1e-5,
+        )
+
+    def test_different_inputs_different_outputs(self, model):
+        """Different inputs must produce different outputs (model is not constant)."""
+        batch_a = {"input_ids": torch.zeros(2, 128, dtype=torch.long),
+                   "attention_mask": torch.ones(2, 128, dtype=torch.long)}
+        batch_b = {"input_ids": torch.ones(2, 128, dtype=torch.long),
+                   "attention_mask": torch.ones(2, 128, dtype=torch.long)}
+        output_a = model(**batch_a)
+        output_b = model(**batch_b)
+        assert not torch.allclose(output_a, output_b), "Model outputs identical for different inputs"
+
+    def test_eval_mode_deterministic(self, model, batch):
+        """Same input in eval mode must produce identical outputs (no dropout randomness)."""
+        model.eval()
+        with torch.no_grad():
+            output_1 = model(**batch)
+            output_2 = model(**batch)
+        torch.testing.assert_close(output_1, output_2)
+
+    def test_gradient_flows(self, model, batch):
+        """Gradients must flow to all parameters during backward pass."""
+        model.train()
+        logits = model(**batch)
+        loss = logits.sum()
+        loss.backward()
+        for name, param in model.named_parameters():
+            if param.requires_grad:
+                assert param.grad is not None, f"No gradient for parameter: {name}"
+                assert torch.any(param.grad != 0), f"Zero gradient for parameter: {name}"
+```
+
+### Pipeline Tests
+
+```python
+# tests/test_pipeline.py
+import pytest
+import tempfile
+import os
+from omegaconf import OmegaConf
+from src.training.trainer import Trainer
+
+@pytest.fixture
+def tiny_config():
+    """Minimal config for fast pipeline smoke test."""
+    return OmegaConf.create({
+        "training": {"epochs": 2, "batch_size": 4, "seed": 42},
+        "optimizer": {"type": "adam", "lr": 1e-3},
+        "data": {"num_samples": 32},  # Tiny dataset
+    })
+
+class TestTrainingPipeline:
+    def test_training_runs_without_error(self, tiny_config, tmp_path):
+        """Full training pipeline must complete without error on tiny data."""
+        trainer = Trainer(cfg=tiny_config, output_dir=str(tmp_path))
+        result = trainer.fit()
+        assert "val_loss" in result
+        assert result["val_loss"] < float("inf")
+
+    def test_checkpoint_saves_and_loads(self, tiny_config, tmp_path):
+        """Checkpoint must be saved and restored with identical predictions."""
+        trainer = Trainer(cfg=tiny_config, output_dir=str(tmp_path))
+        trainer.fit()
+
+        checkpoint_path = tmp_path / "best.pt"
+        assert checkpoint_path.exists(), "Checkpoint was not saved"
+
+        # Load checkpoint and verify predictions are identical
+        import torch
+        from src.models.classifier import TextClassifier
+        model_a = trainer.model
+        model_b = TextClassifier.from_checkpoint(str(checkpoint_path))
+
+        test_input = torch.randint(0, 1000, (2, 128))
+        model_a.eval()
+        model_b.eval()
+        with torch.no_grad():
+            torch.testing.assert_close(model_a(test_input), model_b(test_input))
+
+    def test_inference_pipeline_output_format(self, tiny_config, tmp_path):
+        """Inference pipeline must return predictions in expected format."""
+        trainer = Trainer(cfg=tiny_config, output_dir=str(tmp_path))
+        trainer.fit()
+
+        from src.serving.predictor import Predictor
+        predictor = Predictor(str(tmp_path / "best.pt"))
+        result = predictor.predict({"text": "test input"})
+
+        assert hasattr(result, "prediction")
+        assert hasattr(result, "confidence")
+        assert 0.0 <= result.confidence <= 1.0
+```
+
+### Regression Tests
+
+```python
+# tests/test_regression.py
+"""
+Regression tests compare a new model version against the production baseline.
+Run these before promoting any model to staging.
+"""
+import pytest
+import numpy as np
+from src.evaluation.evaluator import evaluate_model
+from src.models.classifier import TextClassifier
+
+PRODUCTION_BASELINE = {
+    "accuracy": 0.872,
+    "f1": 0.864,
+    "roc_auc": 0.934,
+}
+REGRESSION_TOLERANCE = 0.02  # Allow up to 2pp regression
+
+class TestModelRegression:
+    @pytest.fixture(scope="class")
+    def candidate_metrics(self, holdout_dataset):
+        """Evaluate the candidate model on the holdout set."""
+        model = TextClassifier.from_registry("candidate")
+        return evaluate_model(model, holdout_dataset)
+
+    def test_accuracy_no_regression(self, candidate_metrics):
+        threshold = PRODUCTION_BASELINE["accuracy"] - REGRESSION_TOLERANCE
+        assert candidate_metrics["accuracy"] >= threshold, (
+            f"Accuracy regression: {candidate_metrics['accuracy']:.3f} < {threshold:.3f}"
+        )
+
+    def test_f1_no_regression(self, candidate_metrics):
+        threshold = PRODUCTION_BASELINE["f1"] - REGRESSION_TOLERANCE
+        assert candidate_metrics["f1"] >= threshold
+
+    def test_roc_auc_no_regression(self, candidate_metrics):
+        threshold = PRODUCTION_BASELINE["roc_auc"] - REGRESSION_TOLERANCE
+        assert candidate_metrics["roc_auc"] >= threshold
+```
+
+### Testing Best Practices for ML
+
+- **Test data must not touch training data**: Use a separate fixture dataset for tests, not samples from the training set
+- **Tests must be fast**: Unit and model tests must run in < 10 seconds total; use tiny models and tiny data
+- **Parametrize for edge cases**: Use `@pytest.mark.parametrize` to test multiple input types (empty, max-length, all-zeros, all-ones)
+- **Numerical precision**: Use `rtol`/`atol` tolerances in `numpy.testing.assert_allclose` and `torch.testing.assert_close` — never use `==` for floats
+- **Mock heavy dependencies**: Mock database connections, S3 calls, and MLflow logging in unit tests — tests must not require external services to run
+- **CI enforcement**: Run `pytest tests/` in CI on every commit; block PRs that break tests

package/content/knowledge/ml/ml-training-patterns.md

@@ -0,0 +1,269 @@
+---
+name: ml-training-patterns
+description: Data loaders, training loops, distributed training with DDP and FSDP, checkpointing strategies, and hyperparameter tuning patterns
+topics: [ml, training, data-loaders, distributed-training, ddp, fsdp, checkpointing, hyperparameter-tuning]
+---
+
+The training loop is the heart of every ML project, but it is also where most bugs hide: data leaking between splits, gradients not zeroed, mixed precision overflows, checkpoints saved incorrectly, and distributed training hanging on a single slow worker. These are not exotic edge cases — they are the standard bugs that every ML engineer encounters. A well-structured training pipeline prevents them through clear separation of concerns and defensive coding.
+
+## Summary
+
+Build training pipelines with properly configured data loaders (worker count, pinned memory, prefetch), clean training loops with explicit gradient management, mixed precision for efficiency, and robust checkpointing. For large models or large datasets, use PyTorch DDP for multi-GPU training or FSDP for models too large to fit on a single GPU. Manage hyperparameter search with a systematic tool (Optuna, Ray Tune, W&B Sweeps) rather than manual iteration.
+
+## Deep Guidance
+
+### Data Loaders
+
+`torch.utils.data.DataLoader` is the standard interface for batched data loading. Configure it correctly:
+
+```python
+from torch.utils.data import DataLoader
+from src.data.dataset import MyDataset
+
+def build_dataloader(
+    dataset: MyDataset,
+    batch_size: int,
+    split: str,
+    num_workers: int = 4,
+) -> DataLoader:
+    is_train = split == "train"
+    return DataLoader(
+        dataset,
+        batch_size=batch_size,
+        shuffle=is_train,           # Shuffle only training data
+        num_workers=num_workers,     # Parallel data loading workers
+        pin_memory=True,             # Pin CPU memory for faster GPU transfer
+        prefetch_factor=2,           # Prefetch 2 batches per worker
+        persistent_workers=True,     # Keep workers alive between epochs
+        drop_last=is_train,          # Drop incomplete final batch (training only)
+    )
+```
+
+**`num_workers` guidance**:
+- Start with `min(os.cpu_count(), 8)` and tune from there
+- Set to 0 for debugging (single-process, easier stack traces)
+- On Windows, set to 0 if you encounter multiprocessing issues
+- Bottleneck check: if GPU utilisation < 80%, increase workers or enable prefetch
+
+**Common data loader bugs**:
+- Using `shuffle=True` on validation/test sets (breaks reproducibility checks)
+- Not setting `worker_init_fn` when using random augmentation in workers (workers share the same seed without this)
+- `pin_memory=True` on a machine without GPU (no-op but wastes memory)
+
+### Training Loop Structure
+
+```python
+def train_epoch(
+    model: nn.Module,
+    loader: DataLoader,
+    optimizer: torch.optim.Optimizer,
+    criterion: nn.Module,
+    scaler: torch.cuda.amp.GradScaler,
+    device: torch.device,
+) -> dict[str, float]:
+    model.train()
+    total_loss = 0.0
+    n_batches = 0
+
+    for batch in loader:
+        inputs, targets = batch
+        inputs = inputs.to(device, non_blocking=True)
+        targets = targets.to(device, non_blocking=True)
+
+        # Zero gradients BEFORE forward pass
+        optimizer.zero_grad(set_to_none=True)  # Faster than zero_grad()
+
+        # Mixed precision forward pass
+        with torch.autocast(device_type="cuda", dtype=torch.float16):
+            outputs = model(inputs)
+            loss = criterion(outputs, targets)
+
+        # Scaled backward pass
+        scaler.scale(loss).backward()
+
+        # Gradient clipping (before unscaling)
+        scaler.unscale_(optimizer)
+        torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
+
+        # Optimizer step
+        scaler.step(optimizer)
+        scaler.update()
+
+        total_loss += loss.item()
+        n_batches += 1
+
+    return {"loss": total_loss / n_batches}
+```
+
+**Critical training loop rules**:
+1. `model.train()` before training, `model.eval()` before evaluation — these affect BatchNorm and Dropout
+2. `optimizer.zero_grad()` at the start of each batch, not the end
+3. Clip gradients before the optimizer step
+4. Use `loss.item()` (not `loss`) when accumulating — `.item()` detaches from the computation graph
+
+### Mixed Precision Training
+
+Mixed precision (float16/bfloat16 for computation, float32 for parameters) typically provides 2–3x speedup on modern GPUs with minimal accuracy impact:
+
+```python
+# Setup
+scaler = torch.cuda.amp.GradScaler()
+
+# Training step (shown above)
+with torch.autocast(device_type="cuda", dtype=torch.float16):
+    outputs = model(inputs)
+    loss = criterion(outputs, targets)
+
+scaler.scale(loss).backward()
+scaler.unscale_(optimizer)
+torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
+scaler.step(optimizer)
+scaler.update()
+```
+
+**bfloat16 vs float16**:
+- `bfloat16`: Same dynamic range as float32, less precision. Better for training stability. Requires Ampere GPU (A100, A30, RTX 30xx) or newer.
+- `float16`: Better precision than bfloat16 but narrower dynamic range (overflow risk). Works on all CUDA GPUs.
+- Default to `bfloat16` on Ampere+, `float16` on older GPUs.
+
+### Checkpointing
+
+Save and restore training state completely — not just model weights:
+
+```python
+def save_checkpoint(
+    path: str,
+    model: nn.Module,
+    optimizer: torch.optim.Optimizer,
+    scheduler,
+    scaler: torch.cuda.amp.GradScaler,
+    epoch: int,
+    metrics: dict,
+) -> None:
+    torch.save({
+        "epoch": epoch,
+        "model_state_dict": model.state_dict(),
+        "optimizer_state_dict": optimizer.state_dict(),
+        "scheduler_state_dict": scheduler.state_dict(),
+        "scaler_state_dict": scaler.state_dict(),
+        "metrics": metrics,
+    }, path)
+
+def load_checkpoint(path: str, model, optimizer, scheduler, scaler):
+    checkpoint = torch.load(path, map_location="cpu")
+    model.load_state_dict(checkpoint["model_state_dict"])
+    optimizer.load_state_dict(checkpoint["optimizer_state_dict"])
+    scheduler.load_state_dict(checkpoint["scheduler_state_dict"])
+    scaler.load_state_dict(checkpoint["scaler_state_dict"])
+    return checkpoint["epoch"], checkpoint["metrics"]
+```
+
+**Checkpoint strategy**:
+- Save every N epochs AND on best validation metric (two separate files)
+- Keep last K checkpoints (delete older ones to save disk)
+- Always test checkpoint resume — bugs in resume code are discovered in production during long training runs, not in testing
+
+### Distributed Training: DDP
+
+PyTorch DistributedDataParallel (DDP) is the standard for multi-GPU training. Each GPU runs an independent process with a full model copy; gradients are averaged across GPUs after each backward pass:
+
+```python
+# Launch: torchrun --nproc_per_node=4 train.py
+import torch.distributed as dist
+from torch.nn.parallel import DistributedDataParallel as DDP
+from torch.utils.data.distributed import DistributedSampler
+
+def train_distributed():
+    dist.init_process_group(backend="nccl")
+    rank = dist.get_rank()
+    local_rank = int(os.environ["LOCAL_RANK"])
+    world_size = dist.get_world_size()
+
+    device = torch.device(f"cuda:{local_rank}")
+    torch.cuda.set_device(device)
+
+    model = MyModel().to(device)
+    model = DDP(model, device_ids=[local_rank])
+
+    # Each rank gets a different data partition
+    sampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank)
+    loader = DataLoader(dataset, sampler=sampler, batch_size=batch_size_per_gpu)
+
+    for epoch in range(epochs):
+        sampler.set_epoch(epoch)  # Required for shuffle to work correctly
+        train_epoch(model, loader, ...)
+
+    # Save only from rank 0
+    if rank == 0:
+        torch.save(model.module.state_dict(), "model.pt")  # .module unwraps DDP
+
+    dist.destroy_process_group()
+```
+
+**DDP best practices**:
+- Use `torchrun` (not `torch.multiprocessing.spawn`) for launch
+- Effective batch size = `batch_size_per_gpu × world_size` — scale learning rate accordingly (linear scaling rule)
+- Always call `sampler.set_epoch(epoch)` or shuffle is deterministic across epochs
+- Log and save only from rank 0
+
+### Distributed Training: FSDP
+
+Fully Sharded Data Parallel (FSDP) shards model parameters across GPUs, enabling training of models too large for a single GPU:
+
+```python
+from torch.distributed.fsdp import FullyShardedDataParallel as FSDP
+from torch.distributed.fsdp import MixedPrecision
+import torch
+
+bf16_policy = MixedPrecision(
+    param_dtype=torch.bfloat16,
+    reduce_dtype=torch.bfloat16,
+    buffer_dtype=torch.bfloat16,
+)
+
+model = FSDP(
+    model,
+    mixed_precision=bf16_policy,
+    auto_wrap_policy=transformer_auto_wrap_policy,  # Wrap each transformer layer
+)
+```
+
+Use FSDP when model parameters exceed single-GPU memory. Use DDP when the model fits on one GPU — DDP is simpler and has less communication overhead.
+
+### Hyperparameter Tuning
+
+Never tune hyperparameters manually at scale. Use a systematic search tool:
+
+**Optuna** (open source, flexible):
+```python
+import optuna
+
+def objective(trial: optuna.Trial) -> float:
+    lr = trial.suggest_float("lr", 1e-5, 1e-2, log=True)
+    batch_size = trial.suggest_categorical("batch_size", [16, 32, 64])
+    dropout = trial.suggest_float("dropout", 0.0, 0.5)
+
+    model = build_model(dropout=dropout)
+    val_loss = train_and_evaluate(model, lr=lr, batch_size=batch_size)
+    return val_loss  # Optuna minimises by default
+
+study = optuna.create_study(direction="minimize", sampler=optuna.samplers.TPESampler())
+study.optimize(objective, n_trials=50, n_jobs=4)
+
+print(f"Best params: {study.best_params}")
+print(f"Best value: {study.best_value:.4f}")
+```
+
+**Key hyperparameters to tune** (in order of impact):
+1. Learning rate (most impactful — always tune first)
+2. Batch size (affects generalisation and training speed)
+3. Architecture (model size, depth, width)
+4. Regularisation (dropout, weight decay)
+5. Learning rate schedule (warmup steps, decay type)
+
+**Search strategies**:
+- Random search: Surprisingly effective, easy to parallelise
+- Bayesian optimisation (TPE in Optuna): More efficient for small budgets
+- Grid search: Only for 1–2 hyperparameters with small ranges
+
+Report the best result with multiple seeds (mean ± std) — a single seed result may be a lucky draw.

package/content/methodology/browser-extension-overlay.yml

@@ -0,0 +1,82 @@
+# methodology/browser-extension-overlay.yml
+name: browser-extension
+description: >
+  Browser extension overlay — injects extension domain knowledge into existing
+  pipeline steps for manifest configuration, content scripts, service workers,
+  cross-browser compatibility, store submission, and security patterns.
+project-type: browser-extension
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+# Map browser-extension knowledge entries into existing pipeline steps so that
+# browser extension domain expertise is injected during prompt assembly.
+# Includes UX/design steps (extensions have UI).
+# Maps: manifest → tech-stack + coding-standards; content-scripts → security;
+#       service-workers → system-architecture; cross-browser → tdd + add-e2e-testing;
+#       store-submission → operations.
+knowledge-overrides:
+  # Foundational
+  create-prd:
+    append: [browser-extension-requirements]
+  user-stories:
+    append: [browser-extension-requirements]
+  # manifest → coding-standards
+  coding-standards:
+    append: [browser-extension-conventions, browser-extension-manifest]
+  project-structure:
+    append: [browser-extension-project-structure]
+  dev-env-setup:
+    append: [browser-extension-dev-environment]
+  git-workflow:
+    append: [browser-extension-conventions]
+
+  # Architecture & Design
+  # service-workers → system-architecture
+  system-architecture:
+    append: [browser-extension-architecture, browser-extension-service-workers]
+  # manifest → tech-stack
+  tech-stack:
+    append: [browser-extension-architecture, browser-extension-manifest]
+  adrs:
+    append: [browser-extension-architecture]
+  domain-modeling:
+    append: [browser-extension-architecture]
+  # UX/design steps (extensions have UI)
+  ux-spec:
+    append: [browser-extension-architecture]
+  design-system:
+    append: [browser-extension-conventions]
+  # content-scripts → security
+  security:
+    append: [browser-extension-security, browser-extension-content-scripts]
+  # store-submission → operations
+  operations:
+    append: [browser-extension-store-submission]
+
+  # Testing
+  # cross-browser → tdd + add-e2e-testing
+  tdd:
+    append: [browser-extension-testing, browser-extension-cross-browser]
+  add-e2e-testing:
+    append: [browser-extension-testing, browser-extension-cross-browser]
+  create-evals:
+    append: [browser-extension-testing]
+  story-tests:
+    append: [browser-extension-testing]
+
+  # Reviews (mirror authoring steps)
+  review-architecture:
+    append: [browser-extension-architecture, browser-extension-service-workers]
+  review-ux:
+    append: [browser-extension-architecture]
+  review-security:
+    append: [browser-extension-security, browser-extension-content-scripts]
+  review-operations:
+    append: [browser-extension-store-submission]
+  review-testing:
+    append: [browser-extension-testing, browser-extension-cross-browser]
+
+  # Planning
+  implementation-plan:
+    append: [browser-extension-architecture]