sentinel-dev¶
Audits the neuroflow plugin repo for internal consistency. Writes its report to .neuroflow/sentinel-dev.md in the plugin repo root.
One implementation per check. Every mechanical check lives once, in scripts/automation/repo_checks.py, under a stable id (V1–V15). validate_pr.py runs it on every PR (.github/workflows/validate.yml) and sentinel_check.py runs it daily and posts to Discussion #168. This spec describes those checks and adds only the ones that need judgement. Do not redo a V-check by hand; to change one, edit repo_checks.py and its tests in tests/automation/.
Step 1 — Mechanical checks (script)¶
From the plugin repo root:
Drop --base when there is no origin/main (V7 then does not run). For a grouped markdown report, python scripts/automation/sentinel_check.py --report-only prints the same findings and never touches git or GitHub.
| Exit code | Meaning | What to do |
|---|---|---|
| 0 | No failures | Copy any warnings into the report; go to Step 2. |
| 1 | Failures | Copy every [Vn] failure and warning into the report; go to Step 2. |
| 2 | Usage or internal error | Report it; do not guess the results. |
| Id | Severity | What it verifies |
|---|---|---|
| V1 | fail | plugin.json, marketplace.json and hooks/hooks.json are valid JSON |
| V2 | fail | Version sync: plugin.json = marketplace.json plugins[].version = mkdocs.yml extra.version = .neuroflow/project_config.md plugin version. Fix: bump_version.py --sync |
| V3 | fail | Command frontmatter: name (= filename), description, phase (canonical, parsed live from neuroflow-core's phase taxonomy), reads, writes, lifecycle (full / light / quiet); requires / produces / next are lists and next names existing commands; argument-hint is a string |
| V4 | fail | Every command has docs/commands/<name>.md |
| V5 | fail | Skill folder = SKILL.md name; agent filename = agent name; user-invocable and disable-model-invocation are true or false |
| V6 | fail | hooks.json structure; every command hook ends with ; true or \|\| true; an optional modules key names exactly one existing module file |
| V7 | fail | With --base: substantive changes bump the plugin.json version (the exempt list is shared with .githooks/pre-push) |
| V8 | fail / warn | Rule markers: every <!-- nf-rule: ID --> uses an id from neuroflow-core's rule table, and every id a guard in hooks/mod/ cites (nf-rule: ID) has a marker in skills/ or commands/. Warns about rules that have no marker yet |
| V9 | fail / warn | No skill folder shares a command's name (the command shadows the skill); warns when an agent and a skill share one |
| V10 | fail / warn | Propagation: every command, skill and agent has a README row and a mkdocs nav entry; every relative link and image in README.md resolves (the whole file: Markdown targets and HTML src, href and srcset; a link into the docs site names a page in docs/; an in-page anchor that no heading or id defines warns); the mkdocs.yml theme logo and favicon and the plugin.json icon exist; no dead nav links; the nav lists each page once |
| V11 | fail | No dead neuroflow:<name> references inside SKILL.md files |
| V12 | fail / warn | Release notes: README has one What's new section, and two or more fail (the earlier notes live in docs/changelog.md); none, or one for another version than plugin.json, warns; docs/changelog.md has that version as its newest ## X.Y.Z entry (warn) |
| V13 | warn | The repo's own .neuroflow/ holds only reasoning/ and sessions/ folders |
| V14 | fail / warn | Sensitive info: PEM private-key material fails; emails and hardcoded secrets warn [needs human review] |
| V15 | warn | Path hygiene: the old dotted .neuroflow/.flowie/ path, paths into a project-level .neuroflow/flowie/ or .neuroflow/hive/, and the legacy flowie_profile: / flowie_project: / hive_member: fields |
If Python is unavailable, say so in the report and do the table's checks by reading the files.
Step 2 — Judgement checks¶
J1 — Hooks documentation¶
Read docs/concepts/hooks.md (and docs/concepts/mods.md when hooks.json names a module) and the note in the Installation section of README.md on what installing adds. Every hook in hooks/hooks.json, and the hooks module if modules names one, must be described on those pages, and every hook the pages or the README name must exist. Flag both directions.
J2 — Real names and institutions¶
Scan the plugin tree (agents/, commands/, skills/, docs/, hooks/, scripts/, .neuroflow/, root *.md files) for:
- Real personal names in non-example context: a sequence of two or more capitalised words (likely a full name) that is not clearly labelled as a sample (
e.g. Jane Smith), not inside an HTML comment, and not an author credit. Mark each finding[needs human review]— tool names and proper nouns produce false positives. - Institutional affiliations in non-example context: real institution names, department names, or postal addresses outside clearly-labelled example content. Examples use neutral placeholders ("University of Example"). Mark each finding
[needs human review].
Do not print a sensitive value verbatim; mask it (e.g. email: j***@exam***.com, private key at line 14 of scripts/setup.py). sentinel-dev never removes or redacts on its own: the maintainer decides for each finding.
J3 — retired¶
Concept-map placement went with the mind map in 0.2.22; like a retired V id, J3 stays unused.
J4 — Guards and prose agree (only if hooks/mod/ exists)¶
V8 proves that a marker exists, not that the guard enforces what the prose says. For each rule id a guard cites, read the marked prose and the guard. Flag a guard that blocks more than the rule states, and a rule the guard enforces only partly without saying so in its deny reason.
Report¶
Write to .neuroflow/sentinel-dev.md in the plugin repo root:
Last run: YYYY-MM-DD
## Issues found
- [check id] [description of issue]
## All clear
(written only if zero issues found)
Then ask the user: for each issue, fix automatically or leave for manual review?
Fixes sentinel-dev may apply after the user agrees: version drift (python scripts/automation/bump_version.py --sync), missing README rows and nav entries (the user reviews the wording), and stale paths flagged by V15. Never automatic: sensitive information (V14, J2) and anything under hooks/mod/ (J4).
After applying any fixes, run validate_pr.py again and rewrite .neuroflow/sentinel-dev.md to reflect the current state — either listing only the remaining unfixed issues, or writing "All clear" if everything was resolved.