Guardrails

This document formalizes guardrails for AI agents and humans working in this repository. It is derived from Agent Context and is the single reference for constraints and conventions that must be respected when editing or adding content.

Purpose

Guardrails ensure:

  • Consistent use of terminology and document structure
  • Correct cross-referencing and single source of truth
  • No secrets in the repo
  • Traceable gap remediation

Domain rules

Rule Description
Work item = Task Work items and tasks are the same entity. A task is a work item with level = Task. Do not treat them as separate concepts in docs or design.
Methodology-agnostic The design does not prescribe agile, waterfall, or any specific methodology. Keep descriptions neutral.

Documentation conventions

1. Gap identifiers

  • Gaps are tracked in 16 — Gap Analysis (TODO) with stable identifiers GAP-001, GAP-002, etc.
  • Reference gaps by id in chat or in other docs (e.g. “address GAP-003”).
  • When a gap is remediated: mark the item with [x] and optionally add a “Resolved: …” note.

2. Gap and remediation format

Each gap is written as a todo so progress can be tracked by toggling the checkbox:

- [ ] **GAP-XXX** — **Title:** Description. *Remediate: …*

When resolved:

- [x] **GAP-XXX** — **Title:** Description. *Remediate: …* Resolved: brief note.

3. Document numbering

  • Design docs use a two-digit prefix (00–16) for ordering and stable filenames.
  • New design docs use the next number (e.g. 17) and must be added to the docs index.

4. Cross-references in docs

  • Links between docs use the built site form with .html extension, because the published site is generated by Jekyll.
  • Example: [03 — Data Model](03-data-model.html).
  • Source files remain .md.

5. Docs index

  • The canonical list of design docs is index.
  • When adding a new doc, add a row to the table with: title, link (.html), and a short description.

6. Single source of truth

Topic Canonical doc
Definitions (terms, SUDO, scope) 00 — Definitions
Data model (entities, schema, PostgreSQL) 03 — Data Model
MCP surface (tools, resources, context) 04 — MCP Surface
Identifiers (GUID, slug, prefixes) 08 — Identifiers

When changing an entity or concept:

  1. Update the canonical doc first.
  2. Update any references in other docs.
  3. If the change closes a gap, update 16 — Gap Analysis (TODO) (mark resolved).

7. No hardcoded secrets

  • Configuration (e.g. OAuth client IDs, database URLs, API keys) is documented as environment variables or config keys only.
  • Never commit secrets, keys, or credentials to the repository.

Summary checklist (for agents)

Before submitting edits:

  • Terminology: work item vs task used correctly; methodology-agnostic wording.
  • Gaps: any new gap has GAP-XXX id and correct format; resolved gaps marked with [x] and optional “Resolved”.
  • New doc: two-digit prefix, added to index with title, .html link, description.
  • Links: inter-doc links use .html form.
  • Canonical docs: entity/concept changes updated in 00, 03, 04, or 08 as appropriate, plus references.
  • No secrets or hardcoded credentials.
  • Agent Context — Workspace description, document list, and how to build/serve docs locally.
  • The repository root may also contain a .cursorrules file that distills these guardrails for Cursor and other agent tooling.