@nurix/etna 0.10.1 → 0.13.0

package/data/harnesses/code/scripts/check-doc-drift.sh

@@ -1,135 +0,0 @@
-#!/usr/bin/env bash
-# scripts/check-doc-drift.sh - Detect potentially stale docs based on recent code changes
-# plugins: [nurix-harness]
-
-set -euo pipefail
-
-DAYS="${1:-14}"
-# Resolve the repo root from this script's own location — it lives at either
-# <root>/scripts/ (kit source) or <root>/.claude/scripts/ (installed into a
-# project). Strip whichever suffix applies; works regardless of git or cwd,
-# and stays correct when the harness sits in a monorepo subdirectory.
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-case "$SCRIPT_DIR" in
-    */.claude/scripts) REPO_ROOT="${SCRIPT_DIR%/.claude/scripts}" ;;
-    */scripts) REPO_ROOT="${SCRIPT_DIR%/scripts}" ;;
-    *) REPO_ROOT="$(dirname "$SCRIPT_DIR")" ;;
-esac
-FEATURES_DIR="$REPO_ROOT/docs/features"
-TMP_OWNS=$(mktemp)
-TMP_STALE=$(mktemp)
-TMP_UNOWNED=$(mktemp)
-trap 'rm -f "$TMP_OWNS" "$TMP_STALE" "$TMP_UNOWNED"' EXIT
-
-echo "Checking for doc drift over the last $DAYS days..."
-echo ""
-
-# Extract owns patterns from a markdown file
-extract_owns() {
-    local file="$1"
-    awk '
-        /^---$/ { fm++; next }
-        fm == 1 && /^owns:/ { in_owns = 1; next }
-        fm == 1 && in_owns && /^  +- / {
-            sub("^  +- ", "")
-            gsub(/^[ \t]+|[ \t]+$/, "")
-            print
-            next
-        }
-        fm == 1 && in_owns && /^[a-z]/ { exit }
-        fm >= 2 { exit }
-    ' "$file"
-}
-
-# Get recently changed files
-changed_files=$(cd "$REPO_ROOT" && git log --since="$DAYS days ago" --name-only --pretty=format:"" | sort -u | grep -v '^$' || true)
-
-if [ -z "$changed_files" ]; then
-    echo "No files changed in the last $DAYS days."
-    exit 0
-fi
-
-changed_count=$(echo "$changed_files" | wc -l | tr -d ' ')
-echo "Found $changed_count changed files in the last $DAYS days."
-echo ""
-
-# Build ownership map: pattern\tdoc
-find "$FEATURES_DIR" -name "*.md" ! -name "README.md" -print0 | sort -z | while IFS= read -r -d '' file; do
-    rel_path="${file#$REPO_ROOT/}"
-    extract_owns "$file" | while IFS= read -r pattern; do
-        [ -z "$pattern" ] && continue
-        printf '%s\t%s\n' "$pattern" "$rel_path" >> "$TMP_OWNS"
-    done
-done
-
-# Check each changed file against ownership
-echo "$changed_files" | while IFS= read -r changed_file; do
-    [ -z "$changed_file" ] && continue
-    # Skip non-source files
-    case "$changed_file" in
-        docs/*|.claude/*|.github/*|node_modules/*|package*.json|*.lock*|*.config*) continue ;;
-    esac
-
-    found_owner=0
-    while IFS=$'\t' read -r pattern doc; do
-        prefix="${pattern%%\*\**}"
-        prefix="${prefix%%\**}"
-        case "$changed_file" in
-            ${prefix}*)
-                found_owner=1
-                # Check if the doc was also modified recently
-                if ! echo "$changed_files" | grep -q "^${doc}$"; then
-                    printf '%s\t%s\n' "$doc" "$changed_file" >> "$TMP_STALE"
-                fi
-                break
-                ;;
-        esac
-    done < "$TMP_OWNS"
-
-    if [ "$found_owner" -eq 0 ]; then
-        case "$changed_file" in
-            src/*|app/*|packages/*) echo "$changed_file" >> "$TMP_UNOWNED" ;;
-        esac
-    fi
-done
-
-# Report stale docs
-if [ -s "$TMP_STALE" ]; then
-    echo "## Potentially Stale Docs"
-    echo ""
-    echo "These docs own code that changed recently, but the docs themselves were not updated:"
-    echo ""
-    current_doc=""
-    sort "$TMP_STALE" | while IFS=$'\t' read -r doc file; do
-        if [ "$doc" != "$current_doc" ]; then
-            [ -n "$current_doc" ] && echo ""
-            echo "**$doc**"
-            current_doc="$doc"
-        fi
-        echo "  - $file"
-    done
-    echo ""
-else
-    echo "## No Stale Docs Detected"
-    echo ""
-    echo "All docs whose owned code changed were also updated."
-fi
-
-echo ""
-
-# Report unowned files
-if [ -s "$TMP_UNOWNED" ]; then
-    unowned_count=$(wc -l < "$TMP_UNOWNED" | tr -d ' ')
-    echo "## Unowned Changed Files ($unowned_count)"
-    echo ""
-    echo "These changed source files have no owning feature doc:"
-    echo ""
-    sort -u "$TMP_UNOWNED" | head -30 | while IFS= read -r file; do
-        echo "- $file"
-    done
-    if [ "$unowned_count" -gt 30 ]; then
-        echo "- ... and $((unowned_count - 30)) more"
-    fi
-else
-    echo "## No Unowned Changed Files"
-fi

package/data/harnesses/code/skills/introspect/SKILL.md

@@ -1,136 +0,0 @@
----
-name: introspect
-description: Pre-implementation impact analyzer. Reads a plan in docs/history/plans/ and checks every Proposed Change against the typed boundaries in docs/boundaries/ to surface cascading risks before coding starts. Produces a severity-ranked violation report with suggested plan additions. Read-only. Triggers on "introspect", "check this plan", "impact analysis", "/introspect", "what could break", "boundary check before I start".
-plugins: [nurix-harness]
----
-
-# Introspect Skill
-
-Pre-implementation impact analysis. Reads a plan, intersects every proposed change with the documented boundaries in `docs/boundaries/`, and surfaces cascading risk _before_ implementation. The complement to `contract-monitor`, which scans the live codebase _after_ changes land.
-
-The skill is read-only. It does not edit the plan, modify code, or write to memory. Output is a report the user reviews and acts on.
-
----
-
-## When to Use
-
-Trigger this skill when:
-
-- The user types `/introspect`, "introspect", "check this plan", "impact analysis", "what could break"
-- A plan exists in `docs/history/plans/` and the user is about to start implementation
-- A plan was recently revised and the user wants to re-check boundary impact
-
-Do not run it when:
-
-- No `docs/boundaries/` exists, or it's empty — tell the user to baseline the typed boundaries first via the `boundary-mapper` agent (`baseline boundaries`)
-- No plan exists — tell the user to write a plan first (documentation skill, `create plan`)
-- The user wants post-implementation auditing — that's the `contract-monitor` agent
-
----
-
-## Inputs
-
-- **Plan path**: user-provided. If unspecified, use the most recent file in `docs/history/plans/` (sorted by filename date).
-- **Boundaries**: every file in `docs/boundaries/` is mandatory input. Stop if the folder is missing or empty (suggest `boundary-mapper`).
-- **Source files**: read on demand to verify intersections — never guess from plan text alone.
-
----
-
-## Workflow
-
-### Phase 1: Load
-
-1. Resolve the plan path. If the user named a feature, glob `docs/history/plans/*{feature}*.md` and pick the newest.
-2. Read the plan in full.
-3. Confirm it has a `Status:` field. If `Complete` or `Abandoned`, ask the user whether they want to introspect a frozen plan anyway — it's usually a mistake.
-4. Read every file in `docs/boundaries/`. For each boundary, parse the `[BOUNDARY: type · severity]` header plus: **Bounds** (the modules on each side of the contract), **Shape** (the transcribed contract, or a `file:line` pointer to self-locating code), **Invariants** (what must hold), **Blast radius** (what breaks if violated), and the **Safe-change checklist**. The severity (CRITICAL / HIGH / MED / LOW) sets the review depth for any change that touches that boundary.
-
-### Phase 2: Parse Proposed Changes
-
-The plan template's **Proposed Changes** subsections are load-bearing — introspect relies on their exact structure. Extract content from each:
-
-| Subsection | What introspect uses it for |
-|------------|------------------------------|
-| **New Files** | New paths to check against ownership and the modules each boundary **Bounds** |
-| **Modified Files** | Existing paths to check against boundaries that **Bound** them |
-| **New Entities / State** | Entity strings, state slices, schema additions — checked against the `domain` and `db-schema` boundaries |
-| **API Changes** | New or modified routes, contracts, request/response shapes — checked against the `api` / `wire-contracts` boundaries |
-| **Cross-Module Contracts Affected** | The plan author's own admission of boundaries touched — start here, then verify |
-
-If a subsection is missing or empty, note it in the report (the plan may be incomplete) but continue with what's there.
-
-### Phase 3: Analyze
-
-For each boundary × proposed change pair, check intersection:
-
-1. **Bounds overlap** — does the change touch any module the boundary **Bounds**, or any file its **Shape** pointer (`file:line`) locates?
-2. **Invariant overlap** — does the change introduce code shapes the boundary's **Invariants** prohibit (raw string literal where a shared constant is required, new entity type not in the canonical array, persisted field without selector fallback)?
-3. **Shape overlap** — does the change modify the canonical **Shape** of a boundary (the `ENTITY_TYPES` array, the shared constants file, the persistence schema, the API envelope)?
-
-Whenever an intersection is plausible from plan text, **read the actual source files** to verify. Never guess from plan text alone.
-
-Assign severity. Anchor it to the **boundary's own severity** (it sets the floor), then adjust by the concrete risk this change carries — a change against a CRITICAL/HIGH boundary starts at that floor; downgrade only with a stated reason. The boundary's **Blast radius** is the evidence for the rating:
-
-- **Critical** — silent data loss, corrupted persistence, broken cross-entity references
-- **High** — stale state, broken lookups, schema selectors without fallbacks
-- **Medium** — potential mismatch, string-coupling that's likely to drift
-- **Low** — unlikely issue, code smell, easily caught in review
-
-### Phase 4: Report
-
-Produce a markdown report:
-
-```
-# Introspect — {plan filename}
-
-Plan: {path}
-Boundaries: {N} files evaluated
-Intersections found: {N} ({critical}/{high}/{medium}/{low})
-
-## Violations
-
-| # | Boundary | Risk | Severity | Plan step |
-|---|----------|------|----------|-----------|
-
-## Suggested Plan Additions
-
-For each violation, a specific recommendation:
-
-- **Violation #1**: Add step X to Implementation Steps — {one-line action}
-- **Violation #2**: Add to Done Criteria — {one-line check}
-- **Violation #3**: Update Cross-Module Contracts Affected — {missing entry}
-
-## Missing Subsections
-
-{If any Proposed Changes subsection was empty or absent, list it here}
-
-## New Cross-Module Contracts Detected
-
-{If the plan introduces a cross-cutting contract not yet in `docs/boundaries/`, describe the proposed boundary (type, Bounds, Shape, suggested severity) and recommend running the `boundary-mapper` agent to formalize it — never write a boundary file directly.}
-```
-
-The severity-ranked table is the load-bearing output. Suggestions are advisory — the user decides which to fold back into the plan.
-
-### Phase 5: Hand Off
-
-After producing the report:
-
-- If the user accepts a suggested plan addition, they edit the plan themselves (or invoke the documentation skill to do it). Introspect never edits plans.
-- If new contracts are detected, suggest running the `boundary-mapper` agent to formalize them as a typed boundary — do not write to `docs/boundaries/` from this skill.
-
----
-
-## Rules
-
-- **Read-only**. Never edit the plan, source code, boundaries, or memory.
-- **Verify against source**. Never report a violation purely from plan text — read the files the plan claims it will touch.
-- **Plan structure is load-bearing**. If a plan was not written using the documentation skill's plan template, the Proposed Changes subsections may be missing. Note this clearly rather than fabricating intersections.
-- **A clean report is valid**. Plans with no intersections produce an empty violations table — say so, don't pad.
-- **Be specific**. Cite file paths, plan-step numbers, boundary names, and the exact code shape that breaks the contract.
-- **Don't replicate contract-monitor**. Introspect checks intent (plan text). Contract-monitor checks reality (code). If the user wants to scan live code, route them to contract-monitor.
-
----
-
-## Output Location
-
-The report is returned in the chat — not written to disk. The user reviews it and folds insights back into the plan manually (or via the documentation skill).