From 2ac51b869018f6ea919f4ee3620c5269e98b3968 Mon Sep 17 00:00:00 2001 From: Tom Softreck Date: Sat, 5 Sep 2026 23:15:40 +0200 Subject: [PATCH] [ticket-009] docs: adopt canonical placement and validation --- .github/workflows/verify.yml | 19 +++++++++++++++++++ .governance/docs.json | 7 +++++++ AGENTS.md | 22 ++++++++++++++++++++++ README.md | 4 ++++ TODO.md | 2 ++ docs/README.md | 14 ++++++++++++++ project/ticket-009/README.md | 15 +++++++++++++++ project/ticket-009/intent.json | 30 ++++++++++++++++++++++++++++++ 8 files changed, 113 insertions(+) create mode 100644 .governance/docs.json create mode 100644 AGENTS.md create mode 100644 docs/README.md create mode 100644 project/ticket-009/README.md create mode 100644 project/ticket-009/intent.json diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index 676e948..2699e30 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -15,10 +15,29 @@ jobs: timeout-minutes: 10 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.12" cache: pip + - 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[@]}" - name: Install test dependencies run: python -m pip install --disable-pip-version-check -e '.[dev]' - name: Run unit tests diff --git a/.governance/docs.json b/.governance/docs.json new file mode 100644 index 0000000..d94224d --- /dev/null +++ b/.governance/docs.json @@ -0,0 +1,7 @@ +{ + "schema": "wellmanifest.docs/adoption/v1", + "repository": "semcod/mcp", + "standard": "wellmanifest/docs", + "source_revision": "fdb0fcaa7c606dc2503cabb71eff64d5f86ee659", + "policy_sha256": "affe2ca5700b8225829d110ef704c793e280efae2349751ab7e3f3ef3303126e" +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3ac047a --- /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 `verify` 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 66acbda..a654235 100644 --- a/README.md +++ b/README.md @@ -660,3 +660,7 @@ Zobacz plik LICENSE. ## License Licensed under Apache-2.0. + +## Documentation ownership + +Follow [repository documentation instructions](AGENTS.md) and use the [documentation index](docs/README.md). The immutable adoption pin is `.governance/docs.json`; the existing `verify` job checks documentation placement and structure. diff --git a/TODO.md b/TODO.md index 7cbbecf..70dd31a 100644 --- a/TODO.md +++ b/TODO.md @@ -1,5 +1,7 @@ # TODO +Before research or writing, follow [documentation placement](AGENTS.md) and index final results in [docs/README.md](docs/README.md). + **Generated by:** prefact v0.1.56 **Generated on:** 2026-05-03T22:01:45.084267 **Total issues:** 128 active, 28 completed diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..59988d8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# MCP documentation + +Before writing information, reports or plans, follow the [repository documentation instructions](../AGENTS.md). + +## Existing documentation + +- [CHAT_PLAYBOOKS](CHAT_PLAYBOOKS.md) +- [ENV2MCP](ENV2MCP.md) +- [IDE_AND_AGENT_INTEGRATION](IDE_AND_AGENT_INTEGRATION.md) +- [LINKED_EXAMPLES](LINKED_EXAMPLES.md) +- [PRODUCT](PRODUCT.md) +- [SEMCOD_MCP_CLI](SEMCOD_MCP_CLI.md) +- [USAGE](USAGE.md) +- [USE_CASES](USE_CASES.md) diff --git a/project/ticket-009/README.md b/project/ticket-009/README.md new file mode 100644 index 0000000..880f87c --- /dev/null +++ b/project/ticket-009/README.md @@ -0,0 +1,15 @@ +# Ticket 009: Documentation placement and validation + +- **Status**: IN_PROGRESS +- **Workflow state**: PUBLICATION +- **Issue**: https://github.com/semcod/mcp/issues/9 + +SESSION_EXECUTION_AUTHORIZATION: user requested updating all repositories so durable reports and plans are stored correctly and continuing versioned publication. Add immutable wellmanifest/docs 0.1.0 adoption, root agent guidance, a documentation index and checker wiring in the existing verify job. Preserve runtime, historical documents and private recovery data. + +Identity comes from GitHub issue #9; this repository has no managed new-project allocator or manifest. This gap is recorded, not presented as full governance adoption. + +- AC-01: Reports, plans and information resolve to canonical repository paths before writing. +- AC-02: The published checker accepts the tracked pin and index; existing verify checks remain. +- AC-03: Existing tests and applicable configuration checks pass before independent exact-head Validator approval. + +Validation: published docs checker passes (tracked adoption and index; no migrated profile documents); pytest, shell syntax and Compose validation pass. Existing CI checks remain. The private standard checkout uses the existing organization-provided ORG_SYNC_PAT only for the fixed reviewed repository/revision, with credential persistence disabled; no secret contents were accessed. Full managed new-project governance is absent in this legacy repository. diff --git a/project/ticket-009/intent.json b/project/ticket-009/intent.json new file mode 100644 index 0000000..d61c2f5 --- /dev/null +++ b/project/ticket-009/intent.json @@ -0,0 +1,30 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-009", + "summary": "Adopt published documentation placement and validation", + "workstream": "integration", + "classification": { + "kind": "SERVICE", + "priority": "P1", + "origin": "requested" + }, + "allowedPaths": [ + "AGENTS.md", + "README.md", + "TODO.md", + "docs/README.md", + ".governance/docs.json", + ".github/workflows/verify.yml", + "project/ticket-009/**" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md", + ".env" + ], + "stacks": [ + "python" + ], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null +}