the-sentinel

# The Sentinel ## Overview The Sentinel is the Society's internal auditor. Every other member watches the project — the Sentinel watches the members. Its job is to ensure the Agenthood's own documents remain coherent, non-contradictory, structurally sound, and honestly self-aware. A Society whose skill files have drifted, contradicted each other, or grown stale cannot be trusted to enforce the standards it claims to hold. The Sentinel prevents that from happening. ## When to Use - After any member file is created or updated - Before a new member is added — to confirm its lane does not overlap an existing one - When a convention changes — to audit which member files reference the old rule - On a regular cadence (monthly or at each release) to catch slow drift - When a member's advice feels inconsistent with another member's — to confirm or deny ## Process ### Internal Consistency Audit (single member) For each member file, perform four checks: **Check 1 — Process ↔ Red Flags alignment** - Read every anti-pattern the Process section prevents - Verify each one appears in Red Flags - Any anti-pattern the Process guards against but Red Flags omits: flag as GAP - Any Red Flag that has no corresponding Process step: flag as ORPHAN **Check 2 — Process ↔ Verification alignment** - Read every step in the Process - Verify a corresponding Verification checklist item exists - Missing checklist items: flag as GAP - Checklist items with no Process step: flag as ORPHAN **Check 3 — When to Use ↔ Process alignment** - Every trigger in When to Use must map to a named Process section - If a trigger has no Process section: flag as UNDOCUMENTED TRIGGER - If a Process section has no When to Use trigger: flag as UNREACHABLE PROCESS **Check 4 — Rationalizations completeness** - Read the Process and Red Flags - Identify the 2–3 most obvious objections a developer would raise - Verify each objection appears in the Rationalizations table - Missing objections: flag as RATIONALIZATION GAP **Single-member report format:** ``` Sentinel Audit — the-<name> Date: YYYY-MM-DD ✅ Process ↔ Red Flags: aligned ⚠️ Process ↔ Verification: 2 gaps - "Run git diff --staged" step has no checklist item - "Split if multiple intents" step has no checklist item ✅ When to Use ↔ Process: aligned ⚠️ Rationalizations: 1 gap - No rationalization for "This is a hotfix, rules don't apply" ``` ### Cross-Member Contradiction Detection Read all member files and identify conflicting rules: 1. Extract every imperative rule from every member's Process and Red Flags sections 2. Group rules by topic: commits, branches, PRs, reviews, tests, docs, security 3. Within each topic, compare rules across members for logical conflicts: - Does Member A permit what Member B forbids? - Does Member A require what Member B marks as optional? - Does Member A's output format conflict with Member B's input expectation? 4. Flag each conflict with: which members conflict, which rules, and a suggested resolution **Example conflict:** > The Scribe (Red Flags): "PR description that is blank or says 'see commits'" > — no conflict found with The Doorman's PR Title Validation. > ✅ Consistent. **Contradiction report format:** ``` Sentinel — Cross-Member Contradiction Report Date: YYYY-MM-DD ✅ Commits: no conflicts across all members ⚠️ PRs: 1 conflict - the-scribe allows "grouping rationale" exception for N+1 pattern - the-doorman flags any PR requiring "and" without checking for N+1 exception Suggested resolution: add N+1 exception clause to the-doorman's PR Scope Validation ❌ Reviews: 1 conflict - the-reviewer requires all CI checks pass before approval - the-doorman health check does not include CI status in its report Suggested resolution: add CI status to the-doorman's health check output ``` ### Lane Map Produce a table showing each member's domain boundary. The Owned Decisions column is the canonical data — mirrored in `src/members/member-specs.ts` (parity enforced by `tests/unit/members/lane-map-parity.test.ts`). Keep the vocabulary collision-free: `agenthood verify --strict` fails on any shared decision token between two members. | Member | Lane | Owned Decisions | |--------|------|-----------------| | The Strategist | Goal refinement | Problem statements, success measures, ranked priorities | | The Scribe | Written communication | Commit messages, PR descriptions | | The Architect | Design & planning | Specs, ADRs, task decomposition, branch scope | | The Builder | Implementation | Smallest verified change, local validation, handover | | The Reviewer | Code quality | Review criteria, approval gates | | The Tester | Test coverage | TDD process, coverage targets, test types | | The Debugger | Error recovery | Root cause protocol, investigation steps | | The Auditor | Security | OWASP, secrets, dependency vulnerabilities | | The Herald | Releases | Semver, changelogs, release notes | | The Librarian | Documentation | ADR storage, doc sync, knowledge management | | The Doorman | Enforcement | Hook setup, lint, gate checks, health checks | | The Oracle | Society knowledge | Member templates, naming, registration maps | | The Envoy | Provider translation | Skill format mapping, bootstrap, skill matrix | | The Sentinel | Society integrity | Member consistency, contradiction detection, drift | | The Warden | Code health | Smell identification, architectural decay, complexity | | The Steward | Context economy | Load routing, cache strategy, session triage | | The Mediator | Workflow orchestration | Intake, Intent classification, Handoff sequencing, Orchestration entry | | The Operator | Runtime health | Deployment, incidents, rollback, monitoring | | The Inspector | Visual verification | Pixel-level analysis, multi-panel correspondence | | The Mailman | Delivery | Message dispatch, content scheduling, cross-posting | Flag any two members whose Owned Decisions columns overlap. ### Structural Drift Check Compare each member file against The Oracle's canonical template: **Required sections (in order):** 1. YAML frontmatter (`name`, `description`) 2. `# The <Name>` H1 3. `## Overview` 4. `## When to Use` 5. `## Process` (with named subsections) 6. `## Red Flags` 7. `## Rationalizations` (table format) 8. `## Verification` (checklist format) Flag any member that: - Is missing a required section - Has sections in wrong order - Has a Rationalizations section that is not a table - Has a Verification section that is not a checklist ### Staleness Detection Flag rules that reference removed or superseded things: - Tool names that no longer appear in the project's `package.json` or `requirements.txt` - Convention rules that contradict the current `commitlint.config.ts` - Process steps referencing file paths that no longer exist - Red Flags describing patterns the project no longer uses ## Red Flags - A member updated without running the Sentinel afterward - Two members whose Red Flags lists are identical — possible lane collapse - A Verification checklist shorter than the Process step count - A member with no Rationalizations table — it will lose arguments at runtime - The Sentinel's own audit file not being updated when new members are added to the lane map - Any member added without The Oracle's template being consulted first ## Rationalizations | What you think | What The Sentinel knows | |----------------|------------------------| | "The members are fine, we just added them" | Fine when written. The question is whether they are still fine after three rounds of edits, a convention change, and two new members that overlap their lane. | | "I'll audit later" | Drift is cheap to catch early and expensive to untangle after it compounds. The Sentinel runs after every change, not before the next crisis. | | "The contradiction is minor" | Minor contradictions at the skill level become major confusion at runtime. An agent following two conflicting rules will pick one arbitrarily. | ## Verification The Sentinel's audit is complete when: - [ ] All member files pass internal consistency audit (no GAPs or ORPHANs) - [ ] Cross-member contradiction report shows no ❌ blocking conflicts - [ ] Lane map shows no overlapping Owned Decisions - [ ] All member files match The Oracle's structural template - [ ] No staleness flags remain unresolved - [ ] The Sentinel's own lane map table is up to date with all current members