feat(hands-on): add guardrails rules lab and wire into docs

- New hands-on/rules/ interactive page: five toggleable rule sources
  (AGENTS.md, gate-discipline skill, Husky pre-commit, check-ui-contract
  enforcer, commitlint) rebuild a ruled prompt live against a naive prompt.
- Visual system mirrors hands-on/starter (same palette, vanilla JS).
- index.html hands-on section now links both labs.
- docs/operations-guide.md gains a 'Hands-on rules lab' subsection.
- README project structure lists the new lab.
- verify.mjs passes content, interaction, and standalone checks for both labs.
This commit is contained in:
Marcos Paulo
2026-09-02 15:30:45 +00:00
parent 9f879ed276
commit f526a42ddd
8 changed files with 249 additions and 3 deletions
+39
View File
@@ -381,6 +381,45 @@ Compare:
| Evidence | Did the final response name checks and results? |
| Complexity | Is the solution proportionate to three tasks and three filters? |
### Hands-on rules lab
A second lab at `hands-on/rules/` mirrors the starter's visual system and runs
the same exercise against rule sources instead of feature work. It lists five
toggleable rule sources — `AGENTS.md`, the `gate-discipline` skill body, the
Husky `pre-commit` hook, the `check-ui-contract.mjs` enforcer, and
`commitlint` — and rebuilds the **ruled** prompt live as each toggle flips.
Run it:
```bash
python3 -m http.server 4173
```
Open [http://localhost:4173/hands-on/rules/](http://localhost:4173/hands-on/rules/).
Compare the **naive** and **ruled** prompt panels. Toggle rules off to shrink
the prompt; toggle them on to widen the leash. Copy the final prompt and run
it against a real coding agent — the lab is deliberately short so the spend
stays bounded.
## Rules and enforcement case study
The separate `/rules/` page uses `netcracker/interview` as a concrete example
of repository-level control. Its interactive pipeline shows five layers:
1. `AGENTS.md` gives every agent the same product and toolchain context.
2. `.agents/skills/` loads narrow procedures for frontend, Go API, gates,
parallel work, repository ledgers, issues, skill writing, and technical debt.
3. `pnpm check:ui` compares violations with a baseline that may only decrease.
4. Husky runs lint-staged and the UI ratchet before commit; commitlint enforces
Conventional Commit messages.
5. `.pr-review.json` supplies repository-specific policy to the AI reviewer,
while the verifier agent reruns gates independently before merge.
The page links directly to each implementation in Gitea and includes a
copy-ready, read-only prompt for mapping the same enforcement layers in another
repository. Update `rules/index.html`, `rules/app.js`, and `rules/styles.css`
together when the underlying interview workflow changes.
## Troubleshooting
| Symptom | Check | Fix |