mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
Bo
e556834d3d
## Legible membrane, Train 1: fix what ships Intent source: `docs/plans/2026-09-02-legible-membrane-plan.md` (added in this PR). Provenance: the 2026-09-02 field audit of this repo against mattpocock/skills, compound-engineering, and the jsm corpus. Three defects a stranger hits today, all verified on `main` before the change: 1. **Codex projection truncated 51 of 56 skill descriptions mid-clause** (`scripts/codex-sync.sh` capped prose at 44 chars, so the Codex router read "Freshly judge whether a finished change is Triggers: …"). Now: first sentence of the source prose plus the full `Triggers:` clause, abbreviation- and quote-aware; the per-catalog bound is computed live as "Codex prose average may not exceed Claude's" (cross-multiplied, floor-free) with a 180-char hard ceiling. `using-flywheel` is exempted from runtime-phrase rewriting so its cross-runtime text projects verbatim. The dormant `ao codex ensure-start` emitter and the `# /x`→`# $x` title rewrite are removed. A literal oracle pins five twins and a rule oracle covers all 56. 2. **23 shebang-bearing shell entry points were committed non-executable**, including `scripts/regen-all.sh` and three gate scripts. Now `100755`, with an advisory gate `shell.exec-bits` (fast+full, fail-closed on enumeration error, reads the index blob, skips symlinks by stated policy). 3. **`tests/run-all.sh` was red on `main`**: the GOALS validator asserted a pre-08-25 file shape, and validate's description exceeded the 180-char budget. The validator now parses only the `## Gates` block (stops at any heading, like production), requires cited script paths to exist, takes its path via argv, and fails closed on tokenization; four negative fixtures. validate's description is 177 chars and gains the reality-check negative. `AGENTS.md` quotes CI's authoritative bats and Go commands. README and `docs/install-day2-ops.md` replace "No other runtime is required" with a runtime table derived by reading each skill's procedure (HARD / OPTIONAL / conditional), covered by a bats test that grounds every HARD row in an invocation line. Evidence on the tip: full gate 71/71 (HEAD binary), CI's bats command green across `tests/scripts/*.bats`, `tests/run-all.sh` green, Go build/vet/test green, golangci-lint clean, security gate quick PASS, `scripts/regen-all.sh --check` clean. Each lane was validated by a fresh context; the integrated train had two cross-family (Codex) review rounds and every finding is closed on this tip. Out of scope (successor intent): promoted set / `skills-internal/`, the process-artifact sweep, "It's working if" blocks, routing clusters, doctrine diet. One pre-existing drift noted for a follow-up: `packs/agentops-executor/agents/validator/skills/validate/SKILL.md` carries a stale third description that no gate binds.
71 lines
3.2 KiB
Bash
Executable File
71 lines
3.2 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# shellcheck shell=bash
|
|
# scripts/lib/docs-scope.sh — sourced library: shared LIVE-doc scope resolution
|
|
# and the "is this doc historical-by-design" exemption test.
|
|
#
|
|
# Source it (do NOT execute it):
|
|
# . "$(CDPATH= cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/docs-scope.sh"
|
|
#
|
|
# Shared LIVE-doc scope helper (age-gate-the-ungated-egwt.1)
|
|
# so any docs-scoped gate resolves the SAME live-doc set and the SAME
|
|
# historical-exemption rule from one place. The retired-tech line-level
|
|
# REMOVAL_LANG past-tense exemption is retired-tech-specific and stays in that
|
|
# check script — it is deliberately NOT part of this lib.
|
|
#
|
|
# IMPORTANT — behavior-preserving contract: this lib does NOT `set -euo pipefail`
|
|
# on behalf of its callers. Historical extractor
|
|
# sets strict mode itself; forcing it here could change a different caller's
|
|
# behavior. The functions below are pure/idempotent and safe under either mode.
|
|
#
|
|
# Scope resolution is anchored at DOCS_ROOT (default: the current directory).
|
|
# Callers that `cd` to the repo root before use get the historical relative
|
|
# `docs/...` paths unchanged; tests inject DOCS_ROOT to point at a fixture tree.
|
|
|
|
# docs_scope_live_files — emit the LIVE docs/**/*.md set (one path per line),
|
|
# NUL-safe ordering via `sort`. Paths are emitted relative to DOCS_ROOT and
|
|
# always begin with `docs/` (matching the extracting script's historical output).
|
|
#
|
|
# The exclude list is the dated/historical-archive set copied verbatim from
|
|
docs_scope_live_files() {
|
|
local root="${DOCS_ROOT:-.}"
|
|
( cd "$root" && find docs -name '*.md' \
|
|
-not -path 'docs/adr/*' \
|
|
-not -path 'docs/audits/*' -not -path 'docs/plans/*' -not -path 'docs/brainstorms/*' \
|
|
-not -path 'docs/council*/*' -not -path 'docs/handoffs/*' -not -path 'docs/learnings/*' \
|
|
-not -path 'docs/evidence/*' -not -path 'docs/releases/*' -not -path 'docs/convergence/*' \
|
|
-not -path 'docs/rescope/*' -not -path 'docs/reduction/*' -not -path 'docs/migration-trackers/*' \
|
|
-not -path 'docs/sovereignty-proof/*' -not -path 'docs/rfcs/*' -not -path 'docs/code-map/*' \
|
|
| sort )
|
|
}
|
|
|
|
# docs_scope_is_exempt FILE — return 0 (exempt / historical-by-design) if the
|
|
# doc opts out of live-staleness scanning by ANY of:
|
|
# - a migration/upgrade/retirement/closeout/index filename glob
|
|
# - a RETIRED / HISTORICAL / SUPERSEDED banner in its FIRST 15 lines
|
|
# - living under docs/adr/
|
|
# Otherwise return 1 (a live doc, in scope).
|
|
#
|
|
# FILE is resolved relative to DOCS_ROOT when it is not already readable as-is,
|
|
# so callers that pass a `docs/...` path after `cd`-ing to the root keep working
|
|
# unchanged, while a test can point DOCS_ROOT at a fixture tree.
|
|
docs_scope_is_exempt() {
|
|
local f="$1"
|
|
case "$f" in
|
|
*-migration*|*-retirement*|*-sunset*|*-closeout*|*CHANGELOG*) return 0 ;;
|
|
*MIGRATION*|*UPGRADING*|*documentation-index*) return 0 ;;
|
|
esac
|
|
# docs/adr/ is historical by design.
|
|
case "$f" in
|
|
docs/adr/*|*/docs/adr/*) return 0 ;;
|
|
esac
|
|
# self-declared historical banner in the first 15 lines
|
|
local path="$f"
|
|
if [ ! -r "$path" ] && [ -n "${DOCS_ROOT:-}" ] && [ -r "${DOCS_ROOT%/}/$f" ]; then
|
|
path="${DOCS_ROOT%/}/$f"
|
|
fi
|
|
if head -n 15 "$path" 2>/dev/null | grep -qiE 'RETIRED|HISTORICAL|SUPERSEDED'; then
|
|
return 0
|
|
fi
|
|
return 1
|
|
}
|