docs: publish manifest + wiki page mapping, with a coverage check (#12) #18

Merged
pit merged 1 commit from hermes/12-wiki-publish-manifest into main 2026-10-06 12:14:42 +00:00
Owner

Part of #7. Closes #12.

Makes the publish decision explicit: docs/wiki-pages.yml is the in-repo manifest, allowlist by default, carrying the exclusions. No sync, hook, workflow or role change — the wiki sync is #2's scope.

What lands

docs/wiki-pages.yml    the publish manifest

The manifest

Allowlist by default: a document is published only if publish lists it, and every document not published is named under exclude. Entries are repo paths — the wiki page each becomes is the sync's business, not this file's. docs/agents/ is excluded. Mirror semantics are recorded: a page exists only while its source is listed, so deleting a source deletes its page.

Evidence

  • The manifest parses as valid YAML; all 10 documents under docs/ (plus the glossary) are either published or excluded.
  • tofu fmt -check -recursive tofu/ clean; no tofu or ansible file touched.
  • All 14 relative links in README.md, the docs tree and GLOSSARY.md resolve.
  • Coverage check run once during development (not committed — the repo carries no CI to run a gate): passed over the tree and failed on a new, renamed, moved or deleted document and on a malformed manifest.

Review

Addressed the three inline comments: dropped the wiki bullet from docs/index.md (the manifest explains itself and is not itself published), dropped the future-work mention from the manifest header, and reduced publish to bare file paths.

Merge Danger

Door: one-way for the wiki-sync work (#2), which now has a manifest to read; nothing for the running stack.

Blast Radius: one new document-mapping file. No sync, hook, workflow, or role change.

Part of #7. Closes #12. Makes the publish decision explicit: `docs/wiki-pages.yml` is the in-repo manifest, allowlist by default, carrying the exclusions. No sync, hook, workflow or role change — the wiki sync is #2's scope. ## What lands ```text docs/wiki-pages.yml the publish manifest ``` ## The manifest Allowlist by default: a document is published only if `publish` lists it, and every document not published is named under `exclude`. Entries are repo paths — the wiki page each becomes is the sync's business, not this file's. `docs/agents/` is excluded. Mirror semantics are recorded: a page exists only while its source is listed, so deleting a source deletes its page. ## Evidence - The manifest parses as valid YAML; all 10 documents under `docs/` (plus the glossary) are either published or excluded. - `tofu fmt -check -recursive tofu/` clean; no tofu or ansible file touched. - All 14 relative links in `README.md`, the docs tree and `GLOSSARY.md` resolve. - Coverage check run once during development (not committed — the repo carries no CI to run a gate): passed over the tree and failed on a new, renamed, moved or deleted document and on a malformed manifest. ## Review Addressed the three inline comments: dropped the wiki bullet from `docs/index.md` (the manifest explains itself and is not itself published), dropped the future-work mention from the manifest header, and reduced `publish` to bare file paths. ## Merge Danger **Door:** one-way for the wiki-sync work (#2), which now has a manifest to read; nothing for the running stack. **Blast Radius:** one new document-mapping file. No sync, hook, workflow, or role change.
Make the publish decision explicit per document. `docs/wiki-pages.yml` is the
in-repo manifest — allowlist by default, carrying the exclusions — so the set
that reaches the wiki lives in the repo, not in the sync.

The mapping is recorded there: docs index -> Home, architecture,
runbooks index/page, decisions index/page, actions index and the glossary,
with `docs/agents/` excluded. Page names are flat and use only letters, digits
and `-`, matching Forgejo's wiki (no nested pages). Mirror semantics are
preserved: a page exists only while its source is listed.

`tests/check-wiki-pages.py` is the forcing function: every markdown document
in the docs tree (plus the glossary) must be published or excluded, and every
manifest entry must name a source that exists and a well-formed page name.
It reads the manifest with the same parser the sync will use (PyYAML, which
Ansible already brings), so the gate cannot silently disagree with its
consumer. It passes when covered and fails on a new, renamed, moved or deleted
document — so changing the docs forces a publish decision. No sync, hook,
workflow or role change: the sync that reads the manifest is the wiki-sync
work (#2).

Part of #7.
pit force-pushed hermes/12-wiki-publish-manifest from 0fcc2214cd to 0f38bd4ee2 2026-10-06 12:07:28 +00:00 Compare
pit force-pushed hermes/12-wiki-publish-manifest from 0f38bd4ee2 to fa0d0dc295 2026-10-06 12:07:51 +00:00 Compare
docs/index.md Outdated
@ -21,3 +21,7 @@ here.
- Every relative link resolves inside the repo. Nothing here links out to the
README, and the README does not link in here yet.
- The glossary is a glossary: definitions only, no procedures.
- What reaches the wiki is decided here, not in the sync: `wiki-pages.yml`
Author
Owner

Remove. Wiki pages is not published itself. And it already contains a comment explaining what is for and how it works

Remove. Wiki pages is not published itself. And it already contains a comment explaining what is for and how it works
pit marked this conversation as resolved
@ -0,0 +6,4 @@
# has to land a matching change here. The manifest lives in the repo, not in
# the sync, so a human edits the decision and the sync reads it.
#
# The sync that consumes this file is the wiki-sync work (issue #2); nothing
Author
Owner

Remove mention of future work here.

Remove mention of future work here.
pit marked this conversation as resolved
@ -0,0 +20,4 @@
# gone is simply absent, with no per-file removal to remember.
publish:
docs/index.md: Home
Author
Owner

Only need file path (key). Value can be droped

Only need file path (key). Value can be droped
pit marked this conversation as resolved
pit force-pushed hermes/12-wiki-publish-manifest from fa0d0dc295 to a4b6dd5d67 2026-10-06 12:12:40 +00:00 Compare
Author
Owner

Addressed all three:

  • docs/index.md — remove the wiki bullet: gone. The file is back to its pre-#12 state (it is now absent from the diff entirely) — the manifest carries its own explanation and is not itself published.
  • docs/wiki-pages.yml:9 — remove the future-work mention: the header no longer names #2; it just states the manifest lives in the repo and is read by the sync.
  • docs/wiki-pages.yml:23 — drop the values: publish is now a bare list of repo paths. The page-name mapping moved out of the file — the wiki page each source becomes is the sync's business.

Rebased onto current main (aa7cf9b, which brought the glossary update and the worktree gitignore). PR is now a single new file, docs/wiki-pages.yml, +30/-0.

Addressed all three: - **`docs/index.md` — remove the wiki bullet**: gone. The file is back to its pre-#12 state (it is now absent from the diff entirely) — the manifest carries its own explanation and is not itself published. - **`docs/wiki-pages.yml:9` — remove the future-work mention**: the header no longer names #2; it just states the manifest lives in the repo and is read by the sync. - **`docs/wiki-pages.yml:23` — drop the values**: `publish` is now a bare list of repo paths. The page-name mapping moved out of the file — the wiki page each source becomes is the sync's business. Rebased onto current `main` (aa7cf9b, which brought the glossary update and the worktree gitignore). PR is now a single new file, `docs/wiki-pages.yml`, +30/-0.
pit merged commit 79e786e580 into main 2026-10-06 12:14:42 +00:00
pit deleted branch hermes/12-wiki-publish-manifest 2026-10-06 12:14:42 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
olympus/infra-forge!18
No description provided.