@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/skills/nornir-schedule/assets/quota.md

@@ -0,0 +1,131 @@
+---
+name: nornir-quota
+description: >-
+  Agent-only decision procedure for resolving a matched crew-dispatch profile
+  array from quota-axi's default TOON, ranking by spendPriority after three
+  orthogonal gates.
+  Load when a dispatch rule or default resolves to more than one profile candidate.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# quota-array-dispatch
+
+This skill is the single owner of the completion-aware profile-array selection procedure.
+`AGENTS.md` section 4 owns the always-loaded intake boundary, load trigger, malformed-config refusal, every-candidate accounting, and strongest-reasoning/tie safety rules.
+`harness-adapters` owns harness verification, model/provider discovery, and effort fallback.
+`quota-axi` remains data-only: it publishes `spendPriority` as a comparable scalar and never recommends, selects, ranks, or infers a route.
+Do not add a daemon, opaque composite score, routing wrapper, hard-coded model-specific policy, or producer-side route recommendation.
+Deterministic shell owns only schema, configuration, and version validation plus concrete spawn safeguards; every model-to-provider, provider-to-credential, and quota-applicability relation is yours to establish transparently and to show your evidence for.
+
+## Worker-side quota helper
+
+The canonical shell helper for a worker that has already performed its model-selection reasoning and now needs to pick the first viable candidate is `bin/brokk-quota-choose.sh`.
+Pass it the intake's already-captured default TOON or permitted JSON fallback through stdin or `--snapshot`; it never takes another quota snapshot, so it selects from the same quota state as the intake.
+Pass each candidate as `harness:model`, with earlier candidates preferred.
+The helper maps each harness to its primary provider family and applies the provider-wide scopes plus the exact model or product scopes for the model.
+An `exhausted_now` runway vetoes the candidate.
+The helper selects a candidate only when its applicable quota has a known `effectivePercentRemaining` greater than zero.
+This is an optional narrow helper with a known limitation: it maps each harness to one primary provider family only, so a candidate whose established provider differs from that primary family is checked against the wrong quota row.
+Authoritative multi-provider routing - including provider discovery from the harness catalog and quota matching by that explicit provider - stays owned by this skill's intake procedure above and AGENTS.md section 4, not by the helper.
+Use it only when the brief already fixed the candidate order and every candidate's provider is the harness's primary family.
+It does not replace the reasoning-class, runway-feasibility, or authentication gates above.
+Brokk can optionally arm `bin/brokk-procevent-quota.sh` for a recurring mid-task check that wakes when the tracked provider drops below its configured threshold or its runway becomes `exhausted_now`.
+
+## Read the default TOON
+
+Start each intake by running `quota-axi` once with no `--json`, and reuse that TOON for every candidate.
+Post-consolidation quota-axi (the floor owned by `bin/brokk-quota-axi-lib.sh`) puts `spendPriority` in the default `quota[]` block beside `effectivePercentRemaining`, `runway`, `confidence`, `limitedBy`, and `resetsAt`.
+Sparse `exhaustion[]` carries finite-runway seconds only for `projected_exhaustion` and `exhausted_now`.
+Sparse `attention[]` names auth, stale, and unmeasurable facts.
+`spendPriority` is THE quota-perspective ranker.
+It already computes the economics that older instructions reconstructed by hand from headroom, pace, reserve, and window-id lists; do not recompute those.
+Do not read `--json` on the normal path, and do not reach for `--full` to rebuild that economics.
+
+After reading the TOON, fall back to one `quota-axi --json` call only when that TOON is genuinely ambiguous for the decision, or when the installed quota-axi is somehow below the floor so its TOON lacks `spendPriority`.
+Ambiguous means a candidate's `spendPriority` is the literal `unknown` or unmeasurable, a real tie still needs extra evidence, or a candidate's eligibility is unclear from `quota[]` plus `attention[]`.
+The fallback therefore has an explicit TOON-then-JSON call sequence; reuse its JSON result and do not take any further quota snapshots.
+Below-floor is rare: bootstrap enforces `BROKK_QUOTA_AXI_MIN` and normally reports `MISSING` before dispatch; if an intake somehow reaches an older build whose TOON lacks `spendPriority`, use the defensive `--json` fallback rather than treating the missing scalar as healthy.
+`--json` is a defensive belt, not a habit; never reach for it because it feels more complete.
+Read `quota-axi auth --json` only when a candidate's credential surface is in question.
+
+For each candidate, preserve explicit `harness`, `model`, and `provider`; `harness-adapters` owns identity, and model/provider never infer harness.
+
+## Three gates, then spendPriority
+
+Apply the three cheap orthogonal gates first.
+`spendPriority` ranks only among candidates that pass all three.
+It cannot override a hard-gate failure, and it is never hidden inside a new composite score.
+
+### 1. Eligibility
+
+Deterministic shell must never map a model to a provider, a provider to a credential store, or a name prefix to a family.
+You establish those relations yourself, in the open, from the candidate's own authoritative catalog (`harness-adapters` owns the per-harness discovery surface) plus the one intake snapshot.
+
+Confirm the catalog lists the candidate's model and record the provider family it reports.
+A model the catalog does not list is concrete contradictory evidence: block that candidate and quote the catalog result.
+Apply quota at the granularity the vendor actually supplies.
+A provider-level or `all_models`/`all_products` scope bounds every model you established in that family, including one with no window of its own.
+A named-model or named-product scope is an additional bound for that model alone.
+Match the candidate to its `quota[]` row by that established provider and scope; a stale, auth-required, or unmeasurable scope is named in `attention[]` instead of a fabricated number.
+
+A candidate authenticates through its own tuple's surface; another harness's CLI can never gate it, and `harness=pi` with `model=xai/grok-*` is Pi using xAI rather than the standalone Grok CLI.
+`quota-axi auth --json` lists each provider's credential sources independently, so read the one source the candidate actually uses rather than collapsing a provider to a single status.
+A provider can carry a healthy source beside a missing or expired one; the unused source's state is not the candidate's state.
+A Pi-hosted family may authenticate through the vendor's own store with no `pi:`-prefixed source at all, which is normal and never evidence against the candidate.
+
+Uncertainty and ineligibility are different findings:
+
+- No model-level window, no matching auth source, an unmeasurable or `unknown` scope, or a surface quota-axi does not model at all is disclosed uncertainty.
+  Keep the candidate eligible, state the unknown, and prefer known viable evidence when otherwise comparable.
+- An expired credential is a short-lived session token the owning vendor renews on next use, not a sign-out.
+- Only concrete contradictory evidence blocks: an authoritative catalog proving the model unsupported, or proof that the credential the candidate actually selects is unusable.
+- Reserve login wording for that proven-unusable case, and name the harness, model, surface, and evidence.
+
+When a credential's local classification is the only thing standing between a candidate and a block, get ground truth before blocking.
+`bin/brokk-vendor-auth-probe.sh` is the only approved vendor-credential probe; its `--help` owns the registered probes and mechanics.
+It takes no harness, model, or provider and returns a fact, not a route: only `authenticated` and `unauthenticated` are ground truth, while `indeterminate`, `timeout`, and `unavailable` establish nothing and must never be read as either outcome.
+Never launch a vendor CLI yourself, and never probe a credential store the candidate does not use.
+Grok prepaid `credits` are unrelated to paid-window headroom; never read them as exhaustion.
+
+Malformed configuration is an actionable error, not a candidate to rank around.
+
+### 2. Reasoning-class fit
+
+Keep only candidates that meet the required reasoning class for this task (a simple bug fix versus very-difficult design).
+Never use `spendPriority` or remaining quota to silently replace that class.
+When every remaining candidate is tight, dispatch inside the strongest-reasoning class if one of those candidates can proceed, or stop and report that the strongest-class choice cannot proceed rather than downgrading it to spend or conserve quota.
+
+### 3. Runway feasibility floor
+
+Known runway that will not last until the inspectable likely-completion horizon fails this gate, even when that candidate has the highest `spendPriority`.
+Read `runway` from the `quota[]` row: `through_reset` passes this generic feasibility floor because the window reaches its refill without exhausting; never compare its `resetsAt` with the completion horizon as though reset were an exhaustion deadline.
+`exhausted_now` is zero, and `projected_exhaustion` uses the matching `exhaustion[]` row's `usableRunwaySeconds`.
+A high `spendPriority` on a nearly empty window that will exhaust soon must not route into a mid-task stall.
+Unknown or unmeasurable runway stays eligible with disclosed uncertainty and is never assumed to pass.
+Do not invent a generic percentage floor, and honor an explicit Allfather floor for a candidate when one exists.
+
+## Rank by spendPriority
+
+Among candidates that pass all three gates, pick the highest known `spendPriority`.
+A higher known scalar is better: positive means paid allowance is on track to reach reset unused, `0` is exact utilization, and negative means overdrawn against the reset clock.
+Rank only from comparable known scalars.
+Never treat absent, `unknown`, or unmeasurable `spendPriority` as zero or as healthy; `0` means exact utilization, a different claim from unknown.
+An unknown `spendPriority` keeps the candidate eligible with disclosed uncertainty.
+Prefer known viable evidence when otherwise comparable.
+After the permitted TOON-to-JSON fallback, escalate to Brokk instead of routing if no candidate can be ranked or runway uncertainty prevents proving the feasibility floor for any candidate that could be selected.
+Never resolve that terminal uncertainty by treating unknown as healthy or by choosing arbitrarily.
+Show the scalar or the literal `unknown` in the rationale; do not hide it in a score.
+
+Do not compare headroom against runway by hand.
+Do not use pace or signed reserve as a later tie-break layer.
+Do not read `aheadWindowIds`, `behindWindowIds`, `onPaceWindowIds`, `limitingWindowIds`, or other window-id lists to reconstruct what `spendPriority` already computed.
+
+Genuine ties: stop and report every tied candidate for Allfather choice.
+Do not select by array order, harness name, or another arbitrary identity ordering.
+Report duplicate concrete profiles as a configuration error.
+
+Account for every candidate visibly before selecting or escalating, naming its catalog evidence, provider relation, applicable quota and authentication facts, remaining uncertainty, fit and reasoning class, `spendPriority`, and runway-versus-horizon result.
+A blocked credential report must name `harness`, `model`, authentication surface, and concrete failure evidence; never emit a bare `Grok unauthenticated` statement.
+Never conclude with an unexplained "best quota" label.

package/.agents/skills/nsr-compliance/README.md

@@ -0,0 +1,3 @@
+# nsr-compliance — compliance — NorthStar scaffold/audit + the .compliance/ harness
+
+See `SKILL.md` for the full skill.

package/.agents/skills/nsr-compliance/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: nsr
+description: >-
+  WayOfNorthStarRules — the doctrine and its deterministic gate. Load when
+  creating a new NSR-compliant project, converting a legacy repo to the
+  NorthStar layout, auditing a repo for NSR compliance, generating the
+  .compliance/ harness, or running its gates (danger, wiring, env, paths).
+  One skill for the NorthStar law.
+allowed-tools: run_shell_command, run_bash_command, edit, write
+metadata:
+  internal: true
+---
+
+# nsr-compliance — compliance — NorthStar scaffold/audit + the .compliance/ harness
+
+The NorthStar doctrine and the compliance harness that enforces it, under one
+skill.
+
+```
+assets[2]{path,load_when}:
+  "assets/nsr/scaffold-spec.md","scaffold a new NSR repo · convert a legacy repo · audit compliance (master spec, templates, scripts)"
+  "assets/nsrcompliance/SKILL.md","generate and run the .compliance/ harness: danger, wiring, env, path gates + telemetry"
+```
+
+Stamp the harness into a repo:
+
+```bash
+.agents/skills/nsr/assets/nsrcompliance/generate.sh [TARGET] [--force] [--dry-run]
+```

package/.agents/skills/nsr-compliance/assets/nsr/README.md

@@ -0,0 +1,40 @@
+# NSR Skill
+
+Scaffold + validate Way-Of NorthStar compliant projects.
+
+## Layout
+
+```
+NSR/
+├── SKILL.md           # Skill manifest (agent-facing workflow)
+├── README.md          # This file
+├── assets/            # Project templates (the source of truth for a new repo)
+│   ├── root/          # Root routing files (AGENTS.md, STRUCTURE.md, ...)
+│   ├── RULES/         # Execution rules (kept at root)
+│   ├── docs/          # Granular docs tree (BEST_PRACTICES, CI_CD, DEVELOPER_SETUP, HOSTING, RUNBOOK, features, research)
+│   ├── agents_skills/ # .agents/skills/ automation layer templates
+│   └── compliance/       # .compliance/ deterministic harness templates
+└── scripts/
+    ├── scaffold.sh    # Create OR convert a project to the NSR layout
+    └── validate.sh    # Audit a repo against NSR compliance gates
+```
+
+## Quick Start
+
+```bash
+# New project
+.agents/skills/NSR/scripts/scaffold.sh ./my-project --name MyProject --description "SaaS thing"
+
+# Existing repo (adds missing NSR pieces, never overwrites)
+.agents/skills/NSR/scripts/scaffold.sh . --name "Existing" --description "Adopting NSR"
+
+# Audit
+.agents/skills/NSR/scripts/validate.sh ./my-project
+```
+
+## Rules
+
+- Templates are generic; the scaffolder substitutes project name/description.
+- Never overwrite an existing file during conversion.
+- The scaffolder's post-condition is a passing `validate.sh`.
+- Keep this skill in sync with `WayOfNorthstarRules.md`.

package/.agents/skills/nsr-compliance/assets/nsr/assets/RULES/README.md

@@ -0,0 +1,15 @@
+# RULES/
+
+Modular, single-responsibility rule files. Indexed by `RULES.md` (root). Kept at the repo root per the NSR layout.
+
+## Files
+
+- `security.md` — Access control, secrets, vulnerability gates.
+- `git-workflow.md` — Branching, commit message, merge protocol.
+- `tech-stack.md` — One primary stack per feature, pinned versions.
+- *(add more: `multi-tenancy.md`, `testing.md`, ...)*
+
+## Rules
+
+- One topic per file; concrete and enforceable.
+- Keep `RULES.md` (root) in sync.

package/.agents/skills/nsr-compliance/assets/nsr/assets/RULES/git-workflow.md

@@ -0,0 +1,18 @@
+# Git Workflow — __PROJECT__
+
+## Branching
+- Feature branches named `feat/<feature>-<short-desc>` or `fix/<ticket>`.
+- Branches created via `.agents/skills/git_ops/create_branch.sh` (naming + ticket link enforced).
+
+## Commits
+- Use `.agents/skills/git_ops/safe_commit.sh` — runs pre-commit gates + formats message.
+- Conventional style: `feat:`, `fix:`, `docs:`, `chore:`.
+- No bare `git commit -m ...` — always via skill script.
+
+## Merge / PR
+- Push via `sync_upstream.sh` (rebase + conflict check).
+- PR must pass all gates (`.compliance/gates/*`) and reviewer approval.
+
+## Enforced By
+- `.agents/skills/git_ops/` scripts.
+- `.compliance/gates/check_platform.sh` (no `pkill`/`taskkill`/raw kill).

package/.agents/skills/nsr-compliance/assets/nsr/assets/RULES/security.md

@@ -0,0 +1,22 @@
+# Security Rules — __PROJECT__
+
+## Access Control
+- Auth via the project's identity provider; roles scoped per tenant.
+- API tokens required on every request; tenant resolved per-request from token claims.
+
+## Secrets
+- Never commit secrets. All secrets via env / secret manager.
+- `.env` is git-ignored; only `.env.example` templates are committed.
+- Keys injected at deploy time via `docs/CI_CD/deployment/deploy.sh` + secret manager.
+
+## Tenant Isolation
+- Queries are scoped by tenant at the DB layer — never fetch across tenants.
+
+## Vulnerability Gates
+- `.compliance/gates/check_env.sh` fails if required secrets are absent.
+- Dependencies pinned in `TECH_STACK.md`; no floating/latest in production.
+- Run `.agents/skills/features/<feature>/test.sh` before any PR.
+
+## Enforced By
+- `.compliance/gates/*` — exit-code gates.
+- CI deploy order: `check_env → check_paths → check_platform → validate_code`.

package/.agents/skills/nsr-compliance/assets/nsr/assets/RULES/tech-stack.md

@@ -0,0 +1,8 @@
+# Tech-Stack Rules — __PROJECT__
+
+1. **One primary stack per feature** — see `TECH_STACK.md` mapping; no undocumented second stacks.
+2. **Pin versions** — recorded in `TECH_STACK.md`; no floating/latest in production.
+3. **No new stack without registration** — update `TECH_STACK.md` + `FEATURES.md` first.
+4. **Cross-platform** — stacks run on Mac/Linux/Windows or are containerized with pinned images.
+5. **License & cost vetting** — before adopting a new stack.
+6. **Consistency over novelty** — prefer the existing stack for a category.

package/.agents/skills/nsr-compliance/assets/nsr/assets/agents_skills/NSRcompliance/SKILL.md

@@ -0,0 +1,71 @@
+# SKILL.md — Embedded Agent Skill Compliance
+
+Headless CLI runner + local validation layer — the sole, script-first compliance mechanism.
+
+The compliance skill is **self-contained**: it needs no rest of the NSR repo. It carries its own runner, gates, telemetry, envelopes, templates, and a generator that stamps `.compliance/` into whatever repo it is deployed into.
+
+## Purpose
+
+- Generate the deterministic `.compliance/` harness into a repo with one command.
+- Execute feature + lifecycle scripts and gate checks locally inside that repo.
+- Enforce typed envelopes (validated before any run) and wired, non-stub scripting.
+- Record every run (phase, status, latency, cost) into a local SQLite DB.
+
+## Capabilities
+
+- **Generate** — `generate.sh [TARGET]` stamps a `.compliance/` tree into the host repository (idempotent; `--force`). Stack-agnostic: the wiring that follows adapts to whatever stack the repo uses.
+- **Harness** — `harness/runner.py` orchestrates gates + feature scripts; validates typed envelopes; full `--plan` runs (envelope → gates → feature action → result envelope); `--list` shows the script registry.
+- **Danger validation** — `gates/check_danger.sh` flags scripts containing dangerous primitives unless they declare `# gate: dev|guard|human`. The runner refuses to auto-run human/guard-gated scripts.
+- **Wiring awareness** — `gates/check_wiring.sh` reports which scripts are still shipped stubs vs bound to the project's real commands (`--strict` must pass before agents are trusted).
+- **Gates** — `gates/check_env.sh`, `check_paths.sh`, `check_platform.sh`, `validate_code.sh`, `verify_docs.py` decide pass/fail by `$? == 0`.
+- **Config** — `config/core_four.yaml` governs Context, Model, Prompt, Tools per phase.
+- **Envelopes** — `harness/envelopes/task_envelope.json` (+ `result_envelope.json`) valid task packets; success must be earned.
+- **Telemetry** — `telemetry/logger.py` writes runs/events to SQLite (`runs.db`); readers poll SQLite.
+
+## Usage
+
+```
+# 1. Generate the harness into this repo (self-contained)
+.agents/skills/NSRcompliance/generate.sh
+
+# 2. Report wiring status; strict before trusting agents
+.compliance/gates/check_wiring.sh
+.compliance/gates/check_wiring.sh --strict
+
+# 3. Danger audit
+.compliance/gates/check_danger.sh
+
+# 4. Validate a task envelope (exit 1 on any schema violation)
+.compliance/harness/runner.py --envelope .compliance/harness/envelopes/task_envelope.json
+
+# 5. Full run: envelope -> gates -> feature action -> result envelope
+.compliance/harness/runner.py --plan <task-envelope.json> --action test
+
+# 6. Run a feature / all gates / inspect the registry
+.compliance/harness/runner.py --feature <name> --action test
+.compliance/harness/runner.py --gates
+.compliance/harness/runner.py --list
+
+# 7. Telemetry
+.compliance/telemetry/logger.py log --phase plan --status success --latency-ms 120
+.compliance/telemetry/logger.py query --last 10
+```
+
+## Wiring to the project (what binds the compliance to your stack)
+
+The compliance is project-agnostic by design; the WIRING layer is where it benefits the specific project.
+
+1. Replace the stub bodies in `.agents/skills/lifecycle/{start,stop,status,smoke_test}.sh` with your real commands (Phoenix: `mix phx.server`; Node: `npm run dev`; Django: `manage.py runserver`...). Existing procedures are **wrapped, never replaced** — delegate to them and add env/exit-code guards.
+2. For every feature in `FEATURES.md`, wire `features/<name>/{setup,test,smoke_test,rollback}.sh` to the app's real suites and seeds.
+3. Add `# gate: dev|guard|human` to any script that touches production-affecting primitives.
+4. Prove it: `check_wiring.sh --strict` and `check_danger.sh` must pass.
+
+Walkthrough: `docs/BEST_PRACTICES/compliance-wiring.md`.
+
+## Rules
+
+- Zero ad-hoc shell commands — invoke compliance scripts only.
+- Gate results are evaluated by `$? == 0`, never by parsing text output.
+- Never lose a function: wiring delegates to existing procedures and adds guards.
+- Generated `.compliance/` is derived from this skill — regenerate, don't hand-edit both copies.
+- Syncs with WayOfTeams (Kanban Board, Knowledge Base, Anchor Memory) over MCP.

package/.agents/skills/nsr-compliance/assets/nsr/assets/agents_skills/NSRcompliance/config/core_four.yaml

@@ -0,0 +1,16 @@
+core_four:
+  context:
+    default: "docs/features/*.md"
+    routing: "AGENTS.md, STRUCTURE.md, FEATURES.md"
+    scoped: ".agents/skills/**/SKILL.md"
+  model:
+    coding: "fast-cheap-model"
+    planning: "large-reasoning-model"
+    default: "default-model"
+  prompt:
+    system: "Follow WayOfNorthstarRules.md and AGENTS.md. No ad-hoc shell commands."
+    per_feature: ".agents/skills/features/<feature>/SKILL.md"
+  tools:
+    allowed_scripts: ".agents/skills/**"
+    forbidden: ["npm test", "git commit -m", "kill -9"]
+    handoff_format: "JSON/YAML typed envelopes"

package/.agents/skills/nsr-compliance/assets/nsr/assets/agents_skills/NSRcompliance/gates/check_danger.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# check_danger: validate that scripts may be run by the compliance, or are explicitly gated.
+#
+# Any script containing a dangerous primitive (data loss, force ops, shell
+# injection, destructive commands) MUST declare its blast radius in a comment:
+#
+#   # gate: dev    - safe for agents/automation in dev; human confirm in prod
+#   # gate: guard  - must not run until a required guard script passes
+#   # gate: human  - irreversible; agents must never run this alone
+#
+# A script with dangerous primitives and no # gate: annotation FAILS this check.
+#
+# Usage:
+#   check_danger.sh            # scan .agents/skills/{lifecycle,git_ops,features,compliance}
+#   check_danger.sh --path <f> # evaluate a single script in isolation
+set -e
+
+find_root() {
+  local d; d="$(cd "$(dirname "$0")" && pwd)"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/.agents" ]; then echo "$d"; return 0; fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+ROOT="$(find_root)" || { echo "[check_danger] FAIL: no repo root (.agents/ not found upward)"; exit 1; }
+SINGLE_PATH=""
+
+DANGER_PRIMS=(
+  'rm[[:space:]]+-rf'
+  'rm[[:space:]]+-fr'
+  ':\(\)[[:space:]]*\{'
+  'kill[[:space:]]+-9'
+  'pkill'
+  'taskkill'
+  'git[[:space:]]+push[[:space:]]+--force'
+  'git[[:space:]]+reset[[:space:]]+--hard'
+  'DROP[[:space:]]+(TABLE|DATABASE)'
+  'TRUNCATE[[:space:]]+TABLE'
+  'dd[[:space:]]+if='
+  'mkfs'
+  'chmod[[:space:]]+-R[[:space:]]+777'
+  'curl[[:space:]].*\|[[:space:]]*sh'
+  'wget[[:space:]].*\|[[:space:]]*sh'
+)
+
+GATE_RE='^[[:space:]]*# gate:[[:space:]]*(dev|guard|human)([[:space:]]+.*|:|$)'
+
+has_danger() {
+  local f="$1" prim
+  for prim in "${DANGER_PRIMS[@]}"; do
+    grep -qiE "$prim" "$f" 2>/dev/null && return 0
+  done
+  return 1
+}
+
+has_gate() { grep -qiE "$GATE_RE" "$1" 2>/dev/null; }
+
+check_file() {
+  local f="$1" g
+  has_danger "$f" || return 0
+  if has_gate "$f"; then
+    g="$(grep -iE "$GATE_RE" "$f" | head -1 | sed -E 's/^[[:space:]]*//')"
+    echo "  OK   [gated] $g"
+    echo "        $f"
+  else
+    echo "  FAIL [ungated danger] $f"
+    echo "        contains a dangerous primitive but no '# gate:' annotation"
+    return 1
+  fi
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path) SINGLE_PATH="$2"; shift 2 ;;
+    -h|--help) echo "usage: check_danger.sh [--path FILE]"; exit 0 ;;
+    -*) echo "unknown option: $1"; exit 1 ;;
+    *) SINGLE_PATH="$1"; shift ;;
+  esac
+done
+
+fail=0
+
+if [ -n "$SINGLE_PATH" ]; then
+  check_file "$SINGLE_PATH" || fail=1
+else
+  echo "[check_danger] scanning $ROOT/.agents/skills for dangerous primitives"
+  for f in "$ROOT"/.agents/skills/lifecycle/*.sh \
+           "$ROOT"/.agents/skills/git_ops/*.sh \
+           "$ROOT"/.agents/skills/features/*/*.sh; do
+    [ -f "$f" ] || continue
+    check_file "$f" || fail=1
+  done
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "[check_danger] FAIL: dangerous scripts without a # gate: annotation"
+  exit 1
+fi
+echo "[check_danger] PASS: no undeclared dangerous scripts"
+exit 0

package/.agents/skills/nsr-compliance/assets/nsr/assets/agents_skills/NSRcompliance/gates/check_wiring.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# check_wiring: does the compliance actually touch the project, or is it still stubs?
+#
+# A script is WIRED when the shipped STUB marker is gone from its body. A freshly
+# scaffolded repo is 100% stubs — that is fine during bootstrap. Before you trust
+# the compliance (run agents against it, deploy for real) run --strict: it must pass.
+#
+# Usage:
+#   check_wiring.sh             # report wired vs stub; exit 0 unless required scripts missing
+#   check_wiring.sh --strict    # exit 1 if any required script is missing or still a stub
+set -e
+
+find_root() {
+  local d; d="$(cd "$(dirname "$0")" && pwd)"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/.agents" ]; then echo "$d"; return 0; fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+ROOT="$(find_root)" || { echo "[check_wiring] FAIL: no repo root (.agents/ not found upward)"; exit 1; }
+STRICT=0
+[ "${1:-}" = "--strict" ] && STRICT=1
+
+fail=0
+
+echo "[check_wiring] scanning for real-world wiring under $ROOT"
+
+is_stub() {
+  grep -qiE '\bSTUB\b|# stub[: ]' "$1" 2>/dev/null
+}
+
+check_script() {
+  local f="$1"
+  [ -f "$f" ] || { [ "$STRICT" -eq 1 ] && { echo "  FAIL [MISSING] $f"; fail=1; }; return 0; }
+  if is_stub "$f"; then
+    if [ "$STRICT" -eq 1 ]; then
+      echo "  FAIL [STUB  ] $f"
+      fail=1
+    else
+      echo "  warn [STUB  ] $f (not wired — see docs/BEST_PRACTICES/compliance-wiring.md)"
+    fi
+  else
+    echo "  ok   [WIRED ] $f"
+  fi
+}
+
+# lifecycle is mandatory for a project to be operable
+for f in start stop status smoke_test; do
+  check_script "$ROOT/.agents/skills/lifecycle/$f.sh"
+done
+
+# every feature dir must have its five script domains wired
+for d in "$ROOT"/.agents/skills/features/*/; do
+  [ -d "$d" ] || continue
+  for f in setup test smoke_test rollback; do
+    check_script "$d/$f.sh"
+  done
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "[check_wiring] STRICT FAIL — compliance scripts are stubs/missing, not wired to the project."
+  echo "[check_wiring] Wire them per docs/BEST_PRACTICES/compliance-wiring.md, then re-run."
+  exit 1
+fi
+[ "$STRICT" -eq 1 ] && echo "[check_wiring] PASS (strict) — every required script is wired"
+[ "$STRICT" -eq 0 ] && echo "[check_wiring] PASS (report) — nothing missing for a bootstrap repo"
+exit 0

package/.agents/skills/nsr-compliance/assets/nsr/assets/agents_skills/NSRcompliance/gates/validate_code.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Deterministic gate: run test + lint checks. Exit 0 = pass, non-zero = fail.
+set -e
+
+echo "[gate] validate_code: running lint + test gates"
+
+gates_passed=0
+
+for gate in .compliance/gates/*.sh; do
+  if [ -x "$gate" ]; then
+    echo "[gate] running $gate"
+    "$gate" || gates_passed=1
+  fi
+done
+
+for script in .agents/skills/features/*/test.sh; do
+  if [ -f "$script" ]; then
+    echo "[gate] running $script"
+    bash "$script" || gates_passed=1
+  fi
+done
+
+if [ "$gates_passed" -eq 0 ]; then
+  echo "[gate] PASS ($? == 0)"
+  exit 0
+fi
+
+echo "[gate] FAIL"
+exit 1

package/.agents/skills/nsr-compliance/assets/nsr/assets/agents_skills/NSRcompliance/gates/verify_docs.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# Deterministic gate: ensure STRUCTURE.md, FEATURES.md, HOSTING/, DEVELOPER_SETUP/ and TECH_STACK.md are in sync with the repo.
+import json
+import pathlib
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[4]
+MANDATORY = [
+    "AGENTS.md", "ARCHITECTURE.md", "STRUCTURE.md", "FEATURES.md",
+    "RULES.md", "BEST_PRACTICES.md", "CI_CD.md", "TECH_STACK.md", "README.md",
+]
+MANDATORY_DIRS = [
+    "RULES", "docs/features", "docs/BEST_PRACTICES", "docs/CI_CD",
+    "docs/DEVELOPER_SETUP", "docs/HOSTING", "docs/RUNBOOK", "docs/research",
+    ".agents/skills", ".compliance",
+]
+EXPLICIT_DOCS = {
+    "docs/HOSTING": ["README.md", "_template.md"],
+    "docs/DEVELOPER_SETUP": ["README.md"],
+}
+EXPLICIT_SUBDIRS = {
+    "docs/HOSTING": [],          # hosting-N.md files are enumerated dynamically
+    "docs/DEVELOPER_SETUP": ["developers"],  # dev-N.md files are enumerated dynamically
+}
+
+
+def enumerate_explicit(directory: str, subdir: str) -> list:
+    base = ROOT / directory
+    if subdir:
+        base = base / subdir
+    if not base.exists():
+        return []
+    return sorted(p.name for p in base.glob("*.md") if p.name not in ("README.md", "_template.md"))
+
+
+def main() -> int:
+    missing = [f for f in MANDATORY if not (ROOT / f).exists()]
+    missing_dirs = [d for d in MANDATORY_DIRS if not (ROOT / d).exists()]
+
+    problems = []
+    for directory, required in EXPLICIT_DOCS.items():
+        for name in required:
+            if not (ROOT / directory / name).exists():
+                problems.append(f"{directory}/{name}")
+
+    # Every hosting/developer must have its own explicit file (numbered *_N.md or dev-N.md)
+    for directory, subdirs in EXPLICIT_SUBDIRS.items():
+        subdirs_to_check = subdirs if subdirs else [""]
+        for subdir in subdirs_to_check:
+            entries = enumerate_explicit(directory, subdir)
+            if not entries:
+                problems.append(f"{directory}/{subdir}/<explicit file missing>" if subdir else f"{directory}/<hosting file missing>")
+
+    if missing or missing_dirs or problems:
+        print(json.dumps({
+            "missing_files": missing,
+            "missing_dirs": missing_dirs,
+            "explicit_docs_missing": problems,
+        }))
+        return 1
+    print(json.dumps({"ok": True, "docs_synced": True}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())