secretzero-precommit-validation
Use before completing feature work, after making code changes, or when preparing for commit/merge. Runs the full pre-commit validation suite, auto-resolves common failures (lint, formatting, test count mismatches), and reports structured results. Integration point for verification-before-completion, finishing-a-development-branch, and code review workflows.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-31
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- secretzero-precommit-validation
- metadata
- { "internal": true }
- description
- Use before completing feature work, after making code changes, or when preparing for commit/merge. Runs the full pre-commit validation suite, auto-resolves common failures (lint, formatting, test count mismatches), and reports structured results. Integration point for verification-before-completion, finishing-a-development-branch, and code review workflows.
03 SKILL.md 正文
SecretZero Pre-Commit Validation Skill
Use this skill to validate code quality and test coverage before completing any feature work, committing changes, or preparing for code review.
When to Use
MUST use before:
- Completing feature implementation
- Creating a commit or PR
- Claiming work is ready for review
- Merging code to main
Triggers:
- "run pre-commit", "run pre-commit tests", "validate before commit"
- "complete the feature", "finish this work", "ready to commit"
- Automatic gate in
verification-before-completionorfinishing-a-development-branchskills
What It Does
The skill executes the full pre-commit validation suite:
- Linting (
task lint): Python static analysis, unused variables, code quality - Testing (
task test): Full pytest suite (1180+ tests) - Security scan (
task security:scan):pip-audit+bandit - Formatting (auto): Black code formatting on violations
- Schema validation: Secretfile manifests
- Documentation links (optional): Hyperlink validation
Output
Returns a structured report:
{
"status": "passed" | "failed",
"tests_passed": 1180,
"tests_failed": 0,
"lint_issues": 0,
"formatting_fixed": 0,
"failures": [],
"details": "All checks passed! Ready for commit."
}
Common Failures & Auto-Resolution
Unused Variable Warnings
Symptom: F841 Local variable 'x' is assigned but never used
Resolution: The skill auto-identifies and removes unused variable assignments. Example:
# Before
style_name = style.get("Style Category", "") # Assigned but never used
keywords = style.get("Keywords", "") # Used
# After
keywords = style.get("Keywords", "") # Only used variables remain
Code Formatting Issues
Symptom: would reformat /path/to/file.py
Resolution: Auto-runs task format and re-validates.
Test Count Mismatches
Symptom: Test expects 5 capabilities but finds 6 (or vice versa)
Resolution: The skill identifies the mismatch and provides guidance:
AWS provider now has 6 capabilities (added retrieve_iam_user_credentials).
Update test assertion from len(capabilities) == 5 to == 6
Add assertion: assert caps.get_capability("retrieve_iam_user_credentials") is not None
Schema Validation Failures
Symptom: Secretfile manifests invalid or out of sync with schema
Resolution: Runs task schema:update to regenerate schema and example files.
Security Vulnerabilities
Symptom: pip-audit reports known vulnerabilities (GHSA/CVE), e.g. vulnerable transitive packages.
Resolution:
- Bump dependency floors in
pyproject.toml([tool.uv.override-dependencies]) - Add package to
exclude-newer-packagewhen needed to bypass the global recency window - Refresh
uv.lock - Re-run
task security:scanand then full pre-commit validation
Invocation
Direct Usage (Standalone)
# Run and report results
./scripts/agent.pre-commit.sh --mode full
# Quick validation (lint + format only)
./scripts/agent.pre-commit.sh --mode fast
Within a Skill Workflow
When called by another skill (e.g., verification-before-completion):
- Executes validation suite
- Catches and auto-resolves common failures (formatting, unused vars)
- Reports pass/fail with structured output
- Guides user through manual fixes if needed (test count updates, etc.)
Example from verification-before-completion:
## ✅ Pre-Commit Validation Passed
- All 1180 tests passed ✓
- Linting clean ✓
- Formatting applied ✓
- Ready for commit
Example from finishing-a-development-branch (auto-gate):
Pre-commit validation is required before merge. Running now...
[Output shows failures + auto-fixes applied]
Retry validation...
[All checks now pass]
Proceeding with branch completion.
Integration Points
With verification-before-completion Skill
completion-claimed → invoke this skill → pass? → proceed : halt + guide fixes
With finishing-a-development-branch Skill
merge/squash → validate pre-commit required → invoke skill → all pass? → complete : retry
With requesting-code-review Skill
ready for review → validate pre-commit → pass? → create PR : request fixes
Manual Workflow
# Make changes
# ... code work ...
# Validate before commit
task lint && task test
# Or use the skill for auto-resolution
./scripts/agent.pre-commit.sh --mode full
Failure Categories & Guidance
| Category | Example | Auto-Resolved? | Guidance |
|---|---|---|---|
| Unused variables | F841 in linting | ✅ Yes | Removed from code |
| Code formatting | Black violations | ✅ Yes | Auto-formatted via task format |
| Test count mismatch | Expected 5, got 6 | ⚠️ Partial | Identifies issue; user updates assertion |
| Import errors | Missing dependency | ❌ No | Install via uv pip install |
| Logic errors | Test assertion fails | ❌ No | User debugs test logic |
| Schema drift | Secretfile.yml vs schema | ✅ Yes | Regenerated via task schema:update |
| Dependency CVEs | pip-audit vulnerability findings |
⚠️ Partial | Raise floor + refresh lockfile, then re-run scan |
Output Interpretation
PASSED (All green):
====================== 1180 passed, 23 warnings in 12.76s ======================
All checks passed!
✓ Secretfile is valid
[Ready for commit]
FAILED (Issues found):
Found 3 errors.
1 file would be reformatted.
FAILED tests/test_X.py::TestY::test_z - assert 6 == 5
When failures occur:
- Skill auto-resolves what it can (formatting, unused vars)
- Re-runs validation
- Reports remaining issues with guidance
- If all resolved → report success
- If manual fixes needed → show what user needs to fix
Exit Codes
- 0: All checks passed ✅
- 1: Checks failed, some auto-resolved but manual fixes needed
- 201: Timeout or severe error (rare; usually schema or dependency issue)
Context Efficiency
This skill is designed to be lightweight for agents:
- ✅ Handles output parsing internally (no manual log parsing)
- ✅ Auto-resolves common issues
- ✅ Returns structured results (JSON-friendly)
- ✅ Works across sessions without setup
- ✅ Integrates seamlessly with other skills
For users: Just invoke it. The skill handles the rest.
For other skills: Can call this skill to guarantee pre-commit state before proceeding (e.g., finishing-a-development-branch auto-gates on validation pass).
Related Skills
verification-before-completion: Calls this skill as part of completion verificationfinishing-a-development-branch: Uses this as a hard gate before mergerequesting-code-review: Validates pre-commit passes before creating PR
04 同仓库更多 Skills
secretzero
Compatibility entrypoint for SecretZero skills. Enforces the absolute rule: never consume secrets in agent context — use SecretZero for all secret handling. Routes to secretzero-author, secretzero-agent, secretzero-handle, and secretzero-agent-adopt.
secretzero-handle
Use when the task touches `.env`, dotenv/json/yaml secret files, local `file` targets, or any workflow where secret material could enter agent context. Enforces `SZ_AGENT_MODE=true` spill-safe CLI usage, ingest preseed, strict manifest validation, and safe discovery patterns alongside `secretzero-agent` / `secretzero-author`.
secretzero-author
Use when authoring, reviewing, or walking a user through a new or existing `Secretfile.yml`. Guided session: manifest root, inventory table, optional local discovery, add/edit loop with secret-type and target menus, validate, optional `secretzero web`. Hermes + MCP notes included. Safe contextless discovery, `.szvar` lanes, policy-bound targets. Inherits absolute rule from `skills/secretzero/SKILL.md`. Co-load `skills/secretzero-handle/SKILL.md` for `.env` / spill-safe CLI.
secretzero-agent
Use for agentic and operational SecretZero workflows including unified `agent sync`, CLI/API/MCP parity, secure human-in-the-loop vectors, and automation-safe run loops.
secretzero-agent-adopt
Use for agent runtime integration: discover Hermes/OpenClaw installs, bootstrap SecretZero environments with `secretzero agent list` / `agent adopt`, lockfile preseed, and restore loops. Inherits absolute rule from `skills/secretzero/SKILL.md` (SecretZero only; never secrets in context).
secretzero
Compatibility entrypoint for SecretZero skills. Enforces the absolute rule: never consume secrets in agent context — use SecretZero for all secret handling. Routes to secretzero-author, secretzero-agent, secretzero-handle, and secretzero-agent-adopt.