diff --git a/.github/workflows/test-locked.yml b/.github/workflows/test-locked.yml index c42bf24..80fcfa6 100644 --- a/.github/workflows/test-locked.yml +++ b/.github/workflows/test-locked.yml @@ -20,9 +20,28 @@ jobs: python-version: ["3.10", "3.13"] steps: - uses: actions/checkout@v7 + with: + fetch-depth: 0 - uses: actions/setup-python@v7 with: python-version: ${{ matrix.python-version }} + - name: Check out immutable documentation standard + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: wellmanifest/docs + ref: fdb0fcaa7c606dc2503cabb71eff64d5f86ee659 # v0.1.0 + path: .docs-standard + token: ${{ secrets.ORG_SYNC_PAT }} + persist-credentials: false + - name: Validate documentation placement + shell: bash + env: + DOCS_BASE: ${{ github.event.pull_request.base.sha }} + run: | + set -euo pipefail + args=(--root . --standard-revision fdb0fcaa7c606dc2503cabb71eff64d5f86ee659) + if [[ -n "$DOCS_BASE" ]]; then args+=(--base "$DOCS_BASE"); fi + python .docs-standard/docs/standard/check.py "${args[@]}" - run: python -m pip install uv - name: Install locked test dependencies run: uv sync --locked --extra dev --python "${{ matrix.python-version }}" diff --git a/.governance/docs.json b/.governance/docs.json new file mode 100644 index 0000000..965fa67 --- /dev/null +++ b/.governance/docs.json @@ -0,0 +1,7 @@ +{ + "schema": "wellmanifest.docs/adoption/v1", + "repository": "semcod/docval", + "standard": "wellmanifest/docs", + "source_revision": "fdb0fcaa7c606dc2503cabb71eff64d5f86ee659", + "policy_sha256": "affe2ca5700b8225829d110ef704c793e280efae2349751ab7e3f3ef3303126e" +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dc3bb3c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,22 @@ +# Repository agent instructions + + +## Documentation placement + +Before research or writing, identify the owning repository, document kind and canonical path using [wellmanifest/docs 0.1.0](https://github.com/wellmanifest/docs/blob/fdb0fcaa7c606dc2503cabb71eff64d5f86ee659/docs/standard/POLICY.md). Resolve existing documents through the artifact registry when available; update the canonical document instead of creating duplicates. + +- Durable information: `docs/information/.md`. +- Analysis and final reports: `docs/analysis/.md`. +- Refactoring plans: `docs/refactoring/.md`. +- Architecture decisions: `docs/decisions/.md`. +- Index every delivered document in `docs/README.md`. +- Cross-repository results have one owner, `subactor/docs`, under `architecture/{information,analysis,refactoring,decisions}/`, indexed in its root `README.md`. Other repositories link to that source. + +Use the standard's JSON metadata and section templates. Keep stable IDs, increment the declared version when findings change, update dates, bind exact source revisions and evidence, and separate facts, hypotheses and recommendations. Preserve historical append-only versioning. + +A final report or plan must not exist only in `$HOME/.local/state`, `/tmp`, agent session storage, chat or `project/ticket-*`. Tickets contain bounded intent and a link to the canonical result. Raw logs, transcripts, secrets, working databases, backups and Git bundles remain in private ignored recovery storage; publish only safe receipt references and digests when needed. + +Before completion, verify placement, metadata, index links and Git tracking. The final response links to the repository document and states whether it is local, committed, in a PR or merged. Documentation status and session prose never grant execution or merge approval. + +The adoption pin is `.governance/docs.json`. The existing `Locked tests` workflow runs the checker from the immutable standard revision. Validate changed documents and report actual CI results; metadata or prose alone never proves enforcement or grants approval. + diff --git a/README.md b/README.md index e55ed49..eced14d 100644 --- a/README.md +++ b/README.md @@ -208,3 +208,7 @@ _Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 13:37 ## Dependency maintenance See [internal dependency updates](docs/dependencies.md) for daily updates, locked tests and Python support. + +## Documentation ownership + +Follow [agent documentation instructions](AGENTS.md) and maintain the [documentation index](docs/README.md). diff --git a/TODO.md b/TODO.md index 87df496..7ba39e6 100644 --- a/TODO.md +++ b/TODO.md @@ -228,3 +228,5 @@ docval fix docs/ --project . --no-dry-run --- *Generated by docval v0.1.1 on 2026-04-13* + +Documentation deliverables follow [AGENTS.md](AGENTS.md) and the [canonical index](docs/README.md). diff --git a/docs/README.md b/docs/README.md index e4e1274..54b94c9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -268,4 +268,11 @@ pytest | `examples/` | Usage examples | [Browse](./examples) | | `mkdocs.yml` | MkDocs configuration | — | - \ No newline at end of file + +## Documentation ownership and index + +Follow the [repository instructions](../AGENTS.md). New final reports belong in `analysis/`, information in `information/`, refactoring plans in `refactoring/` and decisions in `decisions/`; index each delivered document here. Raw logs and backups remain private. Cross-repository results belong in `subactor/docs`. + +- [Dependency policy](dependencies.md) + +The generated content above retains its historical format; the new documentation profile is not retroactively claimed for it. diff --git a/project/ticket-002/README.md b/project/ticket-002/README.md new file mode 100644 index 0000000..91608d6 --- /dev/null +++ b/project/ticket-002/README.md @@ -0,0 +1,11 @@ +# Ticket 002: Documentation placement + +- **Status**: IN_PROGRESS +- **Workflow state**: PUBLICATION +- **Issue**: https://github.com/semcod/docval/issues/2 + +SESSION_EXECUTION_AUTHORIZATION: user requested updating all repositories to save final documentation in canonical versioned paths. Adopt instructions, an immutable docs pin and the checker in existing tests; preserve generated historical content. Publish through independent Validator. + +Accepted base: 14242e95ea7938a0097f5f5b03697f804e716a45. This repository lacks a managed new-project allocator and manifest; GitHub issue 2 allocated the identity under its legacy process. This work does not claim full new-project adoption. + +Validation: existing pytest suite passed; published docs checker passed pin/index validation (0 profiled historical documents). Existing locked dependency installation and both Python matrix entries are preserved. Managed governance remains absent; no bypass or conformance claim. diff --git a/project/ticket-002/intent.json b/project/ticket-002/intent.json new file mode 100644 index 0000000..d54919c --- /dev/null +++ b/project/ticket-002/intent.json @@ -0,0 +1,24 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-002", + "summary": "Adopt canonical documentation placement and validation", + "workstream": "integration", + "allowedPaths": [ + "AGENTS.md", + "README.md", + "TODO.md", + "docs/README.md", + ".governance/docs.json", + ".github/workflows/test-locked.yml", + "project/ticket-002/**" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md" + ], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null, + "stacks": [ + "python" + ] +}