settled-reach/docs/sprints/sprint-5/ci.md

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 5 — CI Briefing	Pre-commit FactId typo check validation hook	sprint	archived	5	ci

Sprint 5: Live — CI Tasks

Goal: Content at scale — FRIEND packs, PC-as-NPC authoring, NPC style guide

Branch: ci Agents: Justine (CI/CD lead)

New Tickets

#	Title	Blocked by
#393	Pre-commit FactId typo check	—

Use db/connectors/ticket show <id> for full details.

Key Decisions

• decisions/content.md — D-035 (tag taxonomy with FactId references)
• decisions/architecture.md — D-030 (testability architecture)

Notes

#393: Pre-commit FactId typo check

What exists:

• Content directory structure at content/
• YAML schema files in content/_schema/
• Canonical facts defined in global knowledge files (check content/global/knowledge/)
• make validate-content CLI from Sprint 4 (#392)
• Pre-commit hooks infrastructure at .config/pre-commit/ or similar

What to deliver:

• Grep-based pre-commit check validating FactId references in YAML content files against canonical facts.yaml
• Cheap v0.1 bridge until full cross-reference validation lands in later sprint
• Should catch typos like npc_identity.kael_davan.occupation vs npc_identity.kael_davan.job before commit

Implementation approach:

1. Extract canonical FactId list from global knowledge YAML files
2. Extract all FactId references from campaign content YAML files
3. Compare: flag any referenced FactId that doesn't exist in canonical list
4. Hook into pre-commit (runs before git commit, fails if violations found)

File location:

• Script: .config/pre-commit/check-fact-ids.sh or tooling/lint/check-fact-ids.py
• Configuration: .pre-commit-config.yaml (if using pre-commit framework) or .git/hooks/pre-commit

Performance constraint: Must run fast (<2 seconds) — content authors will run this on every commit. Grep-based approach should be sufficient for v0.1 scale (~hundreds of facts, ~tens of content files).

Integration: Coordinate with copy team (Mellanie, Paula) on FactId naming conventions. Review content/global/knowledge/entity-attributes.yaml and similar files for canonical fact definitions.

Gotcha: Some FactIds might be templated or dynamic (role-based, not hardcoded). Check with content team on how to handle template slots like {role}.occupation.

Test plan:

1. Create test content file with valid FactId → pre-commit passes
2. Create test content file with typo FactId → pre-commit fails with clear error
3. Fix typo → pre-commit passes

---

Sprint Success Criteria

By end of Sprint 5, CI team delivers:

1. FactId typo check — pre-commit hook operational, tested, documented
2. Integration with content workflow — copy team uses check during FRIEND pack authoring

This is a single-ticket sprint for CI. Goal is content quality assurance — prevent FactId typos from reaching main branch during heavy content authoring sprint.

PR Workflow

When ready to submit, create a PR with tea CLI:

tea pr create \
  --repo jpmschweitzer/settled-reach \
  --login schweitz \
  --title "feat(ci): pre-commit FactId validation" \
  --description "Sprint 5 CI delivery - see docs/sprints/sprint-5/ci.md" \
  --base main \
  --head ci