@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/architecture/references/likec4-reference.md

@@ -0,0 +1,136 @@
+# LikeC4 DSL — Syntax Reference
+
+[LikeC4](https://likec4.dev/) describes a C4 model as code and renders it as
+interactive, drill-down diagrams. Soleur keeps ONE consolidated model and scopes
+it to each C4 level with views. A project is a directory of `.c4` files merged
+together; Soleur splits it into `spec.c4`, `model.c4`, `views.c4`.
+
+## Project shape
+
+```likec4
+// spec.c4 — declare element kinds + tags once
+specification {
+  element actor     { style { shape person } }
+  element system
+  element container
+  element database  { style { shape storage } }
+  element component { style { shape component } }
+  tag external
+}
+```
+
+```likec4
+// model.c4 — declare every element ONCE; nesting creates C4 boundaries
+model {
+  customer = actor "Customer" {
+    description "Uses the product"
+  }
+
+  platform = system "Acme Platform" {
+    web = system "Web App" {
+      ui  = container "Dashboard" {
+        technology "React, Next.js"
+        description "UI and session management"
+        style { shape browser }
+      }
+      api = container "API Routes" {
+        technology "Next.js API"
+      }
+    }
+    db = database "Primary DB" {
+      technology "PostgreSQL"
+    }
+  }
+
+  stripe = system "Stripe" {
+    #external
+    description "Payments"
+  }
+
+  // relationships: from -> to "label" { technology "..." }
+  customer -> ui "Uses" { technology "HTTPS" }
+  ui  -> api "Calls" { technology "HTTPS" }
+  api -> db  "Reads/writes" { technology "SQL" }
+  api -> stripe "Charges" { technology "HTTPS" }
+}
+```
+
+```likec4
+// views.c4 — one view per level; `view <id> of <el>` enables drill-down
+views {
+  view context {
+    title "System Context (C4 L1)"
+    include customer, platform, stripe
+    style element.tag == #external { color muted }
+    autoLayout TopBottom
+  }
+
+  // `of platform` → the `platform` box in `context` gets a drill-down button
+  view containers of platform {
+    title "Containers (C4 L2)"
+    include customer, platform.web, platform.web.ui, platform.web.api, platform.db, stripe
+    autoLayout TopBottom
+  }
+}
+```
+
+## Rules that matter
+
+| Concept | Mermaid C4 (old) | LikeC4 (now) |
+|---------|------------------|--------------|
+| Element | `System(id,"L","D")` | `id = system "L" { description "D" }` |
+| Tech    | 2nd arg of `Container(...)` | `technology "…"` property |
+| External | `_Ext` suffix | `#external` tag |
+| Boundary | `Container_Boundary(...) {}` | element **nesting** (parent `{ child }`) |
+| Relationship | `Rel(a,b,"L","T")` | `a -> b "L" { technology "T" }` |
+| Drill-down | not possible | `view X of <element>` + `navigateTo` |
+
+- **Declare each element once.** Different views `include` subsets of the one
+  model — never redefine an element per view.
+- **Reference nested elements by qualified path** in views and cross-boundary
+  relationships: `platform.web.ui`. Top-level ids may be used unqualified.
+- **Nesting is the boundary.** A parent element with children renders as a
+  boundary box; there is no separate boundary keyword.
+- **Descriptions / multi-line:** single quotes `'…'`, double quotes `"…"`, or
+  triple quotes `'''…'''` / `"""…"""` for multi-line.
+- **Views:** `include *` pulls the element and its descendants (inside `view of
+  X`, scoped to X). Use explicit `include a, b, c` for precise level fidelity.
+  `autoLayout TopBottom | LeftRight`. Style by tag: `style element.tag == #external { color muted }`.
+
+## Drill-down (the point of LikeC4)
+
+Define a level-specific view `of` a parent element. LikeC4 adds a navigation
+button on that element in any higher view, so the reader clicks Context →
+Containers → Components. Relationships you draw to/from a parent element (e.g.
+`customer -> platform`) coexist with finer-grained edges to its children
+(`customer -> ui`) — both are kept; each view shows the ones whose endpoints it
+includes.
+
+## Validate
+
+```bash
+npx -y likec4@1.50.0 validate --no-use-dot .                 # parse + check references
+_c4_out=$(mktemp -p "$(mktemp -d -t soleur-run.$$.XXXXXXXX)")
+npx -y likec4@1.50.0 export json --no-use-dot -o "$_c4_out" .  # element/relation/view counts
+# ... read the counts from "$_c4_out" (jq) — then `rm -f "$_c4_out"; rmdir "$(dirname "$_c4_out")"`; an
+# anonymous `"$(mktemp)"` path can never be found again, so name it (#10017)
+```
+
+Pin the version every writer pins (`likec4@1.50.0`, the `LIKEC4_VERSION` constant) and always pass
+`--no-use-dot`: inside a container likec4 defaults to the graphviz `dot` binary, which produces a
+different layout than the server's wasm render — or, without graphviz, a zero-view model.
+
+Export to a temp path, as above, never into the diagrams directory. Never write raw `export json`
+output onto the committed `model.likec4.json`. Every writer publishes the canonical
+one-value-per-line format with blank view hashes, which is what lets git merge two regenerations
+(ADR-235, #8542):
+
+- In any repo, run `bash <plugin-root>/scripts/render-c4-model.sh` (in a SKILL.md fence, `${CLAUDE_PLUGIN_ROOT}`) — the plugin's
+  renderer, which the merge resolver also runs (the Soleur repo keeps a
+  `scripts/regenerate-c4-model.sh` wrapper around it). `soleur:sync`'s C4 producer canonicalizes
+  too. To canonicalize by hand, go through a temp file so a failure never truncates the artifact:
+  `node <plugin-root>/lib/c4-canonical-cli.mjs "$raw" > "$tmp" && mv "$tmp" model.likec4.json`.
+- To check a committed file, run `node <plugin-root>/lib/c4-canonical-cli.mjs --check model.likec4.json`.
+  It prints `canonical` (exit 0) or `not-canonical` (exit 1).
+
+Full docs: <https://likec4.dev/>.

package/skills/architecture/references/nfr-reference.md

@@ -0,0 +1,126 @@
+# Non-Functional Requirements — Reference Guide
+
+Non-Functional Requirements (NFRs) define how the system should behave rather than what it should do. Every architecture decision should consider its impact on NFRs.
+
+## NFR Categories
+
+| Category | Scope | Example NFRs |
+|----------|-------|-------------|
+| Observability | Can we see what the system is doing? | Logging, monitoring, tracing, dashboards |
+| Resilience | Does the system recover from failures? | Circuit breakers, graceful shutdown, auto-healing |
+| Testing | Can we verify the system works? | Functional tests, performance tests, synthetic monitoring |
+| Configuration & Delivery | Can we deploy and configure safely? | Externalized config, CI/CD, canary upgrades |
+| Scaling & Recovery | Can the system grow and recover? | Auto-scaling, readiness/liveness probes, backup |
+| Security | Is the system protected? | Encryption, rate limiting, attack detection, image security |
+| Data Quality | Is the data trustworthy? | Freshness, accuracy, LLM-readiness |
+
+## NFR Register Structure
+
+The canonical NFR register lives at `knowledge-base/engineering/architecture/nfr-register.md`. It contains all NFRs organized per-container and per-link with applicability matrices.
+
+### Per-Container/Link Format
+
+Each NFR has its own section with a table mapping to C4 containers and links:
+
+```markdown
+### NFR-NNN: Title
+
+**Category:** X | **Scope:** Y | **System-Level Status:** Z
+
+| Container/Link | Status | Enforced By | Evidence |
+|----------------|--------|-------------|----------|
+| Dashboard | Implemented | Cloudflare | WAF managed rulesets |
+| Agent Runtime -> Anthropic | Not Implemented | — | No circuit breaker |
+```
+
+### NFR Scope Classification
+
+Each NFR has a scope that determines which rows appear in its table:
+
+| Scope | Description | Rows to Include |
+|-------|-------------|-----------------|
+| Container-scoped | Applies to individual containers | Container rows only |
+| Link-scoped | Applies to relationships between containers | Link rows only |
+| Both | Applies to containers and links | Both container and link rows |
+
+### System-Level Rollup
+
+System-level status is derived from per-container/link statuses using explicit precedence:
+
+1. If any applicable container/link is **Not Implemented** -> system-level is **Not Implemented**
+2. Else if any is **Partial** -> system-level is **Partial**
+3. Else if all are **Implemented** -> system-level is **Implemented**
+4. **N/A** rows are excluded from rollup. An NFR where all rows are N/A has system-level **N/A**
+
+## How to Reference NFRs in ADRs
+
+When writing the `## NFR Impacts` section of an ADR, reference NFRs by their ID **and the specific container or link affected**:
+
+```markdown
+## NFR Impacts
+
+- **NFR-014 (Externalized Configuration) on New Service container:** Maintained — uses Doppler for secrets (no change)
+- **NFR-026 (Encryption In-Transit) on Agent Runtime -> New Service link:** Implemented — SDK enforces HTTPS
+- **NFR-007 (Circuit Breaker) on Agent Runtime -> New Service link:** Risk introduced — no fallback; filed as follow-up
+- **NFR-001 (Logging) on New Service container:** Needs attention — structured logging required
+```
+
+Per-container references are more precise than system-level references. Use the format: `NFR-NNN (Name) on <Container/Link>`.
+
+### Assessment Checklist
+
+When evaluating NFR impacts for a decision, first identify which C4 containers and links the decision affects, then check each category for the affected containers/links:
+
+1. **Observability:** Does this change add containers or links that need monitoring? Will existing logging capture the new behavior per container?
+2. **Resilience:** Does this introduce new failure modes on specific links? Are there fallbacks for new external dependencies?
+3. **Testing:** Can the change be tested per container? Does it need new test types (load, integration, E2E)?
+4. **Configuration & Delivery:** Does this add new secrets or deployment steps for specific containers?
+5. **Scaling & Recovery:** Does this change scaling for specific containers? Are there new stateful components or backup requirements?
+6. **Security:** Does this expose new attack surfaces on specific links, handle sensitive data in new containers, or change access control?
+7. **Data Quality:** Does this change how data is created, stored, or accessed per container? Are there new consistency requirements?
+
+### When to Update the NFR Register
+
+Update `knowledge-base/engineering/architecture/nfr-register.md` when:
+
+- An ADR changes the status of an NFR on a specific container/link (e.g., Agent Runtime -> New Service: Not Implemented -> Implemented)
+- A new NFR is identified that is not in the register
+- The enforcement tool changes for a specific container/link
+- An NFR becomes N/A or newly relevant for a container/link due to architecture changes
+- A new container or link is added to the C4 diagram (see Maintenance Procedure below)
+
+## NFR Status Definitions
+
+| Status | Criteria |
+|--------|----------|
+| **Implemented** | Actively enforced by a tool or mechanism. Verified working. |
+| **Partial** | Some coverage but known gaps. Document what is and is not covered. |
+| **Not Implemented** | Acknowledged but no mechanism in place. May have a roadmap item. |
+| **N/A** | Not applicable at current scale or architecture. Revisit when conditions change. |
+
+## Common NFR Patterns by Decision Type
+
+| Decision Type | Typically Affects |
+|---------------|------------------|
+| New external service integration | NFR-001 (Logging), NFR-007 (Circuit Breaker), NFR-026 (Encryption In-Transit), NFR-041 (Link Access Control) |
+| Infrastructure change | NFR-002-004 (Monitoring), NFR-010 (Scalability), NFR-016 (CD), NFR-019 (Auto-scaling), NFR-038 (Least Privilege) |
+| New user-facing feature | NFR-008 (Latency), NFR-011 (Functional Testing), NFR-025 (Rate Limiting), NFR-042 (LLM-Ready Docs) |
+| Data model change | NFR-027 (Encryption At-Rest), NFR-029 (Data Freshness), NFR-030 (Data Accuracy), NFR-040 (Retention Policy) |
+| Security change | NFR-023-028 (security category), NFR-038-041, NFR-047 |
+| Deployment change | NFR-016-018 (CD, Graceful Shutdown, Canary), NFR-021-022 (Readiness/Liveness), NFR-032 (Auto Rollback), NFR-036 (Immutable Releases) |
+| New container addition | See Maintenance Procedure below |
+
+## Maintenance Procedure: Adding New Containers
+
+When a new container is added to the C4 container diagram (`knowledge-base/engineering/architecture/diagrams/c4-model.md`):
+
+1. **Classify the container** as runtime, passive, or infrastructure (see Container Classification in the register)
+2. **Add the container** to the Container & Link Inventory table in the NFR register
+3. **Add new links** involving this container to the Link Classification table
+4. **Review each NFR section** and add rows for the new container/links where applicable:
+   - Runtime containers: check all container-scoped NFRs (Logging, Monitoring, Testing, Config, etc.)
+   - Passive containers: check only Documentation (NFR-015), LLM-Ready Documentation (NFR-042), and Encryption At-Rest (NFR-027) if containing sensitive data
+   - Infrastructure containers: check monitoring, security, and scaling categories
+5. **For new links:** check all link-scoped NFRs (Circuit Breaker, Latency, Rate Limiting, Encryption In-Transit, Distributed Tracing, Access Control, Certificate Scope)
+6. **Update the summary table** to reflect new rollup counts
+7. **Verify** container/link names match the C4 diagram exactly

package/skills/archive-kb/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: archive-kb
+description: "This skill should be used when archiving completed knowledge-base artifacts (brainstorms, plans, specs) to their archive/ subdirectories with timestamp prefixes and git history preservation."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Archive Knowledge-Base Artifacts
+
+Archive brainstorms, plans, and spec directories for a completed feature branch.
+The script generates timestamps internally and uses `git mv` to preserve history.
+
+> **Superseded in part (ADR-174, #7399).** Archival's only real benefit was removing
+> rows from `knowledge-base/INDEX.md`, and that is now done at index-generation time:
+> inside a spec directory only `spec.md` and `tasks.md` are indexed. A spec directory
+> is live working state until `ship` Phase 6 step 2.5 reads `decision-challenges.md`
+> from it (ADR-084 §5) — an earlier gate that forced archival before merge was built
+> and reverted for that ordering reason. The constraint was ordering, not gating:
+> ship `## Phase 6.45: KB Artifact Archival` runs after the last live-path reads, and
+> the `ship-kb-archive-gate.sh` hook denies only a merge that would land live paths.
+>
+> Retiring its spec/plan discovery paths is tracked by **#7400**. Discovery is now
+> three axes: the slug match (below) UNIONED with the branch diff — files added or
+> modified on the branch under `knowledge-base/project/{plans,brainstorms,specs}`
+> are this feature's artifacts by commit provenance, so a topic-named plan
+> (`2026-10-08-...-plan.md` never matches the slug glob) and a non-`feat-*` spec
+> dir are both found — UNIONED with untracked `??` paths under the same roots
+> (the only class the branch diff can never see; an uncommitted spec dir
+> collapses to `specs/<dir>` and a lone root-level file does not fire).
+> The partial-run WARNING stays: it fires when exactly one
+> class is found and the other is silent.
+>
+> **ship integration:** `ship` Phase 6.45 (KB Artifact Archival) invokes this
+> script after its last live-artifact reads (decision-challenges render, `##
+> Operator Holds`) and the `git mv` rides the feature PR — archival is part of
+> ship, not a follow-up. The `ship-kb-archive-gate.sh` PreToolUse hook denies a
+> `gh pr merge` while live additions remain under the three KB roots.
+>
+> Measured (kb-archive-gate, 2026-10-12): `--dry-run` on the feature worktree
+> lists `plans/2026-10-12-feat-kb-archive-gate-plan.md` and `specs/kb-archive-gate`
+> — and nothing under `learnings/`, which is never archived.
+
+## Usage
+
+Run the archive script from the repository root. It derives the feature slug
+from the current branch name automatically:
+
+    bash "${CLAUDE_PLUGIN_ROOT}/skills/archive-kb/scripts/archive-kb.sh"
+
+To preview what would be archived without making changes:
+
+    bash "${CLAUDE_PLUGIN_ROOT}/skills/archive-kb/scripts/archive-kb.sh" --dry-run
+
+To archive a specific slug (override branch detection):
+
+    bash "${CLAUDE_PLUGIN_ROOT}/skills/archive-kb/scripts/archive-kb.sh" my-feature-slug
+
+## What It Archives
+
+The script discovers artifacts matching the feature slug:
+
+| Directory | Match Pattern | Type |
+|-----------|--------------|------|
+| `knowledge-base/project/brainstorms/` | Filename contains slug | File glob |
+| `knowledge-base/project/plans/` | Filename contains slug | File glob |
+| `knowledge-base/project/specs/feat-<slug>/` | Exact directory name | Directory match |
+
+All `archive/` subdirectories are excluded from discovery.
+
+## When to Use
+
+- During the compound skill's archival step (Step E in compound-capture)
+- After completing a feature when brainstorm/plan artifacts should be archived
+- During the ship workflow to archive feature artifacts before merge
+
+## Notes
+
+**No `secret-scan-allow-rename` label is required for archival.** The destinations here (`knowledge-base/project/{plans,specs}/archive/`) match the gitleaks path allowlist — but so do the sources, so the `git mv` creates no new unscanned surface. `rename-guard` exempts allowlist -> allowlist renames per rename pair; see [secret-scanning.md](../../../../knowledge-base/engineering/operations/secret-scanning.md).
+
+- The script calls `git add` before `git mv` to handle untracked files
+- A single timestamp is generated per invocation for consistency
+- Exit code 0 for success (including "no artifacts found")
+- Exit code 1 for errors (not in git repo, invalid arguments)
+- Spec directories are moved as a whole via `git mv` on the directory

package/skills/archive-kb/scripts/archive-kb.sh

@@ -0,0 +1,300 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Archive knowledge-base artifacts for a feature branch.
+# Moves brainstorms, plans, and specs to archive/ subdirectories
+# with timestamped prefixes, preserving git history.
+#
+# Usage: archive-kb.sh [--dry-run] [slug]
+#   --dry-run  Show what would be archived without executing
+#   slug       Feature slug (default: derived from current branch)
+
+readonly SCRIPT_NAME="archive-kb.sh"
+
+# --- Argument Parsing ---
+
+DRY_RUN=false
+EXPLICIT_SLUG=""
+
+usage() {
+  echo "Usage: ${SCRIPT_NAME} [--dry-run] [slug]" >&2
+  echo "  --dry-run  Show what would be archived without executing" >&2
+  echo "  slug       Feature slug (default: derived from current branch)" >&2
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --help|-h)
+      usage
+      ;;
+    -*)
+      echo "Error: Unknown flag: $1" >&2
+      usage
+      ;;
+    *)
+      if [[ -n "$EXPLICIT_SLUG" ]]; then
+        echo "Error: Multiple slug arguments provided" >&2
+        usage
+      fi
+      EXPLICIT_SLUG="$1"
+      shift
+      ;;
+  esac
+done
+
+# --- Environment Checks ---
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "Error: Not inside a git repository" >&2
+  exit 1
+fi
+
+if [[ ! -d "knowledge-base" ]]; then
+  echo "No knowledge-base directory found"
+  exit 0
+fi
+
+# --- Slug Derivation ---
+
+derive_slug() {
+  local branch safe slug
+  branch=$(git rev-parse --abbrev-ref HEAD)
+  # Normalize slashes to hyphens
+  safe=$(echo "$branch" | tr '/' '-')
+  slug="$safe"
+  # Strip prefixes in sequence (order matters: feature- before feat-)
+  slug="${slug#feature-}"
+  slug="${slug#feat-}"
+  slug="${slug#fix-}"
+  echo "$slug"
+}
+
+if [[ -n "$EXPLICIT_SLUG" ]]; then
+  SLUG="$EXPLICIT_SLUG"
+else
+  SLUG=$(derive_slug)
+fi
+
+if [[ -z "$SLUG" ]]; then
+  echo "Error: Could not derive feature slug from branch name" >&2
+  exit 1
+fi
+
+# --- Discovery ---
+
+discover_artifacts() {
+  local slug="$1"
+  local artifacts=()
+
+  # Enable nullglob so empty globs expand to nothing
+  shopt -s nullglob
+
+  # Brainstorms and plans
+  local file_dirs=(
+    "knowledge-base/project/brainstorms"
+    "knowledge-base/project/plans"
+  )
+  for dir in "${file_dirs[@]}"; do
+    for f in "$dir"/*"${slug}"*; do
+      [[ -f "$f" && "$f" != */archive/* ]] && artifacts+=("$f")
+    done
+  done
+
+  # Specs
+  if [[ -d "knowledge-base/project/specs/feat-${slug}" ]]; then
+    artifacts+=("knowledge-base/project/specs/feat-${slug}")
+  fi
+
+  shopt -u nullglob
+
+  printf '%s\n' "${artifacts[@]}"
+}
+
+ARTIFACTS=()
+while IFS= read -r line; do
+  [[ -n "$line" ]] && ARTIFACTS+=("$line")
+done < <(discover_artifacts "$SLUG")
+
+# Branch-diff discovery (#9803 follow-up): files ADDED or MODIFIED on this
+# branch under the KB artifact roots are this feature's artifacts by commit
+# provenance — no filename match needed. This is what catches a topic-named
+# plan (`2026-10-08-fix-sandbox-hardening-cluster-plan.md` never matches the
+# branch-derived slug) and a spec dir that is not `feat-<slug>` (the slug
+# probe cannot reach `fix-*`/`chore-*` dirs). Spec FILES collapse to their
+# spec DIR; archive/ paths are already archived and excluded. Unioned with
+# the slug and untracked results — the three axes (name match, commit
+# provenance, worktree state) cover what any one alone misses.
+discover_branch_diff() {
+  local base st f sub
+  base=$(git merge-base HEAD origin/main 2>/dev/null | head -1) || return 0
+  [[ -z "$base" ]] && return 0
+  while IFS=$'\t' read -r st f; do
+    case "$f" in
+      */archive/*) ;;                                     # already archived
+      # Spec files collapse to their DIR — but only on A rows (the branch
+      # created the dir, so it is this feature's). An M row is a drive-by
+      # edit to a sibling feature's live spec — collapsing it would archive
+      # mid-flight work that is not ours.
+      knowledge-base/project/specs/*/*)
+        [[ "$st" == A* ]] || continue
+        sub=${f#knowledge-base/project/specs/}
+        printf 'knowledge-base/project/specs/%s\n' "${sub%%/*}" ;;
+      knowledge-base/project/plans/*|knowledge-base/project/brainstorms/*)
+        [[ -f "$f" ]] && printf '%s\n' "$f" ;;
+    esac
+  done < <(git diff --name-status --diff-filter=AM "$base"...HEAD -- \
+      knowledge-base/project/plans \
+      knowledge-base/project/brainstorms \
+      knowledge-base/project/specs 2>/dev/null)
+}
+while IFS= read -r line; do
+  [[ -n "$line" ]] && ARTIFACTS+=("$line")
+done < <(discover_branch_diff | sort -u)
+
+# Untracked-path discovery (#7383 residual): an UNCOMMITTED artifact is
+# invisible to both axes above — the slug glob needs a filename match and
+# branch-diff needs commit provenance, and a never-committed topic-named
+# plan or non-`feat-*` spec dir has neither. `git status --porcelain` `??`
+# rows are the only signal. `??` rows ONLY: staged/modified rows on tracked
+# files are commit-provenance's job (a staged-but-never-committed file is
+# #9172's class — noted, not fixed here). `--untracked-files=all` pins the
+# `??` enumeration against `status.showUntrackedFiles` config (`no` would
+# silently empty the axis; `normal` would collapse a fully-untracked dir to
+# a bare `specs/` row the patterns below cannot reach). The `*/archive/*`
+# exclusion and specs collapse mirror branch-diff: an untracked file inside
+# `specs/<dir>/` emits `specs/<dir>`, while a lone ROOT-LEVEL file
+# (`specs/.gitkeep`, `specs/notes.md`) has no second path component and does
+# not fire. Plans/brainstorms root files DO fire — they are the artifacts.
+discover_untracked() {
+  local st f sub
+  while IFS= read -r -d '' line; do
+    st=${line:0:2}
+    [[ "$st" == '??' ]] || continue
+    f=${line:3}
+    case "$f" in
+      */archive/*) ;;                                     # already archived
+      knowledge-base/project/specs/*/*)
+        sub=${f#knowledge-base/project/specs/}
+        sub=${sub%%/*}
+        # Collapse to the dir ONLY when the dir is wholly untracked —
+        # `??` carries no provenance, so a stray file inside a
+        # partially-tracked spec dir (a sibling feature's live work, the
+        # M-row rule's analog) must not pull the whole dir into the move.
+        if git ls-files --error-unmatch -- "knowledge-base/project/specs/${sub}" >/dev/null 2>&1; then
+          continue
+        fi
+        printf 'knowledge-base/project/specs/%s\n' "$sub" ;;
+      knowledge-base/project/plans/*|knowledge-base/project/brainstorms/*)
+        [[ -f "$f" ]] && printf '%s\n' "$f" ;;
+    esac
+  done < <(git status --porcelain -z --untracked-files=all -- \
+      knowledge-base/project/plans \
+      knowledge-base/project/brainstorms \
+      knowledge-base/project/specs 2>/dev/null || true)
+}
+while IFS= read -r line; do
+  [[ -n "$line" ]] && ARTIFACTS+=("$line")
+done < <(discover_untracked | sort -u)
+
+# Dedupe the union (an artifact reachable by more than one axis — e.g. an
+# untracked slug-named file hits both the glob and `??` rows).
+if [[ ${#ARTIFACTS[@]} -gt 0 ]]; then
+  mapfile -t ARTIFACTS < <(printf '%s\n' "${ARTIFACTS[@]}" | sort -u)
+fi
+
+# A PARTIAL run must not read as a complete one (#8416).
+#
+# `discover_artifacts` derives ONE slug per run, and a feature's plan and spec
+# routinely carry DIFFERENT slugs -- the plan is named for its topic, the spec
+# for its branch. The plan glob (`*${slug}*`) then matches nothing, the spec
+# probe matches, and the run prints `Archived 1 artifact(s)` and exits 0 with
+# the plan silently left behind. SKILL.md has documented that gap in prose since
+# it was first hit; it was hit again on #8325, which is the signal that prose was
+# not the fix (`wg-when-a-workflow-gap-causes-a-mistake-fix`).
+#
+# This deliberately adds NO new discovery: #7400 tracks retiring the spec/plan
+# discovery paths entirely, so widening them would build on a mechanism slated
+# for removal. It only makes the ASYMMETRY audible -- one class found, the other
+# silent -- which is the state a reader mistakes for completeness. The operand is
+# the classes DISCOVERED, never a count, because a count cannot distinguish "the
+# feature has no plan" from "the plan is named something else".
+_found_class() {
+  local want="$1" a
+  for a in "${ARTIFACTS[@]}"; do
+    [[ "$a" == knowledge-base/project/"${want}"/* ]] && return 0
+  done
+  return 1
+}
+if [[ ${#ARTIFACTS[@]} -gt 0 ]]; then
+  _have_plan=no; _have_spec=no
+  _found_class plans && _have_plan=yes
+  _found_class specs && _have_spec=yes
+  if [[ "$_have_plan" != "$_have_spec" ]]; then
+    if [[ "$_have_plan" == no ]]; then
+      _found="spec"; _missing="plan"; _hint="knowledge-base/project/plans/"
+    else
+      _found="plan"; _missing="spec"; _hint="knowledge-base/project/specs/feat-<slug>/"
+    fi
+    echo "WARNING: found a ${_found} for slug \"${SLUG}\" but NO ${_missing}." >&2
+    echo "         A feature's plan and spec often carry different slugs, so this run may be" >&2
+    echo "         incomplete. Check ${_hint} and re-run with the other slug if one exists." >&2
+  fi
+fi
+
+# --- No artifacts case ---
+
+if [[ ${#ARTIFACTS[@]} -eq 0 ]]; then
+  echo "No artifacts found for slug \"${SLUG}\""
+  exit 0
+fi
+
+# --- Timestamp (generated once for consistency) ---
+
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+
+# --- Dry-run mode ---
+
+print_archive_path() {
+  local artifact="$1"
+  local ts="$2"
+  local name dest_dir
+  name=$(basename "$artifact")
+  dest_dir=$(dirname "$artifact")
+  echo "  ${artifact} -> ${dest_dir}/archive/${ts}-${name}"
+}
+
+if [[ "$DRY_RUN" == true ]]; then
+  echo "Dry run -- would archive ${#ARTIFACTS[@]} artifact(s) for slug \"${SLUG}\":"
+  for artifact in "${ARTIFACTS[@]}"; do
+    print_archive_path "$artifact" "$TIMESTAMP"
+  done
+  exit 0
+fi
+
+# --- Archival Execution ---
+
+archive_artifact() {
+  local artifact="$1"
+  local ts="$2"
+  local name dest_dir archive_dir
+  name=$(basename "$artifact")
+  dest_dir=$(dirname "$artifact")
+  archive_dir="${dest_dir}/archive"
+
+  mkdir -p "$archive_dir"
+  # git add handles both untracked files and already-tracked files (no-op)
+  git add "$artifact"
+  git mv "$artifact" "${archive_dir}/${ts}-${name}"
+  echo "  ${archive_dir}/${ts}-${name}"
+}
+
+echo "Archived ${#ARTIFACTS[@]} artifact(s) for slug \"${SLUG}\":"
+
+for artifact in "${ARTIFACTS[@]}"; do
+  archive_artifact "$artifact" "$TIMESTAMP"
+done