Skip to content

Commit 90c4135

Browse files
author
Arturo R Montesinos
committed
Initial import of ChatGPT5-created .zip project
0 parents  commit 90c4135

16 files changed

Lines changed: 659 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: curator-ci
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
validate-and-test:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- uses: actions/setup-python@v5
13+
with:
14+
python-version: "3.11"
15+
16+
- name: Install tooling
17+
run: |
18+
python -m pip install --upgrade pip
19+
pip install ruff mypy pytest jsonschema
20+
21+
- name: Lint (Ruff)
22+
run: ruff check . && ruff format --check .
23+
24+
- name: Type-check (MyPy)
25+
run: mypy . || true # advisory by default
26+
27+
- name: Fast tests (if any)
28+
run: |
29+
if [ -f tests/__init__.py ] || compgen -G "tests/test_*.py" > /dev/null; then
30+
pytest -q
31+
else
32+
echo "No tests yet"
33+
fi
34+
35+
- name: Validate AI_CURATOR_RECIPE front-matter against schema (if present)
36+
if: hashFiles('AI_CURATOR_RECIPE.md') != ''
37+
run: |
38+
python - <<'PY'
39+
import sys, yaml, json, jsonschema, pathlib
40+
from yaml import SafeLoader
41+
schema = json.loads(pathlib.Path('docs/curation/ai_curator_recipe.schema.json').read_text())
42+
# Extract YAML front-matter
43+
p = pathlib.Path('AI_CURATOR_RECIPE.md').read_text()
44+
if not p.startswith('---'):
45+
print('No YAML front-matter found in AI_CURATOR_RECIPE.md', file=sys.stderr)
46+
sys.exit(1)
47+
fm = p.split('---', 2)[1]
48+
data = yaml.load(fm, Loader=SafeLoader)
49+
jsonschema.validate(data, schema)
50+
print('Front-matter validated OK.')
51+
PY
52+
53+
- name: Guard: ADR index & lint (if ADRs exist)
54+
run: |
55+
if [ -d docs/adr ]; then
56+
python scripts/lint_adrs.py
57+
python scripts/check_adr_index.py
58+
else
59+
echo "No ADRs yet"
60+
fi

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# keep build artifacts, venvs, caches out
2+
dist/
3+
build/
4+
*.egg-info/
5+
__pycache__/
6+
.pytest_cache/
7+
.venv/
8+
.env/
9+
10+
# Always include curator docs
11+
!docs/curation/**

‎.pre-commit-config.yaml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Global pre-commit, curated for Software Curatorship projects
2+
exclude: ^docs/curation/
3+
4+
repos:
5+
- repo: https://github.com/astral-sh/ruff-pre-commit
6+
rev: v0.6.8
7+
hooks:
8+
- id: ruff
9+
args: ["--fix"]
10+
- id: ruff-format
11+
12+
- repo: local
13+
hooks:
14+
- id: mypy
15+
name: mypy
16+
entry: mypy --config-file pyproject.toml .
17+
language: system
18+
pass_filenames: false
19+
- id: adr-index
20+
name: ADR index check
21+
entry: python scripts/check_adr_index.py
22+
language: system
23+
pass_filenames: false
24+
- id: adr-lint
25+
name: ADR lint
26+
entry: python scripts/lint_adrs.py
27+
language: system
28+
pass_filenames: false
29+
- id: print-guard
30+
name: print guard (no bare print without file=)
31+
entry: python scripts/check_prints.py
32+
language: system
33+
pass_filenames: false
34+
- id: fast-tests
35+
name: fast tests subset
36+
entry: bash scripts/fast_tests.sh
37+
language: system
38+
pass_filenames: false

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# curator-seed
2+
3+
A minimal, production-grade starter for **Software Curatorship**.
4+
It provides the *operational grammar* (baseline recipe, schema, prompts, and guardrail scripts) to make any repository **self-documenting**, **self-verifying**, and **curator-friendly**.
5+
6+
## What’s inside
7+
8+
- `docs/curation/` — the “secret sauce” (baseline, schema, prompts, curation log template).
9+
- `scripts/` — small guardrails (ADR index check, ADR linter, print guard, fast tests).
10+
- `.github/workflows/ci.yml` — sample CI that validates your recipe and runs guardrails.
11+
- `.pre-commit-config.yaml` — pre-commit hooks for fast feedback.
12+
- `pyproject.toml` — minimal Ruff/MyPy config (safe defaults).
13+
14+
## Quickstart (existing project)
15+
16+
1. **Copy the folder** `docs/curation/` into your repo (or use this as a template repo).
17+
2. Add (or adapt) the guardrail `scripts/` you want.
18+
3. Commit, then open your Copilot/AI chat and paste:
19+
- `docs/curation/PROMPT_upgrade_to_v0.3.md` (baseline alignment), and optionally
20+
- `docs/curation/PROMPT_upgrade_with_tooling.md` (CI/pre-commit wiring).
21+
22+
> Tip: If your project does not yet have an `AI_CURATOR_RECIPE.md`, start with `PROMPT_instrument_curator_project.md` (for brand-new repos).
23+
24+
## Quickstart (new project)
25+
26+
1. Keep this structure.
27+
2. Ask Copilot/AI to **instrument the project** using `docs/curation/PROMPT_instrument_curator_project.md`.
28+
3. Commit the generated `AI_CURATOR_RECIPE.md` and `docs/curation/CURATION_LOG.md`.
29+
4. Ensure CI is green.
30+
31+
## Philosophy
32+
33+
- **AI drafts; human curator approves.**
34+
- Changes that affect users must be backed by **tests** and **ADRs**.
35+
- **Determinism** and **provenance** are first-class citizens.
36+
37+
---
38+
39+
**License:** MIT.
40+
41+
**Version of baseline included here:** 0.3 (as of 2025-10-25).

‎docs/curation/AI_CURATOR_RECIPE_BASELINE_v0.3.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
version: 0.3
3+
project: (fill with repo name)
4+
baseline_commit: (git SHA or tag)
5+
curated_by: (name or org)
6+
---
7+
8+
# AI Curator Recipe — Baseline (v0.3)
9+
10+
> This file defines the common framework for Software Curatorship projects.
11+
> Each repository customizes **§2 Product Contract**, **§10 Releases**, and **Appendix A**.
12+
> All other sections remain normatively identical across curated projects.
13+
14+
## 1) Intent & Scope <!-- @curator:required -->
15+
- Keep runtime minimal; favor clarity and determinism.
16+
- All user-visible behavior is test-backed and explained via ADRs.
17+
- Provenance is transparent (README “Attribution & Curation”, ADR-0010, AUTHORS).
18+
- Optional per-repo goals may be listed here.
19+
20+
## 2) Product Contract (plain language) <!-- @curator:required -->
21+
Describe the externally visible behavior of the CLI, API, or service.
22+
23+
| Aspect | Description |
24+
|--------|--------------|
25+
| **Inputs** | Command-line args, API payloads, files, env vars |
26+
| **Outputs/streams** | stdout → data; stderr → diagnostics |
27+
| **Exit codes** | Enumerate all used numeric codes |
28+
| **Determinism** | Define ordering, rounding, locale, or sampling rules |
29+
30+
> See Appendix A for detailed project-specific contracts.
31+
32+
## 3) Curation Principles <!-- @curator:required -->
33+
- AI drafts; human curator approves and is accountable.
34+
- Non-trivial changes: add/update tests and ADRs.
35+
- Prefer stdlib/zero-deps unless ADR justifies otherwise.
36+
- Maintain transparency of reasoning and provenance.
37+
38+
## 4) Repository Map <!-- @curator:required -->
39+
List canonical folders and files expected to exist.
40+
Example: `src/`, `tests/`, `docs/adr/`, `scripts/`, `.github/workflows/ci.yml`, `.pre-commit-config.yaml`.
41+
42+
## 5) ADR Policy <!-- @curator:required -->
43+
- Sections: **Context · Decision · Consequences**
44+
- Status flow: Proposed → Accepted → Superseded
45+
- Index file `docs/adr/README.md` auto-maintained; CI fails if stale.
46+
47+
## 6) Testing Strategy <!-- @curator:required -->
48+
- Cover contracts (inputs, outputs, invariants).
49+
- Add at least one edge case per behavior change.
50+
- Keep deterministic; network-free fast subset (`scripts/fast_tests.sh`).
51+
52+
## 7) Automation — Self-Verifying <!-- @curator:required -->
53+
| Stage | Tools | Purpose |
54+
|--------|--------|---------|
55+
| **Local (pre-commit)** | Ruff, mypy, ADR guards, print-guard, fast tests | Prevent regressions early |
56+
| **CI** | Lint → Type → Tests → Build → ADR checks | Guarantee reproducibility |
57+
58+
Optional additions: locale pinning, determinism diff, version parity check.
59+
60+
## 8) Definition of Done <!-- @curator:required -->
61+
- Lint/types/tests/build all green.
62+
- Tests cover new/changed behavior.
63+
- Docs/ADRs updated.
64+
- Provenance intact.
65+
- Packaging/version sanity verified.
66+
67+
## 9) AI Assistant Operating Procedure <!-- @curator:required -->
68+
1. Read tree & targets.
69+
2. Expand curator’s ask → checklist.
70+
3. Propose minimal diffs.
71+
4. Run checks; iterate to green or mark deferrals.
72+
5. Summarize deltas (Done/Deferred).
73+
6. Keep attribution; never remove license/provenance.
74+
75+
## 10) Releases & Versioning <!-- @curator:required -->
76+
- Semantic Versioning.
77+
- Define single source of truth for version.
78+
- Tag `vX.Y.Z`; CI green required.
79+
- Release notes + changelog optional but recommended.
80+
81+
## 11) Maintenance Rhythm <!-- @curator:optional -->
82+
Periodic curator duties: run pre-commit on all files, review README accuracy, ADR housekeeping, close incidents with guardrails.
83+
84+
## Deferred with Rationale <!-- @curator:required -->
85+
List any postponed improvements and explain why.
86+
87+
## Appendix A — Project-Specific Contracts <!-- @curator:required -->
88+
Use structured bullets mirroring §2.
89+
Include any CLI/API specifics, determinism rules, and domain invariants.
90+
All listed behaviors must have at least one validating test.
91+
92+
> Validated against `ai_curator_recipe.schema.json`
93+
> Last baseline change: 2025-10-25

‎docs/curation/CURATION_LOG_template.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Curation Log (template v2)
2+
3+
| Field | Description |
4+
|-------|--------------|
5+
| **project** | (repo name) |
6+
| **baseline_version** | 0.3 |
7+
| **curator** | (human maintainer) |
8+
| **round_date** | YYYY-MM-DD |
9+
| **copilot_model** | (e.g., GitHub Copilot Chat GPT-5 Oct 2025) |
10+
| **status** | in-progress / accepted / superseded |
11+
12+
---
13+
14+
## Summary
15+
Short paragraph summarizing the goal of this curation round.
16+
17+
## Key Decisions
18+
- Decision 1 — summary + ADR link
19+
- Decision 2 — summary + ADR link
20+
21+
## AI/Curator Interaction Notes
22+
- Prompt(s) used
23+
- Copilot responses worth preserving
24+
- Deviations or surprises
25+
26+
## Artifacts Produced
27+
- Updated files / new tests / ADR numbers
28+
29+
## Verification
30+
- [x] Pre-commit passed
31+
- [x] CI green
32+
- [x] ADR index updated
33+
- [x] README verified
34+
35+
## Follow-ups / Deferrals
36+
- Item → planned ADR
37+
- Item → future automation step

‎docs/curation/PROMPT_instrument_curator_project.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Prompt: Instrument a new project for Software Curatorship
2+
3+
You are assisting in **instrumenting a completely new project** to apply the Software Curatorship methodology.
4+
5+
The folder `docs/curation/` already contains the core curator assets:
6+
- `AI_CURATOR_RECIPE_BASELINE_v0.3.md`
7+
- `ai_curator_recipe.schema.json`
8+
- `CURATION_LOG_template.md`
9+
- `PROMPT_upgrade_to_v0.3.md`
10+
- `PROMPT_upgrade_with_tooling.md`
11+
12+
Follow these steps to turn this repository into a **curator-ready** project.
13+
14+
---
15+
16+
## 1. Read the Baseline
17+
Open and read `docs/curation/AI_CURATOR_RECIPE_BASELINE_v0.3.md`.
18+
This file defines the canonical structure, headings, and required curator comments (`<!-- @curator:required -->`, etc.).
19+
20+
## 2. Create the Initial AI_CURATOR_RECIPE.md
21+
Generate a new `AI_CURATOR_RECIPE.md` at the root of the repository by copying the baseline and filling in the required metadata:
22+
23+
```yaml
24+
---
25+
version: 0.3
26+
project: <project name>
27+
baseline_commit: <current git SHA>
28+
curated_by: <your name or organization>
29+
---
30+
```
31+
32+
Then:
33+
- Keep all baseline sections and headings.
34+
- Fill **§2 Product Contract** with the project’s current or intended inputs/outputs/contracts.
35+
- Leave **Deferred with Rationale** and **Appendix A** empty or marked *TBD* if the project is new.
36+
37+
## 3. Add a Curation Log Entry
38+
Copy `docs/curation/CURATION_LOG_template.md` to `docs/curation/CURATION_LOG.md` and fill in:
39+
- `project`
40+
- `baseline_version = 0.3`
41+
- `round_date = <today>`
42+
- `status = in-progress`
43+
44+
## 4. Validate the Recipe
45+
Add or verify a CI step that validates the new recipe:
46+
47+
```bash
48+
python -m jsonschema -F frontmatter docs/curation/ai_curator_recipe.schema.json AI_CURATOR_RECIPE.md
49+
```
50+
51+
If the validation fails, fix headings or front-matter until it passes.
52+
53+
## 5. Add Tooling Hooks
54+
- Add Ruff, MyPy, ADR lint, and fast-test hooks as defined in `PROMPT_upgrade_with_tooling.md`.
55+
- Exclude `docs/curation/` from all lint and type checks.
56+
- Ensure `.github/workflows/ci.yml` runs the recipe validation.
57+
58+
## 6. Initialize ADR and Incident Structure
59+
Create the following minimal directories and files:
60+
```
61+
docs/adr/README.md # ADR index
62+
scripts/check_adr_index.py
63+
scripts/lint_adrs.py
64+
```
65+
Optionally create `docs/incidents/` with a placeholder `.gitkeep` file.
66+
67+
## 7. Verify Pre-commit & CI Run
68+
Execute:
69+
```bash
70+
pre-commit run --all-files
71+
pytest -q || echo "No tests yet"
72+
```
73+
Ensure CI passes linting and recipe validation steps.
74+
75+
## 8. Produce Summary Output
76+
Output:
77+
- The generated `AI_CURATOR_RECIPE.md`
78+
- The created `CURATION_LOG.md` entry
79+
- A short bullet list summarizing added scripts, config changes, or deferrals
80+
81+
---
82+
83+
**Goal:** Turn this repository into a baseline-compliant, self-documenting, self-verifying project ready for AI-assisted Software Curatorship.
84+
85+
**After this step:** you can immediately start curating — write ADR-0001 to document the project’s purpose, and use the baseline as the project’s living contract.

0 commit comments

Comments
 (0)