From 40640a65e79361459768d08ba183873c223ed11a Mon Sep 17 00:00:00 2001 From: Sawako Yamanaka Date: Sun, 27 Sep 2026 10:47:32 +0000 Subject: [PATCH 1/3] ci: validate documentation and run the Scribe suite on PRs Co-Authored-By: Paperclip --- .github/workflows/ci.yml | 65 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..8e9e045 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,65 @@ +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 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 + ' From 87d26e879dc590e25477ccc5825714b623de097a Mon Sep 17 00:00:00 2001 From: Sawako Yamanaka Date: Sun, 27 Sep 2026 10:49:46 +0000 Subject: [PATCH 2/3] fix(ci): syntax-check both documented shell runners Co-Authored-By: Paperclip --- .github/workflows/ci.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8e9e045..6b2cbd7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -30,7 +30,9 @@ jobs: test -s docs/SYNTAX.md test -s docs/DESIGN.md - name: Check documented shell entry points - run: bash -n tests/run.sh examples/run.sh + run: | + bash -n tests/run.sh + bash -n examples/run.sh tests: name: Scribe tests From b328ddeecd214b5c47015cca27c1e4bc0e71dc47 Mon Sep 17 00:00:00 2001 From: Sawako Yamanaka Date: Sun, 27 Sep 2026 13:53:36 +0000 Subject: [PATCH 3/3] docs: harmonize governance and contribution authority Co-Authored-By: Paperclip --- .github/pull_request_template.md | 25 +++++++ AGENTS.md | 4 ++ CLAUDE.md | 16 +++++ CONTRIBUTING.md | 22 +++++++ GOVERNANCE.md | 110 +++++++++++++++++++++++++++++++ README.md | 6 ++ SECURITY.md | 16 +++++ testing.md | 34 ++++++++++ 8 files changed, 233 insertions(+) create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.md create mode 100644 SECURITY.md create mode 100644 testing.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..4e7263c --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b3e0105 --- /dev/null +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..339885e --- /dev/null +++ b/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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e7cd270 --- /dev/null +++ b/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. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..8a064db --- /dev/null +++ b/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. diff --git a/README.md b/README.md index f7f639a..bc0cf53 100644 --- a/README.md +++ b/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. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..28813c2 --- /dev/null +++ b/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). diff --git a/testing.md b/testing.md new file mode 100644 index 0000000..12acb14 --- /dev/null +++ b/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.