Author the agent guide content

The v5 guide prose, verified two ways. A scripted walkthrough gave a
fresh agent nothing but the guide and a demo board: it created a card
(fresh lowercase UUID, correct bottom rank), moved one to a lane top
with modified and modified-by re-stamped, deleted one into .trash/,
attached a file into attachments/, picked `fern` off the palette table,
and quoted a colon title — and the resulting board loads through
BoardLoader with zero warnings. The walkthrough's one finding is fixed:
the trash-arrival rule now reads formulaically ("smallest order minus
1024") instead of the spatially ambiguous "below the smallest order".

Content drift-guards join the suite: every palette name the app resolves
must appear in the guide (a Palette rename now fails a test instead of
teaching agents dead colors), the rewrite's conventions are present by
name (.trash/, attachments/, modified-by, CLAUDE.user.md, the
stage-only-your-own-paths rule), and the pathfinder's retired vocabulary
(media/, tombstones) cannot resurface — the only deleted: mention is the
warning never to write it.

Claude-Session: https://claude.ai/code/session_01SR4XGjmBE16ZUYWpfFHXwY
This commit is contained in:
2026-07-28 22:03:38 -04:00
parent b3812ed928
commit 7ba90a8cc9
2 changed files with 48 additions and 3 deletions
+45
View File
@@ -568,3 +568,48 @@ struct AgentGuideRegistryTests {
#expect(store.reloadFailure == nil)
}
}
// MARK: - 5. The content
/// What the guide *says*, pinned where saying it wrong would mislead every agent that reads it
/// the authoring card's contract (08-agent-integration.md The agent guide's list): the schema it
/// condenses is 01-storage-format.md's, post-pivot, and the vocabulary it teaches must be the
/// app's own.
@Suite("Agent guide ▸ the content")
struct AgentGuideContentTests {
/// The palette tables are transcribed prose, and transcriptions drift. Tying every name to
/// `Palette`'s own tables makes a palette rename a failing guide test rather than a silently
/// wrong document teaching agents colors the app no longer resolves.
@Test("Every palette name the app resolves appears in the guide")
func paletteNamesMatchTheSource() {
for color in Palette.foregrounds + Palette.backgrounds {
#expect(AgentGuide.content.contains("`\(color.name)`"), "missing palette name: \(color.name)")
}
}
@Test("The guide teaches the current conventions by name")
func currentVocabularyIsPresent() {
let content = AgentGuide.content
// The rewrite's list, 08 The agent guide: attachments, the trash, self-stamping, the
// user extension point, staging etiquette each findable by the string an agent would
// grep for.
#expect(content.contains(".trash/"))
#expect(content.contains("attachments/"))
#expect(content.contains("modified-by"))
#expect(content.contains("CLAUDE.user.md"))
#expect(content.contains("git add -A"))
#expect(content.contains("schema: 1"))
}
/// The pathfinder's guide taught `media/` and tombstone deletes; both are retired
/// (01-storage-format.md Changes from the pathfinder schema; Deletion). The one legitimate
/// mention of `deleted:` is the warning never to write it.
@Test("Retired vocabulary does not resurface")
func retiredVocabularyIsAbsent() {
let content = AgentGuide.content
#expect(!content.contains("media/"))
#expect(!content.contains("tombstone"))
#expect(content.contains("Never write a `deleted:` key"))
}
}