Land the SDoc dev bridge recovered from the orphaned bran-dev worktree

.bran/policy.yaml

@@ -56,6 +56,20 @@ coverage:
   - unclassified
 
 document_coverage:
+  canonical_documents:
+    - AGENTS.md
+    - CLAUDE.md
+    - docs/README.md
+    - docs/bugs/2026-07-25-hook-fires-on-command-tokens-not-target-paths.md
+    - docs/bugs/2026-07-25-query-ranking-favors-path-tokens-over-content.md
+    - docs/integrations/proposals/okf-bundle-scan-scope.md
+    - docs/integrations/proposals/okf-layered-profile-separation.md
+    - docs/submissions/bran-build-week/README.md
+    - docs/submissions/bran-build-week/customer-setup/README.md
+    - docs/submissions/bran-build-week/demo-recording-runbook.md
+    - docs/submissions/bran-build-week/demo-video-outline.md
+    - docs/submissions/bran-build-week/research-paper.md
+    - docs/submissions/bran-build-week/submission-checklist.md
   legacy_documents:
     - README.md
     - docs/integrations/agent-setup.md

.closeout.json

@@ -0,0 +1,6 @@
+{
+  "commands": [
+    { "id": "fast", "run": "./tools/ci/check.sh --fast", "blocking": true },
+    { "id": "drift-guard", "run": "python3 tools/ci/public_export.py check --public-dir ../../bran", "blocking": true }
+  ]
+}

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: true
 contact_links:
   - name: Security issue
-    url: https://github.com/alphazede/bran/security/advisories/new
-    about: Don't file security problems publicly. Use a private GitHub security advisory.
+    url: https://github.com/alphazede/bran/blob/main/CONTRIBUTING.md#security
+    about: Don't file security problems publicly. See CONTRIBUTING for how to report them.

.github/workflows/bran-fast.yml

@@ -4,14 +4,12 @@ on:
   pull_request:
   push:
     branches: [main]
-  workflow_dispatch:
 
 permissions:
   contents: read
 
 jobs:
   fast:
-    if: ${{ !(github.event_name == 'push' && github.repository == 'alphazede/bran-dev' && github.event.repository.private == true && github.event.repository.custom_properties.delivery_profile == 'private-owner-direct') }}
     runs-on: ubuntu-24.04
     timeout-minutes: 30
     steps:

AGENTS.md

@@ -0,0 +1,133 @@
+---
+type: agent-instructions
+title: BRAN Internal Repository Instructions
+okf_status: active
+status: stable
+tags:
+  - internal
+  - bran
+freshness: "2026-08-18"
+resource: https://github.com/alphazede/bran-dev
+public_boundary: private
+---
+
+# BRAN Agent Instructions
+
+This is BRAN's main development workspace. Make every source, test,
+documentation, planning, and research change here first. Send exported changes
+to `alphazede/bran` only as reviewed snapshots through the approved export and
+pull-request sync process; do not develop or manually edit BRAN in that
+checkout.
+
+The exporter builds a reviewed snapshot from a committed revision. That
+snapshot must never run ahead of this repository or include private plans,
+submission evidence, unpublished proposals, agent instructions, or local
+`.bran` data.
+
+## Repository map
+
+See the [documentation index](docs/README.md) for integration guides, plans,
+and submissions.
+
+- `crates/`: Rust source for Core, CLI, and TUI.
+- `schemas/`, `fixtures/`, `examples/`, and `benches/`: schemas, test data,
+  examples, and benchmarks.
+- `docs/integrations/`: integration guides that may ship with BRAN.
+- `docs/plans/`: internal BRAN plans. Follow its path-specific `AGENTS.md`.
+- `docs/submissions/`: private research and submission evidence. Keep it out of
+  exports unless the owner approves a scrubbed artifact.
+- `skill/use-bran/`: the BRAN skill for agent integrations.
+
+The separate Arena harness lives at
+`/home/spectre/alphazede/agentic-eval-arena`; keep harness implementation and
+hidden evaluation material there.
+
+## Working rules
+
+1. Make BRAN source changes here. Use `alphazede/bran` only to receive an
+   approved exported snapshot through a pull request; do not develop or
+   manually edit BRAN there.
+2. Keep scanning, ranking, packet generation, and offline browsing usable
+   without a provider account.
+3. Never add credentials, raw authentication state, private corpora, hidden
+   grader truth, or unsanitized provider traces.
+4. Report requested, effective, and attested capabilities separately. If
+   something is unavailable, say so.
+5. Treat exporting, syncing, tagging, releasing, and publishing as separate
+   actions. Each requires owner approval.
+6. Preserve unrelated user changes. Remove a temporary branch or worktree only
+   after proving it is clean and reachable from its integration branch.
+
+## Validation
+
+Run the smallest relevant test while you work. For most integrated changes,
+run:
+
+```sh
+./tools/cutover/publish-hygiene.sh
+./tools/ci/check.sh --fast
+```
+
+`./tools/cutover/publish-hygiene.sh` calls the shared workspace guard and derives the
+public surface from `public-export.json`. It fails closed when `okf_status` or
+`public_boundary` frontmatter would be exported. A bare `type:` remains valid.
+For `SKILL.md`, this is also a correctness check because agent hosts parse its
+frontmatter.
+
+A packaged release binary must be built through `build/build-pinned.sh`, which
+compiles the StrictDoc bridge pins in and re-hashes every pinned file first. See
+[`build/README.md`](build/README.md); a bare `cargo build --release` produces a
+binary whose `sdoc` command fails closed as `sdoc_runtime_unavailable`.
+
+Reserve `./tools/ci/check.sh --full` for changes that affect release, security,
+conformance, or performance behavior. Do not install missing tools or contact
+live providers solely to validate a local source change.
+
+`okf-v0.1` remains a supported selectable compatibility profile. `okf-v0.2` is
+additive and does not replace it. Native policy keeps the BRAN producer
+extensions `okf_status`, `freshness`, and `public_boundary`. When a document
+also carries the OKF v0.2 `status` field, the mapping is `draft` → `draft`,
+`active` → `stable`, and `deprecated` → `deprecated`. Optional v0.2
+`stale_after` is allowed only when a real expiry date exists; it is not a
+rename of `freshness` and is not required.
+
+## Preparing a clean snapshot
+
+`public-export.json` lists what may and may not ship. Every tracked path must be
+classified, and any unclassified path stops the export. The exporter reads
+committed Git blobs, never files from an uncommitted working tree.
+
+From a clean committed `bran-dev` checkout, create a new scrubbed snapshot in
+an absent or empty directory:
+
+```sh
+python3 tools/ci/public_export.py snapshot --output /path/to/empty/snapshot
+```
+
+After committing the snapshot, compare its contents and file modes, export
+receipt, Git state, and configured remote:
+
+```sh
+python3 tools/ci/public_export.py check --public-dir /path/to/bran
+```
+
+Before pushing, inspect every exported file for private or sensitive data. Then
+run the hygiene gate.
+
+The source is a reviewed committed bran-dev revision and the checked snapshot
+was produced by the approved exporter. Push that committed checked snapshot to
+a generic non-default branch in `alphazede/bran`. Open a draft PR targeting
+public main. The PR body must name the exact bran-dev source commit, the exact
+public export commit, and validation evidence. Public `main` is protected and
+cannot be pushed to directly. Wait for the required fast and CodeQL checks to
+pass. Owner review of the exact exported diff and separate authorization to
+merge are required; only then merge the pull request with a merge commit. Never
+squash-merge an export: squashing discards the reviewed export commits and
+rewrites the published snapshot into a commit no reviewer approved. The exporter
+does not open pull requests. Passing the export checks does not authorize tagging or
+publishing a package.
+
+
+## Fixable review findings
+
+Never pass or accept `ACCEPT_WITH_FINDINGS` while a fixable bug remains. If an actionable review finding can be repaired without causing a regression or violating the approved contract, the verdict is `REPAIR_REQUIRED`; fix it in the authorized repair round and rerun deterministic verification. `ACCEPT_WITH_FINDINGS` is reserved for owner-approved residual risk or a finding that cannot be repaired within the approved contract without causing a regression.

CLAUDE.md

@@ -0,0 +1,97 @@
+---
+type: repository-guide
+title: BRAN Claude Code Guide
+okf_status: active
+status: stable
+tags:
+  - internal
+  - bran
+freshness: "2026-08-18"
+resource: https://github.com/alphazede/bran-dev
+public_boundary: private
+---
+
+# CLAUDE.md — BRAN
+
+**You are Claude Code** — implementer and reviewer for BRAN.
+
+> Claude Code does **not** auto-load `AGENTS.md`. Open [`AGENTS.md`](AGENTS.md)
+> on session start (and the path-specific `docs/plans/AGENTS.md` inside a plan
+> dir). [`AGENTS.md`](AGENTS.md) is canonical; this file is the Claude-Code
+> lens over it.
+
+This private `alphazede/bran-dev` repository is the canonical workspace for
+BRAN source, planning, and research. The public `alphazede/bran` repository is
+a downstream product export, **not** the place to develop or manually edit
+BRAN. It receives approved exported snapshots only through pull requests. Use
+`$use-bran` for architecture, terminology, and knowledge questions when the OKF
+overlay is present.
+
+## Repository map
+
+- `crates/` — Rust source for Core, CLI, and TUI.
+- `schemas/`, `fixtures/`, `examples/`, `benches/` — contracts and evidence.
+- `docs/integrations/` — public-compatible integration guidance.
+- `docs/plans/` — internal BRAN plans (follow its path-specific `AGENTS.md`).
+- `docs/submissions/` — private research/submission evidence; never copy into a
+  public repo without an explicit scrub and owner approval.
+- `skill/use-bran/` — the public agent-facing BRAN skill.
+- Arena harness lives separately at `/home/spectre/alphazede/agentic-eval-arena`
+  — keep harness implementation and hidden evaluation material there.
+
+## Working rules (full detail in `AGENTS.md`)
+
+1. Make BRAN source changes **here**; use `alphazede/bran` only for approved
+   pull-request syncs of exported snapshots.
+2. Keep deterministic scanning, ranking, packets, and offline operation usable
+   without a provider account.
+3. Never add credentials, raw auth state, private corpora, hidden grader truth,
+   or unsanitized provider traces. No AI model coauthor lines in commits.
+4. Keep requested capability separate from effective/attested capability;
+   unavailable behavior must remain visible.
+5. Treat public export, public-repository sync, release, tag creation, and
+   publication as separate owner-authorized actions.
+6. Preserve unrelated user changes. Remove a temporary branch/worktree only
+   after proving it is clean and reachable from its integration branch.
+
+## Validation
+
+Use the narrowest relevant test while working. Normal integrated check:
+
+```sh
+./tools/cutover/publish-hygiene.sh
+./tools/ci/check.sh --fast
+```
+
+Build a packaged release binary with `build/build-pinned.sh`, not a bare
+`cargo build --release`; see [`build/README.md`](build/README.md).
+
+The publish-hygiene command uses the shared `Alphazedehq` implementation and
+derives BRAN's public files from `public-export.json`; any reported
+classification metadata blocks export readiness.
+
+Use `./tools/ci/check.sh --full` only when the change affects the full release,
+security, conformance, or performance surface. Do not install missing tools or
+run live provider evaluations merely to satisfy a local source change.
+
+Public snapshots are governed by `public-export.json` and produced only from a
+clean committed source with `python3 tools/ci/public_export.py snapshot`. Use
+the tool's `check` command against the public checkout before any sync or
+release action; it fails closed on content, mode, receipt, worktree, or remote
+drift. Inspect every exported file for private or sensitive data, then run the
+hygiene gate. The source is a reviewed committed bran-dev revision and the
+checked snapshot was produced by the approved exporter. Push that committed
+checked snapshot to a generic non-default branch. Open a draft PR targeting
+public main. The PR body must name the exact bran-dev source commit, the exact
+public export commit, and validation evidence. Public `main` is protected and
+cannot be pushed to directly. Wait for the required fast and CodeQL checks to
+pass. Owner review of the exact exported diff and separate authorization to
+merge are required; only then merge it with a merge commit. Never squash-merge
+an export: squashing discards the reviewed export commits and rewrites the
+published snapshot into a commit no reviewer approved. The exporter does not
+open pull requests.
+
+
+## Fixable review findings
+
+Never pass or accept `ACCEPT_WITH_FINDINGS` while a fixable bug remains. If an actionable review finding can be repaired without causing a regression or violating the approved contract, the verdict is `REPAIR_REQUIRED`; fix it in the authorized repair round and rerun deterministic verification. `ACCEPT_WITH_FINDINGS` is reserved for owner-approved residual risk or a finding that cannot be repaired within the approved contract without causing a regression.

CODE_OF_CONDUCT.md

@@ -29,9 +29,8 @@ any public space where you're speaking for BRAN.
 
 ## Reporting
 
-Report privately through
-[GitHub Security Advisories](https://github.com/alphazede/bran/security/advisories/new)
-and state that it is a code of conduct report. Do not open a public issue.
+Email 1wgrumph@gmail.com. Reports stay private, and I'll respond as quickly as
+I reasonably can.
 
 I'll decide what action to take, up to and including blocking someone from the
 project. If your behaviour makes the project worse for other people, you'll be

CONTRIBUTING.md

@@ -4,13 +4,18 @@ Thanks for taking a look. Bug reports are genuinely useful, and the ranking
 heuristics are where I've been wrong most often, so that's a good place to
 push.
 
-## This repository
+## First, a note about this repository
 
-This is the canonical BRAN source. Issues and pull requests belong here.
+This repository is a published snapshot. BRAN is developed somewhere else, and
+the code here is exported from there and signed.
 
-Open a branch, send a PR against `main`, and keep `./tools/ci/check.sh --fast`
-green. Please don't include anything private in issues or PRs. Repository
-paths, source excerpts, and query text often carry more than you'd expect.
+**That means pull requests opened here can't be merged.** Not because they
+aren't welcome, but because the next export would overwrite them. Sorry. If you
+want to change something, open an issue and we'll work out the shape of it
+first. If a change is worth making, I'll carry it upstream and credit you in
+the commit.
+
+Issues, questions, and bug reports are all in the right place here.
 
 ## Building and testing
 
@@ -61,9 +66,8 @@ reported separately, on purpose.
 
 ## Security
 
-Don't open a public issue for a security problem. Report it privately through
-[GitHub Security Advisories](https://github.com/alphazede/bran/security/advisories/new).
-See [SECURITY.md](SECURITY.md).
+Don't open a public issue for a security problem. Email 1wgrumph@gmail.com
+instead and I'll deal with it.
 
 ## Licence