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

Open
#302 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.