docs: document orphan-YAML gate + --allow-new-files in README and AGENTS#31
Merged
Conversation
Followup to PR #30 (orphan-YAML pre-flight gate). The gate landed in the engine but neither README.md nor AGENTS.md mentioned the new default-on behavior or the --allow-new-files override. Agents and human operators reading those docs would hit the gate unexpectedly. README.md: - Updated push command-table row to mention the gate + flag - New "Creating new resources after the first push (orphan-YAML gate)" section under Suggested Workflows, explaining the three cases (new / rename / cruft), the --allow-new-files override, and the AI-agent caveat (do NOT auto-pass without confirming) - Documents the automatic suppressions (--bootstrap, .vapi-ignore, selective-push scope) AGENTS.md: - Common commands table row for "Push with new resources" with the --allow-new-files flag + explicit AI-agent caveat - New "Orphan-YAML gate" subsection under "npm run push" explaining the gate behavior, override flag, AI-agent guidance, and suppression rules. Notes that the same gate fires inside `apply` and the flag propagates through `apply --allow-new-files` - New bash command-block lines for `npm run push --allow-new-files` and `npm run apply --allow-new-files` Docs-only PR. Skipping test-writer and code-reviewer per the always-apply rule for docs-only changes.
Merged
11 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Followup to PR #30. The orphan-YAML pre-flight gate landed in the engine but neither README.md nor AGENTS.md mentioned the new default-on behavior or the
--allow-new-filesoverride. Agents and human operators reading those docs would hit the gate unexpectedly.This PR adds:
README.md:
--allow-new-filesoverride, and the AI-agent caveat--bootstrap,.vapi-ignore, selective-push scope)AGENTS.md:
--allow-new-filesflag + explicit AI-agent caveatapplyand the flag propagates throughnpm run push --allow-new-filesandnpm run apply --allow-new-filesTest plan
Skipping test-writer/code-reviewer per the always-apply rule for docs-only PRs.