fix: harden Claude wiki build validation

Author: kushagrchitkar

src/codealmanac/integrations/harnesses/claude/client.py

@@ -42,7 +42,7 @@
 from codealmanac.services.harnesses.requests import RunHarnessRequest
 
 CLAUDE_COMMAND = "claude"
-CLAUDE_RUN_TIMEOUT_SECONDS = 900
+CLAUDE_RUN_TIMEOUT_SECONDS = 90 * 60
 CLAUDE_ALLOWED_TOOLS = (
     "Read",
     "Write",
@@ -52,6 +52,7 @@
     "Grep",
     "LS",
     "Bash",
+    "Agent",
 )
 CLAUDE_MAX_TURNS = 100
 

src/codealmanac/manual/evidence.md

@@ -13,6 +13,15 @@ Every durable claim should be supported by a named source. Use frontmatter
 `sources:` entries for the materials that support the page, then cite
 non-obvious claims inline with `[@source-id]`.
 
+The `sources:` entries in frontmatter are the materials actually used and cited
+in the article. They are not inspiration, research notes, or a list of files
+that helped you understand the subject. If a source is not cited in the article
+with `[@source-id]`, it does not belong in `sources:`.
+
+Before finishing a page, compare every `sources:` id against the body. If an id
+is not cited with `[@source-id]`, either cite it next to the claim it supports
+or remove it.
+
 A page with factual code, architecture, product, workflow, or decision claims
 but no inline citations is suspect. Navigation pages and manual pages can be
 lighter when they do not make those claims.
@@ -33,6 +42,9 @@ Use precise file sources when source code supports the claim. The source entry
 should point to the file, directory, commit, PR, issue, transcript, manual page,
 or web page that would help a maintainer verify the claim.
 
+Directory source paths must end with `/`, for example `src/api/v1/`. Without the
+trailing slash, the validator treats the path as a file.
+
 When evidence conflicts, state the conflict plainly or defer the claim. Do not
 turn a transcript, diff, or note into source of truth for behavior the code
 contradicts.

src/codealmanac/manual/how-to-write.md

@@ -110,3 +110,8 @@ Most pages should include enough connective tissue to orient the reader:
 
 These are page shapes, not mandatory headings. Use the shape when it helps the
 reader.
+
+## Frontmatter
+
+Quote any frontmatter string that contains `:`, `"`, `'`, `[`, `]`, `{`, or
+`}`. When unsure, quote `title:` and `summary:` values.

src/codealmanac/manual/links.md

@@ -26,6 +26,15 @@ inside the same documentation neighborhood:
 [Page format](../reference/page-format)
 ```
 
+Markdown links should point to actual wiki pages, not folders. Folders are only
+for organizing page files. If no page exists for a subject, mention it as plain
+text instead of linking it.
+
+Do not link to `README` in Markdown links. A folder README is addressed by the
+folder route, such as `architecture`, not `architecture/README`.
+
+Use kebab-case page routes. Do not invent underscore slugs.
+
 Only link real targets. Do not leave placeholder links in finished pages. If a
 subject is useful but does not yet deserve a page, mention it as plain text.
 

src/codealmanac/prompts/operations/build.md

@@ -25,6 +25,20 @@ Make a coverage map before writing pages. Write it to
 `almanac/coverage-map.md`, then treat it as the contract for the rest of the
 run.
 
+Write `coverage-map.md` with valid page frontmatter:
+
+```yaml
+---
+title: Coverage Map
+summary: Frozen page inventory for this first wiki build.
+topics: [build, wiki, reference]
+sources: []
+---
+```
+
+Even though `coverage-map.md` is working state, it lives under `almanac/` and
+must pass normal page validation.
+
 Write `coverage-map.md` with one main section:
 
 ## Page Inventory
@@ -138,9 +152,29 @@ For each writing sub-agent, provide:
 - the evidence files listed for those pages
 - the planned links to nearby pages
 
+Do not summarize, paraphrase, or compress the manual guidance when prompting
+writing sub-agents. Include the relevant manual text directly in the sub-agent
+prompt, including `how-to-write.md`, `evidence.md`, `links.md`, and every
+folder-specific manual needed for that batch.
+
+Every writing sub-agent prompt must include the exact source frontmatter shape:
+
+```yaml
+sources:
+  - id: source-id
+    type: file
+    path: path/to/file.py
+```
+
+Use `type`, not `kind`. Directory evidence is still `type: file`; mark it with a
+trailing slash in `path`.
+
 When a batch contains pages from different folders, include every relevant
 folder-specific manual in the sub-agent prompt.
 
+A writing batch is not fully assigned until its sub-agent prompt includes the
+full manual packet and the exact source schema example.
+
 The sub-agent's task is to write encyclopedia-quality articles about this
 codebase. Each page should feel like a focused Wikipedia article for one
 codebase subject: it should define the subject, explain why it exists here, show
@@ -175,9 +209,10 @@ Use simple, direct prose. Avoid jargon when plain language works. Structure
 sections so each page has a clear through line and later sections build on
 earlier sections without simply repeating them.
 
-Use inline citations for non-obvious claims. Use Markdown links for related
-wiki pages. Put relevant files and folders in `sources:` frontmatter entries
-with `type: file`.
+Use inline citations for non-obvious claims. Put only cited evidence in
+`sources:` frontmatter entries. Do not use `sources:` as a context list or
+bibliography. Every `sources:` entry must be cited in the page body with
+`[@source-id]`, or removed. Directory source paths must end with `/`.
 
 Assign `almanac/getting-started.md` to a writing sub-agent as the front door to
 the finished wiki. If it is drafted early, send it back to a writing or repair
@@ -202,6 +237,10 @@ missing citations, missing links between related pages, duplicate or overlapping
 explanations, terminology drift, or wrong folder placement, dispatch repair
 sub-agents with the exact pages and changes needed.
 
+Run `codealmanac validate` before committing. If validation fails, do not commit.
+Fix validation issues first, rerun validation, and commit only after validation
+passes.
+
 Before stopping, make sure every missing planned page has an exact
 repo-evidence removal reason in `coverage-map.md`, or write the missing page.
 

tests/test_claude_adapter.py

@@ -286,6 +286,7 @@ def test_claude_sdk_client_maps_typed_message_stream(tmp_path: Path):
     assert options.mcp_servers == {}
     assert options.tools == list(CLAUDE_ALLOWED_TOOLS)
     assert options.allowed_tools == list(CLAUDE_ALLOWED_TOOLS)
+    assert "Agent" in options.allowed_tools
 
 
 def test_claude_sdk_client_maps_result_failure(tmp_path: Path):