BOHICA-LABS / BOHICA-LABS/vsdd-factory
scaffold-claude-md: scope the git/PR rule and add a 'report denials accurately' principle to generated CLAUDE.md
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
The `scaffold-claude-md` skill (Detector 3: Git Workflow) generates a CLAUDE.md that **reports git rules as bare facts** without scoping them. In practice this leaves a silence that an agent will fill with an assumption — most damagingly, inferring a human-merge-approval gate that was never written.
This is especially acute for vsdd-factory, because the factory is the one consumer where the gap actually collides:
- The per-story delivery flow has `pr-manager` **legitimately merging** PRs.
- Claude Code's auto-mode classifier **blocks agent self-approved merges to `main`** as a harness safety guard.
When those two meet, an orchestrator can mistake the *classifier's* block for a *user/project directive* and then paraphrase a policy that doesn't exist ("PRs require human review"). I hit exactly this: I extrapolated a human-approval gate from a rule whose text only mandates "open a PR, don't push directly," and attributed the merge block to the user's directive rather than to the classifier.
## Proposed change
Two additions to the CLAUDE.md the skill generates.
### 1. Scope the push/PR rule (Detector 3 output)
When Detector 3 emits the "direct pushes not permitted / open a PR" bullet, append a scope clause:
> Branch from ``, open a PR. Direct pushes are not permitted. **Scope: this governs _how_ changes reach a protected branch (via a PR/MR), not _who_ may merge it. It does not by itself require human approval of the merge — do not infer a human-approval gate from it. If sign-off is required before merge, it will be stated explicitly or enforced by the harness; otherwise follow the workflow's own merge step.**
This keeps the rule correct for both human-merge repos and the factory's `pr-manager`-merges flow, while removing the inference gap.
### 2. Add a generic "interpreting denials" principle
A short standing principle (template-level, not detector-derived), since it generalizes beyond git:
> - Do not expand a specific prohibition into a broader policy than its text states. If a rule is silent on something, treat it as unspecified — ask, or follow a sensible default; don't invent a constraint and present it as a user/project directive.
> - When a tool, sandbox, or permission classifier denies an action, report the denial's **actual stated reason**. Never re-attribute a harness/classifier block to a directive, and never imply a rule exists that doesn't.
This is the higher-leverage fix: it would have stopped the misattribution at the source (report the classifier block as a classifier block).
## Files
- `skills/scaffold-claude-md/SKILL.md` — Detector 3 (Git Workflow, ~L61–75) and the Assembly template (~L97–117).
## Note on the template's "no methodology" guideline
The skill currently says the generated CLAUDE.md must not duplicate plugin-provided methodology/principles (L121–122). Principle #2 above is arguably a methodology-adjacent behavioral rule. If preferred, #2 could instead live in the orchestrator/agent prompts rather than the generated CLAUDE.md — either home solves it. Flagging so the placement is a deliberate choice.
## Context
Surfaced during a real factory run (Godot/GDScript project): orchestrator presented a merge gate as "per your global directive (PRs get human review)" when the user's CLAUDE.md only required PR-not-direct-push; the actual blocker was the auto-mode classifier's self-approval guard. The user confirmed the underlying guidance was sound — the failure was interpretation, and the fix is to scope the rule and to never re-attribute a harness denial.
Contributor guide
Assessment
This issue has not been assessed yet.