diff --git a/.github/ISSUE_TEMPLATE/01_quick_issue.md b/.github/ISSUE_TEMPLATE/01_quick_issue.md new file mode 100644 index 0000000..739cc76 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01_quick_issue.md @@ -0,0 +1,19 @@ +--- +name: Quick Issue +about: Fast path for questions, confusing docs, or lightweight reports +title: "[QUICK] " +labels: "triage" +assignees: "" +--- + +## What happened? + + + +## What did you expect to find or do? + + + +## Link or path + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 1e0b25b..0e98f67 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: true contact_links: - - name: ORGAN-V Governance Docs + - name: Technical Architecture + url: https://github.com/organvm-v-logos/public-process/blob/main/docs/architecture.md + about: Start here for system diagrams, build flow, and integration contracts + - name: ORGAN-V Docs url: https://github.com/organvm-v-logos/public-process/tree/main/docs - about: Process architecture, dissertation SOP, and publication standards + about: ADRs, data contracts, staging reference, and publication standards diff --git a/.github/ISSUE_TEMPLATE/stranger_test_feedback.md b/.github/ISSUE_TEMPLATE/stranger_test_feedback.md index 939431b..1638674 100644 --- a/.github/ISSUE_TEMPLATE/stranger_test_feedback.md +++ b/.github/ISSUE_TEMPLATE/stranger_test_feedback.md @@ -9,30 +9,23 @@ assignees: "" ## Session Metadata - Date: -- Session type: (live / async) - Participant profile: ## Tasks Attempted -List each task and whether it succeeded. +List the task and result. One task is enough. -1. Task: - Result: ✅ / ❌ -2. Task: - Result: ✅ / ❌ +- Task: +- Result: ## Friction Points -What blocked, confused, or slowed the participant? +What blocked, confused, or slowed the participant? Plain language is enough. ## Trust Signals What increased or decreased confidence in the project? -## Recommended Changes +## Evidence or Suggested Fix -Concrete, testable changes this feedback suggests. - -## Evidence - -Links/screenshots/logs (if available and consented). +Links, screenshots, logs, or a suggested fix if available. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e0cdd2f..67330e1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -55,15 +55,51 @@ jobs: run: | python -m src.indexer \ --posts-dir ../_posts/ \ + --logs-dir ../_logs/ \ --output-dir ../data/ cd .. - if git diff --quiet data/; then - echo "::notice::Data files are up to date" - else - echo "::error::Data files are out of date — run the indexer locally and commit the result" - git diff --stat data/ - exit 1 - fi + python - <<'PY' + import json + import subprocess + import sys + from pathlib import Path + + changed = subprocess.check_output( + ["git", "diff", "--name-only", "--", "data/"], + text=True, + ).splitlines() + + semantic_drift = [] + timestamp_only = [] + for name in changed: + path = Path(name) + if path.suffix != ".json" or not path.exists(): + semantic_drift.append(name) + continue + try: + before = json.loads( + subprocess.check_output(["git", "show", f"HEAD:{name}"], text=True) + ) + after = json.loads(path.read_text()) + except Exception: + semantic_drift.append(name) + continue + before.pop("updated", None) + after.pop("updated", None) + if before == after: + timestamp_only.append(name) + else: + semantic_drift.append(name) + + if semantic_drift: + print("::error::Data files are out of date — run the indexer locally and commit the result") + subprocess.run(["git", "diff", "--stat", "--", *semantic_drift], check=False) + sys.exit(1) + if timestamp_only: + print("::notice::Data drift is limited to generated updated timestamps") + else: + print("::notice::Data files are up to date") + PY - name: Check internal links working-directory: _pipeline diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f225007..e11a3a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,10 +39,14 @@ bundle exec jekyll serve ### Reporting Issues -- Use GitHub Issues for bug reports and feature requests -- Use the provided issue templates when available +- Use **Quick Issue** when you just need to report friction, ask a question, or + file a documentation gap. +- Use the specific bug, feature, first-contribution, or stranger-test templates + only when that structure helps. - Include clear reproduction steps for bugs - For documentation issues, specify which file and section +- Architecture/navigation confusion is useful feedback. If you cannot find the + system diagram you expected, open a Quick Issue and name the path you tried. ### Making Changes diff --git a/README.md b/README.md index ba3a4ba..ab91431 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ > Building in public: the methodology, cross-validation cycle, and lessons learned from coordinating ~79 repositories across 8 GitHub organizations using AI agents as an ensemble of specialized reviewers. -[Introduction](#introduction) | [The Eight-Organ Model](#the-eight-organ-model) | [Methodology](#methodology) | [The Cross-Validation Cycle](#the-cross-validation-cycle) | [Per-Agent Findings](#per-agent-findings) | [Synthesis](#synthesis) | [Simulating Organizational Scale](#simulating-organizational-scale-in-solo-practice) | [Lessons Learned](#lessons-learned) | [Cross-References](#cross-references) +[Introduction](#introduction) | [Technical Architecture](docs/architecture.md) | [The Eight-Organ Model](#the-eight-organ-model) | [Methodology](#methodology) | [The Cross-Validation Cycle](#the-cross-validation-cycle) | [Per-Agent Findings](#per-agent-findings) | [Synthesis](#synthesis) | [Simulating Organizational Scale](#simulating-organizational-scale-in-solo-practice) | [Lessons Learned](#lessons-learned) | [Cross-References](#cross-references) --- @@ -28,6 +28,11 @@ The result is not just a set of repositories. It is evidence that **AI agents ca This essay is itself an ORGAN-V artifact: a public-process document that makes the methodology visible, inspectable, and reproducible. +For the engineering topology, build flow, and integration diagrams, start with +[Technical Architecture](docs/architecture.md). It is the shortest path for a +backend engineer trying to understand how this repository fits into the +eight-organ system. + --- ## The Eight-Organ Model @@ -316,6 +321,7 @@ The system is live. The process is public. The methodology is documented. What c ### Operational Documents +- [Technical Architecture](docs/architecture.md) - [Quality Policy](docs/quality-policy.md) - [Contributor Runway](docs/contributor-runway.md) - [Distribution Instrumentation Standard](docs/distribution-instrumentation.md) diff --git a/_includes/header.html b/_includes/header.html index a038c85..46d1f46 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -4,6 +4,7 @@