diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000..80019f6 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -euo pipefail + +REPO_ROOT="$(git rev-parse --show-toplevel)" +CHANGED="$(git diff --cached --name-only)" + +if ! printf '%s\n' "$CHANGED" | grep -Eq '^(\.github/|README\.md|CONTRIBUTING\.md|SECURITY\.md)'; then + exit 0 +fi + +echo "[pre-commit] .github policy checks" + +python3 - <<'PY' +from pathlib import Path +import sys +import yaml + +root = Path.cwd() +errors = [] +for workflow in sorted((root / ".github" / "workflows").glob("*.yml")): + try: + yaml.safe_load(workflow.read_text(encoding="utf-8")) + except Exception as exc: # noqa: BLE001 + errors.append(f"{workflow.name}: {exc}") + +for tmpl in sorted((root / ".github" / "ISSUE_TEMPLATE").glob("*.md")): + text = tmpl.read_text(encoding="utf-8") + if not text.startswith("---"): + errors.append(f"{tmpl.name}: missing YAML frontmatter block") + +if errors: + for err in errors: + print(err) + sys.exit(1) +PY diff --git a/.github/ISSUE_TEMPLATE/first_contribution.md b/.github/ISSUE_TEMPLATE/first_contribution.md new file mode 100644 index 0000000..3bdbbce --- /dev/null +++ b/.github/ISSUE_TEMPLATE/first_contribution.md @@ -0,0 +1,29 @@ +--- +name: "First Contribution" +about: "Scoped onboarding issue for first-time contributors" +title: "[FIRST-CONTRIB] " +labels: ["good first issue"] +assignees: [] +--- + +## Outcome + +What concrete outcome should be achieved? + +## Scope + +Which files/modules are in scope? Keep scope constrained. + +## Acceptance Criteria + +- [ ] Criteria are explicit and testable +- [ ] Required validation commands are listed +- [ ] Estimated completion time is under one focused day + +## Validation Commands + +List commands a contributor must run before opening a PR. + +## Notes for Reviewer + +Any constraints, caveats, or context a reviewer should know. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 243fd58..ba03967 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -15,4 +15,7 @@ Brief description of the changes. - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review - [ ] I have added tests that prove my fix/feature works -- [ ] New and existing tests pass locally \ No newline at end of file +- [ ] New and existing tests pass locally +- [ ] I ran the relevant repo validation command(s) +- [ ] No secrets or credentials were added +- [ ] Related issue is linked with explicit acceptance criteria diff --git a/BRANCH_PROTECTION_BASELINE.md b/BRANCH_PROTECTION_BASELINE.md new file mode 100644 index 0000000..5f264d3 --- /dev/null +++ b/BRANCH_PROTECTION_BASELINE.md @@ -0,0 +1,38 @@ +# Branch Protection Baseline + +Apply this baseline to default branches (`main`) for all ORGAN-V repositories. + +## Required Settings + +1. Require a pull request before merging. +2. Require approvals: minimum 1. +3. Dismiss stale approvals when new commits are pushed. +4. Require conversation resolution before merge. +5. Require status checks to pass before merge. +6. Restrict force-pushes and deletion on protected branches. +7. Require linear history (optional but recommended). + +## Required Status Checks (by repo) + +### `public-process` +- `Public Process CI / validate` + +### `essay-pipeline` +- `Essay Pipeline CI / test` + +### `analytics-engine` +- `Analytics Engine CI / test` (or equivalent job name in workflow) + +### `reading-observatory` +- `Reading Observatory CI / test` (or equivalent job name in workflow) + +### `editorial-standards` +- `Editorial Standards CI / validate` (or equivalent job name in workflow) + +### `.github` +- `ORGAN-V CI Minimal / validate` (or equivalent job name in workflow) + +## Ownership + +- Repo admin applies settings. +- Any exception requires linked issue + explicit expiry date. diff --git a/CLAUDE.md b/CLAUDE.md index eb945f3..b4088e4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,3 +18,11 @@ *Last synced: 2026-02-24T12:41:28Z* + + +## ⚡ Conductor OS Integration +This repository is a managed component of the ORGANVM meta-workspace. +- **Orchestration:** Use `conductor patch` for system status and work queue. +- **Lifecycle:** Follow the `FRAME -> SHAPE -> BUILD -> PROVE` workflow. +- **Governance:** Promotions are managed via `conductor wip promote`. +- **Intelligence:** Conductor MCP tools are available for routing and mission synthesis. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e57ac7e..e506267 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,13 @@ This organization covers: Essays, process documentation, methodology writing. 4. **Write tests** — maintain or improve coverage 5. **Submit a PR** with clear description of changes +### First-Time Contribution Path + +1. Pick an issue labeled `good first issue`. +2. Confirm scope, validation commands, and acceptance criteria before coding. +3. Keep changes focused; avoid cross-repo refactors on first contribution. +4. Run local validation commands listed in the issue/README. + ### What We Accept - Bug fixes with tests @@ -42,12 +49,19 @@ Essay contributions must include YAML frontmatter (title, author, date, tags, ca - Python: PEP 8, type hints, f-strings - Tests required for all new functionality - Commit messages: imperative mood, <72 chars title +- README structure must follow [README standards](README_STANDARDS.md) ## Getting Help - Open an Issue for questions - Check existing documentation in each repo's README +## Review Service Targets + +- Initial maintainer response: within 3 business days +- Review response after updates: within 3 business days +- Merge decision after approval: within 2 business days + --- *Part of the [organvm eight-organ system](https://github.com/meta-organvm)* diff --git a/GEMINI.md b/GEMINI.md index eb945f3..b4088e4 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -18,3 +18,11 @@ *Last synced: 2026-02-24T12:41:28Z* + + +## ⚡ Conductor OS Integration +This repository is a managed component of the ORGANVM meta-workspace. +- **Orchestration:** Use `conductor patch` for system status and work queue. +- **Lifecycle:** Follow the `FRAME -> SHAPE -> BUILD -> PROVE` workflow. +- **Governance:** Promotions are managed via `conductor wip promote`. +- **Intelligence:** Conductor MCP tools are available for routing and mission synthesis. diff --git a/README.md b/README.md index 533f996..d414be0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,9 @@ # .github Organization profile and community health files + +## Included Governance Assets + +- Issue templates and PR template defaults +- Organization-level workflows +- [Branch protection baseline](BRANCH_PROTECTION_BASELINE.md) +- [README standards](README_STANDARDS.md) diff --git a/README_STANDARDS.md b/README_STANDARDS.md new file mode 100644 index 0000000..e54ae77 --- /dev/null +++ b/README_STANDARDS.md @@ -0,0 +1,59 @@ +# README Standards Overlay (ORGAN-V Logos) + +This document is an organ-level overlay for README policy in `organvm-v-logos`. + +## Canonical Upstream + +Canonical full standards live in: +- `meta-organvm/.github/README_STANDARDS.md` + +This overlay can add stricter local requirements but cannot weaken upstream +requirements. + +## Local Profiles + +Use the profile that matches the repository type. + +### Profile A: Governance Repo (`.github`) + +Required: +- `#` title +- `## Included Governance Assets` +- links to org governance docs (for example branch protection baseline) + +### Profile B: Flagship Narrative Repo (`public-process`) + +Required: +- `#` title +- `## Introduction` +- `## Methodology` +- `## Lessons Learned` + +### Profile C: Code/Automation Repos + +Applies to: +- `essay-pipeline` +- `editorial-standards` +- `analytics-engine` +- `reading-observatory` + +Required: +- `#` title +- one context section: `## Overview` or `## Current State` or `## Introduction` +- one execution section: `## Development` or `## Setup` or `## Getting Started` + +Recommended: +- `## Architecture` +- `## Testing` and/or validation commands +- CI badge near top + +## Enforcement + +Local minimum checks are enforced by: + +```bash +./tools/audit_platform_standards.sh +``` + +Violations must be fixed in the same PR or tracked in a linked issue with owner +and due date.