6 lines
3.2 KiB
Plaintext
6 lines
3.2 KiB
Plaintext
Project Sentinel: Knowledge Management & Documentation ParityVersion: 3.0.0-EnterpriseModule: 12-Workflow-DocsMaps to: docs/workflows/DOCUMENTATION_UPDATES.mdScope: Enforcement of "Doc-Code Parity", automated changelog generation, and knowledge base integrity.1. The "Doc-Code Parity" RuleIn the Sentinel environment, Documentation is treated as code. It must be compiled (verified) and linked. Code that drifts from its documentation is considered "broken build."1.1 The Definition of Done (DoD) GuardrailSentinel modifies the "Definition of Done" for every Sprint Task.Logic:Agent attempts to close task: complete_task(id="T-101").Sentinel Diff Analysis:Did *.go files change? Yes.Did docs/ or README.md change? No.Action: Block Task Completion.Error: "Parity Check Failed. You modified executable code but zero documentation files. You must update the relevant docs or the CHANGELOG before closing this task."1.2 The "Freshness" MetadataMechanism: Sentinel injects a metadata header into every Markdown file it manages.<!-- SENTINEL-METADATA
|
|
last_verified_commit: a1b2c3d
|
|
related_modules: [auth, login]
|
|
freshness_score: 100%
|
|
-->
|
|
Decay: If the related_modules (e.g., auth.go) are modified 10 times, but the Markdown file is not updated, the freshness_score drops.Warning: When an Agent reads a "stale" doc (Score < 50%), Sentinel warns: "Caution: This document may be outdated. Last verified 50 commits ago."2. Architecture Decision Records (ADRs)Sentinel enforces the creation of ADRs for significant structural changes.2.1 Triggering an ADRHeuristic: If an Agent edits > 10 files or introduces a new top-level dependency (e.g., adds Redis).Intervention: Sentinel pauses the workflow.Prompt: "You are making a significant architectural change. Please record this decision."Tool: create_adr(title="Use Redis for Session Store", status="Proposed").2.2 Immutable ArchivesStorage: docs/adr/001-record-name.md.Protection: Once an ADR is marked Accepted, Sentinel locks the file. It cannot be edited, only superseded by a new ADR. This preserves the "Decision History" of the project.3. Automated Changelog ManagementAgents often write terrible changelogs ("updates", "fixes"). Sentinel automates this via the Audit Log.3.1 The "Semantic" Log GeneratorInput: Sentinel reads the audit_log and the git log for the sprint.Processing: It groups changes by:New Features (feat)Bug Fixes (fix)Breaking Changes (!)Output: Sentinel rewrites CHANGELOG.md automatically when archive_sprint is called. The Agent does not edit this file manually; the System generates it to ensure accuracy.4. The Knowledge Base (Vector Ops)How does Sentinel ensure the Agent finds these docs?4.1 RegistrationWhen a new file is added to docs/:Event: File Create.Sentinel Action:Parses the Markdown headers.Extracts keywords.Updates the SQLite knowledge_base table: INSERT INTO resources (path, tags, content_hash)...(Optional) If a Vector DB is configured, generates embeddings.4.2 Dynamic MountingScenario: Agent is working on Task: Update Logging.Query: Sentinel queries the DB for tags IN ('logging', 'monitoring').Action: Sentinel mounts docs/standards/SENTINEL_STANDARD_LOGGING.md into the active context. This ensures the Agent sees the rules for logging at the exact moment it is writing logs. |