Skip to content

Commit 90bf6f1

Browse files
author
Arturo R Montesinos
committed
chore: instrument repo for software curation v0.3
1 parent 5a5bb53 commit 90bf6f1

File tree

4 files changed

+187
-0
lines changed

4 files changed

+187
-0
lines changed

‎.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/**

‎AI_CURATOR_RECIPE.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
version: 0.3
3+
project: odsview-cli-python
4+
baseline_commit: main
5+
curated_by: arturo
6+
---
7+
8+
# AI Curator Recipe (odsview-cli-python)
9+
10+
> This file customizes the baseline Software Curatorship recipe for this
11+
> repository. Sections not explicitly customized here inherit their meaning
12+
> from `docs/curation/AI_CURATOR_RECIPE_BASELINE_v0.3.md`.
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+
- This project provides a **read-only terminal viewer for `.ods` files** aiming
19+
to work well over SSH and in constrained environments (e.g. Termux).
20+
21+
## 2) Product Contract (plain language) <!-- @curator:required -->
22+
23+
Describe the externally visible behavior of the CLI.
24+
For now, this is aspirational and aligned with `docs/curation/BLUEPRINT.md`.
25+
26+
| Aspect | Description |
27+
|--------|-------------|
28+
| **Inputs** | CLI invocation `odsview <file.ods> [options]` (TBD), filesystem `.ods` files |
29+
| **Outputs/streams** | `stdout` → human-readable table or metadata; `stderr` → diagnostics and error messages |
30+
| **Exit codes** | `0` on success; non-zero for invalid CLI usage, file-not-found, parse errors, and internal failures (exact mapping TBD) |
31+
| **Determinism** | Given the same file, CLI options, and environment, output is deterministic (no randomness; locale and encoding rules to be defined in Appendix A) |
32+
33+
> Appendix A will refine these contracts once the first CLI behavior and
34+
> tests are implemented.
35+
36+
## 3) Curation Principles <!-- @curator:required -->
37+
- AI drafts; human curator approves and is accountable.
38+
- Non-trivial changes: add/update tests and ADRs.
39+
- Prefer stdlib/zero-deps unless ADR justifies otherwise.
40+
- Maintain transparency of reasoning and provenance.
41+
42+
## 4) Repository Map <!-- @curator:required -->
43+
- `docs/curation/` — baseline, prompts, blueprint, and curation log.
44+
- `scripts/` — guardrails (recipe validation, ADR checks, fast tests, etc.).
45+
- `.github/workflows/ci.yml` — CI pipeline (lint, type-check, tests, recipe validation).
46+
- `.pre-commit-config.yaml` — local guardrails.
47+
- Future source and test layout (TBD, likely `src/odsview` and `tests/`).
48+
49+
## 5) ADR Policy <!-- @curator:required -->
50+
- ADRs live under `docs/adr/`.
51+
- Each ADR contains **Context · Decision · Consequences**.
52+
- Status flow: Proposed → Accepted → Superseded.
53+
- `docs/adr/README.md` serves as an index; CI should fail if stale.
54+
55+
## 6) Testing Strategy <!-- @curator:required -->
56+
- Cover CLI contracts (inputs, outputs, exit codes, invariants).
57+
- At least one edge case per new behavior (e.g. empty sheet, large sheet,
58+
invalid file).
59+
- Keep deterministic and fast; network-free.
60+
- Provide a fast subset via `scripts/fast_tests.sh`.
61+
62+
## 7) Automation — Self-Verifying <!-- @curator:required -->
63+
64+
| Stage | Tools | Purpose |
65+
|-------|-------|---------|
66+
| **Local (pre-commit)** | Ruff, mypy, ADR guards, print-guard, fast tests | Prevent regressions early |
67+
| **CI** | Lint → Type → Tests → ADR checks → Recipe validation | Guarantee reproducibility |
68+
69+
Curator docs under `docs/curation/` are validated via `scripts/validate_recipe.py`
70+
but excluded from general lint/type checks.
71+
72+
## 8) Definition of Done <!-- @curator:required -->
73+
- Lint/types/tests/build all green.
74+
- Tests cover new/changed behavior.
75+
- Docs/ADRs updated as needed.
76+
- Provenance intact (licenses and curation docs preserved).
77+
- Packaging/version sanity verified.
78+
79+
## 9) AI Assistant Operating Procedure <!-- @curator:required -->
80+
1. Read repository tree and curator’s current goal.
81+
2. Expand the goal into a small checklist of concrete steps.
82+
3. Propose minimal, focused diffs instead of large rewrites.
83+
4. Propose explicit shell commands using this repo’s scripts and tooling
84+
(e.g. `pre-commit run --all-files`, `bash scripts/fast_tests.sh`,
85+
`python scripts/validate_recipe.py …`) and let the human curator run
86+
them in the terminal.
87+
5. Iterate until checks are green or clearly mark any deferrals.
88+
6. Summarize changes (Done/Deferred) and reference ADRs where applicable.
89+
7. Keep attribution; never remove license/provenance.
90+
91+
## 10) Releases & Versioning <!-- @curator:required -->
92+
- Use Semantic Versioning once the CLI is public.
93+
- Define a single source of truth for the version (e.g. `__version__` in
94+
the package module or `pyproject.toml`).
95+
- Tag releases as `vX.Y.Z`; require green CI for tags.
96+
- Maintain lightweight release notes and/or changelog when appropriate.
97+
98+
## 11) Maintenance Rhythm <!-- @curator:optional -->
99+
- Periodically run `pre-commit run --all-files`.
100+
- Review README and `BLUEPRINT.md` for accuracy versus implemented behavior.
101+
- Perform ADR housekeeping (index, statuses, superseded links).
102+
- Review automation scripts and CI for drift.
103+
104+
## Deferred with Rationale <!-- @curator:required -->
105+
- Detailed CLI option and exit code matrix — will be specified in Appendix A
106+
once the first CLI implementation is in place.
107+
- Determinism guarantees for locale/encoding — to be documented alongside the
108+
first end-to-end tests.
109+
110+
## Appendix A — Project-Specific Contracts <!-- @curator:required -->
111+
- **CLI entrypoint**: TBD (likely `odsview` console script).
112+
- **Inputs**: `.ods` file path; optional flags for sheet selection,
113+
max rows, and display options (to be formalized).
114+
- **Outputs**: Human-readable table on `stdout` with truncation rules for
115+
very wide or long sheets.
116+
- **Invariants**:
117+
- Never mutates the source file.
118+
- Fails fast and clearly on unreadable or unsupported files.
119+
- Avoids interactive prompts by default (suitable for automation).
120+
121+
These contracts will be refined and linked to concrete tests and ADRs as the
122+
implementation emerges.

‎docs/adr/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Architecture Decision Records (ADR)
2+
3+
This directory contains Architecture Decision Records for the
4+
`odsview-cli-python` project. ADRs capture **why** significant decisions
5+
were made, not just **what** was implemented.
6+
7+
## Index
8+
9+
> Maintained by tooling (e.g. `scripts/check_adr_index.py`).
10+
> Each entry should be updated whenever ADRs are added or statuses change.
11+
12+
- _No ADRs recorded yet._

‎docs/curation/CURATION_LOG.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Curation Log (odsview-cli-python)
2+
3+
| Field | Description |
4+
|-------|-------------|
5+
| **project** | odsview-cli-python |
6+
| **baseline_version** | 0.3 |
7+
| **curator** | arturo |
8+
| **round_date** | 2025-12-07 |
9+
| **copilot_model** | GitHub Copilot Chat GPT-5.1 (Preview) |
10+
| **status** | in-progress |
11+
12+
---
13+
14+
## Summary
15+
Instrument the `odsview-cli-python` repository for Software Curatorship using
16+
`docs/curation/AI_CURATOR_RECIPE_BASELINE_v0.3.md` and associated prompts.
17+
18+
## Key Decisions
19+
- Initialized `AI_CURATOR_RECIPE.md` based on the v0.3 baseline and the
20+
project blueprint.
21+
- Adopted the curator-seed testing and automation strategy (pre-commit,
22+
CI validation, recipe validation script).
23+
24+
## AI/Curator Interaction Notes
25+
- Used `PROMPT_instrument_curator_project.md` as the primary guide.
26+
- Copilot proposed initial contents for `AI_CURATOR_RECIPE.md` and
27+
`CURATION_LOG.md`; human curator to review, edit, and approve.
28+
29+
## Artifacts Produced
30+
- `AI_CURATOR_RECIPE.md` at repository root.
31+
- `docs/curation/CURATION_LOG.md` (this file).
32+
33+
## Verification
34+
- [ ] Pre-commit passed
35+
- [ ] CI green
36+
- [ ] ADR index updated
37+
- [ ] README verified
38+
39+
## Follow-ups / Deferrals
40+
- Populate Appendix A of `AI_CURATOR_RECIPE.md` with concrete CLI contracts
41+
once the first implementation and tests exist.
42+
- Initialize `docs/adr/` with ADR-0001 describing project purpose and scope.

0 commit comments

Comments
 (0)