docs: harmonize governance and contribution authority

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+# Summary
+
+Describe the final change and owning issue.
+
+## Compatibility and risk
+
+Risk class, affected contracts, exceptions and unresolved controls.
+
+## Validation
+
+Current SHA, exact commands/results, Actions links, Red/Green or justified
+documentation-only N/A. Record missing/skipped checks as Not run with reason.
+
+## Checklist
+
+- [ ] Feature/fix/docs branch targets `dev`; no direct protected-branch push.
+- [ ] Current SHA, Actions run links and individual required results are recorded.
+- [ ] Red/Green evidence, or justified documentation-only N/A with doc/link checks.
+- [ ] Skipped, missing, pending and failed checks are explicit, never called passes.
+- [ ] Yomi reviewed this revision; material fixes have fresh CI and review.
+- [ ] Triggered bot reviews finished; findings/discussions are fixed or dispositioned.
+- [ ] PR owner has a real monitor/event continuation while checks or reviews are pending.
+- [ ] No secrets/private data; environment injection and production boundaries observed.
+- [ ] No protection bypass; check/review state is rechecked immediately before merge.
+- [ ] Main/release/tag/deploy authority and Brad-reserved decisions follow GOVERNANCE.md.

.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: Scribe CI
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: scribe-ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    name: Documentation checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Check changed Markdown whitespace and required documentation
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          git diff --check "$BASE_SHA" HEAD -- '*.md'
+          test -s README.md
+          test -s docs/SYNTAX.md
+          test -s docs/DESIGN.md
+      - name: Check documented shell entry points
+        run: |
+          bash -n tests/run.sh
+          bash -n examples/run.sh
+
+  tests:
+    name: Scribe tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Pull WFL runtime and record immutable image
+        id: runtime
+        run: |
+          docker pull bsbyrdwfl/wfl:nightly
+          image="$(docker image inspect --format '{{index .RepoDigests 0}}' bsbyrdwfl/wfl:nightly)"
+          echo "image=$image" >> "$GITHUB_OUTPUT"
+          {
+            echo "WFL image: $image"
+            docker run --rm --network none "$image" --version
+            echo "Scribe checkout: $(git rev-parse HEAD)"
+          } >> "$GITHUB_STEP_SUMMARY"
+      - name: Run complete existing Scribe suite in a disposable copy
+        env:
+          WFL_IMAGE: ${{ steps.runtime.outputs.image }}
+        run: |
+          docker run --rm --init --network none \
+            --entrypoint /bin/sh \
+            --mount "type=bind,source=$GITHUB_WORKSPACE,target=/source,readonly" \
+            --workdir /work "$WFL_IMAGE" -ec '
+              cp -a /source/. /work/
+              mkdir -p build
+              wfl --test tests/scribe.test.wfl
+            '

AGENTS.md

@@ -0,0 +1,4 @@
+# Agent instructions
+
+Read [CLAUDE.md](CLAUDE.md), the canonical shared agent guidance, and
+[GOVERNANCE.md](GOVERNANCE.md) before working in this repository.

CLAUDE.md

@@ -0,0 +1,16 @@
+# Scribe agent instructions
+
+Read [GOVERNANCE.md](GOVERNANCE.md), [CONTRIBUTING.md](CONTRIBUTING.md),
+[testing.md](testing.md), [SECURITY.md](SECURITY.md), [README.md](README.md),
+[design](docs/DESIGN.md) and [syntax](docs/SYNTAX.md) before changes.
+
+Use your own feature branch → `dev`; no direct dev/main pushes. Yomi reviews
+the current revision; enumerate exact-SHA Actions results, resolve bot
+feedback and keep an actual monitor while processing is pending. Never
+bypass controls. Main/release/tag/deploy authority belongs to Azusa only at
+the fully-green gate, otherwise Brad; reserved decisions stay with Brad.
+
+Preserve the single-file engine and include-based API, HTML auto-escaping,
+trusted raw output and filesystem limitations. No unrelated refactoring.
+Test behavior first with the commands in CONTRIBUTING.md. Keep fixtures
+disposable, secrets out of output and production hosts read-only.

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to Scribe
+
+Read [GOVERNANCE.md](GOVERNANCE.md), [testing.md](testing.md),
+[SECURITY.md](SECURITY.md), [design](docs/DESIGN.md) and [syntax](docs/SYNTAX.md).
+Create your own feature branch from current `dev`; open a PR into `dev`.
+Use a conventional subject such as `docs: clarify contribution policy`.
+Use the [PR template](.github/pull_request_template.md), record actual results,
+and wait for current-revision Yomi review and required CI before a dev merge.
+Main/release/deploy actions follow the conditional CEO gate in GOVERNANCE.md.
+
+## Commands from the repository root
+
+- `bash tests/run.sh /absolute/path/to/wfl`: engine regression suite.
+- `bash examples/run.sh examples/blog.wfl /absolute/path/to/wfl`: blog example.
+- `bash examples/run.sh examples/inheritance.wfl /absolute/path/to/wfl`: inheritance example.
+- `bash examples/run.sh examples/theme.wfl /absolute/path/to/wfl`: theme example.
+
+Record the runtime version and source revision. Use disposable fixtures;
+`build/` contains test output. No engine build step is needed.
+Behavior fixes need intended failing evidence before implementation.
+Prose-only changes use relevant link/policy checks; required CI is not waived.
+Preserve Apache-2.0 and third-party attribution; do not change licensing.

GOVERNANCE.md

@@ -0,0 +1,110 @@
+# Scribe Project Governance
+
+Scribe is the WFL template engine, maintained by Brad / Logbie LLC.
+Contributions remain under [Apache-2.0](LICENSE). Preserve existing attribution.
+
+| Document | Purpose |
+| --- | --- |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Workflow and commands |
+| [testing.md](testing.md) | Test evidence and known limits |
+| [SECURITY.md](SECURITY.md) | Private reporting and engine boundaries |
+| [CLAUDE.md](CLAUDE.md), [AGENTS.md](AGENTS.md) | Agent entry points |
+| [README.md](README.md) | Engine usage |
+| [Design](docs/DESIGN.md), [syntax](docs/SYNTAX.md) | Technical contracts |
+
+## Common contribution policy — version 1.0 (2026-09-27)
+
+This version records Brad's approved Logbie LLC governance and subsequent dev
+merge and CEO delegations of 2026-09-26. It governs contribution authority;
+the repository's technical, compatibility, testing and licensing rules remain
+binding. Report substantive conflicts on the owning issue instead of silently
+relaxing a rule.
+
+### Branches and review
+
+- Start a short-lived feature, fix or documentation branch from current `dev`;
+  open its PR into `dev`. Never push directly to `dev`, `main` or a release
+  branch, or force-push shared branches. Promotion is `dev → main` by PR.
+- Yomi reviews the current revision against governance and testing policy.
+  The PR author, including an agent author, may merge their own PR into `dev`
+  only after applicable CI passes on that reviewed revision and findings are
+  addressed. This delegation needs no separate per-PR Brad approval.
+- Let triggered bot reviews finish; inspect reviews, inline comments and
+  discussions. Fix actionable findings or record a reasoned disposition and
+  resolve required discussions. Recheck checks and reviews immediately before
+  merging. Material changes require fresh applicable CI and Yomi review.
+- The PR owner remains responsible while CI or bot review is pending. Use an
+  actual scheduled monitor or event-driven continuation, not a promise to watch.
+- Do not bypass protections, use an administrator override, remove a check, or
+  rerun a genuine failure merely to manufacture green. Access is not authority.
+
+### Evidence and testing
+
+- Behavior changes start with a test failing for the intended reason, followed
+  by implementation and passing evidence. Retain exact commands, revisions,
+  results and run links under the repository testing policy.
+- GitHub Actions on the current reviewed revision is merge evidence; local
+  checks supplement it. Enumerate required jobs and their individual results.
+  Missing tools, environment failures, missing/pending checks and skipped,
+  cancelled or failed required suites are blocked verification, never passes.
+  An aggregate green result cannot stand in for an unrun required suite.
+- For prose-only work, record “Behavior tests N/A — documentation only” with
+  the reason and relevant documentation, link and policy checks. This does not
+  waive required CI. Existing risk classes and stricter technical gates remain.
+- Run agent-operated runtime tests on Starnet test VM 136 or 104, never VM 143;
+  coordinate risky-test snapshots with Nodoka. Preserve the repository's approved
+  GitHub Actions execution environments and record their actual results.
+
+### Promotion, release and production authority
+
+Azusa, CEO of Logbie LLC, may approve and perform builds, releases, merges to
+`main`, release promotions, tags and production deployments only when every
+required check passed on the exact commit being acted on: none skipped,
+missing, pending, flaky or failing. Record the SHA, required-check set and
+individual result links, then recheck immediately before acting. A different
+SHA or aggregate green is insufficient; a flaky rerun is not a waiver.
+Anything short of fully green stops for Brad's explicit authorization.
+Yomi's current-revision review and handled bot feedback remain required.
+
+Always Brad's decisions regardless of CI: spending money; deleting data,
+agents or repositories; anything touching secrets; VM configuration changes;
+and removing or weakening required checks. Release/deploy workflow changes,
+organization settings/membership and deletion of branches, rulesets or
+workflows also require Brad's explicit approval through the owning issue.
+
+Production hosts are read-only for agents: authorized config/log inspection
+only, without exposing secrets. No edits, restarts, installs or migrations.
+The conditional CEO production-deployment authority above is limited to the
+authorized deployment; it grants no general production administration.
+Other production changes go to Brad through Azusa.
+
+### Credentials, exceptions and enforcement
+
+Never commit, print, log or paste credentials into files, comments, PRs,
+command arguments or remote URLs. Inject authorized tokens through environment
+variables from approved storage, with minimal scope. Suspected exposure:
+stop propagation, report safe metadata, and coordinate response with Brad.
+Do not borrow another agent's or a human's credentials.
+
+Tie governed changes to an owning issue. Record exceptions with scope, reason,
+risk, owner, expiry and follow-up, and obtain Brad's explicit approval before
+acting. A deviation note is not approval and cannot silently amend policy.
+
+Policy text does not configure GitHub. Verify effective protections and actual
+required checks via the API. Report missing controls, identities and platform
+limits explicitly; never call a convention machine-enforced. In particular,
+a shared author identity cannot supply independent GitHub approval. Deferred
+identity enforcement does not authorize bypass or replace Yomi's review.
+
+## Project-specific policy
+
+Preserve HTML auto-escaping, explicit trusted raw output, template syntax and
+existing callers. Scribe does not sandbox the filesystem; trusted template
+paths and bounded nesting remain security contracts. Changes need tests and
+updated technical documentation. Do not add a runtime dependency or language
+change as part of governance work.
+
+AI assistance is welcome under the same quality and licensing bar; authors
+remain accountable and must not expose private data. Treat contributors with
+respect and report conduct concerns privately to info@logbie.com.
+Brad resolves technical/governance disputes and approves policy amendments.

README.md

@@ -189,3 +189,9 @@ upstream — all since addressed:
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).
+
+## Contribution policy
+
+Read [GOVERNANCE.md](GOVERNANCE.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
+Work on feature branches and open PRs into `dev`; current-revision CI and
+Yomi review are required.

SECURITY.md

@@ -0,0 +1,16 @@
+# Scribe security
+
+Report suspected vulnerabilities privately to info@logbie.com with subject
+“Scribe Security Vulnerability”; do not publish exploit details or credentials.
+Include affected Scribe/WFL revisions and a sanitized reproduction. No response
+SLA or supported-release matrix is claimed. Brad coordinates response.
+
+Preserve HTML auto-escaping and explicit trusted `raw` output. Template source
+is trusted code, and include/import/inheritance paths are not a filesystem
+sandbox. See [syntax](docs/SYNTAX.md) and [design](docs/DESIGN.md).
+Security-boundary changes need negative tests under [testing.md](testing.md).
+
+No credentials in files, logs, PRs or comments. Use approved environment
+injection; anything touching secrets is Brad’s decision. Production is
+read-only except the explicitly authorized CEO deployment gate in
+[GOVERNANCE.md](GOVERNANCE.md).

testing.md

@@ -0,0 +1,34 @@
+# Scribe testing policy and profile
+
+Version 1.0, reviewed 2026-09-27. Owner: Brad / Logbie LLC.
+Authority and evidence gates: [GOVERNANCE.md](GOVERNANCE.md).
+
+Behavior changes require an intended failing regression before implementation,
+then passing tests on the affected boundaries. Record base/failing/final SHAs,
+commands, runtime version, environment, results and exact-commit Actions links.
+No retries, skipped required suites or aggregate green may hide a failure.
+
+Run `bash tests/run.sh /absolute/path/to/wfl` from a disposable checkout.
+It invokes `wfl --test tests/scribe.test.wfl`; fixtures write into `build/`.
+Run the examples in [CONTRIBUTING.md](CONTRIBUTING.md) when affected and compare
+rendered output with the corresponding `.expected.html` files. No external
+credentials or production data are needed.
+
+Prose-only work is R0: behavior tests N/A with a reason, plus relevant link,
+Markdown and policy checks. Engine/API changes are at least R2; security,
+untrusted input, escaping, paths and nesting are R3 and need negative cases
+and independent review. Preserve include/inheritance/macro behavior, escaping,
+raw-output trust and bounded nesting. Real file access needs real fixture tests.
+
+Required Actions contexts are `Documentation checks` and `Scribe tests`.
+The proposed CI workflow in PR 4 is still unmerged as of this profile date;
+verify that the PR actually runs both contexts before claiming a pass.
+Linux CI runtime results do not establish Windows/macOS or production support.
+Agent-operated runtime tests use Starnet VM 136/104, never VM 143.
+
+Known gaps: no measured coverage threshold, performance budget, supported
+platform matrix or comprehensive release-candidate gate. Brad owns these gaps;
+review before the next affected change/release. Browser/a11y testing is N/A
+for engine-only prose, but rendered application changes need their app checks.
+Missing evidence stays blocked; exceptions require Brad under GOVERNANCE.md.
+Retain sanitized CI and review evidence with the PR.