diff --git a/README.md b/README.md index ba62f5e..6cb1a51 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ | Path | Purpose | |---|---| -| `templates/ci-guardrails/` | **Layer B.2 CI/Pipeline Cost Economy** reference templates (5 levers) — bootstrap defaults materializing P12 Shared-Resource Pre-flight | +| `templates/ci-guardrails/` | **Layer B.2 CI/Pipeline Cost Economy** reference templates (5 levers) — bootstrap defaults materializing P9 Shared-Resource Pre-flight | | `templates/llm-ci-economy/` | **Layer B.2 sub-domain LLM-Inference-Cost-Economy** — workflow demonstrating prompt-caching, model-tier, diff-only context, trigger-set minimalism LLM-aware, and green-not-skipped draft gate | -| `templates/cost-ledger/` | **Layer B.1** cost-ledger template with three dimensions: token (billed-equivalent), infra/CI, and LLM-API-in-CI (P12) | +| `templates/cost-ledger/` | **Layer B.1** cost-ledger template with three dimensions: token (billed-equivalent), infra/CI, and LLM-API-in-CI (P9) | | `templates/consistency-validators/` | **Layer B.1 Layer 3** consistency validators — workflow and deterministic `validators.py` (cross-references-bidirectional, no-orphan-decs, frontmatter-schema, topic-tags, counter-atomicity) | | `calibration/` | **Layer B.1 Calibration discipline** — deterministic `calibrate.py` (stdlib) parses session `.jsonl`, then percentiles, then bands; `band-calibration-register.md` is the append-only audit trail (v1 baseline 2026-06-15) | @@ -23,7 +23,7 @@ ## Design posture -The **patterns** are vendor-agnostic / stack-agnostic (Layer B.2). Concrete instances (GitHub Actions YAML, specific package managers) are Layer C.2 — each header documents the equivalent for other CI providers so adopters instantiate their own. Guardrails are **bootstrap defaults, never post-incident retrofit** (P12). +The **patterns** are vendor-agnostic / stack-agnostic (Layer B.2). Concrete instances (GitHub Actions YAML, specific package managers) are Layer C.2 — each header documents the equivalent for other CI providers so adopters instantiate their own. Guardrails are **bootstrap defaults, never post-incident retrofit** (P9). ## License diff --git a/templates/ci-guardrails/README.md b/templates/ci-guardrails/README.md index 71aa0d8..6bd9fbb 100644 --- a/templates/ci-guardrails/README.md +++ b/templates/ci-guardrails/README.md @@ -1,6 +1,6 @@ # CI Guardrails — Layer B.2 reference templates -Reference implementation of the **CI/Pipeline Cost Economy** Universal Engineering Pattern (Layer B.2), materializing principle **P12 — Shared-Resource Pre-flight**. +Reference implementation of the **CI/Pipeline Cost Economy** Universal Engineering Pattern (Layer B.2), materializing principle **P9 — Shared-Resource Pre-flight**. These are **bootstrap defaults**, not post-incident retrofits. SliceOps's defining mode is aggressive multi-agent parallelism (Wedge B); CI minutes are a finite, serialized, shared resource that scales with `PR_volume × workflow_weight`. Without these guardrails the framework's main lever silently exhausts the resource (observed empirically: a hardening block hard-stopped an entire pipeline when the included CI minutes ran out under a `$0` default spending limit). diff --git a/templates/ci-guardrails/change-scoped-gating.yml b/templates/ci-guardrails/change-scoped-gating.yml index b732a2e..3ce4e90 100644 --- a/templates/ci-guardrails/change-scoped-gating.yml +++ b/templates/ci-guardrails/change-scoped-gating.yml @@ -6,7 +6,7 @@ # whether the PR actually touches code. A large fraction of SliceOps PRs are # markdown / orchestration / state (DECs, trackers, spawn-prompts) — those must # NOT trigger heavy compute. Without gating, a docs PR burns the same finite CI -# minutes as a heavy code PR (P12 anti-pattern). +# minutes as a heavy code PR (P9 anti-pattern). # # CRITICAL PAIRING: change-gating creates the "required check skipped, PR # blocked forever" trap. ALWAYS pair with `aggregation-required-gate.yml`. diff --git a/templates/ci-guardrails/concurrency-cancel.yml b/templates/ci-guardrails/concurrency-cancel.yml index 96048eb..6c116a6 100644 --- a/templates/ci-guardrails/concurrency-cancel.yml +++ b/templates/ci-guardrails/concurrency-cancel.yml @@ -6,9 +6,9 @@ # (PR / branch), cancel the in-progress run. Its savings scale with iteration # velocity — which is exactly SliceOps's normal mode (push-fix-push, many # parallel agents). This is the dominant cost lever and should be a BOOTSTRAP -# DEFAULT in every workflow, never a post-incident retrofit (P12). +# DEFAULT in every workflow, never a post-incident retrofit (P9). # -# Materializes principle P12 (Shared-Resource Pre-flight): CI minutes are a +# Materializes principle P9 (Shared-Resource Pre-flight): CI minutes are a # finite, serialized, shared resource that scales with PR_volume x workflow_weight. # # Concrete instance below: GitHub Actions. For other CI providers, apply the diff --git a/templates/ci-guardrails/dependency-cache.yml b/templates/ci-guardrails/dependency-cache.yml index 67d6731..9887589 100644 --- a/templates/ci-guardrails/dependency-cache.yml +++ b/templates/ci-guardrails/dependency-cache.yml @@ -4,7 +4,7 @@ # ============================================================================= # Pattern (vendor-agnostic): cache the package-manager store keyed by lockfile # hash so paid CI minutes are not spent re-downloading dependencies every run. -# Shortens every run; compounds with iteration velocity (P12). +# Shortens every run; compounds with iteration velocity (P9). # # Concrete instances below: GitHub Actions for npm / pip / NuGet. Other # providers: GitLab `cache:key:files`, CircleCI `restore_cache`/`save_cache`. diff --git a/templates/ci-guardrails/draft-skip.yml b/templates/ci-guardrails/draft-skip.yml index 03d46e8..45ae2e3 100644 --- a/templates/ci-guardrails/draft-skip.yml +++ b/templates/ci-guardrails/draft-skip.yml @@ -5,7 +5,7 @@ # Pattern (vendor-agnostic): skip expensive jobs (AI audit, link-crawl, heavy # build, e2e) while a PR is in draft. Draft PRs are not mergeable anyway; run # the full suite on `ready_for_review`. Saves finite CI minutes during the -# iterative drafting phase that dominates SliceOps work (P12). +# iterative drafting phase that dominates SliceOps work (P9). # # Concrete instance: GitHub Actions (`github.event.pull_request.draft`). Other # providers: GitLab `$CI_MERGE_REQUEST_DRAFT`, or a label/title convention. diff --git a/templates/consistency-validators/README.md b/templates/consistency-validators/README.md index 2095a56..04a3dd5 100644 --- a/templates/consistency-validators/README.md +++ b/templates/consistency-validators/README.md @@ -21,13 +21,13 @@ Layers 1–2 are manual (frontmatter discipline, pre-merge checklist, and HITL). | `no-orphan-decs` | empty `related-decs` AND empty `topics` ⇒ body must justify isolation | | `frontmatter-schema` | Layer 1 fields present and well-formed | | `topic-tags` | every `topics:` value ∈ canonical topic taxonomy | -| `counter-atomicity` | no two artifacts share `-NNN`; counter store ≥ real max (P12) | +| `counter-atomicity` | no two artifacts share `-NNN`; counter store ≥ real max (P9) | ### Phase 2.5 — denormalized-drift and unit/cost coherence | Check | Enforces | |---|---| -| `principle-count-coherence` | The count of P-NN headings in `principles.md` is the canonical truth; every literal "N principles" / "P1-PN" elsewhere must match. Closes the failure mode that the manual fix-on-touch does not converge (an empirically demonstrated recurrence). | +| `principle-count-coherence` | The count of P-NN headings in `principles.md` is the canonical truth; every literal "N principles" / "P4-PN" elsewhere must match. Closes the failure mode that the manual fix-on-touch does not converge (an empirically demonstrated recurrence). | | `entity-count-coherence` | The count of `NN-*.md` files in `reference/entity-catalog/` is canonical; every literal "N entities" / "N cognitive entities" / "N-entity" must match. Same denormalized-drift family as principle-count. | | `band-unit` | Token-band must be in **billed-equivalent**, NOT total-with-cache (which inflates ~5×). Flags any spec text declaring token-band in total-with-cache as the canonical unit. | | `llm-ci-cost` | **R-LLM-CI-COST.** Workflows calling a paid-LLM endpoint must: have a concurrency cancel-in-progress block, NOT trigger on `synchronize` (without a documented exception), and use a step-level draft gate that ends green-not-skipped (a `skipped` required check blocks the PR permanently). | @@ -37,10 +37,10 @@ Phase 3 (glossary-coverage, supersession-chain acyclicity, vocabulary-changes↔ ## Design - **Vendor-agnostic pattern / GitHub-Actions instance**: the *pattern* is Layer B.1; this concrete workflow is a Layer C.2 instance. Other CI providers: port the same jobs. -- **Deterministic**: `validators.py` is a fixed script (same corpus gives the same result), not stochastic regeneration — B.2 Determinism-over-Regeneration, reinforces P5 (repeatable evidence) and P12 (cost economy). +- **Deterministic**: `validators.py` is a fixed script (same corpus gives the same result), not stochastic regeneration — B.2 Determinism-over-Regeneration, reinforces P6 (repeatable evidence) and P9 (cost economy). - **Paths/prefixes are configurable**: the script takes the corpus root and prefix map as args so adopters bind it to their layout without editing logic. -- **Bootstrap default**: ships with the repo scaffold, not retrofitted post-incident (P12). +- **Bootstrap default**: ships with the repo scaffold, not retrofitted post-incident (P9). ## Adopter instantiation -Copy both files; set the corpus root and `entity:`/prefix conventions; wire `consistency-validators.yml` into branch protection behind the aggregation gate (pair with the CI guardrail templates). Extend with Phase 3 and adopter R15+ checks as the corpus grows (R-rule amendments require a DEC citing a LearningPattern — P7). +Copy both files; set the corpus root and `entity:`/prefix conventions; wire `consistency-validators.yml` into branch protection behind the aggregation gate (pair with the CI guardrail templates). Extend with Phase 3 and adopter R15+ checks as the corpus grows (R-rule amendments require a DEC citing a LearningPattern — P8). diff --git a/templates/consistency-validators/consistency-validators.yml b/templates/consistency-validators/consistency-validators.yml index 026bc04..afb3c65 100644 --- a/templates/consistency-validators/consistency-validators.yml +++ b/templates/consistency-validators/consistency-validators.yml @@ -9,7 +9,7 @@ on: pull_request: types: [opened, synchronize, reopened, ready_for_review] -# Layer B.2 CI/Pipeline Cost Economy — concurrency cancel-in-progress (P12) +# Layer B.2 CI/Pipeline Cost Economy — concurrency cancel-in-progress (P9) concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true diff --git a/templates/consistency-validators/validators.py b/templates/consistency-validators/validators.py index 12aad54..667ed95 100644 --- a/templates/consistency-validators/validators.py +++ b/templates/consistency-validators/validators.py @@ -133,8 +133,11 @@ def check_counter_atomicity(root): PRINCIPLE_RE = re.compile(r"^##\s+P(\d+)\s+—", re.M) ENTITY_FILE_RE = re.compile(r"^(\d+)-[a-z0-9-]+\.md$") +# Count CLAIMS only: the phrase "N canonical principles" or the full-set range +# P1-P12. Band sub-ranges (P1-P3, P4-P10, ...) are NOT count claims — the +# full-set alternative anchors on P12 so sub-ranges do not false-positive. COUNT_PRINCIPLE_RE = re.compile( - r"\b(\d+)\s+canonical\s+principles?\b|\bP1[-–]P(\d+)\b", re.I + r"\b(\d+)\s+canonical\s+principles?\b|\bP1\s*[-–]\s*P(12)\b", re.I ) COUNT_ENTITY_RE = re.compile( # Only the plural form or a quantified specific-noun form is canonical @@ -236,8 +239,17 @@ def check_band_unit(root): body = fh.read() except OSError: continue + lines = body.splitlines() for m in BAND_UNIT_BAD_RE.finditer(body): line = body[: m.start()].count("\n") + 1 + # Skip when the line documents the anti-pattern (corrective markers) + # rather than committing it — e.g. "... NOT total-with-cache; + # the canonical unit is billed-equivalent". + ctx = lines[line - 1].lower() if line - 1 < len(lines) else "" + if any(k in ctx for k in ("billed-equivalent", "inflates", + "canonical unit", "not total", + "instead of", "anti-pattern")): + continue rel = os.path.relpath(p, root) errs.append( f"{rel}:{line}: token-band described as 'total-with-cache' " diff --git a/templates/cost-ledger/README.md b/templates/cost-ledger/README.md index a3e97b3..d79609d 100644 --- a/templates/cost-ledger/README.md +++ b/templates/cost-ledger/README.md @@ -1,7 +1,7 @@ # Cost Ledger template — Layer B.1 -The SliceOps cost-ledger Framework Artifact, extended to a **dual dimension**: token cost and infra/CI cost (per P12 — Shared-Resource Pre-flight). +The SliceOps cost-ledger Framework Artifact, extended to a **dual dimension**: token cost and infra/CI cost (per P9 — Shared-Resource Pre-flight). `cost-ledger-template.md` is the copy-per-adopter template. Instance-specific units (CI provider, currency, quota numbers) are Layer C.2 — the adopter fills them. -The infra/CI dimension exists because token-only ledgers are blind to a finite shared resource until it hard-stops the pipeline. The pre-Block checklist embedded in the template is the operational form of the P12 pre-flight. +The infra/CI dimension exists because token-only ledgers are blind to a finite shared resource until it hard-stops the pipeline. The pre-Block checklist embedded in the template is the operational form of the P9 pre-flight. diff --git a/templates/cost-ledger/cost-ledger-template.md b/templates/cost-ledger/cost-ledger-template.md index 882bda1..9ebad4a 100644 --- a/templates/cost-ledger/cost-ledger-template.md +++ b/templates/cost-ledger/cost-ledger-template.md @@ -3,7 +3,7 @@ > SliceOps cost-ledger with **three dimensions**: token cost, infra/CI cost, and LLM-API-in-CI cost. > A token-only ledger is blind to finite shared resources (CI minutes / API > quota / LLM-API spend) until they hard-stop the pipeline. This template -> materializes P12 (Shared-Resource Pre-flight): the resource must be visible +> materializes P9 (Shared-Resource Pre-flight): the resource must be visible > *before* it cuts. The LLM-API dimension was added when LLM-Inference-Cost- > Economy (B.2 sub-domain) formalized the LLM-API budget as a third resource > class with distinct dynamics (`PR velocity × push-frequency × prompt-size`). @@ -23,13 +23,13 @@ Token-band measured in **billed-equivalent** (input + cache_creation × 1.25 + c |---|---|---|---|---|---| | BL-NN.SL-NNN | M | L | 8M | — | — | -## Infra / CI dimension (P12) +## Infra / CI dimension (P9) | Period | CI minutes used | Budget | Headroom | Alert threshold hit? | |---|---|---|---|---| | YYYY-MM | — | — | — | no | -## LLM-API-in-CI dimension (P12 and LLM-Inference-Cost-Economy) +## LLM-API-in-CI dimension (P9 and LLM-Inference-Cost-Economy) LLM API spend in CI-time audit / code-review / QA / codegen workflows. Scales with `PR velocity × push-frequency × prompt-size` — dynamics distinct from token-throughput and infra-minutes. Per-row: declare model tier, input-context shape (diff vs full file), whether the stable block is cached. @@ -37,7 +37,7 @@ LLM API spend in CI-time audit / code-review / QA / codegen workflows. Scales wi |---|---|---|---|---|---|---|---|---| | llm-audit (PRs) | mid-tier | yes | diff-only | — | $— | $— | — | no | -**Pre-Block checklist (P12 — mandatory before scaling parallelism past the +**Pre-Block checklist (P9 — mandatory before scaling parallelism past the last Block-Retrospective baseline):** - [ ] Enumerate finite/serialized shared resources this Block consumes @@ -57,7 +57,7 @@ last Block-Retrospective baseline):** - [ ] Default for every shared resource = cap+alert, never silent hard-stop ("warned degradation" > "invisible hard-cut") -## Anti-patterns (P12 and LLM-Inference-Cost-Economy) +## Anti-patterns (P9 and LLM-Inference-Cost-Economy) - Spending limit `$0` / default quota leads to "exhaust resource" becoming "invisible hard-cut" instead of "warned degradation" diff --git a/templates/llm-ci-economy/llm-ci-economy.yml b/templates/llm-ci-economy/llm-ci-economy.yml index e48693e..560274f 100644 --- a/templates/llm-ci-economy/llm-ci-economy.yml +++ b/templates/llm-ci-economy/llm-ci-economy.yml @@ -91,7 +91,7 @@ jobs: echo " - model tier matches the task complexity" echo " - input context is the diff, not full files" - # Cost-ledger row (P5): emit a per-run cost estimate for the third + # Cost-ledger row (P6): emit a per-run cost estimate for the third # dimension of the cost-ledger (LLM-API-in-CI). - name: Emit cost-ledger row if: always()