Repository navigation
chore(governance): establish project policies and contribution templates #12
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| name: Bug report | ||
| description: Report a reproducible problem with Scriptorium. | ||
| title: "[Bug]: " | ||
| body: | ||
| - type: markdown | ||
| attributes: | ||
| value: | | ||
| Describe one problem per report and link an existing issue if it covers the same problem. | ||
| Share what you know; use "Unknown" for versions or details you cannot determine. | ||
|
|
||
| **This report and its attachments will be public.** Use synthetic examples and remove | ||
| passwords, session cookies, CSRF tokens, personal information, private drafts, and site data. | ||
| Do not attach a live database, raw production logs, or your complete deployment configuration. | ||
|
|
||
| Report suspected security vulnerabilities privately through | ||
| [SECURITY.md](https://github.com/WebFirstLanguage/Scriptorium/blob/main/SECURITY.md). | ||
|
|
||
| - type: textarea | ||
| id: summary | ||
| attributes: | ||
| label: What is broken? | ||
| description: Describe the problem and who or what it affects. Use a title that names the failing behavior. | ||
| placeholder: "For example: After saving a published page, the public page still shows the previous title." | ||
| validations: | ||
| required: true | ||
|
|
||
| - type: textarea | ||
| id: environment | ||
| attributes: | ||
| label: Versions and environment | ||
| description: | | ||
| Include what you can determine; "Unknown" is fine. From the checkout used to run the site, | ||
| `git rev-parse HEAD` identifies Scriptorium, `wfl --version` identifies WFL, and | ||
| `git submodule status lib/scribe` shows the Scribe revision and checkout status. | ||
| Include that output as-is. Describe relevant settings without credentials, | ||
| private hostnames, or private filesystem paths. | ||
| placeholder: | | ||
| Scriptorium commit or version: | ||
| WFL version: | ||
| Scribe revision and checkout status: | ||
| Operating system and version: | ||
| Browser and version (if relevant): | ||
| Deployment (local, container, reverse proxy, etc.): | ||
| Theme and site extension (stock or customized): | ||
| Data directory (default or configured): | ||
| Fresh install or upgrade: | ||
| validations: | ||
| required: true | ||
|
|
||
| - type: textarea | ||
| id: reproduction | ||
| attributes: | ||
| label: Steps to reproduce | ||
| description: | | ||
| Give the smallest steps that show the problem, including the route, account role, | ||
| and synthetic input when relevant. A minimal WFL or template example is welcome. | ||
| If you cannot reproduce it reliably, describe the sequence you observed. | ||
| placeholder: | | ||
| 1. Start with ... | ||
| 2. Sign in as an admin/author and open ... | ||
| 3. Submit this sample input ... | ||
| 4. Observe ... | ||
| validations: | ||
| required: true | ||
|
|
||
| - type: textarea | ||
| id: expected | ||
| attributes: | ||
| label: Expected behavior | ||
| description: What should happen? Link relevant documentation if it helps explain the expectation. | ||
| validations: | ||
| required: true | ||
|
|
||
| - type: textarea | ||
| id: actual | ||
| attributes: | ||
| label: Actual behavior | ||
| description: What happened instead? Include the exact error or HTTP status when available, with sensitive values removed. | ||
| validations: | ||
| required: true | ||
|
|
||
| - type: dropdown | ||
| id: frequency | ||
| attributes: | ||
| label: How often does it happen? | ||
| options: | ||
| - Every time | ||
| - Sometimes | ||
| - Observed once | ||
| - Not sure | ||
| validations: | ||
| required: true | ||
|
|
||
| - type: textarea | ||
| id: regression | ||
| attributes: | ||
| label: Last working version or recent changes | ||
| description: Optional. Note a last working revision, recent upgrade, Scribe pin change, or theme/configuration change. Say if this is a fresh install. | ||
|
|
||
| - type: textarea | ||
| id: evidence | ||
| attributes: | ||
| label: Relevant logs, screenshots, or minimal example | ||
| description: | | ||
| Optional. Paste only the relevant sanitized excerpt or attach a screenshot/example using | ||
| synthetic data. Remove credentials, cookies, tokens, private content, and personal information. | ||
| Include commands and actual results for any checks you already ran; tests are not required to report a bug. | ||
|
|
||
| - type: textarea | ||
| id: workaround | ||
| attributes: | ||
| label: Workaround or additional context | ||
| description: Optional. Describe any workaround, related issue, or other observation that may help reproduce the problem. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| blank_issues_enabled: true | ||
| contact_links: | ||
| - name: Report a security vulnerability | ||
| url: https://github.com/WebFirstLanguage/Scriptorium/blob/main/SECURITY.md | ||
| about: Use the private reporting process for vulnerabilities; do not publish exploit details or private site data in an issue. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| <!-- | ||
| Title: <type>(<optional scope>): <imperative summary> | ||
| Example: fix(auth): reject expired sessions | ||
|
|
||
| Keep the headings below and replace the prompts with concrete details. | ||
| Scale the detail to the change. Use "N/A — reason" for an inapplicable field; | ||
| record missing checks as "Not run — reason", never as a pass. Drafts may mark | ||
| unfinished evidence as pending. Keep the title and body aligned with the final diff. | ||
| --> | ||
|
|
||
| ## Summary | ||
|
|
||
| <!-- Explain the problem and resulting behavior. Include a brief before/after | ||
| example when useful, observable acceptance criteria, and related issue links. --> | ||
|
|
||
| ## Changes | ||
|
|
||
| <!-- List the material changes and why they are needed. Include only details | ||
| that help a reviewer assess the implementation; omit the work-session history. --> | ||
|
|
||
| ## Compatibility and risk | ||
|
|
||
| - **Risk class and reason:** <!-- R0, R1, R2, or R3; see testing.md. --> | ||
| - **Affected contracts:** <!-- URLs, schema/data/uploads, configuration, themes, | ||
| extension hooks, runtime requirements, or the Scribe pin; say none if unaffected. --> | ||
| - **Upgrade and recovery:** <!-- Migration, backup, rollback or forward-repair | ||
| steps. Link the approved transition plan for a breaking change, or explain N/A. --> | ||
| - **Remaining risks or gaps:** <!-- Untested boundaries, limitations, and any | ||
| exception with its approval, scope, expiry, and follow-up issue; or none. --> | ||
|
|
||
| ## Validation | ||
|
|
||
| - **Tested revision and environment:** <!-- Commit, OS, relevant tool versions; | ||
| include WFL and pinned Scribe revisions for runtime checks. --> | ||
| - **Regression evidence:** <!-- Intended failure before the fix and passing | ||
| result afterward; Green before/after for a refactor; explain N/A for prose. --> | ||
|
|
||
| | Check or exact command | Result and evidence | | ||
| |---|---| | ||
| | <!-- Required automated check --> | <!-- Actual result, counts or CI run link; identify failures and checks not run. --> | | ||
| | <!-- Affected HTTP/UI, security, accessibility, or recovery check --> | <!-- Setup, expected/actual outcome, and evidence; or N/A with reason. --> | | ||
|
|
||
| ## Checklist | ||
|
|
||
| - [ ] The title, summary, and risk assessment match the final diff. | ||
| - [ ] Required validation is recorded above; failures and missing checks are explicit. | ||
| - [ ] Documentation, examples, and upgrade/recovery guidance are updated where applicable. | ||
| - [ ] I reviewed the diff for repository hygiene, secrets, and private site data. | ||
|
|
||
| Follow [CONTRIBUTING.md](https://github.com/WebFirstLanguage/Scriptorium/blob/main/CONTRIBUTING.md), | ||
| [testing.md](https://github.com/WebFirstLanguage/Scriptorium/blob/main/testing.md), and | ||
| [REPOSITORY_HYGIENE.md](https://github.com/WebFirstLanguage/Scriptorium/blob/main/REPOSITORY_HYGIENE.md). | ||
|
|
||
| Report undisclosed vulnerabilities privately using [SECURITY.md](https://github.com/WebFirstLanguage/Scriptorium/blob/main/SECURITY.md). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| name: Governance | ||
|
|
||
| on: | ||
| push: | ||
| branches: [main] | ||
| pull_request: | ||
| branches: [main] | ||
| workflow_dispatch: | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| concurrency: | ||
| group: governance-${{ github.workflow }}-${{ github.ref }} | ||
| cancel-in-progress: true | ||
|
|
||
| jobs: | ||
| repository-checks: | ||
| name: Repository checks (${{ matrix.os }}) | ||
| strategy: | ||
| fail-fast: false | ||
| matrix: | ||
| os: [ubuntu-latest, windows-latest] | ||
| runs-on: ${{ matrix.os }} | ||
| timeout-minutes: 10 | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| with: | ||
| persist-credentials: false | ||
| submodules: recursive | ||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: '3.12' | ||
| - name: Test repository tooling | ||
| run: python -m unittest discover -s tests/tooling -v | ||
| - name: Check repository hygiene | ||
| run: python scripts/check_repo_hygiene.py |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| # Concrete enforcement for REPOSITORY_HYGIENE.md. Changes require review of | ||
| # the policy reason, not just a wider allowlist to make the checker pass. | ||
| schema = 1 | ||
|
|
||
| [root] | ||
| allowed-files = [ | ||
| ".gitignore", ".gitmodules", ".repo-hygiene.toml", ".wflcfg", | ||
| "AGENTS.md", "AI_POLICY.md", "CLAUDE.md", "CODE_OF_CONDUCT.md", | ||
| "CONTRIBUTING.md", "GOVERNANCE.md", "LICENSE", "README.md", | ||
| "REPOSITORY_HYGIENE.md", "SECURITY.md", "main.wfl", "testing.md", | ||
| ] | ||
| allowed-dirs = [ | ||
| ".github", "admin", "app", "docs", "lib", "scripts", "static", | ||
| "TestPrograms", "tests", "themes", | ||
| ] | ||
|
|
||
| [required] | ||
| files = [ | ||
| ".gitignore", ".gitmodules", ".repo-hygiene.toml", ".wflcfg", | ||
| "AGENTS.md", "AI_POLICY.md", "CLAUDE.md", "CODE_OF_CONDUCT.md", | ||
| "CONTRIBUTING.md", "GOVERNANCE.md", "LICENSE", "README.md", | ||
| "REPOSITORY_HYGIENE.md", "SECURITY.md", "main.wfl", "testing.md", | ||
| "docs/ARCHITECTURE.md", "docs/PROJECT-LAYOUT.md", "docs/THEMING.md", | ||
| "scripts/check_repo_hygiene.py", "scripts/run_tests.py", | ||
| "tests/tooling/test_repo_hygiene.py", "tests/tooling/test_run_tests.py", | ||
| ".github/pull_request_template.md", ".github/workflows/governance.yml", | ||
|
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win Require the GitHub issue-template configuration.
🤖 Prompt for AI Agents |
||
| ] | ||
| # These paths must remain Git gitlinks; their contents are upstream-owned. | ||
| gitlinks = ["lib/scribe"] | ||
|
|
||
| [forbidden] | ||
| # Match path components / base names case-insensitively, at any depth. | ||
| dirs = [ | ||
| "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", | ||
| "node_modules", ".venv", "venv", "target", ".cache", | ||
| ] | ||
| names = [".DS_Store", "Thumbs.db", "settings.local.json", "id_rsa", "id_ed25519"] | ||
| patterns = [ | ||
| "*.db", "*.db-*", "*.sqlite", "*.sqlite-*", "*.sqlite3", "*.sqlite3-*", | ||
| "*.log", "*.pyc", "*.pyo", "*.orig", "*.rej", "*.tmp", "*.bak", | ||
| "*_debug.txt", "*.ast.txt", "*.lex.txt", "*.exe", "*.dll", "*.msi", | ||
| ".env", ".env.*", "*.key", "*.pem", "*.p12", "*.pfx", | ||
| "credentials.json", "credentials.*.json", "secrets.json", "secrets.*.json", | ||
| ] | ||
| # Mutable application state. Only the existing empty upload placeholder ships. | ||
| paths = ["data", "static/uploads"] | ||
| allowed-placeholders = ["static/uploads/.gitkeep"] | ||
|
|
||
| [links] | ||
| # Check local inline links/images and reference-link definitions in these files. | ||
| # Fragments, external URLs, code fences, and paths within gitlinks are skipped. | ||
| files = [ | ||
| "README.md", "CLAUDE.md", "AGENTS.md", "GOVERNANCE.md", "CONTRIBUTING.md", | ||
| "CODE_OF_CONDUCT.md", "AI_POLICY.md", "SECURITY.md", "REPOSITORY_HYGIENE.md", | ||
| "testing.md", | ||
| ] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| # Repository guidelines | ||
|
|
||
| Read [CLAUDE.md](CLAUDE.md) first. It is the canonical shared agent guide for | ||
| Scriptorium, including architecture constraints, development commands, and | ||
| links to the binding root governance policies. | ||
|
|
||
| This file is an adapter, not a second policy source. Update `CLAUDE.md` and the | ||
| relevant root policy when guidance changes. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟡 SQLite journals fail hygiene checks
A local
*.sqlite-journalor*.sqlite3-journalremains unignored and enterscheck_repo_hygiene.py. The forbidden patterns reject these SQLite sidecars, so normal local database activity fails the hygiene gate.Was this helpful? React with 👍 or 👎 to provide feedback.