# Project export: Boris This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: Boris is a zero-dependency documentation compiler built in modern Zig 0.16. - Devpost: https://devpost.com/software/boris-ebqd2l - GitHub: https://github.com/drawmeanelephant/boris/ - Video: https://www.youtube.com/embed/P_ooPILrDkY?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 2 GitHub contributor(s) — draw me an elephant (477 commits), Beau Boorman (4 commits) ## Devpost submission (written by the team) ### Overview The Story Behind Boris Most documentation tools make it easy to publish. Fewer make it easy to leave. They tie your knowledge to a particular framework, hosting provider, or ecosystem, making migration feel harder than creating the content in the first place. That question became Boris. Documentation isn't a collection of files. It's a graph of knowledge. Boris was designed around a simple idea: your content should remain yours. Every document, heading, image, link, and piece of metadata becomes part of a structured knowledge graph that can be rendered for humans, understood by AI systems, and migrated without losing context. Choosing Zig wasn't about chasing a new language. It was about building a compiler instead of another JavaScript application. Boris runs entirely in-process, avoids heavyweight runtimes, and produces deterministic output from a single source of truth. From that source, Boris generates two first-class artifacts simultaneously: A fast, semantic static website for people. A structured, AI-ready Context Bundle for retrieval, indexing, and future migrations. The result isn't just another static site generator. It's a compiler built to help you own your documentation today, while making sure it remains portable tomorrow. Additional Boutique Repo for the Hackathingy https://github.com/drawmeanelephant/openai-buildweek-2026 Mediluna Repo github.com/drawmeanelephant/mediluna ## README (from the GitHub repository) # Boris **The Content Exit Hatch** [![Greptile: The War on Bugs](https://www.greptile.com/badge.svg)](https://www.greptile.com/?utm_source=oss_badge&utm_medium=readme&utm_campaign=greptile_for_open_source) Boris is a graph-native publication compiler. It turns Markdown into a validated content graph, then publishes that graph to one or more contracted targets. HTML `dist/` is the default target, not the whole product. Write content locally. Build with one native binary. Inspect the output. Ship it to a static host, to GitHub Pages, to Standard.site, or to a machine projection — from the same frozen graph. [Authoring spine](docs/authoring-spine.md) · [Status](docs/STATUS.md) · [Contracts](docs/contracts/) · [GitHub Pages](docs/github-pages.md) · [Standard.site](docs/standard-site.md) · [Migration](https://github.com/drawmeanelephant/boris-migration-lab) ## What Boris does ```text Markdown + closed frontmatter │ ▼ discover → validate graph → freeze │ ├── HTML site (default: dist/) ├── GitHub Pages (verified target) ├── Standard.site / AT Proto (verified target) ├── Nostr NIP-23 (plan → sign → publish; not verified) ├── JSON IR (--out) ├── RAG / Context / llms.txt (--rag / --context / --llms) └── RSS 2.0 / XML sitemap (--rss / --sitemap) ``` The content model is deliberately small: **Trunks** are root pages, **Satellites** are explicitly parented non-root pages (including nested parent chains), and in-page `Aside`/`Details` blocks stay in document order. Broken parents, wiki-links, headings, includes, and cycles fail with diagnostics instead of quietly producing a broken site. Publication is a **registry**, not a shell recipe. GitHub Pages and Standard.site are verified targets. Nostr NIP-23 is a shipped CLI family (`boris nostr plan` / `sign` / `publish`) and is **not** a verified target: no location adapter, no Proof Pack, no live-smoke gate. The local [Boris Editor](content/guides/editor.md) is a compiler-backed authoring surface, not a second product. ## Features - Native Markdown through the pinned **Oliver** library (Zig, in-process): CommonMark, GFM tables, heading ids/IAL, footnotes, definition lists, strikethrough. - Deterministic HTML output with trusted static layouts and copied assets. - Validated Trunk/Satellite navigation and graph-aware breadcrumbs/children. - `{{include path}}` composition with a reserved fragment library: files under `content/includes/` are never discovered as pages (no stray HTML, no nav entries, no `unreferenced_page` findings); fragments anywhere else compile as normal pages too. - Closed, explicit frontmatter rather than unrestricted YAML or executable MDX. - Authoritative `boris validate` preflight with no generated output or evidence. - Incremental builds, watch mode with a loopback live-preview server (`boris watch --serve`), isolated targets, and bounded page workers. - JSON IR with typed dependency edges and reverse indexes. - Deterministic RAG, Context Bundle, `llms.txt`, and RSS 2.0 exports from the same tree. - Deterministic staged XML sitemap for one public HTML target. - First-class GitHub Pages publication identity and an official verified Actions workflow. - Standard.site / AT Protocol publication: offline plan + explicit login/publish/smoke. The first-tester path against bsky.social is an app password, not browser OAuth. - Nostr NIP-23 long-form publication: offline `nostr plan → sign`, then `nostr publish` delivers the exact signed events over a bounded RFC-6455 client with per-relay `complete`/`partial`/`failed`/`incomplete` evidence. Not a verified target. - Target-local evidence chain: artifacts → checks → claims → Touch Atlas → Proof Pack. - Local Boris Editor: schema-aware completion, compiler-backed problems, live preview. - Standalone migration labs (Astro/Starlight, WordPress, Instagram, Obsidian, Notion, Filed, and related source shapes) live in the [boris-migration-lab](https://github.com/drawmeanelephant/boris-migration-lab) repository. ## Why Boris? Most documentation stacks are also JavaScript application toolchains. Boris takes a narrower path: a local Zig binary that treats documentation as a validated content graph rather than a folder full of unrelated pages. That means fewer moving parts in the publishing path, explicit failure when the structure is wrong, and several machine-readable outputs without maintaining a second content model. Boris is not trying to replace every SSG. It is for people who want a small, inspectable compiler, graph-aware documentation, and more than one honest place to put the result — without requiring a Node runtime to publish the site. ## Nostr NIP-23 publication Pages allowlisted in the profile can be published to the Nostr network as NIP-23 long-form-content events. The pipeline keeps the secret and the network strictly apart: ```text boris nostr plan --profile PROFILE.json # offline: plan JSON on stdout boris nostr sign --plan PLAN.json --key-stdin # offline: key once via stdin, bundle out boris nostr publish --plan PLAN.json --bundle BUNDLE.json # online: exact signed events to relays ``` - **`nostr plan`** is the only profile-selection step; it never reads a key, signs, or contacts a relay. - **`nostr sign`** is the only command that reads a secret — the key (64 hex digits or a NIP-19 `nsec`) is read once from stdin and never accepted from argv, a profile, an environment variable, or a log. It signs the exact NIP-01 event IDs with BIP-340 Schnorr signatures (bitcoin-core/secp256k1, pinned and verified) and writes a signed-event bundle. - **`nostr publish`** never sees a key. It verifies the bundle against the plan offline, then sends the exact signed events to the plan's relays over a bounded in-repo RFC-6455 client (`wss://`; `ws://` only for loopback test relays). Every relay interaction is bounded and recorded: the report classifies the run `complete` / `partial` / `failed` / `incomplete` with per-relay evidence, and a relay that demands NIP-42 authentication is reported honestly as unsupported rather than silently skipped. A bare `boris build` never needs a key, a relay, or the network, and a failed Nostr operation never invalidates a committed website. The normative [`nostr-publication` contract](docs/contracts/nostr-publication.md) specifies the plan, signed-bundle, and report artifacts; the CLI surface is in [`cli.md`](docs/contracts/cli.md). ## Quick start Building Boris requires [Zig 0.16+](https://ziglang.org/) only. Markdown rendering is Oliver, a pure-Zig library pinned by content hash in `build.zig.zon` and fetched by Zig at build time; it is not part of the authoring or publishing workflow. ```bash git clone https://github.com/drawmeanelephant/boris.git cd boris zig build ./zig-out/bin/boris --quiet ``` The sample content is compiled to `dist/`. Open `dist/index.html` or serve the directory with any static file server. That is the whole default path. New to authoring? The [authoring spine](docs/authoring-spine.md) is the teaching path from `boris init` to a published, verified site. It names the publish targets without pretending they are the first command. Useful first commands: ```bash ./zig-out/bin/boris --help ./zig-out/bin/boris --version # print the compiler id (e.g. boris/0.8.2) ./zig-out/bin/boris --out .boris --quiet # JSON IR ./zig-out/bin/boris --rag --quiet # RAG working-context packs ./zig-out/bin/boris --rag --complete --quiet # complete-corpus RAG export ./zig-out/bin/boris --context --quiet # AI Context Bundle ./zig-out/bin/boris --rag-dir ./uploads/rag --scope mascots --split-size 262144 ./zig-out/bin/boris --context-dir ./uploads/context --scope mascots/genny --split-size 131072 ./zig-out/bin/boris --llms --quiet # l [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 607 recognized source files, 1304 KB. - CSS (language) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - PHP (language) — detected in the code - TypeScript (language) — detected in the code - AI coding agent: Codex — evidence: config files committed to the repository ## Codebase structure (from repository index) ### Files (120 of 853) ``` .github/workflows/ci.yml .gitignore AGENTS.md build.zig build.zig.zon CHANGELOG.md content/AGENT-DIRECTIVE.txt content/agents/antigravity.md content/agents/bacon.md content/agents/cicero.md content/agents/codex-children-layout.md content/agents/codex-html-body.md content/agents/codex-migration-lab-ci.md content/agents/codex-release-docs-truth.md content/agents/codex-session-success-story.md content/agents/codex-source-rag.md content/agents/confucius.md content/agents/credits.md content/agents/gauss.md content/agents/gibbs.md content/agents/godel.md content/agents/grok.md content/agents/heisenberg.md content/agents/index.md content/agents/james.md content/agents/jason.md content/agents/kepler.md content/agents/maxwell.md content/agents/mill.md content/agents/nash.md content/agents/noether.md content/agents/ohm.md content/agents/parfit.md content/agents/pauli.md content/agents/poincare.md content/agents/roll-call.md content/agents/turing.md content/agents/volta.md content/contest.md content/contest/how-it-was-built.md content/contest/the-pipeline.md content/contest/what-shipped.md content/contest/what-we-cut.md content/getting-started.md content/guides/apex-markdown.md content/guides/asides.md content/guides/cli-and-modes.md content/guides/overview.md content/guides/rag-export.md content/guides/trunk-satellite.md content/includes/authoring-note.md content/includes/shared-tip.md content/index.md content/reference/frontmatter.md docs/changelog.d/README.md docs/changelog.d/TEMPLATE.md docs/contracts/acceptance.md docs/contracts/apex-abi.md docs/contracts/components.md docs/contracts/content-local-assets.md docs/contracts/context-bundle.md docs/contracts/diagnostics.md docs/contracts/documentation-intelligence.md docs/contracts/fixtures/aggregate/content/badkey.md docs/contracts/fixtures/aggregate/content/orphan.md docs/contracts/fixtures/aggregate/content/self.md docs/contracts/fixtures/aggregate/README.md docs/contracts/fixtures/apex-unified-compat/content/features/autolinks.md docs/contracts/fixtures/apex-unified-compat/content/features/callouts.md docs/contracts/fixtures/apex-unified-compat/content/features/citations.md docs/contracts/fixtures/apex-unified-compat/content/features/definition-lists.md docs/contracts/fixtures/apex-unified-compat/content/features/fenced-divs.md docs/contracts/fixtures/apex-unified-compat/content/features/footnotes.md docs/contracts/fixtures/apex-unified-compat/content/features/heading-attributes.md docs/contracts/fixtures/apex-unified-compat/content/features/images.md docs/contracts/fixtures/apex-unified-compat/content/features/math.md docs/contracts/fixtures/apex-unified-compat/content/features/raw-html.md docs/contracts/fixtures/apex-unified-compat/content/features/smart-typography.md docs/contracts/fixtures/apex-unified-compat/content/features/tables.md docs/contracts/fixtures/apex-unified-compat/content/features/task-lists.md docs/contracts/fixtures/apex-unified-compat/content/features/toc-markers.md docs/contracts/fixtures/apex-unified-compat/content/index.md docs/contracts/fixtures/apex-unified-compat/MATRIX.md docs/contracts/fixtures/apex-unified-compat/README.md docs/contracts/fixtures/apex-unified-compat/REPORT.md docs/contracts/fixtures/apex-unified-compat/theme/layouts/main.html docs/contracts/fixtures/case-id-collision/content/lower.md docs/contracts/fixtures/case-id-collision/content/upper.md docs/contracts/fixtures/case-id-collision/README.md docs/contracts/fixtures/children-slot/content/alpha.md docs/contracts/fixtures/children-slot/content/index.md docs/contracts/fixtures/children-slot/content/zeta.md docs/contracts/fixtures/children-slot/layouts/main.html docs/contracts/fixtures/children-slot/README.md docs/contracts/fixtures/context-bundle-hostile/content/guides/current.md docs/contracts/fixtures/context-bundle-hostile/content/guides/previous.md docs/contracts/fixtures/context-bundle-hostile/README.md docs/contracts/fixtures/cycles/content/a.md docs/contracts/fixtures/cycles/content/b.md docs/contracts/fixtures/cycles/README.md docs/contracts/fixtures/documentation-intelligence/content/guides.md docs/contracts/fixtures/documentation-intelligence/content/guides/reference.md docs/contracts/fixtures/documentation-intelligence/content/guides/start.md docs/contracts/fixtures/documentation-intelligence/content/includes/shared.md docs/contracts/fixtures/documentation-intelligence/content/index.md docs/contracts/fixtures/documentation-intelligence/edge-cases/empty/content/.gitkeep docs/contracts/fixtures/documentation-intelligence/edge-cases/single/content/solo.md docs/contracts/fixtures/documentation-intelligence/expected/check.json docs/contracts/fixtures/documentation-intelligence/expected/check.txt docs/contracts/fixtures/documentation-intelligence/expected/impact-source.json docs/contracts/fixtures/documentation-intelligence/expected/impact-source.txt docs/contracts/fixtures/documentation-intelligence/expected/impact.json docs/contracts/fixtures/documentation-intelligence/expected/impact.txt docs/contracts/fixtures/documentation-intelligence/README.md docs/contracts/fixtures/duplicate-ids/content/alpha.md docs/contracts/fixtures/duplicate-ids/content/beta.md docs/contracts/fixtures/duplicate-ids/README.md docs/contracts/fixtures/duplicate-key/content/dup.md docs/contracts/fixtures/duplicate-key/README.md docs/contracts/fixtures/graph-native-dependencies/content/guides/child.md [733 more files omitted for size] ``` ### Dependencies - tools/migration-lab/fixtures/mini-astro/package.json: astro@4.0.0 - tools/migration-lab/fixtures/mini-theme-astro/package.json: @astrojs/starlight@0.0.0-fixture, astro@0.0.0-fixture ### Recent commits (newest first) - Merge pull request #189 from drawmeanelephant/codex/v080-release - chore: prepare v0.8.0 release - Merge pull request #188 from drawmeanelephant/codex/readme-refresh - docs: refresh README for first-time users - Merge pull request #187 from drawmeanelephant/codex/apex-v1.1.12 - chore: upgrade vendored ApexMarkdown to v1.1.12 - Merge pull request #186 from drawmeanelephant/fix/migration-lab-print-usage - fix(migration-lab): wrap printUsage format string in {s} parameter to compile correctly - Merge pull request #185 from drawmeanelephant/codex/honest-jobs-guidance - Merge branch 'main' into codex/honest-jobs-guidance - docs: clarify bounded jobs guidance - Merge pull request #184 from drawmeanelephant/fix/migration-lab-frontmatter-review-integration - Merge branch 'main' into fix/migration-lab-frontmatter-review-integration - fix(migration-lab): restore main and wire frontmatter review - Merge pull request #183 from drawmeanelephant/feat/grok-try-2-frontmatter-review-lab - fix(migration-lab): complete frontmatter review integration - feat(migration-lab): frontmatter-review preservation report (grok-try-2) - Merge pull request #181 from drawmeanelephant/docs/audit-honesty-v070 - docs: clarify v0.7.0 audit boundaries - docs: clarify v0.7.0 audit boundaries ## Key source files (fetched from GitHub, selected and truncated for size) ### AGENTS.md ```markdown # Agent rules — Boris This file is binding project policy for AI coding agents (and humans pairing with them). ## Session start (read this first) 1. Skim [`docs/STATUS.md`](docs/STATUS.md) for current phase, known gaps, and module map. 2. Skim the top of [`CHANGELOG.md`](CHANGELOG.md) (`[Unreleased]` + latest release). 3. For compiler semantics, open the relevant file under [`docs/contracts/`](docs/contracts/) — those docs are **normative**. 4. Run `zig build test` (or `./scripts/release-gate.sh` for IR-facing work) before and after substantive changes. ## Codex / ChatGPT review rules Use this protocol for repository audits, release reviews, and reviews based on an external AI packet. It supplements the implementation rules below; it does not turn a review-only request into permission to edit product code. ### Scope and authority - Resolve the requested mode first: **review only**, **review plus agent/docs guidance**, or **implement fixes**. In review-only mode, do not patch a defect merely because the fix looks small. Explicitly requested `AGENTS.md` or review guidance may still be edited without widening permission to product code. - Treat external review packets as leads, not repository truth. Record their stated release/version, then compare it with code, canonical contracts, `docs/STATUS.md`, and `CHANGELOG.md`. Stale module spellings, commands, or version claims are packet drift, not product defects. - Use this evidence order: executable behavior and current code → canonical `docs/contracts/` → this file → `docs/STATUS.md` → `CHANGELOG.md` → release gate docs/scripts → README and narrative RAG seeds → external/historical notes. - Do not cite a contract or passing happy-path smoke as proof of implementation. Verify the relevant code path, test, fixture, or black-box behavior. ### Finding discipline Classify every material observation as exactly one of: - **Confirmed defect** — reproduced failure, unsafe reachable code path, or a direct code/contract contradiction. - **Likely defect** — strong code-path evidence, but no reliable reproduction. - **Insufficient evidence** — a material claim cannot be established by the available tests, code, or environment. - **Documented limitation** — behavior matches an explicit current limitation. - **Non-issue / packet drift** — concern is contradicted by current authoritative evidence or applies only to stale briefing text. For actionable findings, report: severity, classification, exact locus, evidence/reproduction, user or release impact, the smallest remediation card, and the verification command. Keep speculative hardening separate from defects. ### Gate and environment handling - Capture the initial `git status --short`; preserve unrelated work and report whether review commands created ignored/generated artifacts. - Run the smallest relevant gates independently before the aggregate gate so a single failure does not hide other evidence. For microreleases, norm [truncated — 15399 more characters] ``` ### content/contest.md ```markdown --- id: contest title: Boris at Build Week status: published tags: [build-week, overview, dogfood] --- # Boris at Build Week Boris is a local Zig documentation compiler for people who want Markdown to be more than a folder full of files. It validates the content graph, builds a static HTML site by default, and can emit structured IR, RAG, Context Bundles, and `llms.txt` from the same source tree. This section is the short version for a curious judge, contributor, or future owner: what the project can do today, how it was made, and where it remains deliberately strict. ## Pick a path | If you have five minutes | Read | |---|---| | What is genuinely shipping? | [[contest/what-shipped|What shipped]] | | How did the human/AI collaboration work? | [[contest/how-it-was-built|How Boris was built]] | | What comes out of one Markdown tree? | [[contest/the-pipeline|The output pipeline]] | | What did the project intentionally refuse to become? | [[contest/what-we-cut|What Boris cuts on purpose]] | ## The human story is part of the artifact The build was continuously human-steered with GPT-5.6 and Codex: architecture, scope cuts, review standards, and merge decisions were treated as product work, not decoration after generation. The project also keeps an evidence-bound [[agents|Agent Field Notes]] section: named worker stories, external-tool credits, and uncertainty are kept separate on purpose. That choice matters because the compiler is itself built around the same idea: make the graph and its boundaries inspectable before asking a machine—or a human—to trust them. ``` ### tools/migration-lab/fixtures/root-content-astro/package.json ``` {"name":"root-content-astro-fixture","private":true} ``` ### tools/migration-lab/fixtures/hostile-theme-astro/package.json ``` { "name": "hostile-theme-astro-fixture", "private": true, "license": "UNLICENSED" } ``` ### tools/migration-lab/fixtures/mini-astro/package.json ``` { "name": "mini-astro-fixture", "private": true, "type": "module", "dependencies": { "astro": "4.0.0" } } ``` ### tools/migration-lab/fixtures/mini-theme-astro/package.json ``` { "name": "mini-theme-astro-fixture", "private": true, "license": "MIT", "dependencies": { "astro": "0.0.0-fixture", "@astrojs/starlight": "0.0.0-fixture" } } ``` ### test/context-bundle-hostile.sh ```shell #!/usr/bin/env bash # Focused black-box hostile coverage for the Context Bundle contract. set -euo pipefail ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" cd "${ROOT}" zig build BORIS="${ROOT}/zig-out/bin/boris" FIXTURE="docs/contracts/fixtures/context-bundle-hostile/content" INVALID="docs/contracts/fixtures/semantic-relations-invalid/content" TMP="$(mktemp -d "${TMPDIR:-/tmp}/boris-context-hostile.XXXXXX")" trap 'rm -rf "${TMP}"' EXIT first="${TMP}/first" second="${TMP}/second" "${BORIS}" --context --context-dir="${first}" --input="${FIXTURE}" --quiet "${BORIS}" --context --context-dir="${second}" --input="${FIXTURE}" --quiet # Repeat exports are byte-identical and source provenance never includes this host root. diff -rq "${first}" "${second}" >/dev/null if rg -F --quiet "${ROOT}" "${first}"; then echo "context bundle leaked an absolute host path" >&2 exit 1 fi # Semantic relations remain in graph output and source fences outgrow source fences. grep -q '"relations": \[' "${first}/graph.json" grep -q '"kind": "supersedes"' "${first}/graph.json" grep -q '"value": "guides/current"' "${first}/graph.json" grep -q '"value": "guides/previous"' "${first}/graph.json" grep -q '^``````markdown$' "${first}/pages/guides/current.md" # A validation failure does not replace the prior complete bundle or leave staging behind. before="$(shasum -a 256 "${first}/manifest.json")" if "${BORIS}" --context --context-dir="${first}" --input="${INVALID}" --quiet; then echo "invalid context input unexpectedly succeeded" >&2 exit 1 fi after="$(shasum -a 256 "${first}/manifest.json")" test "${before}" = "${after}" test ! -e "${first}.boris-context-stage" test ! -e "${second}.boris-context-stage" ``` ### layouts/main.html ```html {{title}} · Boris {{nav}} {{breadcrumb}} {{toc}}
{{content}}
``` ### scripts/build-apex-markdown.sh ```shell #!/usr/bin/env bash # Build static ApexMarkdown (libapex.a + cmark-gfm) for Boris Feature 1. # Invoked from build.zig (Strategy A). User entrypoint remains `zig build`. # # Residual mitigations: # D2 — never link system libyaml (product does not feed YAML metadata into Apex) # D3 — stamp + archive freshness skip so `zig build` does not re-run cmake when idle set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" SRC="${ROOT}/vendor/apex-markdown" BUILD="${ROOT}/vendor/apex-markdown/build" # Bump when configure policy changes (forces reconfigure + rebuild). POLICY_VERSION="boris-apex-policy-2-no-system-libyaml" STAMP="${BUILD}/.boris-apex-stamp" FORCE="${BORIS_FORCE_APEX_BUILD:-0}" LIBS=( "${BUILD}/libapex.a" "${BUILD}/vendor/cmark-gfm/src/libcmark-gfm.a" "${BUILD}/vendor/cmark-gfm/extensions/libcmark-gfm-extensions.a" ) if ! command -v cmake >/dev/null 2>&1; then cat >&2 <<'EOF' error: cmake is required to build vendored ApexMarkdown (Feature 1). Install CMake (compile-time host tool only; not a runtime dependency), then re-run: zig build macOS: brew install cmake Debian: sudo apt-get install cmake Fedora: sudo dnf install cmake EOF exit 1 fi if [[ ! -f "${SRC}/CMakeLists.txt" ]]; then echo "error: missing ${SRC}/CMakeLists.txt (ApexMarkdown pin)" >&2 exit 1 fi need_build=0 need_reconfigure=0 if [[ "${FORCE}" == "1" ]]; then need_build=1 need_reconfigure=1 fi for f in "${LIBS[@]}"; do if [[ ! -f "${f}" ]]; then need_build=1 break fi done stamp_policy="" if [[ -f "${STAMP}" ]]; then stamp_policy="$(head -n1 "${STAMP}" 2>/dev/null || true)" fi if [[ "${need_build}" -eq 0 ]]; then if [[ ! -f "${STAMP}" ]] || [[ "${stamp_policy}" != "${POLICY_VERSION}" ]]; then # Missing or stale stamp: rebuild and reconfigure so D2 cmake flags apply. need_build=1 need_reconfigure=1 elif [[ "${SRC}/CMakeLists.txt" -nt "${STAMP}" ]] || \ [[ "${ROOT}/scripts/build-apex-markdown.sh" -nt "${STAMP}" ]]; then need_build=1 need_reconfigure=1 fi elif [[ ! -f "${STAMP}" ]] || [[ "${stamp_policy}" != "${POLICY_VERSION}" ]]; then need_reconfigure=1 fi # D2: existing caches that linked system libyaml must reconfigure. if [[ -f "${BUILD}/CMakeCache.txt" ]]; then if grep -Eq 'APEX_HAVE_LIBYAML|YAML_FOUND:INTERNAL=1|YAML_LIBRARIES:INTERNAL=.+' \ "${BUILD}/CMakeCache.txt" 2>/dev/null; then echo "build-apex-markdown: dropping cache that saw system libyaml (D2 policy)" need_reconfigure=1 need_build=1 fi fi if [[ "${need_build}" -eq 0 ]]; then # Fast path (D3): archives + stamp current — skip cmake entirely. exit 0 fi if [[ "${need_reconfigure}" -eq 1 ]]; then echo "build-apex-markdown: reconfigure required (policy=${POLICY_VERSION})" rm -rf "${BUILD}" fi jobs="$( if command -v nproc >/dev/null 2>&1; then nproc elif command -v sysctl >/dev/null 2>&1; then sysctl -n hw.ncpu else echo 4 fi )" mkdir -p "${BUILD}" if [[ ! -f "${BUILD}/CMakeCache.txt" ]]; then echo "build-apex-markdown: configuring ${BUILD} (policy=${POLICY_VERSION})" # D2: hide pkg-config and cmake yaml package discovery so host libyaml is never # linked. Product frontmatter is Boris-owned; Apex is not fed YAML metadata options. # Empty pkg-config executable + disable find_package(yaml) keeps builds deterministic. cmake -S "${SRC}" -B "${BUILD}" \ -DCMAKE_BUILD_TYPE=Release \ -DCMARK_TESTS=OFF \ -DCMARK_STATIC=ON \ -DCMARK_SHARED=OFF \ -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \ -DCMAKE_DISABLE_FIND_PACKAGE_yaml=ON \ -DCMAKE_DISABLE_FIND_PACKAGE_PkgConfig=ON fi echo "build-apex-markdown: building apex_static (-j${jobs})" cmake --build "${BUILD}" --target apex_static -j"${jobs}" for f in "${LIBS[@]}"; do if [[ ! -f "${f}" ]]; then echo "error: expected static library missing: ${f}" >&2 exit 1 fi done # Confirm D2: configured tree must not enable libyaml. if [[ -f "${BUILD}/CMakeCache.txt" ]] && \ grep -Eq 'APEX_HAVE_LIBYAML|YAML_FOUND:INTERNAL=1' "${BUILD}/CMakeCache.txt" 2>/dev/null; then echo "error: Apex build unexpectedly enabled libyaml (D2 policy violated)" >&2 exit 1 fi { echo "${POLICY_VERSION}" date -u +"%Y-%m-%dT%H:%M:%SZ" } >"${STAMP}" echo "build-apex-markdown: ok" ``` ### scripts/test-release-gate-git-detection.sh ```shell #!/usr/bin/env bash # Reproducible coverage for release-gate step 7 Git worktree detection. # # Failure mode under test: # Linked worktrees store `.git` as a *file* (gitdir pointer), not a directory. # The old gate predicate `[[ -d .git ]]` was false in worktrees and skipped the # tracked/untracked generated-output cleanliness checks. # # This script: # 1. Asserts the current tree is a Git worktree via `git rev-parse`. # 2. Creates a temporary linked worktree and proves: # - `.git` is not a directory there # - `git rev-parse --is-inside-work-tree` is true # - the old `[[ -d .git ]]` predicate would incorrectly skip # - the new Git-native predicate would run the cleanliness step # 3. Greps scripts/release-gate.sh for the fixed detection (no `-d .git`). # # Run from any checkout of this repo: # ./scripts/test-release-gate-git-detection.sh set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$ROOT" GATE_SCRIPT="${ROOT}/scripts/release-gate.sh" FAIL=0 pass() { printf ' OK %s\n' "$*"; } fail() { printf ' FAIL %s\n' "$*"; FAIL=1; } note() { printf '==> %s\n' "$*"; } # Same predicate as release-gate.sh step 7 (must stay in sync). in_git_work_tree() { command -v git >/dev/null && git rev-parse --is-inside-work-tree >/dev/null 2>&1 } # Old, incorrect predicate (documented for regression coverage only). legacy_d_git_dir_check() { command -v git >/dev/null && [[ -d .git ]] } note "0. Preconditions" command -v git >/dev/null || { echo "git not on PATH"; exit 1; } [[ -f "${GATE_SCRIPT}" ]] || { echo "missing ${GATE_SCRIPT}"; exit 1; } if ! in_git_work_tree; then echo "not inside a git work tree; cannot run this test" exit 1 fi pass "git and release-gate.sh available; inside a work tree" note "1. release-gate.sh uses Git-native detection (not -d .git)" # Flag live shell predicates only (comments may still document the old bug). if grep -nE '^[[:space:]]*(if|elif|while|until).*(\[\[.*-d[[:space:]]+\.git|test[[:space:]]+-d[[:space:]]+\.git)' \ "${GATE_SCRIPT}" >/dev/null 2>&1 \ || grep -nE '^[[:space:]]*(\[\[|test)[[:space:]].*-d[[:space:]]+\.git' \ "${GATE_SCRIPT}" >/dev/null 2>&1; then fail "release-gate.sh still uses [[ -d .git ]] / test -d .git for cleanliness gating" else pass "no live -d .git cleanliness predicate in release-gate.sh" fi if grep -q 'rev-parse --is-inside-work-tree' "${GATE_SCRIPT}"; then pass "release-gate.sh uses git rev-parse --is-inside-work-tree" else fail "release-gate.sh missing git rev-parse --is-inside-work-tree" fi note "2. Current checkout: new vs legacy detection" if in_git_work_tree; then pass "current tree: Git-native check reports inside work tree" else fail "current tree: Git-native check failed unexpectedly" fi if [[ -d .git ]]; then pass "current tree: .git is a directory (primary checkout) — legacy would also run" elif [[ -f .git ]]; then if legacy_d_git_dir_check; then fail "linked worktree: legacy [[ -d .git ]] unexpectedly true" else pass "linked worktree: legacy [[ -d .git ]] would skip (the original bug)" fi if in_git_work_tree; then pass "linked worktree: Git-native check still runs cleanliness" else fail "linked worktree: Git-native check failed" fi else fail "current tree: .git is neither file nor directory" fi note "3. Temporary linked worktree isolation" WT_PARENT="$(mktemp -d "${TMPDIR:-/tmp}/boris-rg-wt.XXXXXX")" WT_PATH="${WT_PARENT}/linked" cleanup_wt() { # Best-effort remove; ignore errors so primary failures stay visible. git worktree remove --force "${WT_PATH}" >/dev/null 2>&1 || true rm -rf "${WT_PARENT}" >/dev/null 2>&1 || true } trap cleanup_wt EXIT # Detached HEAD at current commit — no branch name pollution. if ! git worktree add --detach "${WT_PATH}" HEAD >/dev/null 2>&1; then fail "git worktree add failed (cannot create linked worktree)" else pass "created temporary linked worktree at ${WT_PATH}" # Stay in the parent shell so pass/fail update FAIL; restore cwd afterward. _prev_cwd="$PWD" cd "${WT_PATH}" if [[ -d .git ]]; then fail "linked worktree has .git as directory (unexpected for git worktree add)" elif [[ -f .git ]]; then pass "linked worktree .git is a file (gitdir pointer)" else fail "linked worktree missing .git" fi if legacy_d_git_dir_check; then fail "linked worktree: legacy [[ -d .git ]] would run (expected skip/false)" else pass "linked worktree: legacy [[ -d .git ]] is false (would skip cleanliness)" fi if in_git_work_tree; then pass "linked worktree: Git-native check is true (cleanliness would run)" else fail "linked worktree: Git-native check is false" fi # Light smoke: the same git commands step 7 uses must work here. if git ls-files >/dev/null 2>&1 \ && git status --porcelain --untracked-files=all >/dev/null 2>&1; then pass "linked worktree: git ls-files and status --porcelain work" else fail "linked worktree: git ls-files/status failed" fi cd "${_prev_cwd}" fi echo if [[ "${FAIL}" -ne 0 ]]; then echo "RELEASE-GATE GIT DETECTION TEST FAILED" exit 1 fi echo "RELEASE-GATE GIT DETECTION TEST PASSED" exit 0 ``` [621 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]