docs: document HARD GATE archival in Scribe workflow

[diberry]

Documents the HARD GATE archival mechanism in the Scribe workflow — two-tier thresholds, age-based + count-based fallback, and the no-data-loss invariant.

Review

Needs team review (Flight + FIDO).

[diberry]

🧪 FIDO — Quality Review

Checklist

#	Check	Status
1	Test assertions updated (docs-build.test.ts)	✅ Pass
2	Nav slugs match file paths	✅ Pass
3	Internal links — no /docs/\ prefix	❌ BLOCKER
4	Single blank lines only	✅ Pass
5	No .squad/\ files in diff	❌ BLOCKER
6	Docs build	✅ Pass (0 errors)

---

❌ BLOCKER 1 — Internal links use /docs/\ prefix

In \docs/src/content/docs/features/decision-archival.md, the Related pages section (lines ~131–133) uses /docs/\ prefixed links. This convention is explicitly prohibited.

Offending lines:
\\markdown

• Memory system
• Context hygiene
• Memory & Knowledge
  \\

Required fix — strip the /docs\ prefix:
\\markdown

• Memory system
• Context hygiene
• Memory & Knowledge
  \\

---

❌ BLOCKER 2 — .squad/\ file in diff

.squad/agents/pao/history.md\ is included in this PR diff. Squad agent internal files must not travel with feature docs PRs.

Required fix: Remove .squad/agents/pao/history.md\ from this branch/PR. Commit that file separately or omit it entirely from this changeset.

---

✅ Passing notes

• \docs-build.test.ts\ correctly adds \decision-archival\ to \EXPECTED_FEATURES\ and \config-model\ to \EXPECTED_REFERENCE.
• Nav slugs (\eatures/decision-archival,
  eference/config-model) align with the navigation entries.
• No double blank lines detected in the new doc.
• Docs build is clean — zero errors.

---

Verdict: ❌ NEEDS FIXES (2 blockers — fix link prefixes and remove .squad/\ file from diff)

[diberry]

🏗️ Flight — Lead Review

PR: docs: document HARD GATE archival in Scribe workflow (#661)
Author: @diberry
Scope: New feature doc (features/decision-archival.md), nav registration, test coverage, PAO history entry.

---

✅ What's solid

• Placement is correct. features/ alongside memory is the right home for an internal Scribe workflow mechanism — not concepts/, not reference/.
• Content accuracy. Two-tier thresholds (20KB/30-day → 50KB/7-day escalation), count-based fallback, undated-entry invariant, and the PRE-CHECK → ARCHIVE → INBOX MERGE workflow order are all accurate against the source in nap.ts.
• No-data-loss invariant is called out prominently — entries_before = entries_kept + entries_archived. Critical to have this explicit.
• Test coverage. EXPECTED_FEATURES array updated with decision-archival in correct alphabetical position. ✓
• PAO history entry is thorough and captures the key learnings.
• Experimental banner present. ✓

---

🚫 Blockers

1. Link format — /docs/ prefix must be removed

All three links in the Related pages section use the wrong prefix:

# ❌ Current
- [Memory system](/docs/features/memory)
- [Context hygiene](/docs/features/context-hygiene)
- [Memory & Knowledge](/docs/concepts/memory-and-knowledge)

# ✅ Required
- [Memory system](/features/memory)
- [Context hygiene](/features/context-hygiene)
- [Memory & Knowledge](/concepts/memory-and-knowledge)

Slugs in navigation.ts are registered without a /docs/ prefix — the site router resolves from the content root, not from /docs/src/content/docs/. Every other cross-link in the docs site omits the /docs/ segment. These will 404 in production.

---

2. Whitespace — enforce single blank lines throughout

The doc uses --- section dividers correctly, but verify the raw file has no double blank lines anywhere — particularly:

• Between the ### Invariant block and the code fence that follows
• Between the closing ``` of any code block and the next paragraph
• At the end of the file (trailing newlines)

From the diff the spacing looks clean, but the terminal output wraps long lines making it hard to confirm. Author should run cat -A (or equivalent) to verify no \n\n\n sequences exist before merge.

---

3. Table ordering — archiveDecisions() contract table

The contract table rows are not in a consistent logical order. Current order mixes concerns:

Current row	Category
Threshold	Trigger condition
Age-based first	Primary mechanism
Count-based fallback	Secondary mechanism
Undated entries preserved	Invariant/constraint
Atomic writes	Implementation detail
Dry run support	Developer feature (input)
Return value	API contract (output)

The jump from "Atomic writes" (internal implementation) to "Dry run support" (caller-facing option) to "Return value" breaks the flow. Suggested order:

1. Threshold (when does it run?)
2. Age-based first (primary path)
3. Count-based fallback (secondary path)
4. Undated entries preserved (invariant)
5. Dry run support (opt-in input)
6. Return value (output contract)
7. Atomic writes (implementation note — least important to callers, move last)

---

🟡 Minor notes (non-blocking)

• navigation.ts — Config Model entry: A { title: 'Config Model', slug: 'reference/config-model' } entry was added to the Reference section and config-model was added to EXPECTED_REFERENCE in tests, but no docs/src/content/docs/reference/config-model.md file appears in this diff. If the file exists on the branch and was omitted from the diff, fine — but confirm it's there before merge or the test will fail.
• Practical example table: The last two rows (25 KB / all-recent → count-based fallback and 18 KB / undated only → no archival) break the ascending file-size progression of the first three rows. Consider adding a column header note or reordering to group edge cases together.
• archiveDecisions() heading: Uses backtick formatting in an ## heading — verify the site's Markdown renderer handles this without stripping the backticks from the anchor slug.

---

Summary

The content is accurate and the placement decision is sound. Three items must be fixed before merge: the /docs/ link prefix bug (will 404), whitespace verification, and the contract table row ordering. The Config Model file presence should also be confirmed.

Verdict: NEEDS FIXES

[diberry]

FIDO Quality Review — PR #661 (HARD GATE Archival Docs)

Verdict: NEEDS FIXES

Checklist

• ✅ No /docs/ prefix in internal links — links use /features/... and /concepts/... (correct)
• ✅ No double blank lines — single blank lines throughout (house style)
• ✅ No .squad/ files in the diff — only docs, nav, and test files
• ✅ Table ordering is logical — both threshold and example tables flow naturally
• ✅ Frontmatter — no YAML frontmatter (matches existing docs convention; Starlight infers title from H1)
• ✅ Navigation entry for decision-archival matches page path and is correctly placed after Memory
• ✅ Content is accurate — two-tier thresholds, age-based + count-based fallback, no-data-loss invariant are all correctly described
• ✅ No stale references — all three "Related pages" targets exist (features/memory, features/context-hygiene, concepts/memory-and-knowledge)
• ❌ config-model nav entry and test expectation added without corresponding content page (BLOCKER)

Findings

1. BLOCKER — Orphan config-model reference (out-of-scope change)

navigation.ts adds:

{ title: 'Config Model', slug: 'reference/config-model' }

and test/docs-build.test.ts adds 'config-model' to EXPECTED_REFERENCE, but no docs/src/content/docs/reference/config-model.md file exists in this PR or on the current branch. This will produce a dead nav link and likely fail the docs-build test.

Fix: Remove the config-model additions from both navigation.ts and test/docs-build.test.ts in this PR. Ship them with the PR that actually creates the config-model page.

2. NOTE (non-blocking) — Internal link style differs from existing convention

The new page uses absolute-path links:

- [Memory system](/features/memory)

Existing feature docs use relative links:

See [Skills System](skills.md) for details.

Both work in Starlight. Consistency with existing style is preferred, but this is non-blocking.

Summary

The decision-archival.md content itself is well-structured and accurate. The blocker is the stowaway config-model change — a nav entry and test expectation for a page that doesn't exist yet. Remove those two hunks and this PR is ready to approve.

[diberry]

Flight Review — PR #661 (HARD GATE Archival Docs)

Verdict: NEEDS FIXES

Findings

1. BLOCKER — Phantom reference/config-model page (out of scope)
The PR adds { title: 'Config Model', slug: 'reference/config-model' } to navigation.ts (line 90) and adds 'config-model' to EXPECTED_REFERENCE in test/docs-build.test.ts — but no docs/src/content/docs/reference/config-model.md page exists, not on this branch and not on dev. The docs build test will fail looking for a page that doesn't exist. This change is also unrelated to HARD GATE archival docs. Remove both config-model changes from this PR.

2. NOTE — Two-tier vs. single-tier implementation boundary
The doc describes "two-tier thresholds" (Tier 1: 20 KB/30-day, Tier 2: 50 KB/7-day) as a unified archival system. However, archiveDecisions() in nap.ts only implements Tier 1 (20 KB threshold + 30-day age + count-based fallback). Tier 2 (50 KB/7-day) exists only as Scribe charter instructions (agent-level behavior, not SDK code). The "archiveDecisions() contract" table in this doc only covers Tier 1 parameters, creating an internal inconsistency with the "Two-tier thresholds" section above it. Consider adding a sentence clarifying that the Scribe agent orchestrates the two-tier workflow, calling archiveDecisions() for Tier 1 and applying Tier 2 at the agent level per its charter.

3. NOTE — Nav placement is acceptable
"Decision Archival" placed between "Memory" and "Skills" is reasonable — it's a memory-management companion feature. No issue.

Checklist

Criterion	Status
Architecture / structure	✅ Well-structured: problem → mechanism → thresholds → implementation → example
Link format (no /docs/ prefix)	✅ All links correct: /features/memory, /features/context-hygiene, /concepts/memory-and-knowledge
Whitespace (no double blank lines)	✅ Clean — verified programmatically
.squad/ files in diff	✅ None
Table ordering	✅ Logical — tiers by severity, contract by behavior type, examples chronologically
Navigation entry matches page location	✅ features/decision-archival matches docs/src/content/docs/features/decision-archival.md
Content accuracy	⚠️ See findings #1 and #2
Frontmatter	✅ Matches house style (direct # Heading + experimental warning, no YAML frontmatter)
Internal link targets exist	✅ All three referenced pages verified: memory.md, context-hygiene.md, memory-and-knowledge.md
Test expectations	❌ config-model in EXPECTED_REFERENCE will fail — page doesn't exist

Summary

The archival docs page itself is well-written and accurately documents the HARD GATE mechanism. One blocker: the unrelated config-model navigation + test changes must be removed — they reference a non-existent page and will break the build test. After that fix, this is ready to approve.

[diberry]

Flight Re-Review — PR #661 (HARD GATE Archival Docs)

Verdict: ✅ APPROVE

Previous blocker status

RESOLVED. The stowaway config-model hunks in navigation.ts and docs-build.test.ts have been fully removed. The diff now contains only decision-archival changes across 3 files (133 additions, 0 deletions).

Blocker checklist (all pass)

Criterion	Status	Notes
No config-model entries	✅	0 matches in diff — confirmed via grep
decision-archival in nav	✅	Placed after Memory, before Skills — correct conceptual grouping
decision-archival in test	✅	Alphabetically between copilot-coding-agent and directives
Link format (no /docs/ prefix)	✅	All 3 related-page links use bare paths (/features/memory, /features/context-hygiene, /concepts/memory-and-knowledge)
Link targets exist	✅	All 3 target files verified in repo
No double blank lines	✅	Automated check — clean
No .squad/ files	✅	Only docs, nav, test touched
Frontmatter	✅	No YAML frontmatter — matches existing feature docs pattern (memory.md, context-hygiene.md)
Content accuracy	✅	Two-tier thresholds (20 KB/50 KB), age-based + count-based fallback, no-data-loss invariant, correct file paths

New findings

None. Clean diff.

Summary

The previous blocker (stowaway config-model hunks) is fully resolved. All three files are scoped exclusively to decision-archival documentation. Content is accurate, link formats are correct, alphabetical ordering in the test array is maintained, and the navigation placement is sensible. Ship it.

[diberry]

FIDO Re-Review — PR #661 (HARD GATE Archival Docs)

Verdict: ✅ APPROVE

Previous blocker status

Resolved. The stowaway config-model hunks in navigation.ts and docs-build.test.ts have been removed. The diff now contains only decision-archival-related changes across 3 files.

Checklist

#	Check	Result
1	No config-model entries in diff	✅ Verified — zero matches
2	No /docs/ prefix in internal links	✅ Links use /features/... and /concepts/...
3	No double blank lines	✅ Automated scan passed
4	No .squad/ files in diff	✅ Only doc content, nav, and test changed
5	Table ordering logical	✅ Tiers by escalation, contract by workflow, examples by growth stage
6	Frontmatter correct	✅ H1 heading — matches existing convention (e.g., memory.md)
7	Nav entry matches page path	✅ slug: 'features/decision-archival' → docs/src/content/docs/features/decision-archival.md
8	No stale references	✅ All 3 related-page targets exist: memory.md, context-hygiene.md, memory-and-knowledge.md
9	Test entry alphabetical	✅ decision-archival between copilot-coding-agent and directives
10	Nav placement logical	✅ After Memory (related topic), before Skills

Summary

Clean diff — 3 files, all on-topic. The config-model stowaway is gone. Content is well-structured with accurate internal links, correct table ordering, and proper convention adherence. No blockers remain.

🐕 FIDO approves this PR.

[diberry]

Closing -- will re-open via fork-first pipeline when fully polished.