Add compliance-staging folder, gitignore agents, update docs and kiro config

This commit is contained in:
jramos
2026-04-16 14:41:52 -06:00
parent f141fa58a1
commit a214393723
9 changed files with 396 additions and 44 deletions

View File

@@ -0,0 +1,13 @@
{
"enabled": true,
"name": "Doc Review",
"description": "Manually triggered after merging to master. Reads the recent git diff, classifies the changes, and proposes documentation updates following the doc-updater decision tree and doc-standards.md conventions.",
"version": "1",
"when": {
"type": "userTriggered"
},
"then": {
"type": "askAgent",
"prompt": "Run a documentation review against the latest changes on master. Follow these steps exactly:\n\n1. Run `git log --oneline -10` to see recent commits. If any commit message contains `[skip-docs]`, stop and report NO_DOC_UPDATE_NEEDED.\n\n2. Run `git diff HEAD~1 --stat` to get the list of changed files, then `git diff HEAD~1` to get the full diff. If the diff is larger than 500 lines, report NEEDS_HUMAN_REVIEW with a summary of which areas likely need docs.\n\n3. Read `.kiro/agents/doc-updater.md` for the full decision tree and `.kiro/steering/doc-standards.md` for formatting conventions.\n\n4. Follow the doc-updater decision tree: triage the change, decide if docs need updating, survey existing docs (README.md, docs/ folder), and propose surgical edits.\n\n5. For any proposed changes, apply them directly to the doc files. Only touch README.md and files under docs/. Never touch code files.\n\n6. After applying changes, output the SUMMARY block from the decision tree so Jordan can review what was changed and why."
}
}

View File

@@ -0,0 +1,13 @@
{
"enabled": true,
"name": "Ivanti API Debugger",
"description": "Manually triggered when debugging a failing Ivanti API call. Prompts for the endpoint, request payload, and error response, then invokes the ivanti-api-debugger agent to diagnose the issue and update ivanti-api-reference.md with any findings.",
"version": "1",
"when": {
"type": "userTriggered"
},
"then": {
"type": "askAgent",
"prompt": "You are the Ivanti API Debugger agent. Follow the instructions in `.kiro/agents/ivanti-api-debugger.md` exactly.\n\nAsk the user to provide the following (one clarifying question, not five — accept whatever they paste and infer the rest):\n\n1. The failing endpoint or route — either the Ivanti API path (e.g. `/workflowBatch/falsePositive/request`) or the backend route file/handler that makes the call (e.g. `backend/routes/ivantiWorkflows.js`)\n2. The request payload they sent (curl, JSON body, or code snippet)\n3. The response or error they got back (HTTP status, response body, or error message)\n\nOnce you have that context, follow the full diagnostic workflow described in `.kiro/agents/ivanti-api-debugger.md`: read the relevant route/service code, cross-reference `docs/ivanti-api-reference.md`, check for common Ivanti failure modes, form a hypothesis, and propose a concrete next request to try. If the user confirms a finding, update `docs/ivanti-api-reference.md` using its existing structure."
}
}

View File

@@ -0,0 +1,13 @@
{
"enabled": true,
"name": "Security Audit Tracker",
"description": "Manually triggered to scan the codebase for security issues and maintain a living audit tracker document. Prompts for scan scope (full repo or specific path) and mode (report only or report + update tracker). Invokes the security-audit-tracker agent for static analysis and doc tracking.",
"version": "1",
"when": {
"type": "userTriggered"
},
"then": {
"type": "askAgent",
"prompt": "You are the Security Audit Tracker agent. Follow the instructions in `.kiro/agents/security-audit-tracker.md` exactly.\n\nAsk the user to provide the following two inputs:\n\n1. **Scope:** \"full repo\" to scan the entire codebase, or a specific path/module to focus on (e.g. `backend/routes/`, `frontend/src/components/`, `backend/helpers/ivantiApi.js`)\n2. **Mode:** \"scan only\" (report findings to chat, no file writes) or \"scan + update tracker\" (report findings and merge them into the tracker doc at `docs/security-audit-tracker.md`)\n\nOnce you have both inputs, follow the full diagnostic and tracking workflow described in `.kiro/agents/security-audit-tracker.md`: determine scope, check for the tracker doc (create it if missing), scan for the security failure modes listed in the agent spec, cross-reference against previously tracked findings, and output a prioritised report. In \"scan + update tracker\" mode, also merge findings into the tracker doc and update its metadata."
}
}

View File

@@ -0,0 +1,190 @@
# Documentation Standards — CVE Dashboard
These standards are reverse-engineered from the existing README.md and should be treated as the canonical style guide for all documentation in this repository. When updating docs, match these conventions exactly — consistency matters more than any individual stylistic preference.
---
## Language and Style
- Write in **present tense, active voice**. "The sync fetches findings" — not "Findings will be fetched by the sync."
- Do not use marketing language. No "powerful", "seamless", "robust", "cutting-edge", "unleash". Describe what the thing does, not how great it is.
- No emoji anywhere in documentation. None.
- Prefer precise technical vocabulary over casual phrasing. "Session tokens are stored in `httpOnly` cookies" — not "we keep the login thing in a secure cookie."
- **Spelling:** match whatever spelling variant already appears in the surrounding prose. Do not rewrite existing words to switch between US and British English — consistency within a section matters more than which variant is used.
---
## Punctuation and Formatting
- **Em-dashes (—)** for mid-sentence clarifications or appositives, surrounded by spaces: `sync requires Admin or Standard_User group — the sync then fetches findings`.
- **En-dashes ()** for numeric ranges: `8.59.9 VRR`, `20 attempts per 15-minute window`.
- Use **inline backticks** for: file paths, environment variables, CLI flags, function names, field names, HTTP status codes, and any literal value the reader should type or recognise verbatim.
- Use **bold** (`**text**`) for UI element names (button labels, tab names, form fields) and for label-style emphasis at the start of a sub-point.
- Avoid italics except for rare genuine emphasis. Do not use italics decoratively.
---
## Heading Hierarchy
Use a strict three-tier hierarchy per document:
```
# Document Title (one per file, matches repo/feature name)
## Top-Level Section (Overview, Features, Architecture, etc.)
### Subsection (a named feature, page, or concept)
**Sub-subsection label** (bold paragraph labels — NOT an #### heading)
```
- Do **not** use `####` or deeper headings. If you need a fourth level, it should be a bold inline label followed by content, matching the existing README pattern.
- Separate top-level `##` sections with a horizontal rule (`---`) on its own line, with blank lines above and below.
- Do not place horizontal rules between `###` subsections unless visually necessary.
---
## Table of Contents
- Any document over ~200 lines should open with a Table of Contents using markdown anchor links.
- Nest TOC entries to match heading depth (`##` entries flush-left, `###` entries indented two spaces).
- Anchor slugs: lowercase, spaces become hyphens, em-dashes become `--` (two hyphens). Example: `## Home — CVE Management` becomes `#home--cve-management`.
---
## Tables
Use tables for any reference material with two or more parallel attributes. This includes:
- Permission matrices (group → capabilities)
- Tech stack listings (layer → technology)
- Column descriptions (column → meaning)
- Environment variable references (name → purpose → default)
- Route references (method + path → description → auth requirement)
Table format:
```markdown
| Column | Description |
|---|---|
| `field_name` | What it does |
```
- Always use `---` separators (not `:---:` centred alignment) unless centring is specifically warranted.
- Keep cell content on a single line. If a value is long, prefer prose above or below the table.
- Use inline backticks for literal values inside cells.
---
## Code Blocks
- **Always include a language tag** on fenced code blocks: ` ```bash `, ` ```javascript `, ` ```json `, ` ```python `, ` ```sql `. Bare ` ``` ` is not acceptable.
- Shell commands use `bash` — even for single-line commands.
- Place code blocks on their own line, with blank lines before and after.
- Inside code blocks, do not use markdown formatting (no bold, no italics). Treat them as literal terminal/file content.
- Prefer showing the actual command over describing what to do. "Run `node setup.js` from `backend/`" with a code block — not "initialize the database."
---
## Callouts and Warnings
- Use a blockquote (`>`) for callouts, notes, and warnings. Do not use GitHub-flavoured admonition syntax (`> [!NOTE]`), Docusaurus admonitions, or custom HTML.
- Keep callouts to one or two sentences. If longer, promote to prose.
- Example: `> IVANTI_API_KEY must be set in backend/.env for sync to work.`
Bold prefixes for emphasis are acceptable inside a blockquote: `> **Warning:** This deletes all audit records older than 90 days.`
---
## Feature Documentation Pattern
When documenting a feature or page, follow this structure:
1. **One-sentence summary** of what the feature is and who uses it.
2. **Capability bullets** — what a user can do, grouped by role if access-controlled.
3. **Workflow or interaction details** — how the feature is used in practice (inline editing behaviour, filter semantics, persistence rules).
4. **Integration notes** — what external systems it touches, what credentials it needs, what it caches.
5. **Edge cases and restrictions** — delete rules, rate limits, role requirements.
Bold paragraph labels (`**Inline editing:**`, `**CVE Tooltips:**`, `**Filtering:**`) are the preferred pattern for calling out sub-behaviours within a feature section.
---
## Troubleshooting Entries
Every troubleshooting entry uses the **Symptom → Cause → Fix** triad:
```markdown
### Short description of the problem
**Symptom:** What the user sees or experiences. Be specific about error messages, console output, and observed behaviour.
**Cause:** The underlying reason, explained in one or two sentences. Include the technical mechanism (cookie flag, rate limiter, missing migration) — not just "it's broken."
**Fix:** Either:
1. Concrete action with a command or config change, **or**
2. Alternative action.
```
- Short entries (fix is one command) may collapse Cause into Fix, but Symptom must always appear explicitly.
- Use **Fix:** as the label, not "Solution" or "Resolution."
---
## CHANGELOG
This project does not currently maintain a `CHANGELOG.md`. The doc-updater agent should **not** create one unless explicitly instructed.
When a change ships, rely instead on:
- **Git commit messages** as the primary change history. Write them as complete sentences describing user-observable behaviour, not implementation detail. "Add inline editing to CVE reporting table" — not "fix table.jsx."
- **README updates** as the user-facing record of what the app does now. The README is the source of truth for current behaviour; git log is the source of truth for when and why it changed.
If a `CHANGELOG.md` is introduced later, this section should be rewritten to declare the chosen format. Until then, the agent should leave changelog concerns out of scope.
---
## Migration Documentation
When a feature requires a new database migration:
1. Add the migration filename to the README's **Migrations** section in the order it must be run.
2. If the migration is required for an existing deployment (not just fresh installs), add a Troubleshooting entry using the Symptom → Cause → Fix pattern for the error users will see if they skip it.
3. Note any data-transforming migrations explicitly — users need to know whether the migration is additive (safe to re-run) or transformative (destructive if re-run).
---
## API Reference Documentation
- Document routes as: `METHOD /path/with/:params`
- Group routes by resource or page (CVE routes, Ivanti routes, Audit routes).
- For each route, specify: purpose, required group, request body or query params, response shape summary. Keep it to 24 lines per route.
- Do not duplicate route implementation details. Link to the source file if deeper reference is needed.
- When a route enforces group-based authorisation, state the required group explicitly — do not imply it from context.
---
## What to Update When a Feature Ships
A new feature or meaningful change to existing behaviour should touch:
1. **README.md — Features section:** add or update the relevant `###` subsection, matching the Feature Documentation Pattern above.
2. **README.md — Table of Contents:** if a new feature added a new heading, update the TOC to match.
3. **README.md — Configuration:** if new env vars were introduced, add them to the Configuration table.
4. **README.md — API Reference:** if new routes were added, document them under the appropriate resource group.
5. **README.md — Database Schema:** if tables or columns changed, update the schema section.
6. **README.md — Migrations:** if a new migration was added, append it to the ordered list.
7. **docs/**: if the feature has its own standalone guide (setup guide, integration guide), create or update the relevant file in `docs/`.
If a change does not alter user-observable behaviour, configuration, data model, or API surface, it does not require doc changes. Internal refactors, test additions, and dependency bumps are exempt unless they change how the app is run or deployed.
---
## What NOT to Change
The doc-updater agent and human contributors alike should **leave alone**:
- Tone, voice, and spelling conventions of existing prose. Match, do not rewrite.
- Section ordering in the README — the current order is deliberate and reader-tested.
- Heading wording, unless the underlying feature has genuinely been renamed.
- Examples and command snippets that still work, even if they could be "more elegant."
- The overall shape of the Troubleshooting section — append new entries, do not reorganise existing ones.
Documentation churn is a cost. Only change what the code change requires.