@drafthq/draft 3.4.0 → 3.5.0

package/scripts/tools/okf-validate-quality.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# okf-validate-quality.sh — deterministic per-page SEMANTIC checks for an OKF bundle.
+#
+# okf-validate.sh proves a page is structurally sound (frontmatter, type, links).
+# This proves a page is actually WRITTEN — not a stub, redirect, or template
+# leftover — so that "every module has a page" (okf-coverage-check.sh) cannot be
+# satisfied with placeholder content. Thresholds are per concept TYPE: a
+# Subsystem must carry a diagram and real depth; an ADR or Dependency legitimately
+# does not, so applying one global bar would false-fail them.
+#
+# Pages in scope: any *.md whose frontmatter declares a frozen `type:`. Section
+# index.md pages, log.md, and the generated coverage page are excluded.
+#
+# Checks (per type): required H2 sections, min body lines, >=1 mermaid block
+# (diagram types only), min x-grounded-paths, anti-stub patterns, unreplaced
+# template tokens, duplicate "What it is" paragraphs, and a syntax-only mermaid
+# lint (no Node, no headless browser).
+#
+# Usage:
+#   okf-validate-quality.sh <BUNDLE_DIR> [--strict] [--json]
+#
+# Exit codes: 0 pass, 1 fail, 2 bundle not found.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/tools/_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+BUNDLE=""
+STRICT=0
+JSON=0
+
+usage() {
+    cat <<'EOF'
+okf-validate-quality.sh — per-page semantic / anti-stub checks for an OKF bundle.
+
+Usage:
+  okf-validate-quality.sh <BUNDLE_DIR> [--strict] [--json]
+
+Flags:
+  --strict   Treat warnings (e.g. duplicate paragraphs) as failures.
+  --json     Emit a JSON summary instead of human diagnostics.
+  --help     Show this help.
+
+Exit: 0 pass, 1 fail, 2 bundle not found.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --strict) STRICT=1; shift;;
+        --json) JSON=1; shift;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *) if [[ -z "$BUNDLE" ]]; then BUNDLE="$1"; else echo "Unexpected arg: $1" >&2; exit 1; fi; shift;;
+    esac
+done
+
+[[ -n "$BUNDLE" ]] || { usage >&2; exit 1; }
+[[ -d "$BUNDLE" ]] || { echo "ERROR: bundle directory not found: $BUNDLE" >&2; exit 2; }
+BUNDLE="${BUNDLE%/}"
+
+FAILURES=()   # page\tcheck\tdetail
+WARNINGS=()
+CHECKED=0
+
+fail() { FAILURES+=("$1"$'\t'"$2"$'\t'"$3"); }
+warn() { WARNINGS+=("$1"$'\t'"$2"$'\t'"$3"); }
+
+# Body (everything after the frontmatter block).
+body_of() {
+    awk 'NR==1&&/^---$/{fm=1;next} fm&&/^---$/{fm=0;next} !fm{print}' "$1"
+}
+
+# Count body lines after the frontmatter close (Q-LEN = "lines after frontmatter").
+body_lines() { body_of "$1" | wc -l | tr -d ' '; }
+
+# x-grounded-paths array length (entries inside [ ... ]).
+grounded_count() {
+    local arr
+    arr="$(grep -m1 -E '^x-grounded-paths:' "$1" 2>/dev/null || true)"
+    [[ -z "$arr" ]] && { echo 0; return; }
+    arr="${arr#*[}"; arr="${arr%]*}"
+    arr="$(printf '%s' "$arr" | tr -d ' ')"
+    [[ -z "$arr" ]] && { echo 0; return; }
+    awk -F',' '{print NF}' <<< "$arr"
+}
+
+has_section() { grep -qE "^##[[:space:]]+$1([[:space:]]|$)" "$2"; }
+
+mermaid_block_count() { grep -cE '^[[:space:]]*```mermaid' "$1" || true; }
+
+# Syntax-only mermaid lint: catch the breakers that silently fail previewers
+# without spawning Node. Returns 0 clean, 1 with a reason on stdout.
+mermaid_lint() {
+    local file="$1"
+    # Extract content of every ```mermaid ... ``` block.
+    local blocks; blocks="$(awk '
+        /^[[:space:]]*```mermaid/ {inb=1; next}
+        inb && /^[[:space:]]*```/ {inb=0; next}
+        inb {print}
+    ' "$file")"
+    [[ -z "$blocks" ]] && return 0
+    # Unicode arrows.
+    if printf '%s' "$blocks" | grep -qE '→|⟶|⇒|←'; then
+        echo "unicode arrow in mermaid (use --> not →)"; return 1
+    fi
+    # '&' node chaining (common breaker).
+    if printf '%s' "$blocks" | grep -qE '[A-Za-z0-9_]\s*&\s*[A-Za-z0-9_]'; then
+        echo "'&' node chaining in mermaid"; return 1
+    fi
+    # Reserved bareword node ids.
+    if printf '%s' "$blocks" | grep -qE '(^|[[:space:]])(end|class|click|graph|subgraph)[[:space:]]*(--|==|-\.)'; then
+        echo "reserved word used as node id in mermaid"; return 1
+    fi
+    # Unbalanced subgraph/end.
+    local sg en
+    sg="$(printf '%s' "$blocks" | grep -cE '^[[:space:]]*subgraph' || true)"
+    en="$(printf '%s' "$blocks" | grep -cE '^[[:space:]]*end[[:space:]]*$' || true)"
+    if [[ "$sg" -gt 0 && "$sg" != "$en" ]]; then
+        echo "unbalanced subgraph/end ($sg subgraph, $en end)"; return 1
+    fi
+    return 0
+}
+
+# Normalized hash of the first paragraph under "## What it is" (dup detection).
+whatitis_hash() {
+    local p
+    p="$(awk '
+        /^##[[:space:]]+What it is/ {grab=1; next}
+        grab && /^##[[:space:]]/ {exit}
+        grab && /^[[:space:]]*$/ { if (seen) exit; else next }
+        grab {seen=1; print}
+    ' "$1")"
+    [[ -z "$p" ]] && return 0
+    printf '%s' "$p" | tr '[:upper:]' '[:lower:]' | tr -s ' \t' ' ' | cksum | awk '{print $1}'
+}
+
+ANTI_STUB='see architecture\.md|deferred to ref-docs|\bTBD\b|TODO:[[:space:]]*document|stub page|placeholder page'
+TOKEN_RE='\{[A-Z_]+\}'
+
+# Per-type policy. echoes: sections|min_lines|need_mermaid|min_grounded
+type_policy() {
+    case "$1" in
+        Subsystem|Module|Feature|Entrypoint)
+            echo "What it is;How it works;Used by;Blast radius;See also|25|1|2";;
+        API|DataModel)
+            echo "What it is;How it works;See also|18|0|1";;
+        Dependency)
+            echo "What it is;Used by|10|0|0";;
+        ADR|Runbook)
+            echo "|8|0|0";;
+        *)
+            echo "|8|0|0";;
+    esac
+}
+
+# Seen "What it is" hashes (hash<TAB>rel), as a temp file for bash 3.2 portability.
+WHATIS_SEEN="$(mktemp)"
+trap 'rm -f "$WHATIS_SEEN"' EXIT
+
+while IFS= read -r -d '' page; do
+    rel="${page#"$BUNDLE/"}"
+    base="$(basename "$rel")"
+    # Exclusions: section/root index, log, generated coverage page.
+    [[ "$base" == "index.md" ]] && continue
+    [[ "$base" == "log.md" ]] && continue
+    [[ "$base" == "coverage.md" ]] && continue
+    grep -q '<!-- okf:coverage-generated -->' "$page" 2>/dev/null && continue
+
+    type_val="$(get_yaml_field "$page" type)"
+    [[ -z "$type_val" ]] && continue   # not a concept page
+    CHECKED=$((CHECKED + 1))
+
+    IFS='|' read -r sections min_lines need_mermaid min_grounded <<< "$(type_policy "$type_val")"
+
+    # Q-SEC: required sections.
+    if [[ -n "$sections" ]]; then
+        IFS=';' read -ra secs <<< "$sections"
+        for s in "${secs[@]}"; do
+            has_section "$s" "$page" || fail "$rel" "Q-SEC" "missing required section '## $s'"
+        done
+    fi
+
+    # Q-LEN: body length.
+    bl="$(body_lines "$page")"
+    [[ "$bl" -ge "$min_lines" ]] || fail "$rel" "Q-LEN" "body $bl lines < $min_lines for type $type_val"
+
+    # Q-DIAG: mermaid presence for diagram types.
+    if [[ "$need_mermaid" == "1" ]]; then
+        mc="$(mermaid_block_count "$page")"
+        [[ "$mc" -ge 1 ]] || fail "$rel" "Q-DIAG" "no mermaid block (required for $type_val)"
+    fi
+
+    # Q-MERMAID: syntax lint on any present blocks.
+    if [[ "$(mermaid_block_count "$page")" -ge 1 ]]; then
+        if reason="$(mermaid_lint "$page")"; [[ -n "$reason" ]]; then
+            fail "$rel" "Q-MERMAID" "$reason"
+        fi
+    fi
+
+    # Q-GROUND: grounded paths count.
+    if [[ "$min_grounded" -gt 0 ]]; then
+        gc="$(grounded_count "$page")"
+        [[ "$gc" -ge "$min_grounded" ]] || fail "$rel" "Q-GROUND" "x-grounded-paths $gc < $min_grounded"
+    fi
+
+    # Q-STUB: anti-stub patterns in body.
+    if body_of "$page" | grep -qiE "$ANTI_STUB"; then
+        fail "$rel" "Q-STUB" "matches anti-stub pattern"
+    fi
+
+    # Q-TEMPLATE: unreplaced {TOKEN} placeholders.
+    if body_of "$page" | grep -qE "$TOKEN_RE"; then
+        fail "$rel" "Q-TEMPLATE" "unreplaced template token {PLACEHOLDER}"
+    fi
+
+    # Q-DUP: duplicate "What it is" opening paragraph (warning unless --strict).
+    h="$(whatitis_hash "$page")"
+    if [[ -n "$h" ]]; then
+        prev="$(awk -F'\t' -v h="$h" '$1==h{print $2; exit}' "$WHATIS_SEEN")"
+        if [[ -n "$prev" ]]; then
+            warn "$rel" "Q-DUP" "duplicate 'What it is' paragraph (matches $prev)"
+        else
+            printf '%s\t%s\n' "$h" "$rel" >> "$WHATIS_SEEN"
+        fi
+    fi
+done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
+
+# In --strict, warnings become failures.
+if [[ $STRICT -eq 1 && ${#WARNINGS[@]} -gt 0 ]]; then
+    for w in "${WARNINGS[@]}"; do FAILURES+=("$w"); done
+    WARNINGS=()
+fi
+
+if [[ $JSON -eq 1 ]]; then
+    valid=true; [[ ${#FAILURES[@]} -eq 0 ]] || valid=false
+    printf '{"valid":%s,"bundle":"%s","concepts_checked":%d,"failures":[' \
+        "$valid" "$(json_escape "$BUNDLE")" "$CHECKED"
+    for i in "${!FAILURES[@]}"; do
+        [[ $i -gt 0 ]] && printf ','
+        IFS=$'\t' read -r p c d <<< "${FAILURES[$i]}"
+        printf '{"page":"%s","check":"%s","detail":"%s"}' \
+            "$(json_escape "$p")" "$(json_escape "$c")" "$(json_escape "$d")"
+    done
+    printf '],"warnings":['
+    for i in "${!WARNINGS[@]}"; do
+        [[ $i -gt 0 ]] && printf ','
+        IFS=$'\t' read -r p c d <<< "${WARNINGS[$i]}"
+        printf '{"page":"%s","check":"%s","detail":"%s"}' \
+            "$(json_escape "$p")" "$(json_escape "$c")" "$(json_escape "$d")"
+    done
+    printf ']}\n'
+else
+    if [[ ${#FAILURES[@]} -gt 0 ]]; then
+        echo "OKF quality FAIL: $BUNDLE ($CHECKED concepts checked)" >&2
+        for f in "${FAILURES[@]}"; do
+            IFS=$'\t' read -r p c d <<< "$f"
+            echo "  - [$c] $p: $d" >&2
+        done
+    else
+        echo "OKF quality pass: $BUNDLE ($CHECKED concepts checked)"
+    fi
+    for w in "${WARNINGS[@]:-}"; do
+        [[ -z "$w" ]] && continue
+        IFS=$'\t' read -r p c d <<< "$w"
+        echo "  warn [$c] $p: $d" >&2
+    done
+fi
+
+[[ ${#FAILURES[@]} -eq 0 ]] || exit 1
+exit 0

package/scripts/tools/okf-validate.sh

@@ -34,6 +34,8 @@ OKF_TYPES="Subsystem Module Feature Entrypoint API DataModel Dependency ADR Runb
 BUNDLE=""
 PATH_INDEX=""
 JSON=0
+REVERSE=0
+STRUCTURE_ONLY=0
 
 usage() {
     cat <<'EOF'
@@ -44,7 +46,12 @@ Usage:
 
 Flags:
   --path-index FILE  Validate a path→concept index (JSON): every concept page it
-                     names must exist in the bundle.
+                     names must exist in the bundle (forward check).
+  --reverse          Also require every concept page (excluding section index.md)
+                     to appear in at least one value array of the path-index, so
+                     no page is orphaned from its source grounding. Needs --path-index.
+  --structure-only   Run only the original structural checks (disables --reverse);
+                     for backward-compatible Layer-1 callers.
   --json             Emit a JSON summary instead of human diagnostics.
   --help             Show this help.
 
@@ -55,6 +62,8 @@ EOF
 while [[ $# -gt 0 ]]; do
     case "$1" in
         --path-index) PATH_INDEX="$2"; shift 2;;
+        --reverse) REVERSE=1; shift;;
+        --structure-only) STRUCTURE_ONLY=1; shift;;
         --json) JSON=1; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
@@ -176,6 +185,31 @@ if [[ -n "$PATH_INDEX" ]]; then
     fi
 fi
 
+# --- 6. Reverse index: every concept page is grounded by the index (optional) ---
+# Forward proves the index doesn't name ghosts; reverse proves no page is an
+# orphan with no source mapping (a symptom of hand-written / off-plan pages).
+if [[ $REVERSE -eq 1 && $STRUCTURE_ONLY -eq 0 && -n "$PATH_INDEX" && -f "$PATH_INDEX" ]]; then
+    # All pages the index maps to (its array values).
+    INDEXED_FILE="$(mktemp)"
+    grep -oE '\[[^]]*\]' "$PATH_INDEX" 2>/dev/null \
+        | grep -oE '"[^"]+\.md"' | tr -d '"' | sort -u > "$INDEXED_FILE" || true
+    while IFS= read -r -d '' page; do
+        rel="${page#"$BUNDLE/"}"
+        base="$(basename "$rel")"
+        # Section/root indexes and generated meta pages are not concept pages.
+        [[ "$base" == "index.md" ]] && continue
+        [[ "$base" == "log.md" ]] && continue
+        [[ "$base" == "coverage.md" ]] && continue
+        grep -q '<!-- okf:coverage-generated -->' "$page" 2>/dev/null && continue
+        # Only pages that declare a type are concepts.
+        [[ -z "$(get_yaml_field "$page" "type")" ]] && continue
+        if ! grep -qxF "$rel" "$INDEXED_FILE"; then
+            add_error "concept page not grounded by path-index (orphan): $rel"
+        fi
+    done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
+    rm -f "$INDEXED_FILE"
+fi
+
 # --- Report ---
 if [[ $JSON -eq 1 ]]; then
     valid=true

package/skills/init/SKILL.md

@@ -216,6 +216,16 @@ DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
 
 The tier-gated default rests on **maintainability/readability** (one navigable concept per file, cleaner PRs, a generated `architecture.md` preserved for linear onboarding) — not on the A/B benchmark, which was accuracy-parity (`docs/audit/okf-benchmark.md`). `monolith` is **retained, not retired**: it is the tier-1/2 default, the A/B baseline, and the fallback. If `DRAFT_INIT_MODE` is unset, do not commit to a mode until **Step 1.4.5** has computed the tier.
 
+**OKF Completeness Verification (blocking — tier 3+ `okf` mode).** Completeness is enforced by tooling, not honor system, so the wiki is generated completely for every module/sub-module/component on every run. Before promoting `draft.tmp/` → `draft/`, ALL must hold (see `references/okf-emitter.md` for the pipeline):
+
+1. `okf-plan-concepts.sh` ran and the expected/required/deferred counts were logged **before** any page was written (the concept boundary is a tool output, not an in-context guess).
+2. Every `required` entry in `concept-plan.json` has a non-stub page.
+3. `okf-validate-all.sh … --plan … --strict` exits 0 (structure + per-type quality + coverage all pass).
+4. `systems/coverage.md` was generated by tooling (verify the `<!-- okf:coverage-generated -->` marker) — no required package with `fan_in ≥ floor` is **MISSING**.
+5. On any failure: **do not** atomic-rename; surface `.state/validation-report.json`.
+
+> **Red flag:** writing concept pages without first running `okf-plan-concepts.sh`, or finishing generation while any `required` plan entry is unwritten, is a **completeness failure** — not a stylistic one.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:

package/skills/init/references/okf-emitter.md

@@ -25,7 +25,10 @@ esac
 Everything else in `/draft:init` (5-phase analysis, graph snapshot, `.state/`
 hashing, scope detection, atomic staging) is **reused unchanged**. This mode adds
 a decomposition + serialization stage. It introduces **no new LLM analysis
-engine** and exactly **one** new deterministic helper, `okf-validate.sh`.
+engine**; its deterministic helpers are `okf-plan-concepts.sh` (expected-concept
+set), `okf-validate.sh` (structure), `okf-validate-quality.sh` (per-type
+anti-stub), `okf-coverage-check.sh` (completeness), and `okf-validate-all.sh`
+(the single promotion gate that runs all three), plus `okf-render-views.sh`.
 
 ## Target layout
 
@@ -118,25 +121,64 @@ Derive concepts from the graph, not by hand:
 
 ```
 1. Survey        → existing /draft:init 5-phase + graph snapshot (graph-snapshot.sh)
-2. Plan          → derive the concept list (above) from graph clusters +
-                   entrypoints + features. Topo-sort by dependency so pages that
-                   others link to (overview, core subsystems) generate FIRST —
-                   forward cross-links resolve.
-3. Generate      → per concept, pull grounding from the graph and write the page:
+2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
+                   set from the graph (every package with fan_in ≥ floor → required
+                   Subsystem/Module; entrypoints → required; below-floor / allow-defer
+                   → deferred with a reason) and writes draft.tmp/.state/concept-plan.json.
+                     okf-plan-concepts.sh --repo . [--scope PATH] \
+                       [--manifest FILE] [--min-fan-in 2] [--allow-defer GLOB]... \
+                       --out draft.tmp/.state/concept-plan.json
+                   This replaces the old in-context concept enumeration — the boundary
+                   of the work is now a tool output, not an LLM judgment, so modules
+                   cannot be silently dropped. LOG the counts (expected/required/
+                   deferred) BEFORE writing any page. `generated_order` is topo-ish
+                   (required + high-fan-in first) so forward cross-links resolve.
+3. Generate      → iterate concept-plan.generated_order; write ONE page per REQUIRED
+                   entry, grounding each from the graph:
                      x-callers        ← graph-callers.sh --symbol <c>
                      x-grounded-paths  ← graph-impact.sh  --symbol <c>  (blast radius)
                      x-hotspot-score   ← hotspot-rank.sh
                      overview diagrams ← mermaid-from-graph.sh
                    Record each source path → page in .state/path-to-concept.json.
+                   Loop post-condition: every required concept_id has an output file.
+                   ⚠ Writing pages via shell heredoc without reading x-grounded-paths
+                   sources, or finishing while any required entry is unwritten, is a
+                   completeness failure — not a stylistic one.
 4. Render views  → ai-context.md (synopsis + Concept Map), architecture.md
-                   (concatenated view), wiki/log.md  (see M4).
-5. Validate      → okf-validate.sh draft/wiki \
-                     --path-index draft/.state/path-to-concept.json
-                   FAIL the build (do not atomic-rename) on any dangle, missing
-                   field, bad type, or path-index gap.
-6. Emit          → mv draft.tmp/ draft/ ; update .state/.
+                   (concatenated view + coverage banner), wiki/log.md  (see M4).
+5. Validate      → the promotion gate. Run all layers via the orchestrator:
+                     5a. okf-validate-all.sh draft.tmp/wiki \
+                           --repo . \
+                           --plan draft.tmp/.state/concept-plan.json \
+                           --path-index draft.tmp/.state/path-to-concept.json \
+                           --strict --report draft.tmp/.state/validation-report.json
+                   It runs, in order: okf-validate.sh (structure + reverse index),
+                   okf-validate-quality.sh (per-type anti-stub / depth / mermaid lint),
+                   okf-coverage-check.sh (every required plan entry → real page).
+                   ANY layer failing ⇒ exit non-zero ⇒ DO NOT atomic-rename.
+                   coverage.md (systems/coverage.md) is regenerated by the coverage
+                   layer; it is tool-owned (marker <!-- okf:coverage-generated -->) —
+                   never hand-author it except deferral reasons in the manifest.
+6. Emit          → mv draft.tmp/ draft/  ONLY IF step 5 exit 0 ; update .state/.
+                   On failure keep draft.tmp/ and surface validation-report.json.
 ```
 
+### Validation report schema (`.state/validation-report.json`)
+
+```json
+{ "valid": false, "bundle": "draft.tmp/wiki",
+  "layers": { "structure": "pass", "quality": "pass", "coverage": "fail" } }
+```
+
+### Component manifest (optional — `--manifest FILE`)
+
+When the graph engine is unavailable (or a repo wants an authoritative list), pass
+a plain-text manifest: one component name per line, `#` comments and blanks ignored.
+Every listed component becomes a REQUIRED concept; `--allow-defer GLOB` still moves
+matches to deferred. Without a manifest the plan comes from the graph, and only if
+both are unavailable does it fall back to a heuristic top-level-dir scan (which it
+marks `degraded: true`).
+
 Page bodies are LLM-narrated for readability **but** the graph-derived
 frontmatter and the `Blast radius`/`Used by` sections are deterministic. To keep
 incremental carry-forward byte-identical (open decision 2), cache the narrated
@@ -190,17 +232,22 @@ section `index.md` tables are the injection slots for the routing tables.
 `/draft:init refresh` under `okf` mode:
 
 ```
-1. Diff hashes.json vs working tree     → changed source paths
-2. path-to-concept.json                 → affected concept pages
-3. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
-4. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
-5. Re-validate: okf-validate.sh on the bundle + path-index (cross-links touching
-   changed concepts must still resolve)
-6. Append log.md; update hashes.json + path-to-concept.json
+1. Re-derive the plan: okf-plan-concepts.sh (modules added since last run become
+   REQUIRED — a new package can't slip through a refresh either)
+2. Diff hashes.json vs working tree     → changed source paths
+3. path-to-concept.json                 → affected concept pages
+4. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
+5. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
+6. Re-validate (full gate): okf-validate-all.sh on the bundle with --plan and
+   --path-index. Refresh re-runs structure + quality + coverage — a changed
+   concept must still clear the quality bar, and a newly-required module must
+   still be present.
+7. Append log.md; update hashes.json + path-to-concept.json
 ```
 
 A 1-file change regenerates only the concept(s) that file grounds. Unchanged
-concepts are byte-identical across runs.
+concepts are byte-identical across runs. The full gate still runs, so refresh
+cannot promote a bundle that a newly-added module left incomplete.
 
 ## Backward compatibility (§9)