SENAR Reference: Tooling Requirements

This document specifies what tooling must support for each SENAR component. Requirements are split into two tiers:

  • Core/Foundation — minimum for SENAR Core (1 Pair) and Foundation (1-3 Pairs) configurations, Maturity Level 2
  • Team+ — full requirements for SENAR Team and Enterprise configurations (3+ Pairs, Maturity Level 3+)

SENAR is tool-agnostic by design. These are capability requirements, not product recommendations.

1. Task Tracker

The task tracker is the system of record for all units of work. Every Task, Story, and Increment lives here.

1.1 Required Fields

FieldTypeCore/FoundationTeam+Notes
goalTextSHALLSHALLWhat the Task must accomplish, stated as an outcome
acceptance_criteriaTextSHALLSHALLVerifiable conditions for Task completion
statusEnumSHALLSHALLMinimum states: planning, active, done, blocked
work_typeEnumSHALLSHALLValues: dev, arch, qa, docs, infra, ops
complexityEnumSHOULDSHALLValues: trivial, simple, moderate, complex
story_idReferenceSHOULDSHALLLink to parent Story or requirement
requirement_linkReferenceSHOULDSHALLTraceability link to BR/SR/TR (Standard 3.21)
requirement_levelEnum—SHALLValues: BR, SR, TR — level of the linked requirement
requirement_statusEnum—SHALLValues: draft, approved, verified, deprecated
requirement_parentReference—SHALLLink to parent requirement (for hierarchy navigation)
attempt_countIntegerSHOULDSHALLNumber of implementation attempts (for FPSR calculation)
created_atTimestampSHALLSHALLAuto-set on creation
started_atTimestampSHALLSHALLAuto-set on transition to active
completed_atTimestampSHALLSHALLAuto-set on transition to done
session_idReferenceSHALLSHALLWhich Session completed this Task
supervisor_idReference—SHALLWho supervised this Task
bypass_reasonTextSHOULDSHALLJustification if any Quality Gate was bypassed
knowledge_refsList—SHOULDLinks to relevant Knowledge Base entries
cross_depsList—SHALLCross-project dependency references
costNumeric—SHOULDToken/API cost for this Task

1.2 Required Automations

AutomationCore/FoundationTeam+Description
QG-0 field validationSHALLSHALLBlock transition to active unless goal and acceptance_criteria are non-empty
State transition timestampsSHALLSHALLAuto-capture started_at, completed_at on state change
State transition rulesSHOULDSHALLEnforce valid transitions: planning -> active -> done; blocked can enter/exit from any state
Attempt counter incrementSHOULDSHALLIncrement attempt_count each time Task returns from done to active
Story completion roll-up—SHALLAuto-calculate Story status from child Task statuses
Increment progress tracking—SHALLDashboard showing Increment completion percentage
Bypass trackingSHOULDSHALLRecord which gate was bypassed, by whom, with what justification
Duplicate detection—SHOULDWarn when a new Task goal closely matches an existing Task
Requirement orphan detection—SHOULDIdentify requirements without implementation Tasks and Tasks without requirements
Requirement change impact—SHOULDWhen a BR/SR changes, list all affected downstream artifacts

1.3 Required Reports

ReportCore/FoundationTeam+Description
ThroughputSHALLSHALLTasks completed per Session, with trend over time
Lead Time distributionSHALLSHALLHistogram of completed_at - created_at, segmented by complexity
FPSRSHALLSHALL% of Tasks completed with attempt_count = 1
DERSHALLSHALL% of Tasks where defects found after done status
Task status summarySHALLSHALLCount of Tasks by status, filterable by Increment/Session
Cycle Time—SHALLcompleted_at - started_at distribution
Cost per Task—SHALLTotal cost / Tasks done, segmented by complexity and work type
Cost Predictability—SHALLActual vs. planned cost per Increment
Bypass rate—SHALLGate bypasses / total gate evaluations, by gate type
Supervisor workload—SHOULDTasks per Supervisor per Session, with complexity weighting
Cross-dependency status—SHALLStatus of all cross-project dependencies

2. CI/CD Pipeline

Automated enforcement of QG-2 (Implementation Gate) and supporting infrastructure for QG-3 and QG-4.

2.1 QG-2: Implementation Gate (Automated)

All checks run on every commit or merge request. Pipeline must block merge if any check fails.

CheckCore/FoundationTeam+Notes
Unit tests passSHALLSHALL100% pass rate required
Type checking passesSHALLSHALLLanguage-appropriate: TypeScript strict, mypy, etc.
Linter passesSHALLSHALLZero warnings policy (not just errors)
Security scan (dependencies)SHOULDSHALLKnown CVE detection in dependencies
Security scan (SAST)—SHOULDStatic analysis for security anti-patterns
Build succeedsSHALLSHALLClean build from scratch, no cached state
Test coverage thresholdSHOULDSHALLConfigurable minimum (recommendation: 70%+)
Dependency change detection—SHOULDFlag new dependencies for review
Breaking change detection—SHOULDAPI compatibility checks for shared interfaces

Pipeline configuration requirements:

RequirementCore/FoundationTeam+
Pipeline runs automatically on push/MRSHALLSHALL
Pipeline blocks merge on failureSHALLSHALL
Pipeline results visible to SupervisorSHALLSHALL
No allow_failure — every job either works or is removedSHALLSHALL
Pipeline execution time < 10 minutesSHOULDSHALL
Pipeline provides clear failure messagesSHALLSHALL
Pipeline is version-controlled (pipeline-as-code)SHOULDSHALL

2.2 QG-3: Verification Gate (Review)

RequirementCore/FoundationTeam+Notes
Branch protection on main/production branches—SHALLNo direct push
Merge request required—SHALLAll changes go through MR
Minimum 1 approval required—SHALLApprover must be different from the Supervisor who created the MR
Review checklist integration—SHOULDAI Review Checklist (Guide 02) embedded in MR template
Approval cannot be from the MR author—SHALLEnforce independent verification
Stale approval invalidation—SHOULDRe-approve after new commits

2.3 QG-4: Acceptance Gate (Deployment)

RequirementCore/FoundationTeam+Notes
Staging environment exists—SHALLMirrors production configuration
Staging deployment is automated—SHALLSame pipeline as production, different target
Staging verification step—SHALLManual or automated acceptance test on staging
Production deployment requires explicit approval—SHALLHuman gate — not auto-deploy on merge
Rollback capability—SHALLAbility to revert to previous version within minutes
Deployment tracking—SHALLRecord what was deployed, when, by whom
Smoke tests post-deployment—SHOULDAutomated verification that deployment succeeded
Feature flags—SHOULDAbility to disable features without redeployment

3. Knowledge Base

The Knowledge Base is the persistent memory of the project. AI Agents have no memory between sessions — the KB is how knowledge survives.

3.1 Core Requirements

RequirementCore/FoundationTeam+Notes
Searchable (full-text)SHALLSHALLSupervisor and AI Agent must be able to search by keyword
Categorized by entry typeSHALLSHALLMinimum types: decision, pattern, gotcha, dead_end, observation
Entry has title and bodySHALLSHALLTitle for scanning, body for detail
Entry has creation timestampSHALLSHALLWhen was this knowledge created
Entry has project/scope tagSHOULDSHALLWhich project or area this knowledge applies to
Versioned entries—SHALLTrack changes to knowledge entries over time
Freshness tracking—SHALLlast_reviewed timestamp, updated when entry is confirmed still accurate
Entry status—SHALLValues: current, needs_review, deprecated
Cross-references between entries—SHOULDLink related knowledge entries
Bulk exportSHOULDSHALLExport all entries in a portable format (JSON, markdown)
Entry author tracking—SHALLWho created or last updated this entry

3.2 Entry Types

TypePurposeExample
decisionArchitectural or design choice with rationale”We use UUIDs for all entity IDs because…”
patternReusable approach for common tasks”Error handling in API endpoints follows this structure…”
gotchaNon-obvious behavior that causes problems”CouchDB bulk_docs silently ignores conflicts unless…”
dead_endApproach that was tried and abandoned, with reason”Tried using WebSockets for SSE replacement — failed because…”
observationEmpirical finding worth remembering”Build times increase 2x when running TypeScript strict mode on…”
templateReusable requirement/AC pattern for common task types”REST API endpoint AC: 1. Returns 200 for valid input. 2. Returns 401 without auth…“

3.3 AI Agent Integration

RequirementCore/FoundationTeam+Notes
AI Agent can search KB during sessionSHALLSHALLVia tool/function call or context injection
AI Agent can create KB entries during sessionSHALLSHALLDead Ends and Gotchas discovered during work
Relevant KB entries injected into session contextSHOULDSHALLBased on task area, project, or explicit references
AI Agent can update existing KB entries—SHALLCorrect or extend existing knowledge
KB query results are structuredSHOULDSHALLTitle, type, body, freshness — not raw text dumps
KB access is scoped—SHALLAgent sees relevant project knowledge, not everything
KB entry creation triggers review queue—SHOULDHuman reviews AI-created knowledge entries

3.4 Freshness Management

RequirementCore/FoundationTeam+Notes
Entries older than N increments flagged for review—SHALLConfigurable threshold (recommendation: 3 Increments)
Freshness report available—SHALLDistribution of entry ages, count by status
Deprecated entries excluded from AI context—SHALLStale context is worse than no context
Quality Sweep includes KB freshness auditSHOULDSHALLPart of the ceremony checklist

4. Session Management

Sessions are SENAR’s primary rhythm mechanism. The tooling must support the full session lifecycle.

4.1 Session Lifecycle

RequirementCore/FoundationTeam+Notes
Session start with timestampSHALLSHALLRecords when the Session began
Session end with timestampSHALLSHALLRecords when the Session ended
Session has unique identifierSHALLSHALLFor linking Tasks, metrics, handoffs
Session links to SupervisorSHOULDSHALLWho ran this Session
Session links to Tasks workedSHALLSHALLWhich Tasks were active during this Session
Previous session handoff available at startSHALLSHALLContext continuity

4.2 Checkpoint Capability

RequirementCore/FoundationTeam+Notes
Mid-session checkpointSHOULDSHALLSave context state without ending the Session
Checkpoint captures current task statusSHOULDSHALLWhat’s in progress, what’s done
Checkpoint reminder—SHOULDAlert at configurable intervals (e.g., every 40-60 tool calls)
Checkpoint restores context on session crash—SHOULDRecover from unexpected session termination

4.3 Handoff Documents

RequirementCore/FoundationTeam+Notes
Handoff document created at Session EndSHALLSHALLSummary of what was done and what’s next
Handoff includes completed TasksSHALLSHALLList of Tasks done in this Session
Handoff includes in-progress TasksSHALLSHALLState of Tasks not finished
Handoff includes blockers/risksSHOULDSHALLWhat might prevent the next Session from succeeding
Handoff includes knowledge captured—SHALLKB entries created or updated during the Session
Handoff stored and searchableSHOULDSHALLHistorical handoffs available for reference
Handoff loaded automatically at next Session StartSHOULDSHALLNo manual searching for the latest handoff

4.4 Metrics Capture

RequirementCore/FoundationTeam+Notes
Tool call count per SessionSHOULDSHALLLeading indicator of session complexity and fatigue
Session durationSHALLSHALLDerived from start/end timestamps
Tasks completed per SessionSHALLSHALLThroughput input
Session cost (tokens/API spend)—SHALLFor Cost per Task calculation
Error/retry count—SHOULDHow many times the AI needed correction

5. AI Agent Integration

Requirements for how AI Agents are configured, monitored, and managed within SENAR.

5.1 Context Injection

RequirementCore/FoundationTeam+Notes
Structured project instructionsSHALLSHALLProject-level context loaded at session start (e.g., CLAUDE.md, .cursorrules)
Task context injectionSHALLSHALLGoal, AC, and relevant constraints provided to agent
KB entry injectionSHOULDSHALLRelevant knowledge entries available during work
Codebase conventionsSHOULDSHALLCoding standards, architectural patterns, naming conventions
Scope boundariesSHOULDSHALLExplicit “do not change” instructions
Session history/handoff injectionSHOULDSHALLPrevious session context for continuity

5.2 Output Capture

RequirementCore/FoundationTeam+Notes
Code changes captured in version controlSHALLSHALLStandard git workflow
Session logs available for reviewSHOULDSHALLWhat the AI did, what the Supervisor approved
AI reasoning visibleSHOULDSHOULDWhy the AI made specific choices (for verification)
Output linked to TaskSHALLSHALLWhich Task produced which code changes

5.3 Cost and Token Tracking

RequirementCore/FoundationTeam+Notes
Token usage per session—SHALLInput + output tokens
API cost per session—SHALLDollar cost derived from token usage
Cost per task (derived)—SHALLSession cost / tasks completed
Cost trend over time—SHALLIs the process becoming more or less expensive?
Budget alerts—SHOULDWarn when session/increment cost approaches budget
Cost by model/provider—SHOULDIf multiple models are used, track cost separately

5.4 Multi-Agent Orchestration (Team+)

RequirementCore/FoundationTeam+Notes
Workspace isolation—SHOULDAgents work in isolated environments (worktrees, containers)
Agent-to-agent communication—SHOULDDelegate subtasks to specialized agents
Parallel agent execution—SHOULDMultiple agents working simultaneously under supervision
Agent output aggregation—SHOULDCollect results from multiple agents into unified review
Agent capability profiles—SHOULDDifferent agents for different task types (code, test, docs)

5.5 Agent Configuration Management

Requirements for managing Agent Profiles, Operational Scripts, and the Programmatic Interface (Standard Section 5).

RequirementCore/FoundationTeam+Notes
Script storage in version controlSHALLSHALLScripts stored alongside project code
Script versioning (change history)SHOULDSHALLTrack who changed what, when, and why
Profile definition storageSHOULDSHALLAgent Profiles stored as structured configuration
Profile switching support—SHOULDAbility to switch agent context between profiles within a session
Permission scoping per profile—SHALLEnforce read/write boundaries per Agent Profile
Script propagation mechanism—SHALLPropagate script changes across multiple projects
Script rollback capabilitySHOULDSHALLRevert any script change to previous version
Active script registry—SHALLInventory of active scripts with version identifiers
Script change audit trail—SHALLLog of all script modifications with rationale
Tool inventory per profileSHOULDSHALLDocument which tools each profile can access
Hook execution engine—SHOULDAutomated actions triggered by events (post-session, pre-commit)
Script effectiveness metrics—SHOULDTrack FPSR and error rate per script version

6. Integration Requirements

How the components connect to form a functioning SENAR toolchain.

6.1 Core/Foundation Integrations

IntegrationDescription
Task Tracker <-> Session ManagementSessions reference Tasks; Tasks reference Sessions
Task Tracker <-> CI/CDPipeline results linked to Tasks and merge requests
Knowledge Base <-> AI AgentAgent can search, read, and create KB entries during sessions
Session Management <-> AI AgentSession start/end driven by or coordinated with agent lifecycle

6.2 Team+ Integrations

IntegrationDescription
Task Tracker <-> Knowledge BaseTasks link to relevant KB entries; KB entries link to originating Tasks
CI/CD <-> Task TrackerPipeline failures auto-update Task status to blocked
Session Management <-> MetricsSession metrics auto-populated from session data
Knowledge Base <-> CI/CDArchitectural constraint KB entries enforced in pipeline (aspirational)
Federation <-> Task TrackerCross-project dependency status synchronized
Federation <-> Knowledge BaseCross-project knowledge accessible with proper scoping

7. Selection Guidance

When evaluating tooling options, prioritize:

  1. Automation over manual process — if a ceremony step can be automated, it should be. Manual steps are failure points (see Guide 06, PF-3: Gate Bypass Normalization).

  2. Portability over features — data must be exportable. Vendor lock-in (Guide 06, OF-3) is a recognized failure mode.

  3. AI-accessible over human-only — every data store the Supervisor uses should also be queryable by the AI Agent. If the AI can’t access it, it doesn’t exist for SENAR purposes.

  4. Simple over comprehensive — a task tracker with 5 well-implemented fields beats one with 50 fields nobody fills in. Start with Core/Foundation requirements and add Team+ requirements when needed.

  5. Composable over monolithic — prefer tools that integrate via APIs over all-in-one platforms. SENAR components evolve at different rates; replacing one component should not require replacing all of them.

← Governance & Compliance Code Standards Template →