feat: add dependency introduction gate, evaluation bias hardening, plan-mode blocking, and docs refresh#237
Merged
sanmak merged 4 commits intoMar 29, 2026
Conversation
…an-mode blocking enforcement, and comprehensive docs refresh Three new features: (1) dependency introduction gate with 5-criteria evaluation for new packages, (2) evaluation bias hardening with score variance enforcement and mandatory findings, (3) plan-mode blocking enforcement via marker file state machine that blocks writes until plan-to-spec conversion completes. Documentation refreshed across 11 files to reflect all 29+ completed features -- added Antigravity platform coverage, dependency governance, evaluation/learnings overhead data, updated MARKETPLACE_SUBMISSIONS from v1.1.0 to v1.7.0, and added evaluation and learnings Mermaid diagrams.
File was missing from working tree before the previous commit. Recreated with v1.7.0 version, updated feature descriptions for all 5 platforms, and added Google Antigravity marketplace section.
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughAdds a new Dependency Introduction Gate (Phase 2 scanning, Phase 3 enforcement, audit drift check), hardens adversarial evaluation scoring and dispatcher model-diversity, and implements a plan-mode blocking enforcement marker workflow; wires these into generator templates/context/validation, installer hooks, platform outputs, tests, and documentation. Changes
Sequence Diagram(s)sequenceDiagram
participant Agent
participant design.md
participant dependencies.md
participant RegistryAPI as Registry API
participant GitHubAPI as GitHub API
participant User
Agent->>design.md: Scan for install commands
Agent->>dependencies.md: Read "Detected Dependencies"
Agent->>Agent: Compute net-new packages (<=10)
loop per package
Agent->>RegistryAPI: Query package metadata
alt timeout/failure
Agent->>GitHubAPI: Query repository metadata
end
alt both fail
Agent->>Agent: LLM fallback assessment
end
Agent->>User: ASK_USER (approve/reject + rationale)
end
User->>Agent: Submit decisions
Agent->>design.md: Write ### Dependency Decisions (Decision + rationale)
Agent->>dependencies.md: Update ## Dependency Introduction Policy
sequenceDiagram
participant User
participant PostToolUse
participant MarkerFile as .plan-pending-conversion
participant Agent
participant PreToolUse
participant FromPlan
User->>PostToolUse: Approve plan (ExitPlanMode)
PostToolUse->>MarkerFile: Create/touch marker in specsDir
Agent->>PreToolUse: Attempt write/edit
PreToolUse->>MarkerFile: Check presence
alt marker exists and path disallowed
PreToolUse->>Agent: Block write (exit 2) + stderr message
else allowed path
PreToolUse->>Agent: Allow
end
Agent->>FromPlan: Run /specops from-plan enforcement
FromPlan->>FromPlan: Run enforcement checks (8)
alt all pass
FromPlan->>MarkerFile: Remove marker
FromPlan->>Agent: Notify writes unblocked
else fail
FromPlan->>Agent: Notify conversion failed (marker retained)
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Introduces a dependency governance gate, hardens adversarial evaluation against self-confirmation bias, and enforces plan→spec conversion by blocking writes until /specops from-plan completes; updates generator/validation wiring and refreshes docs to reflect the expanded feature set and new Antigravity platform.
Changes:
- Adds a new always-on Dependency Introduction Gate module and integrates it across workflow, validation, templates, and platform outputs.
- Strengthens evaluation prompts/procedures (evidence-first, mandatory findings, score variance enforcement) and updates evaluation report templates.
- Implements plan-mode blocking via marker file lifecycle + Claude hooks installation, and refreshes documentation/diagrams/versioned references.
Reviewed changes
Copilot reviewed 80 out of 81 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_platform_consistency.py | Adds dependency-introduction marker category to required marker sets. |
| skills/specops/modes/steering.md | Adds “Dependency Introduction Policy” section to steering mode template. |
| skills/specops/modes/pipeline.md | Inserts dependency-introduction gate step and Phase 3 enforcement guidance; updates evaluation rubric text. |
| skills/specops/modes/init.md | Adds “Dependency Introduction Policy” section to init mode template. |
| skills/specops/modes/from-plan.md | Adds marker detection/removal and embeds Dependency Introduction Gate module content. |
| skills/specops/modes/audit.md | Expands audit from 6→7 checks, adding “Dependency Drift”. |
| skills/specops/SKILL.md | Updates routing/enforcement text (marker-based from-plan routing; evaluator model-diversity instruction). |
| scripts/remote-install.sh | Installs/updates Claude hooks: ExitPlanMode marker creation + PreToolUse Write/Edit guard. |
| platforms/claude/modes/steering.md | Adds “Dependency Introduction Policy” section to Claude steering mode output. |
| platforms/claude/modes/init.md | Adds “Dependency Introduction Policy” section to Claude init mode output. |
| platforms/claude/modes/from-plan.md | Adds marker detection/removal and embeds Dependency Introduction Gate module content. |
| platforms/claude/modes/audit.md | Expands audit from 6→7 checks, adding “Dependency Drift”. |
| platforms/claude/install.sh | Installs/updates Claude hooks: ExitPlanMode marker creation + PreToolUse Write/Edit guard. |
| platforms/claude/SKILL.md | Updates routing/enforcement text (marker-based from-plan routing; evaluator model-diversity instruction). |
| generator/validate.py | Adds DEPENDENCY_INTRODUCTION_MARKERS and validates them per-platform + cross-platform consistency loop. |
| generator/templates/cursor.j2 | Wires dependency_introduction module into Cursor output template. |
| generator/templates/copilot.j2 | Wires dependency_introduction module into Copilot output template. |
| generator/templates/codex.j2 | Wires dependency_introduction module into Codex output template. |
| generator/templates/claude.j2 | Wires dependency_introduction module into Claude output template. |
| generator/templates/antigravity.j2 | Wires dependency_introduction module into Antigravity output template. |
| generator/generate.py | Adds dependency_introduction to the common generation context. |
| docs/TOKEN-USAGE.md | Adds evaluation + production learnings overhead sections. |
| docs/TEAM_GUIDE.md | Extends platform behavior table to include Antigravity. |
| docs/STRUCTURE.md | Updates structure listing (new docs/scripts/core module entry) and bumps version/date. |
| docs/SECURITY-AUDIT.md | Adds post-audit feature review table and updated next-audit guidance. |
| docs/REFERENCE.md | Updates invocation/platform references and documents plan enforcement marker lifecycle + new config keys. |
| docs/MARKETPLACE_SUBMISSIONS.md | Refreshes marketplace copy, version, features list, and adds Antigravity submission section. |
| docs/DIAGRAMS.md | Adds Mermaid diagrams for adversarial evaluation and production learnings lifecycle. |
| docs/COMPARISON.md | Updates comparison matrix (adds dependency governance row; platform count 4→5). |
| docs/COMMANDS.md | Updates supported platforms statement and adds Antigravity section. |
| core/workflow.md | Integrates dependency introduction gate at Phase 2 step 5.8 and Phase 3 enforcement rule. |
| core/templates/evaluation.md | Changes evaluation report tables to Evidence/Findings-first format and adjusts verdict punctuation. |
| core/steering.md | Adds “Dependency Introduction Policy” section to dependencies.md steering template. |
| core/reconciliation.md | Expands audit from 6→7 checks, adding “Dependency Drift”. |
| core/mode-manifest.json | Registers dependency-introduction module for spec + from-plan modes. |
| core/from-plan.md | Adds marker detection/removal steps for plan-mode blocking lifecycle. |
| core/evaluation.md | Hardens evaluation prompts/procedures; adds dependency-aware guidance to coherence/fidelity dimensions. |
| core/dispatcher.md | Adds marker-based from-plan routing note; adds model-diversity instruction for delegated evaluators. |
| core/dependency-introduction.md | New core module defining the dependency introduction governance + enforcement procedures. |
| README.md | Adds dependency governance to problems/differentiators lists. |
| QUICKSTART.md | Adds next steps for production learnings and adversarial evaluation. |
| CLAUDE.md | Updates generator guidance and adds security-sensitive files list + contribution rules. |
| CHECKSUMS.sha256 | Updates checksums for generated/changed tracked files. |
| CHANGELOG.md | Adds Unreleased entry describing plan-mode blocking enforcement. |
| .specops/production-learnings/spec.json | Normalizes author shape to object with name. |
| .specops/plan-mode-blocking-enforcement/tasks.md | Adds spec artifact tasks documenting plan-mode blocking enforcement work. |
| .specops/plan-mode-blocking-enforcement/spec.json | Adds completed spec metadata for plan-mode blocking enforcement. |
| .specops/plan-mode-blocking-enforcement/requirements.md | Adds requirements for marker-based plan-mode blocking enforcement. |
| .specops/plan-mode-blocking-enforcement/implementation.md | Adds implementation journal for plan-mode blocking enforcement. |
| .specops/plan-mode-blocking-enforcement/evaluation.md | Adds implementation evaluation report for plan-mode blocking enforcement. |
| .specops/plan-mode-blocking-enforcement/design.md | Adds design doc for plan-mode blocking enforcement. |
| .specops/memory/patterns.json | Adds learningPatterns aggregation data. |
| .specops/memory/learnings.json | Adds a learning entry about evaluator self-confirmation bias. |
| .specops/memory/decisions.json | Adds decision records for plan-mode blocking + dependency introduction gate. |
| .specops/memory/context.md | Updates memory context with newly completed specs. |
| .specops/index.json | Adds new completed specs to index. |
| .specops/from-plan-enforcement-checklist/spec.json | Reformats specDependencies objects for readability. |
| .specops/evaluation-bias-hardening/tasks.md | Adds tasks for evaluation bias hardening work. |
| .specops/evaluation-bias-hardening/spec.json | Adds completed spec metadata for evaluation bias hardening. |
| .specops/evaluation-bias-hardening/requirements.md | Adds requirements for evaluation bias hardening. |
| .specops/evaluation-bias-hardening/implementation.md | Adds implementation journal for evaluation bias hardening. |
| .specops/evaluation-bias-hardening/evaluation.md | Adds implementation evaluation report for evaluation bias hardening. |
| .specops/evaluation-bias-hardening/design.md | Adds design doc for evaluation bias hardening. |
| .specops/dependency-introduction-gate/tasks.md | Adds tasks for dependency introduction gate work. |
| .specops/dependency-introduction-gate/spec.json | Adds completed spec metadata for dependency introduction gate. |
| .specops/dependency-introduction-gate/requirements.md | Adds requirements for dependency introduction gate. |
| .specops/dependency-introduction-gate/implementation.md | Adds implementation journal for dependency introduction gate. |
| .specops/dependency-introduction-gate/evaluation.md | Adds implementation evaluation report for dependency introduction gate. |
| .specops/dependency-introduction-gate/design.md | Adds design doc for dependency introduction gate. |
| .specops/adversarial-evaluation/spec.json | Normalizes author name and formatting. |
| .gitignore | Ignores .plan-pending-conversion marker file. |
| .claude/commands/docs-sync.md | Adds docs-sync mapping for core/dependency-introduction.md. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+814
to
+820
| ### Google Antigravity | ||
|
|
||
| - **Best for:** Multi-agent orchestration via Manager View | ||
| - **Capabilities:** Full feature set including sub-agent delegation (`canDelegateTask: true`) | ||
| - **Special features:** Same invocation pattern as Codex. Supports task delegation via Manager View agents. | ||
| - **Limitation:** Non-interactive (`canAskInteractive: false`) -- interview mode skipped, reconcile blocked | ||
|
|
There was a problem hiding this comment.
This section says Antigravity is non-interactive ("canAskInteractive: false"), but platforms/antigravity/platform.json currently sets canAskInteractive to true. Please reconcile the docs with the platform capability definition (either update the platform.json capability or adjust this documentation).
Comment on lines
+248
to
+256
| | Capability | Claude Code | Cursor | Codex | Copilot | Antigravity | | ||
| | --- | --- | --- | --- | --- | --- | | ||
| | Spec creation + spec.json | Full | Full | Full | Full | Full | | ||
| | Interactive review (ask questions) | Yes | Yes | No | Yes | No | | ||
| | Review feedback collection | Section-by-section | Section-by-section | All-in-prompt | Section-by-section | All-in-prompt | | ||
| | Verdict selection | Interactive choice | Interactive choice | Parsed from prompt | Interactive choice | Parsed from prompt | | ||
| | Revision mode | Interactive guidance | Interactive guidance | Prompt-directed | Interactive guidance | Prompt-directed | | ||
| | Implementation gate override | Ask user | Ask user | Hard stop | Ask user | Hard stop | | ||
| | Progress tracking | TodoWrite tool | Chat responses | stdout | Chat responses | stdout | |
There was a problem hiding this comment.
The table marks Antigravity as not interactive for review workflows, but platforms/antigravity/platform.json declares canAskInteractive: true. Please align this table with the platform capability source of truth so teams don’t make incorrect assumptions about required user interaction.
Comment on lines
+38
to
+39
| **Step 1.5 — Marker detection**: If FILE_EXISTS(`<specsDir>/.plan-pending-conversion`), NOTIFY_USER: "Plan-pending-conversion marker detected. Write/Edit on non-spec files is currently blocked by the PreToolUse guard. This marker will be removed after the post-conversion enforcement pass (step 6.5) succeeds, unblocking all writes." | ||
|
|
There was a problem hiding this comment.
The marker detection message references the post-conversion enforcement pass as “step 6.5”, but this file renumbered that pass to step 7 (“formerly step 6.5”). Update the message to reference step 7 (and keep “formerly 6.5” only where needed) to avoid misleading users during plan-mode blocking incidents.
Comment on lines
+38
to
+39
| **Step 1.5 — Marker detection**: If Use the Bash tool to check if the file exists at(`<specsDir>/.plan-pending-conversion`), Display a message to the user: "Plan-pending-conversion marker detected. Write/Edit on non-spec files is currently blocked by the PreToolUse guard. This marker will be removed after the post-conversion enforcement pass (step 6.5) succeeds, unblocking all writes." | ||
|
|
There was a problem hiding this comment.
The marker detection message still says the marker will be removed after the enforcement pass “(step 6.5)”, but this workflow renumbered that pass to step 7. Please update the step reference so it matches the actual numbered steps in this mode file.
Comment on lines
+38
to
+39
| **Step 1.5 — Marker detection**: If Use the Bash tool to check if the file exists at(`<specsDir>/.plan-pending-conversion`), Display a message to the user: "Plan-pending-conversion marker detected. Write/Edit on non-spec files is currently blocked by the PreToolUse guard. This marker will be removed after the post-conversion enforcement pass (step 6.5) succeeds, unblocking all writes." | ||
|
|
There was a problem hiding this comment.
The marker detection message references the enforcement pass as “step 6.5”, but the mode text renumbered that pass to step 7 (“formerly step 6.5”). Update the message to refer to step 7 so the instructions are internally consistent.
Comment on lines
+377
to
+380
| - Checked by the PreToolUse Write|Edit guard | ||
| - Removed by from-plan mode after the enforcement pass (step 6.5) succeeds | ||
| - Gitignored (ephemeral, not committed) | ||
|
|
There was a problem hiding this comment.
In the Plan Enforcement section, the marker removal bullet says the marker is removed after the enforcement pass “(step 6.5)”. The from-plan workflow now labels the enforcement pass as step 7 (“formerly step 6.5”). Update this reference to step 7 to match the current from-plan numbering.
Comment on lines
+78
to
+82
| | Feature | Version | Security Relevance | | ||
| | --- | --- | --- | | ||
| | **Dependency introduction gate** | v1.5.0 | Always-active gate evaluating new packages against 5 criteria (scope, maintenance, size, security, license). Uses `RUN_COMMAND` for install command detection. Review: path construction from package names, registry API calls. | | ||
| | **Plan-mode blocking enforcement** | Unreleased | Marker file state machine (`.plan-pending-conversion`) blocking Write/Edit via PreToolUse hook. Review: marker creation/deletion race conditions, allowed path prefix matching logic. | | ||
| | **Adversarial evaluation** | v1.7.0 | Hardcoded evaluator prompts (not configurable by users) reduce prompt injection risk. Evaluation scores are written to `evaluation.md` in specsDir. Review: evaluation output sanitization, score parsing. | |
There was a problem hiding this comment.
The post-audit table lists “Dependency introduction gate” as version v1.5.0, but this PR introduces/rewires the dependency introduction gate as part of the v1.7.0 docs refresh. Please correct the version in this row (and/or mark it Unreleased) so the security review checklist reflects when the feature actually shipped.
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
core/reconciliation.md (1)
192-206:⚠️ Potential issue | 🟠 MajorReconcile now includes Dependency Drift but has no repair path defined.
Line 192 runs all 7 checks, but the repair table has no explicit branch for Dependency Drift findings. This leaves reconcile behavior ambiguous for a newly introduced check.
🧭 Suggested doc fix
| Finding Type | Repair Options | | --- | --- | +| Dependency drift (unapproved package) | Mark informational only / Add approved decision in relevant spec design.md / Skip | | File missing (renamed) | Update path in tasks.md / Skip |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@core/reconciliation.md` around lines 192 - 206, The reconciliation doc currently lists repair actions for each Finding Type but omits a branch for "Dependency Drift"; update the table and step 8 to add a clear repair path for Dependency Drift (e.g., options such as "Update dependency to latest compatible version", "Pin dependency to a known-good version", "Run CI/tests and verify", or "Skip") and ensure the prose for the "For each selected finding, apply the appropriate repair" logic explicitly references "Dependency Drift" so reconcile behavior is unambiguous when that check is returned. Include the exact phrase "Dependency Drift" in the new table row and in step 8 so tooling or readers can match the check name to its repair options.
🟡 Minor comments (10)
docs/COMMANDS.md-817-820 (1)
817-820:⚠️ Potential issue | 🟡 MinorAvoid “Full feature set” wording for Antigravity.
This overstates capabilities given the same section explicitly notes non-interactive behavior with blocked reconcile and skipped interview mode.
Suggested wording adjustment
-- **Capabilities:** Full feature set including sub-agent delegation (`canDelegateTask: true`) +- **Capabilities:** Core spec workflow with sub-agent delegation support (`canDelegateTask: true`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/COMMANDS.md` around lines 817 - 820, The "Full feature set" phrasing for Antigravity overstates capabilities; update the description to remove "Full feature set" and accurately reflect that Antigravity supports sub-agent delegation (canDelegateTask: true) but is non-interactive (canAskInteractive: false) with interview mode skipped and reconcile blocked—e.g., change the first bullet to something like "Supports sub-agent delegation (`canDelegateTask: true`) but is non-interactive (`canAskInteractive: false`), interview mode skipped and reconcile blocked" so the three bullets are consistent.docs/COMMANDS.md-3-3 (1)
3-3:⚠️ Potential issue | 🟡 MinorInclude Antigravity in the quick-reference platform grouping.
The intro now lists Antigravity, but the quick-reference header still omits it, which can make command mapping ambiguous.
Suggested quick-reference header fix
-| Command | Claude Code | Cursor / Codex / Copilot | +| Command | Claude Code | Cursor / Codex / Copilot / Antigravity |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/COMMANDS.md` at line 3, The quick-reference header in COMMANDS.md omits Google Antigravity even though the intro mentions it; update the quick-reference header text (the header that groups platforms/columns) to include "Google Antigravity" or "Antigravity" alongside Claude Code, Cursor, OpenAI Codex, and GitHub Copilot so the platform grouping matches the intro and command mappings.docs/REFERENCE.md-378-378 (1)
378-378:⚠️ Potential issue | 🟡 MinorUpdate stale enforcement step number.
Line 378 still references “step 6.5”; this should match the current post-conversion enforcement step numbering (step 7) to keep operational docs consistent.Suggested patch
-- Removed by from-plan mode after the enforcement pass (step 6.5) succeeds +- Removed by from-plan mode after the enforcement pass (step 7) succeeds🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/REFERENCE.md` at line 378, Update the stale enforcement step number in the docs by replacing the phrase "step 6.5" with the current post-conversion enforcement step "step 7" in the sentence that reads "Removed by from-plan mode after the enforcement pass (step 6.5) succeeds" so the reference matches the current enforcement step numbering..specops/plan-mode-blocking-enforcement/evaluation.md-13-13 (1)
13-13:⚠️ Potential issue | 🟡 MinorFix stale workflow cross-reference in evaluation evidence.
Line 13 references marker removal after “step 6.5”, but the enforced post-conversion pass is now step 7.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specops/plan-mode-blocking-enforcement/evaluation.md at line 13, Update the stale workflow cross-reference in the evaluation evidence text: locate the sentence mentioning "marker removal after “step 6.5”" in .specops/plan-mode-blocking-enforcement/evaluation.md and change the referenced step to "step 7" so the line reads that the plan detector removes the marker after step 7; keep the rest of the sentence and context intact and ensure the numeric step matches the enforced post-conversion pass.docs/TOKEN-USAGE.md-84-84 (1)
84-84:⚠️ Potential issue | 🟡 MinorUse “bug fixes” for consistency and lint friendliness.
Line 84 uses “bugfixes”; use “bug fixes” to avoid style/spelling noise in docs QA.
✏️ Suggested doc tweak
-- **Phase 4 capture**: When triggered (auto mode: after all specs and bugfixes), the capture prompt adds approximately 100-200 tokens. +- **Phase 4 capture**: When triggered (auto mode: after all specs and bug fixes), the capture prompt adds approximately 100-200 tokens.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/TOKEN-USAGE.md` at line 84, Update the documentation text where the phrase "bugfixes" appears (specifically the Phase 4 capture line in TOKEN-USAGE.md) to use "bug fixes" for consistency; locate the string "**Phase 4 capture**: When triggered (auto mode: after all specs and bugfixes), the capture prompt adds approximately 100-200 tokens." and replace "bugfixes" with "bug fixes" so the line reads "...after all specs and bug fixes...".docs/MARKETPLACE_SUBMISSIONS.md-37-44 (1)
37-44:⚠️ Potential issue | 🟡 MinorFeature description is stale against current audit/reconcile behavior.
Line 37 still says drift detection has 5 checks, but this PR updates reconciliation to 7 checks. Also, Line 43 command list should include
reconcileif audit/reconcile is being advertised.📝 Suggested update
-> - Drift detection: 5 automated checks with audit and reconcile commands +> - Drift detection: 7 automated checks with audit and reconcile commands ... -> Commands: `/specops` (subcommands: `init`, `view`, `list`, `interview`, `steering`, `memory`, `learn`, `map`, `audit`, `pipeline`, `initiative`, `from-plan`, `feedback`, `version`, `update`) +> Commands: `/specops` (subcommands: `init`, `view`, `list`, `interview`, `steering`, `memory`, `learn`, `map`, `audit`, `reconcile`, `pipeline`, `initiative`, `from-plan`, `feedback`, `version`, `update`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/MARKETPLACE_SUBMISSIONS.md` around lines 37 - 44, Update the stale marketplace doc: change the "Drift detection: 5 automated checks" text to "7 automated checks" to match the updated reconciliation behavior, and add the "reconcile" subcommand to the /specops command list so it reads e.g. "... `audit`, `reconcile`, `pipeline`, ...". Locate the "Drift detection" bullet and the `/specops` commands line in MARKETPLACE_SUBMISSIONS.md and edit those two places accordingly to reflect the current audit/reconcile behavior..specops/plan-mode-blocking-enforcement/implementation.md-8-8 (1)
8-8:⚠️ Potential issue | 🟡 MinorMinor: Capitalize "GitHub" for consistency.
The static analysis tool correctly identified that "github" should be "GitHub" (the official capitalization).
-- Config: loaded from `.specops.json` -- vertical: builder, specsDir: .specops, taskTracking: github +- Config: loaded from `.specops.json` -- vertical: builder, specsDir: .specops, taskTracking: GitHub🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specops/plan-mode-blocking-enforcement/implementation.md at line 8, Update the capitalization in the configuration description: replace the lowercase token "github" in the string "Config: loaded from `.specops.json` -- vertical: builder, specsDir: .specops, taskTracking: github" with the correct "GitHub" so the line reads "... taskTracking: GitHub".platforms/antigravity/specops.md-2709-2712 (1)
2709-2712:⚠️ Potential issue | 🟡 MinorFix step-sequencing typo in From Plan flow.
Line 2709 says “Proceed to step 7” immediately after completing step 7, but the next step is 8. This can cause incorrect execution routing in non-interactive flows.
Suggested fix
- Proceed to step 7. + Proceed to step 8.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@platforms/antigravity/specops.md` around lines 2709 - 2712, The step-sequencing text in the "From Plan" flow is incorrect: change the literal "Proceed to step 7." to "Proceed to step 8." so the transition after completing step 7 correctly routes to step 8 (the **Complete** phase); update the single string that contains "Proceed to step 7." in the spec content so non-interactive routing and any references that parse step numbers use the correct target (step 8 / Complete)..specops/plan-mode-blocking-enforcement/tasks.md-5-32 (1)
5-32:⚠️ Potential issue | 🟡 MinorTask 1's completed state contradicts the branch contents.
This task says
core/dependency-introduction.mdwas deleted and no longer exists, but the branch also ships that module anddocs/STRUCTURE.mdnow lists it. Please rewrite this as a rollback-then-recreate step or remove it, otherwise the spec history is misleading.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specops/plan-mode-blocking-enforcement/tasks.md around lines 5 - 32, Task 1 claims deletion of core/dependency-introduction.md while the branch still contains that module and docs/STRUCTURE.md references it; update the task to reflect reality by either (A) converting it to a "rollback then recreate" workflow that first deletes core/dependency-introduction.md, updates docs/STRUCTURE.md and all references, commits the rollback, then adds a new create-task to reintroduce the module with proper SpecOps flow, or (B) remove Task 1 entirely and instead add a corrective task that synchronizes branch contents with SpecOps (remove or update the shipped module and STRUCTURE references), and update the Implementation Steps and Acceptance Criteria accordingly so Task 1 no longer claims a completed deletion that contradicts the branch..specops/dependency-introduction-gate/design.md-113-115 (1)
113-115:⚠️ Potential issue | 🟡 MinorFix drift-check count wording for consistency.
Line 114 still says “Six Drift Checks section” while this design introduces the 7th check.
📝 Suggested fix
- **Interface:** New check in the Six Drift Checks section of `core/reconciliation.md` + **Interface:** New check in the Seven Drift Checks section of `core/reconciliation.md`🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specops/dependency-introduction-gate/design.md around lines 113 - 115, Update the interface wording that currently says "Six Drift Checks section" to reflect the new seventh check: change the phrase in the Interface line to "Seven Drift Checks section of `core/reconciliation.md`" and ensure any cross-references or anchors in `core/reconciliation.md` that list/check count are updated to include the new 7th drift check introduced here; check the "Responsibility" and "Interface" lines for consistency with `core/dependency-safety.md` ecosystem detection and lock file parsing dependencies.
🧹 Nitpick comments (4)
docs/COMPARISON.md (1)
120-120: Use consistent platform naming for Antigravity.This row uses
Antigravitywhile the matrix above usesGoogle Antigravity. Aligning terminology avoids ambiguity.Suggested wording tweak
-| Supported platforms | 5 (Claude Code, Cursor, Codex, Copilot, Antigravity) | 26+ named agents + generic | +| Supported platforms | 5 (Claude Code, Cursor, Codex, Copilot, Google Antigravity) | 26+ named agents + generic |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/COMPARISON.md` at line 120, The comparison table row uses "Antigravity" while the matrix above uses "Google Antigravity"; update the table cell text in the diff (the string "Antigravity" in the Supported platforms row) to "Google Antigravity" so the terminology is consistent across the document.CLAUDE.md (1)
87-87: Consider aligning the security-sensitive file list with the canonical set.
Line 87 currently lists only part of the known sensitive files; this can dilute review rigor when other sensitive paths change. Prefer either a complete list or a pointer to one authoritative source to avoid drift.Based on learnings: “Security-sensitive files require extra scrutiny when modified … core/workflow.md, core/safety.md, core/review-workflow.md, core/feedback.md, schema.json, spec-schema.json, platforms/claude/SKILL.md, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, setup.sh, scripts/remote-install.sh, generator/generate.py, hooks/pre-commit, hooks/pre-push.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` at line 87, The sensitive-file list in CLAUDE.md is incomplete; update the list on the line that enumerates "Changes to these files require extra scrutiny" to either include the full canonical set (core/workflow.md, core/safety.md, core/review-workflow.md, core/feedback.md, schema.json, spec-schema.json, platforms/claude/SKILL.md, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, setup.sh, scripts/remote-install.sh, generator/generate.py, hooks/pre-commit, hooks/pre-push) or replace it with a single authoritative pointer (e.g., "see canonical-sensitive-files.txt" or similar) and ensure any referenced canonical file exists and is maintained; modify the CLAUDE.md sentence accordingly to use the chosen authoritative source or the expanded list so reviewers always see the complete set.scripts/remote-install.sh (2)
485-488: Silent fail-open on JSON parse errors is intentional but worth documenting.try: data = json.load(sys.stdin) fp = data.get('file_path', '') except Exception: sys.exit(0)This allows writes to proceed if stdin parsing fails. For a security guard, this is a reasonable default (avoid blocking legitimate operations due to unexpected input formats), but it means malformed hook invocations bypass the guard entirely.
Consider adding a comment clarifying this is intentional:
except Exception: + # Fail-open: don't block writes if hook receives unexpected input format sys.exit(0)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/remote-install.sh` around lines 485 - 488, The try/except around json.load(sys.stdin) that assigns data and fp and exits with sys.exit(0) on any Exception is intentionally a silent "fail-open" to allow writes when stdin parsing fails; update the code by inserting a clear explanatory comment immediately above the try/except block (around the json.load/sys.exit logic) stating that malformed hook input is intentionally allowed to pass (security guard will not block writes on JSON parse errors), include the rationale and any reference to expected input format, and mention that this behavior is deliberate and should only be changed with explicit review.
474-497: PreToolUse guard relies on dispatcher's path containment — verify this is intentional.The guard reads
specsDirfrom.specops.json(line 480) and allows writes to paths starting with that value (line 490). However, it doesn't independently validate thatspecsDiris contained within the project (no../rejection, no absolute path check).This appears to rely on the dispatcher's Path Containment rules (dispatcher.md lines 156-164) having already sanitized
.specops.jsonat configuration time. If a malicious.specops.jsonwithspecsDir: "../../../tmp"were somehow present, writes to../../../tmp/foo.mdwould be allowed.If dispatcher validation is the intended trust boundary: Consider adding a brief comment in the hook explaining this dependency for future maintainers.
If defense-in-depth is desired: Add path containment validation within the guard itself:
🛡️ Optional hardening
specs = json.load(open('.specops.json')).get('specsDir', '.specops') +# Path containment (defense-in-depth) +if specs.startswith('/') or '..' in specs: + specs = '.specops' marker = os.path.join(specs, '.plan-pending-conversion')🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/remote-install.sh` around lines 474 - 497, The PreToolUse guard in NEW_PRE_CMD uses the user-provided specsDir from .specops.json (the variable specs) to build allowed paths but does not validate that specs is a safe, project-contained path; update the python snippet inside NEW_PRE_CMD to either (A) add a clear inline comment stating this hook trusts dispatcher validation as the intended boundary, or (B — recommended for defense-in-depth) resolve specs to an absolute canonical path (realpath), reject absolute or parent-traversal values that escape the repo root (compare realpath(specs) against the repo root realpath), and only allow writes when the normalized file_path begins with the canonical specs path or other canonical allowed prefixes (marker, allowed list); reference variables to change: specs, marker, allowed, and the stdin-parsed fp handling.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.specops/dependency-introduction-gate/requirements.md:
- Line 135: The non-functional requirement "Performance: The dependency
introduction gate must not add more than 5 seconds to Phase 2 execution
(registry API calls use 10-second timeouts)" is internally inconsistent and
untestable; update the requirement for clarity and feasibility by either
increasing the cap to exceed the existing network call timeout (e.g., ≥10s) or
by changing it to a relative/operational metric (e.g., "should not add more than
50% of Phase 2's baseline time" or "should complete within X seconds under
normal network conditions"), and explicitly state the measurement method and
conditions (e.g., measured end-to-end during Phase 2 excluding external
retry/backoff delays, and under what network timeout assumptions). Ensure the
revised NFR replacing the original sentence references the "dependency
introduction gate" and "Phase 2" so reviewers can locate and validate the
change.
In @.specops/evaluation-bias-hardening/design.md:
- Around line 51-57: Update the model-diversity instruction so it is also
applied to the Phase 4A initial handoff path (the Phase 4A / step 5 entry that
dispatches the first implementation-evaluation subagent), not just dispatcher
steps 6 and 7; in core/dispatcher.md add the same prompt-level instruction ("If
your platform supports model selection, use a different model than the one that
generated the artifacts being evaluated. Model diversity reduces
self-confirmation bias.") to any dispatch logic that runs when Phase 4A/step 5
triggers a sub-agent dispatch with canDelegateTask: true (specifically for
Claude Code and Antigravity) so the first impl-eval subagent is covered by the
rule.
In @.specops/memory/decisions.json:
- Around line 158-160: The PreToolUse guard currently checks path prefixes using
any(fp.startswith(a) for a in allowed) which is vulnerable to symlink and
traversal bypasses; update the guard to first canonicalize the candidate path
and each allowed prefix using os.path.realpath (or abspath then realpath), then
verify containment using os.path.commonpath or an explicit directory-boundary
check (e.g., compare os.path.commonpath([real_fp, real_allowed]) ==
real_allowed) for each entry in allowed; reference the variables allowed and fp
and the PreToolUse guard where this check occurs and ensure allowed entries are
resolved to absolute/real paths before performing the containment test.
In @.specops/plan-mode-blocking-enforcement/requirements.md:
- Around line 76-77: Remove the stale deletion instruction referencing
`core/dependency-introduction.md` from the requirements text: find and delete
the line "- Delete `core/dependency-introduction.md` (created outside SpecOps
workflow)" and any duplicate occurrence (noted at the other location) so the
requirements no longer direct removal of an active module; leave a clear note if
you need to document that the file is now part of the intended system.
In `@core/dependency-introduction.md`:
- Around line 182-184: The Platform Adaptation section currently uses concrete
platform names in the examples (e.g., "Claude Code, Cursor, Copilot", "Codex")
which violates the core module guideline; update the bullets referencing
canAskInteractive and canTrackProgress to use abstract capability descriptions
instead of platform names (e.g., "capable of interactive prompts" vs
"non-interactive/default decision"), remove all concrete tool names, and
rephrase the examples so they reference capability states for canAskInteractive
and canTrackProgress (and any mention of default recommendation behavior) rather
than specific platforms or tool brands.
In `@core/evaluation.md`:
- Line 81: Update the "Score variance check" behavior in core/evaluation.md to
add a clear termination rule: when uniform scores are detected during the score
variance check (the "Score variance check" step that references re-running step
2 without consuming maxIterations), limit the automatic structural re-run to a
single retry; if the retry also yields uniform scores, treat it as a normal
failed iteration (record a failure message such as "Uniform scores detected
after retry -- iteration failed") and proceed to consume/advance maxIterations
as usual. Mention the exact rule near the existing "Score variance check" text
and apply the same change to the second occurrence of the rule (line ~156) so
the behavior is deterministic and cannot loop indefinitely.
- Around line 103-105: Update the "Design Fidelity" criterion wording to scope
dependency checks to only the dependencies introduced or changed by the current
spec: replace the phrase "all installed packages match the approved list in
design.md ### Dependency Decisions" with language like "packages added or
modified by this spec match the approved list in design.md ### Dependency
Decisions"; ensure the row titled "Design Fidelity" is the one edited and keep
the reference to the "### Dependency Decisions" section for guidance.
In `@core/from-plan.md`:
- Around line 38-39: The step-number references around the marker lifecycle are
inconsistent: update the text that mentions the .plan-pending-conversion marker
(and the PreToolUse guard) so it references the canonical "post-conversion
enforcement pass" instead of a mismatched numeric step (replace "step 6.5" with
the canonical phrase used elsewhere), and adjust the later loop reference so it
advances to the final completion step rather than looping back to "step 7" —
ensure both occurrences (the detection message referencing the marker and the
later flow that currently points to step 7) use the same canonical identifier
("post-conversion enforcement pass" / "completion step") so the
blocking→unblocking path is unambiguous.
In `@core/reconciliation.md`:
- Around line 109-112: The reconciliation step currently only collects approved
packages from specs with status == "completed", which is too narrow; update the
logic that reads index.json and enumerates specs (the READ_FILE and specsDir
logic) to include specs that are not explicitly rejected — for example, include
statuses like "completed" and "in-progress" (or any spec that contains a `###
Dependency Decisions` table) so approvals in actively implemented specs are
counted; keep the same extraction from each spec's `<spec-name>/design.md` where
`Decision == "Approved"` and build the union from that broader set to avoid
false warnings about approved-but-not-yet-completed dependencies.
In `@docs/STRUCTURE.md`:
- Around line 81-82: Update the "Three-Tier Architecture" section in CLAUDE.md
to include the new core module entry core/dependency-introduction.md (Dependency
introduction gate) in the inline list of core modules; locate the Three-Tier
Architecture section in CLAUDE.md and add core/dependency-introduction.md
alongside the existing entries such as core/workflow.md and
core/decomposition.md so the core modules list matches docs/STRUCTURE.md.
In `@platforms/antigravity/specops.md`:
- Around line 4151-4157: The "uniform scores → re-run without consuming
`maxIterations`" step can loop indefinitely; add a guarded re-evaluation cap:
introduce a `uniformReevalLimit` (e.g., 3) and a `uniformReevalCount` tracked in
`evaluation.spec` (updated when you detect "Uniform scores detected") and, when
`uniformReevalCount` >= `uniformReevalLimit`, stop auto re-runs and treat as a
failed evaluation (or proceed to Phase 3 with an incomplete-evaluation flag)
instead of repeating; update the logic described in "Score variance check" and
the step that edits `<specsDir>/<spec-name>/spec.json` to increment and persist
`uniformReevalCount` so the guard survives restarts.
- Around line 4136-4140: Mandatory-finding enforcement is bypassable when
minScore defaults to 7; update the evaluation logic that handles the "Mandatory
finding" rule and any cap-at-7 behavior so that a dimension with zero concrete
findings cannot pass even if minScore == 7: specifically, in the routine that
applies the cap (look for references to minScore, the "Mandatory finding" rule,
or cap-to-7 logic), add an explicit check that if findings.length === 0 (or
equivalent indicator) then mark the dimension as failed or assign a score below
minScore (e.g., 0) regardless of minScore, and ensure the final pass/fail
calculation respects this override so the default threshold cannot be used to
bypass the rule.
In `@platforms/claude/install.sh`:
- Around line 203-224: The PRE_CMD guard currently reads file_path from
data.get('file_path') and compares relative prefixes which fails for absolute
paths; update NEW_PRE_CMD so it extracts the path from the nested tool_input
(e.g., data.get('tool_input', {}).get('file_path', '')), convert both specs and
incoming fp to absolute normalized paths via os.path.abspath/os.path.normpath,
and replace the simple startswith checks with secure containment checks using
os.path.commonpath (or equivalent) to test whether fp lies inside specs,
'.claude/plans', or '.claude/memory' directories; ensure marker logic (marker =
os.path.join(specs, '.plan-pending-conversion')) still works with absolute specs
and exit codes remain unchanged.
---
Outside diff comments:
In `@core/reconciliation.md`:
- Around line 192-206: The reconciliation doc currently lists repair actions for
each Finding Type but omits a branch for "Dependency Drift"; update the table
and step 8 to add a clear repair path for Dependency Drift (e.g., options such
as "Update dependency to latest compatible version", "Pin dependency to a
known-good version", "Run CI/tests and verify", or "Skip") and ensure the prose
for the "For each selected finding, apply the appropriate repair" logic
explicitly references "Dependency Drift" so reconcile behavior is unambiguous
when that check is returned. Include the exact phrase "Dependency Drift" in the
new table row and in step 8 so tooling or readers can match the check name to
its repair options.
---
Minor comments:
In @.specops/dependency-introduction-gate/design.md:
- Around line 113-115: Update the interface wording that currently says "Six
Drift Checks section" to reflect the new seventh check: change the phrase in the
Interface line to "Seven Drift Checks section of `core/reconciliation.md`" and
ensure any cross-references or anchors in `core/reconciliation.md` that
list/check count are updated to include the new 7th drift check introduced here;
check the "Responsibility" and "Interface" lines for consistency with
`core/dependency-safety.md` ecosystem detection and lock file parsing
dependencies.
In @.specops/plan-mode-blocking-enforcement/evaluation.md:
- Line 13: Update the stale workflow cross-reference in the evaluation evidence
text: locate the sentence mentioning "marker removal after “step 6.5”" in
.specops/plan-mode-blocking-enforcement/evaluation.md and change the referenced
step to "step 7" so the line reads that the plan detector removes the marker
after step 7; keep the rest of the sentence and context intact and ensure the
numeric step matches the enforced post-conversion pass.
In @.specops/plan-mode-blocking-enforcement/implementation.md:
- Line 8: Update the capitalization in the configuration description: replace
the lowercase token "github" in the string "Config: loaded from `.specops.json`
-- vertical: builder, specsDir: .specops, taskTracking: github" with the correct
"GitHub" so the line reads "... taskTracking: GitHub".
In @.specops/plan-mode-blocking-enforcement/tasks.md:
- Around line 5-32: Task 1 claims deletion of core/dependency-introduction.md
while the branch still contains that module and docs/STRUCTURE.md references it;
update the task to reflect reality by either (A) converting it to a "rollback
then recreate" workflow that first deletes core/dependency-introduction.md,
updates docs/STRUCTURE.md and all references, commits the rollback, then adds a
new create-task to reintroduce the module with proper SpecOps flow, or (B)
remove Task 1 entirely and instead add a corrective task that synchronizes
branch contents with SpecOps (remove or update the shipped module and STRUCTURE
references), and update the Implementation Steps and Acceptance Criteria
accordingly so Task 1 no longer claims a completed deletion that contradicts the
branch.
In `@docs/COMMANDS.md`:
- Around line 817-820: The "Full feature set" phrasing for Antigravity
overstates capabilities; update the description to remove "Full feature set" and
accurately reflect that Antigravity supports sub-agent delegation
(canDelegateTask: true) but is non-interactive (canAskInteractive: false) with
interview mode skipped and reconcile blocked—e.g., change the first bullet to
something like "Supports sub-agent delegation (`canDelegateTask: true`) but is
non-interactive (`canAskInteractive: false`), interview mode skipped and
reconcile blocked" so the three bullets are consistent.
- Line 3: The quick-reference header in COMMANDS.md omits Google Antigravity
even though the intro mentions it; update the quick-reference header text (the
header that groups platforms/columns) to include "Google Antigravity" or
"Antigravity" alongside Claude Code, Cursor, OpenAI Codex, and GitHub Copilot so
the platform grouping matches the intro and command mappings.
In `@docs/MARKETPLACE_SUBMISSIONS.md`:
- Around line 37-44: Update the stale marketplace doc: change the "Drift
detection: 5 automated checks" text to "7 automated checks" to match the updated
reconciliation behavior, and add the "reconcile" subcommand to the /specops
command list so it reads e.g. "... `audit`, `reconcile`, `pipeline`, ...".
Locate the "Drift detection" bullet and the `/specops` commands line in
MARKETPLACE_SUBMISSIONS.md and edit those two places accordingly to reflect the
current audit/reconcile behavior.
In `@docs/REFERENCE.md`:
- Line 378: Update the stale enforcement step number in the docs by replacing
the phrase "step 6.5" with the current post-conversion enforcement step "step 7"
in the sentence that reads "Removed by from-plan mode after the enforcement pass
(step 6.5) succeeds" so the reference matches the current enforcement step
numbering.
In `@docs/TOKEN-USAGE.md`:
- Line 84: Update the documentation text where the phrase "bugfixes" appears
(specifically the Phase 4 capture line in TOKEN-USAGE.md) to use "bug fixes" for
consistency; locate the string "**Phase 4 capture**: When triggered (auto mode:
after all specs and bugfixes), the capture prompt adds approximately 100-200
tokens." and replace "bugfixes" with "bug fixes" so the line reads "...after all
specs and bug fixes...".
In `@platforms/antigravity/specops.md`:
- Around line 2709-2712: The step-sequencing text in the "From Plan" flow is
incorrect: change the literal "Proceed to step 7." to "Proceed to step 8." so
the transition after completing step 7 correctly routes to step 8 (the
**Complete** phase); update the single string that contains "Proceed to step 7."
in the spec content so non-interactive routing and any references that parse
step numbers use the correct target (step 8 / Complete).
---
Nitpick comments:
In `@CLAUDE.md`:
- Line 87: The sensitive-file list in CLAUDE.md is incomplete; update the list
on the line that enumerates "Changes to these files require extra scrutiny" to
either include the full canonical set (core/workflow.md, core/safety.md,
core/review-workflow.md, core/feedback.md, schema.json, spec-schema.json,
platforms/claude/SKILL.md, .claude-plugin/plugin.json,
.claude-plugin/marketplace.json, setup.sh, scripts/remote-install.sh,
generator/generate.py, hooks/pre-commit, hooks/pre-push) or replace it with a
single authoritative pointer (e.g., "see canonical-sensitive-files.txt" or
similar) and ensure any referenced canonical file exists and is maintained;
modify the CLAUDE.md sentence accordingly to use the chosen authoritative source
or the expanded list so reviewers always see the complete set.
In `@docs/COMPARISON.md`:
- Line 120: The comparison table row uses "Antigravity" while the matrix above
uses "Google Antigravity"; update the table cell text in the diff (the string
"Antigravity" in the Supported platforms row) to "Google Antigravity" so the
terminology is consistent across the document.
In `@scripts/remote-install.sh`:
- Around line 485-488: The try/except around json.load(sys.stdin) that assigns
data and fp and exits with sys.exit(0) on any Exception is intentionally a
silent "fail-open" to allow writes when stdin parsing fails; update the code by
inserting a clear explanatory comment immediately above the try/except block
(around the json.load/sys.exit logic) stating that malformed hook input is
intentionally allowed to pass (security guard will not block writes on JSON
parse errors), include the rationale and any reference to expected input format,
and mention that this behavior is deliberate and should only be changed with
explicit review.
- Around line 474-497: The PreToolUse guard in NEW_PRE_CMD uses the
user-provided specsDir from .specops.json (the variable specs) to build allowed
paths but does not validate that specs is a safe, project-contained path; update
the python snippet inside NEW_PRE_CMD to either (A) add a clear inline comment
stating this hook trusts dispatcher validation as the intended boundary, or (B —
recommended for defense-in-depth) resolve specs to an absolute canonical path
(realpath), reject absolute or parent-traversal values that escape the repo root
(compare realpath(specs) against the repo root realpath), and only allow writes
when the normalized file_path begins with the canonical specs path or other
canonical allowed prefixes (marker, allowed list); reference variables to
change: specs, marker, allowed, and the stdin-parsed fp handling.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: f672bc45-8b1b-403e-be92-6f54ae1a9264
⛔ Files ignored due to path filters (20)
CHECKSUMS.sha256is excluded by!CHECKSUMS.sha256platforms/claude/SKILL.mdis excluded by!platforms/claude/SKILL.mdplatforms/claude/SKILL.monolithic.mdis excluded by!platforms/claude/SKILL.monolithic.mdplatforms/claude/modes/audit.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/from-plan.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/init.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/pipeline.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/spec.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/steering.mdis excluded by!platforms/*/modes/*.mdplatforms/codex/SKILL.mdis excluded by!platforms/codex/SKILL.mdplatforms/copilot/specops.instructions.mdis excluded by!platforms/copilot/specops.instructions.mdplatforms/cursor/specops.mdcis excluded by!platforms/cursor/specops.mdcskills/specops/SKILL.mdis excluded by!skills/specops/SKILL.mdskills/specops/SKILL.monolithic.mdis excluded by!skills/*/SKILL.monolithic.mdskills/specops/modes/audit.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/from-plan.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/init.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/pipeline.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/spec.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/steering.mdis excluded by!skills/*/modes/*.md
📒 Files selected for processing (61)
.claude/commands/docs-sync.md.gitignore.specops/adversarial-evaluation/spec.json.specops/dependency-introduction-gate/design.md.specops/dependency-introduction-gate/evaluation.md.specops/dependency-introduction-gate/implementation.md.specops/dependency-introduction-gate/requirements.md.specops/dependency-introduction-gate/spec.json.specops/dependency-introduction-gate/tasks.md.specops/evaluation-bias-hardening/design.md.specops/evaluation-bias-hardening/evaluation.md.specops/evaluation-bias-hardening/implementation.md.specops/evaluation-bias-hardening/requirements.md.specops/evaluation-bias-hardening/spec.json.specops/evaluation-bias-hardening/tasks.md.specops/from-plan-enforcement-checklist/spec.json.specops/index.json.specops/memory/context.md.specops/memory/decisions.json.specops/memory/learnings.json.specops/memory/patterns.json.specops/plan-mode-blocking-enforcement/design.md.specops/plan-mode-blocking-enforcement/evaluation.md.specops/plan-mode-blocking-enforcement/implementation.md.specops/plan-mode-blocking-enforcement/requirements.md.specops/plan-mode-blocking-enforcement/spec.json.specops/plan-mode-blocking-enforcement/tasks.md.specops/production-learnings/spec.jsonCHANGELOG.mdCLAUDE.mdQUICKSTART.mdREADME.mdcore/dependency-introduction.mdcore/dispatcher.mdcore/evaluation.mdcore/from-plan.mdcore/mode-manifest.jsoncore/reconciliation.mdcore/steering.mdcore/templates/evaluation.mdcore/workflow.mddocs/COMMANDS.mddocs/COMPARISON.mddocs/DIAGRAMS.mddocs/MARKETPLACE_SUBMISSIONS.mddocs/REFERENCE.mddocs/SECURITY-AUDIT.mddocs/STRUCTURE.mddocs/TEAM_GUIDE.mddocs/TOKEN-USAGE.mdgenerator/generate.pygenerator/templates/antigravity.j2generator/templates/claude.j2generator/templates/codex.j2generator/templates/copilot.j2generator/templates/cursor.j2generator/validate.pyplatforms/antigravity/specops.mdplatforms/claude/install.shscripts/remote-install.shtests/test_platform_consistency.py
Comment on lines
+51
to
+57
| ### 4. Dispatcher Model Diversity (`core/dispatcher.md`) | ||
|
|
||
| Steps 6 and 7 gain a model diversity instruction for `canDelegateTask: true` dispatch: | ||
|
|
||
| > When dispatching the evaluator sub-agent, include this instruction in the sub-agent prompt: "If your platform supports model selection, use a different model than the one that generated the artifacts being evaluated. Model diversity reduces self-confirmation bias." | ||
|
|
||
| This is a prompt-level instruction, not a platform capability. It applies to Claude Code and Antigravity (the two `canDelegateTask: true` platforms). |
There was a problem hiding this comment.
Include the initial Phase 4A handoff in this model-diversity rule.
Restricting the instruction to dispatcher steps 6 and 7 still leaves the first implementation-evaluation subagent uncovered, because step 7 only runs after a failed evaluation/remediation cycle. The design should also attach the same instruction to the Phase 4A entry path (step 5 / equivalent initial impl-eval dispatch).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.specops/evaluation-bias-hardening/design.md around lines 51 - 57, Update
the model-diversity instruction so it is also applied to the Phase 4A initial
handoff path (the Phase 4A / step 5 entry that dispatches the first
implementation-evaluation subagent), not just dispatcher steps 6 and 7; in
core/dispatcher.md add the same prompt-level instruction ("If your platform
supports model selection, use a different model than the one that generated the
artifacts being evaluated. Model diversity reduces self-confirmation bias.") to
any dispatch logic that runs when Phase 4A/step 5 triggers a sub-agent dispatch
with canDelegateTask: true (specifically for Claude Code and Antigravity) so the
first impl-eval subagent is covered by the rule.
Comment on lines
4151
to
4157
| 3. **Score variance check**: After all dimensions are scored, check whether all dimension scores are identical. If all scores are the same value, the evaluation auto-fails: record "Uniform scores detected -- re-evaluate with distinct per-dimension justification" and re-run the evaluation from step 2. This re-run does NOT consume a `maxIterations` cycle. | ||
| 4. Create the file at `<specsDir>/<spec-name>/evaluation.md` using the Evaluation Report Template. If the file already exists, append the new iteration (do not overwrite prior iterations). | ||
| 5. Edit the file at `<specsDir>/<spec-name>/spec.json` to update the `evaluation.spec` object with `iterations`, `passed`, `scores`, and `evaluatedAt`. | ||
| 6. If ALL dimensions score at or above `minScore`: evaluation passes -- signal for Phase 3 dispatch. | ||
| 7. If ANY dimension scores below `minScore` AND current iteration < `maxIterations`: evaluation fails -- signal for Phase 2 revision with evaluation.md feedback as input context. | ||
| 8. If ANY dimension scores below `minScore` AND current iteration >= `maxIterations`: Tell the user("Spec evaluation did not pass after {iterations} iterations. Proceeding to implementation with known spec gaps: {list of failing dimensions}.") and signal for Phase 3 dispatch with an incomplete evaluation flag. | ||
|
|
There was a problem hiding this comment.
Guard score-variance re-evaluation against infinite loops.
The “uniform scores → re-run without consuming maxIterations” rule can loop forever if the evaluator keeps returning identical scores.
Suggested fix
-3. **Score variance check**: After all dimensions are scored, check whether all dimension scores are identical. If all scores are the same value, the evaluation auto-fails: record "Uniform scores detected -- re-evaluate with distinct per-dimension justification" and re-run the evaluation from step 2. This re-run does NOT consume a `maxIterations` cycle.
+3. **Score variance check**: After all dimensions are scored, check whether all dimension scores are identical.
+ - If all scores are identical on the first attempt, record "Uniform scores detected -- re-evaluate with distinct per-dimension justification" and re-run once.
+ - If scores are still identical after one re-run, treat the evaluation as failed for this iteration and continue with normal iteration accounting (`maxIterations` applies).Also applies to: 4226-4232
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@platforms/antigravity/specops.md` around lines 4151 - 4157, The "uniform
scores → re-run without consuming `maxIterations`" step can loop indefinitely;
add a guarded re-evaluation cap: introduce a `uniformReevalLimit` (e.g., 3) and
a `uniformReevalCount` tracked in `evaluation.spec` (updated when you detect
"Uniform scores detected") and, when `uniformReevalCount` >=
`uniformReevalLimit`, stop auto re-runs and treat as a failed evaluation (or
proceed to Phase 3 with an incomplete-evaluation flag) instead of repeating;
update the logic described in "Score variance check" and the step that edits
`<specsDir>/<spec-name>/spec.json` to increment and persist `uniformReevalCount`
so the guard survives restarts.
…ardening, drift scope, docs - Fix step 6.5→7 and 7→8 references in core/from-plan.md and docs/REFERENCE.md - Fix PreToolUse guard: read tool_input.file_path, use absolute path containment - Cap score variance re-evaluation at one re-run to prevent infinite loops - Cap mandatory-finding score at minScore-1 to prevent bypass at default threshold - Scope dependency check to spec-introduced packages only - Widen dependency drift approved set to include in-progress/in-review specs - Remove platform names from core/dependency-introduction.md (platform-agnostic) - Add core/dependency-introduction.md to CLAUDE.md module list - Reconcile Antigravity canAskInteractive docs with platform.json (true) - Fix security audit version for dependency introduction gate - Remove stale delete instruction for core/dependency-introduction.md - Resolve contradictory 5s/10s performance requirement
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
core/reconciliation.md (1)
109-109:⚠️ Potential issue | 🟠 MajorStatus filter likely misses active specs (
implementing) in approved-union extraction.Line 109 uses
"in-progress", but this module’s lifecycle usesimplementing(see Line 67/Line 90). That mismatch can exclude currently implementing specs from the approved dependency union and produce falseDependency Driftwarnings.Suggested fix
-3. **Collect approved dependencies**: READ_FILE(`<specsDir>/index.json`) to enumerate all specs. For each spec with `status` in (`"completed"`, `"in-progress"`, `"in-review"`), READ_FILE(`<specsDir>/<spec-name>/design.md`) and extract packages from the `### Dependency Decisions` table where `Decision` is `Approved`. Build a union set of all approved packages across all matching specs. Including in-progress and in-review specs prevents false warnings for dependencies that were approved in a spec's design but whose spec is not yet completed. +3. **Collect approved dependencies**: READ_FILE(`<specsDir>/index.json`) to enumerate all specs. For each spec with `status` in (`"completed"`, `"implementing"`, `"in-review"`), READ_FILE(`<specsDir>/<spec-name>/design.md`) and extract packages from the `### Dependency Decisions` table where `Decision` is `Approved`. Build a union set of all approved packages across all matching specs. Including implementing and in-review specs prevents false warnings for dependencies that were approved in a spec's design but whose spec is not yet completed.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@core/reconciliation.md` at line 109, The status filter in the approved-dependencies collection step currently checks for "completed", "in-progress", and "in-review" which mismatches this module's lifecycle (which uses "implementing"); update the list of accepted statuses used when enumerating specs (the READ_FILE(`<specsDir>/index.json`) filtering step) to include "implementing" alongside "completed" and "in-review" so specs in the implementing state are included in the approved-union and avoid false Dependency Drift warnings.
🧹 Nitpick comments (1)
platforms/claude/install.sh (1)
230-239: Replace existingspecops-plan-guardcommands instead of skipping them.
NEW_PRE_CMDchanged in this branch, but rerunning the installer keeps any existingspecops-plan-guardcommand verbatim. That makes guard fixes non-upgradable. Mirroring the PostToolUse replacement behavior here will keep reinstalls deterministic.Suggested update path
- if "specops-plan-guard" in hook.get("command", ""): - found_pre = True - print("PreToolUse Write/Edit guard already installed (skipped)") + if "specops-plan-guard" in hook.get("command", ""): + hook["command"] = NEW_PRE_CMD + found_pre = True + print("Updated PreToolUse Write/Edit guard") break🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@platforms/claude/install.sh` around lines 230 - 239, The PreToolUse detection currently sets found_pre True and skips when any existing hook.command contains "specops-plan-guard", which prevents replacing stale commands (e.g., NEW_PRE_CMD); change the logic in the loop that inspects settings["hooks"]["PreToolUse"] so that instead of skipping on match it replaces the matching hook's "command" with the new command string (the same update approach used for PostToolUse), ensuring you update the found_pre flag appropriately and preserve other hook fields; reference the variables/functions found_pre, settings["hooks"]["PreToolUse"], and the "specops-plan-guard" command string when making the change.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Line 87: Update the security-sensitive files statement in CLAUDE.md so it is
not presented as a definitive, exhaustive list: either expand the list to
include the missing sensitive files (e.g., add core/feedback.md,
spec-schema.json, platforms/claude/SKILL.md, .claude-plugin/plugin.json,
.claude-plugin/marketplace.json and any other repo-specific guardrail/config
files) or change the sentence to explicitly indicate non-exhaustiveness (e.g.,
“includes, but is not limited to:” before the enumerated files). Ensure you
reference the existing symbols in the file (the current listed entries:
core/workflow.md, core/safety.md, core/review-workflow.md, schema.json,
setup.sh, scripts/remote-install.sh, generator/generate.py, hooks/pre-commit,
hooks/pre-push) and either append the additional filenames or switch the wording
to clarify the list is illustrative rather than complete.
In `@platforms/antigravity/specops.md`:
- Line 2319: The approved-dependencies filter is using the wrong status value:
replace the `"in-progress"` status check with the workflow's active status
`"implementing"` wherever the approved-set is built (e.g., in the code that
reads `<specsDir>/index.json` and filters specs by `status` for the
approved-set/collectApprovedDependencies logic) so specs with status
`"implementing"` are included along with `"completed"` and `"in-review"` when
extracting `### Dependency Decisions` entries marked `Approved`.
In `@platforms/claude/install.sh`:
- Around line 173-180: The NEW_POST_CMD currently resolves .specops.json and the
specsDir relative to the session CWD; change it to always root to the project by
prefixing/cd to $CLAUDE_PROJECT_DIR and canonicalizing paths before use.
Specifically update NEW_POST_CMD so the python JSON lookup opens
"$CLAUDE_PROJECT_DIR/.specops.json" (or computes specsDir relative to
$CLAUDE_PROJECT_DIR), create the "$CLAUDE_PROJECT_DIR/$SPECS_DIR" directory, and
write the marker to "$CLAUDE_PROJECT_DIR/$SPECS_DIR/.plan-pending-conversion";
mirror the same $CLAUDE_PROJECT_DIR rooting/canonicalization approach used in
the PreToolUse guard to ensure containment checks use project-rooted absolute
paths.
---
Duplicate comments:
In `@core/reconciliation.md`:
- Line 109: The status filter in the approved-dependencies collection step
currently checks for "completed", "in-progress", and "in-review" which
mismatches this module's lifecycle (which uses "implementing"); update the list
of accepted statuses used when enumerating specs (the
READ_FILE(`<specsDir>/index.json`) filtering step) to include "implementing"
alongside "completed" and "in-review" so specs in the implementing state are
included in the approved-union and avoid false Dependency Drift warnings.
---
Nitpick comments:
In `@platforms/claude/install.sh`:
- Around line 230-239: The PreToolUse detection currently sets found_pre True
and skips when any existing hook.command contains "specops-plan-guard", which
prevents replacing stale commands (e.g., NEW_PRE_CMD); change the logic in the
loop that inspects settings["hooks"]["PreToolUse"] so that instead of skipping
on match it replaces the matching hook's "command" with the new command string
(the same update approach used for PostToolUse), ensuring you update the
found_pre flag appropriately and preserve other hook fields; reference the
variables/functions found_pre, settings["hooks"]["PreToolUse"], and the
"specops-plan-guard" command string when making the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: c8e628dd-12bc-415a-b64d-b95896f97b2a
⛔ Files ignored due to path filters (14)
CHECKSUMS.sha256is excluded by!CHECKSUMS.sha256platforms/claude/SKILL.monolithic.mdis excluded by!platforms/claude/SKILL.monolithic.mdplatforms/claude/modes/audit.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/from-plan.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/pipeline.mdis excluded by!platforms/*/modes/*.mdplatforms/claude/modes/spec.mdis excluded by!platforms/*/modes/*.mdplatforms/codex/SKILL.mdis excluded by!platforms/codex/SKILL.mdplatforms/copilot/specops.instructions.mdis excluded by!platforms/copilot/specops.instructions.mdplatforms/cursor/specops.mdcis excluded by!platforms/cursor/specops.mdcskills/specops/SKILL.monolithic.mdis excluded by!skills/*/SKILL.monolithic.mdskills/specops/modes/audit.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/from-plan.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/pipeline.mdis excluded by!skills/*/modes/*.mdskills/specops/modes/spec.mdis excluded by!skills/*/modes/*.md
📒 Files selected for processing (13)
.specops/dependency-introduction-gate/requirements.md.specops/plan-mode-blocking-enforcement/requirements.mdCLAUDE.mdcore/dependency-introduction.mdcore/evaluation.mdcore/from-plan.mdcore/reconciliation.mddocs/COMMANDS.mddocs/REFERENCE.mddocs/SECURITY-AUDIT.mddocs/TEAM_GUIDE.mdplatforms/antigravity/specops.mdplatforms/claude/install.sh
✅ Files skipped from review due to trivial changes (6)
- docs/COMMANDS.md
- docs/TEAM_GUIDE.md
- docs/SECURITY-AUDIT.md
- docs/REFERENCE.md
- .specops/dependency-introduction-gate/requirements.md
- .specops/plan-mode-blocking-enforcement/requirements.md
🚧 Files skipped from review as they are similar to previous changes (2)
- core/from-plan.md
- core/dependency-introduction.md
|
|
||
| ## Security-Sensitive Files | ||
|
|
||
| Changes to these files require extra scrutiny: `core/workflow.md`, `core/safety.md`, `core/review-workflow.md`, `schema.json`, `setup.sh`, `scripts/remote-install.sh`, `generator/generate.py`, `hooks/pre-commit`, `hooks/pre-push`. These control agent behavior, security guardrails, configuration validation, file system operations, or output generation. Core modules must use abstract operations and validate user-supplied paths (relative, contained under repo root, no `../` traversal). |
There was a problem hiding this comment.
Security-sensitive file list looks incomplete; make it exhaustive or explicitly non-exhaustive.
The current wording reads as definitive, but several known sensitive files are missing. Either add the omitted files or change wording to “includes (not limited to)” to avoid under-scoping reviews.
✏️ Suggested doc fix
-Changes to these files require extra scrutiny: `core/workflow.md`, `core/safety.md`, `core/review-workflow.md`, `schema.json`, `setup.sh`, `scripts/remote-install.sh`, `generator/generate.py`, `hooks/pre-commit`, `hooks/pre-push`. These control agent behavior, security guardrails, configuration validation, file system operations, or output generation. Core modules must use abstract operations and validate user-supplied paths (relative, contained under repo root, no `../` traversal).
+Changes to these files require extra scrutiny (including but not limited to): `core/workflow.md`, `core/safety.md`, `core/review-workflow.md`, `core/feedback.md`, `schema.json`, `spec-schema.json`, `platforms/claude/SKILL.md`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `setup.sh`, `scripts/remote-install.sh`, `generator/generate.py`, `hooks/pre-commit`, `hooks/pre-push`. These control agent behavior, security guardrails, configuration validation, file system operations, or output generation. Core modules must use abstract operations and validate user-supplied paths (relative, contained under repo root, no `../` traversal).Based on learnings: "Security-sensitive files require extra scrutiny when modified — they can alter agent behavior, security guardrails, or configuration validation: core/workflow.md, core/safety.md, core/review-workflow.md, core/feedback.md, schema.json, spec-schema.json, platforms/claude/SKILL.md, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, setup.sh, scripts/remote-install.sh, generator/generate.py, hooks/pre-commit, hooks/pre-push."
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Changes to these files require extra scrutiny: `core/workflow.md`, `core/safety.md`, `core/review-workflow.md`, `schema.json`, `setup.sh`, `scripts/remote-install.sh`, `generator/generate.py`, `hooks/pre-commit`, `hooks/pre-push`. These control agent behavior, security guardrails, configuration validation, file system operations, or output generation. Core modules must use abstract operations and validate user-supplied paths (relative, contained under repo root, no `../` traversal). | |
| Changes to these files require extra scrutiny (including but not limited to): `core/workflow.md`, `core/safety.md`, `core/review-workflow.md`, `core/feedback.md`, `schema.json`, `spec-schema.json`, `platforms/claude/SKILL.md`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `setup.sh`, `scripts/remote-install.sh`, `generator/generate.py`, `hooks/pre-commit`, `hooks/pre-push`. These control agent behavior, security guardrails, configuration validation, file system operations, or output generation. Core modules must use abstract operations and validate user-supplied paths (relative, contained under repo root, no `../` traversal). |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` at line 87, Update the security-sensitive files statement in
CLAUDE.md so it is not presented as a definitive, exhaustive list: either expand
the list to include the missing sensitive files (e.g., add core/feedback.md,
spec-schema.json, platforms/claude/SKILL.md, .claude-plugin/plugin.json,
.claude-plugin/marketplace.json and any other repo-specific guardrail/config
files) or change the sentence to explicitly indicate non-exhaustiveness (e.g.,
“includes, but is not limited to:” before the enumerated files). Ensure you
reference the existing symbols in the file (the current listed entries:
core/workflow.md, core/safety.md, core/review-workflow.md, schema.json,
setup.sh, scripts/remote-install.sh, generator/generate.py, hooks/pre-commit,
hooks/pre-push) and either append the additional filenames or switch the wording
to clarify the list is illustrative rather than complete.
Comment on lines
+173
to
+180
| NEW_POST_CMD = ( | ||
| 'if [ -f .specops.json ]; then ' | ||
| 'SPECS_DIR=$(python3 -c "import json; print(json.load(open(\'.specops.json\')).get(\'specsDir\',\'.specops\'))" 2>/dev/null || echo ".specops"); ' | ||
| 'mkdir -p "$SPECS_DIR"; ' | ||
| 'touch "$SPECS_DIR/.plan-pending-conversion"; ' | ||
| 'echo "SPECOPS ENFORCEMENT: Plan approved. Marker set at $SPECS_DIR/.plan-pending-conversion. ' | ||
| 'Write/Edit on non-spec files is blocked until /specops from-plan converts the plan into a structured spec."; ' | ||
| 'fi # specops-hook' |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n platforms/claude/install.sh | head -250 | tail -100Repository: sanmak/specops
Length of output: 4577
🌐 Web query:
Anthropic Claude code hooks CLAUDE_PROJECT_DIR documentation
💡 Result:
CLAUDE_PROJECT_DIR is an environment variable automatically set by Anthropic's Claude Code tool when executing hooks. It points to the root directory of the current project, enabling hook scripts to reference project-specific files and resources reliably, regardless of the hook's execution context or working directory. Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that run automatically at specific lifecycle points in Claude Code sessions, such as before/after tool use, session start/end, directory changes, etc. They provide deterministic control for tasks like formatting code, blocking dangerous commands, sending notifications, or reloading environment variables. To use CLAUDE_PROJECT_DIR in a hook script, reference it directly in commands within settings.json, e.g.: json { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": ""$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh" } ] } ] } } This allows the script at .claude/hooks/protect-files.sh to access project files via $CLAUDE_PROJECT_DIR. Configuration is done in JSON files like ~/.claude/settings.json (user-wide), .claude/settings.json (project-specific, commit-able), or .claude/settings.local.json (local overrides). Use /hooks in Claude Code to browse configured hooks. Official documentation: - Hooks guide: https://docs.anthropic.com/en/docs/claude-code/hooks-guide and https://code.claude.com/docs/en/hooks-guide - Hooks reference: https://docs.anthropic.com/en/docs/claude-code/hooks and https://code.claude.com/docs/en/hooks - Full docs index: https://code.claude.com/docs/llms.txt
Citations:
- 1: https://docs.anthropic.com/en/docs/claude-code/hooks-guide
- 2: https://docs.anthropic.com/en/docs/claude-code/hooks
- 3: https://code.claude.com/docs/en/hooks
- 4: https://code.claude.com/docs/en/hooks-guide
- 5: https://docs.anthropic.com/en/docs/claude-code/settings
- 6: http://code.claude.com/docs/en/env-vars
🏁 Script executed:
rg 'CLAUDE_PROJECT_DIR' platforms/claude/ --type sh --type pyRepository: sanmak/specops
Length of output: 40
🏁 Script executed:
rg '\$CLAUDE_PROJECT_DIR' --type sh --type pyRepository: sanmak/specops
Length of output: 40
🏁 Script executed:
head -20 platforms/claude/install.shRepository: sanmak/specops
Length of output: 529
Root both hook commands at $CLAUDE_PROJECT_DIR, not the session CWD.
Claude's hook execution context may not be the project root. Both hooks resolve .specops.json, .claude/plans, .claude/memory, and relative specsDir values against the current working directory, creating a silent bypass: if a hook runs from a nested directory, the PostToolUse hook will miss the config, and the PreToolUse guard will skip enforcement without error.
The PreToolUse guard's sys.exit(0) when .specops.json is not found in CWD means writes to non-spec files can proceed unchecked if the hook is not rooted to the project directory. Fix both commands to root all paths to $CLAUDE_PROJECT_DIR and canonicalize before containment checks.
Suggested fix for PreToolUse guard
NEW_PRE_CMD = (
"python3 -c \"\n"
"import json, sys, os\n"
- "if not os.path.isfile('.specops.json'):\n"
+ "project = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())\n"
+ "config = os.path.join(project, '.specops.json')\n"
+ "if not os.path.isfile(config):\n"
" sys.exit(0)\n"
- "specs = json.load(open('.specops.json')).get('specsDir', '.specops')\n"
+ "specs = json.load(open(config)).get('specsDir', '.specops')\n"
+ "specs = os.path.realpath(specs if os.path.isabs(specs) else os.path.join(project, specs))\n"
"marker = os.path.join(os.path.abspath(specs), '.plan-pending-conversion')\n"
"if not os.path.isfile(marker):\n"
" sys.exit(0)\n"
"try:\n"
" data = json.load(sys.stdin)\n"
" fp = data.get('tool_input', {}).get('file_path', '')\n"
"except Exception:\n"
" sys.exit(0)\n"
"if not fp:\n"
" sys.exit(0)\n"
- "fp = os.path.normpath(os.path.abspath(fp))\n"
- "allowed = [os.path.abspath(specs), os.path.abspath('.claude/plans'), os.path.abspath('.claude/memory')]\n"
+ "fp = os.path.realpath(fp)\n"
+ "allowed = [specs, os.path.realpath(os.path.join(project, '.claude/plans')), os.path.realpath(os.path.join(project, '.claude/memory'))]\n"Apply the same $CLAUDE_PROJECT_DIR base in NEW_POST_CMD (lines 173–180) for .specops.json and .plan-pending-conversion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@platforms/claude/install.sh` around lines 173 - 180, The NEW_POST_CMD
currently resolves .specops.json and the specsDir relative to the session CWD;
change it to always root to the project by prefixing/cd to $CLAUDE_PROJECT_DIR
and canonicalizing paths before use. Specifically update NEW_POST_CMD so the
python JSON lookup opens "$CLAUDE_PROJECT_DIR/.specops.json" (or computes
specsDir relative to $CLAUDE_PROJECT_DIR), create the
"$CLAUDE_PROJECT_DIR/$SPECS_DIR" directory, and write the marker to
"$CLAUDE_PROJECT_DIR/$SPECS_DIR/.plan-pending-conversion"; mirror the same
$CLAUDE_PROJECT_DIR rooting/canonicalization approach used in the PreToolUse
guard to ensure containment checks use project-rooted absolute paths.
…atus enum - remote-install.sh: mirror install.sh fix -- use tool_input.file_path, add empty-path guard, switch to os.path.commonpath for path containment - core/reconciliation.md: replace invalid "in-progress" status with "implementing" per spec-schema.json enum
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 80 out of 81 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+206
to
+210
| "if not os.path.isfile('.specops.json'):\n" | ||
| " sys.exit(0)\n" | ||
| "specs = json.load(open('.specops.json')).get('specsDir', '.specops')\n" | ||
| "marker = os.path.join(os.path.abspath(specs), '.plan-pending-conversion')\n" | ||
| "if not os.path.isfile(marker):\n" |
There was a problem hiding this comment.
The injected PreToolUse guard will raise and exit non-zero if .specops.json exists but contains invalid JSON (e.g., partial write), because json.load(open('.specops.json')) is not wrapped in a try/except. PreToolUse non-zero exits can cause unexpected blocking or noisy stack traces; this guard should fail-open (exit 0) on JSON decode / IO errors when reading .specops.json and also handle os.path.commonpath ValueError defensively.
Comment on lines
+478
to
+482
| "if not os.path.isfile('.specops.json'):\n" | ||
| " sys.exit(0)\n" | ||
| "specs = json.load(open('.specops.json')).get('specsDir', '.specops')\n" | ||
| "marker = os.path.join(os.path.abspath(specs), '.plan-pending-conversion')\n" | ||
| "if not os.path.isfile(marker):\n" |
There was a problem hiding this comment.
Same as the local installer: the PreToolUse guard command loads .specops.json without handling JSON decode / IO failures. If .specops.json is malformed, the hook process will exit non-zero and may disrupt tool execution. Wrap the .specops.json load in a try/except and fail-open (exit 0) on errors; also consider guarding os.path.commonpath against ValueError to avoid unexpected non-zero exits.
|
|
||
| ## Summary | ||
|
|
||
| Upgraded the ExitPlanMode hook enforcement from advisory to blocking using a marker file state machine. The PostToolUse hook now creates a `.plan-pending-conversion` marker in specsDir when a plan is approved. A new PreToolUse Write|Edit guard blocks non-spec writes (exit code 2) when the marker exists, allowing only writes to specsDir, `.claude/plans/`, and `.claude/memory/`. The marker is removed by `from-plan` mode after the post-conversion enforcement pass (step 6.5) succeeds. Both local and remote installers updated with idempotent hook installation. Core modules (`core/from-plan.md`, `core/dispatcher.md`) document the marker lifecycle using abstract operations. All 10 tasks completed, 8/8 tests pass, 200+ validation checks pass, ShellCheck clean, checksums valid. |
There was a problem hiding this comment.
The summary still says the marker is removed after the enforcement pass at “step 6.5”, but core/from-plan.md renumbered the post-conversion enforcement pass to step 7 (“formerly 6.5”). Update the journal text to reference step 7 so the spec artifact doesn’t conflict with the shipped workflow instructions.
Suggested change
| Upgraded the ExitPlanMode hook enforcement from advisory to blocking using a marker file state machine. The PostToolUse hook now creates a `.plan-pending-conversion` marker in specsDir when a plan is approved. A new PreToolUse Write|Edit guard blocks non-spec writes (exit code 2) when the marker exists, allowing only writes to specsDir, `.claude/plans/`, and `.claude/memory/`. The marker is removed by `from-plan` mode after the post-conversion enforcement pass (step 6.5) succeeds. Both local and remote installers updated with idempotent hook installation. Core modules (`core/from-plan.md`, `core/dispatcher.md`) document the marker lifecycle using abstract operations. All 10 tasks completed, 8/8 tests pass, 200+ validation checks pass, ShellCheck clean, checksums valid. | |
| Upgraded the ExitPlanMode hook enforcement from advisory to blocking using a marker file state machine. The PostToolUse hook now creates a `.plan-pending-conversion` marker in specsDir when a plan is approved. A new PreToolUse Write|Edit guard blocks non-spec writes (exit code 2) when the marker exists, allowing only writes to specsDir, `.claude/plans/`, and `.claude/memory/`. The marker is removed by `from-plan` mode after the post-conversion enforcement pass (step 7, formerly 6.5) succeeds. Both local and remote installers updated with idempotent hook installation. Core modules (`core/from-plan.md`, `core/dispatcher.md`) document the marker lifecycle using abstract operations. All 10 tasks completed, 8/8 tests pass, 200+ validation checks pass, ShellCheck clean, checksums valid. |
Comment on lines
+31
to
+66
| |-- enforcement pass (step 6.5) succeeds | ||
| |-- removes marker: rm -f .specops/.plan-pending-conversion | ||
| v | ||
| Write/Edit now unblocked -- implementation proceeds through spec | ||
| ``` | ||
|
|
||
| ### PostToolUse Hook (Upgraded) | ||
|
|
||
| Current (advisory): | ||
| ```bash | ||
| test -f .specops.json && echo "SPECOPS HOOK: ..." # specops-hook | ||
| ``` | ||
|
|
||
| New (creates marker + advisory): | ||
| ```bash | ||
| if [ -f .specops.json ]; then SPECS_DIR=$(python3 -c "import json; print(json.load(open('.specops.json')).get('specsDir','.specops'))" 2>/dev/null || echo ".specops"); mkdir -p "$SPECS_DIR"; touch "$SPECS_DIR/.plan-pending-conversion"; echo "SPECOPS ENFORCEMENT: Plan approved. Marker set at $SPECS_DIR/.plan-pending-conversion. Write/Edit on non-spec files is blocked until /specops from-plan converts the plan into a structured spec."; fi # specops-hook | ||
| ``` | ||
|
|
||
| Key elements: | ||
| - Reads `specsDir` from `.specops.json` (defaults to `.specops`) | ||
| - Creates the directory if needed (`mkdir -p`) | ||
| - Creates the marker file (`touch`) | ||
| - Emits a user-visible enforcement message | ||
| - `# specops-hook` marker preserved for idempotent detection | ||
|
|
||
| ### PreToolUse Guard (New) | ||
|
|
||
| ```json | ||
| { | ||
| "matcher": "Write|Edit", | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "python3 -c \"\nimport json, sys, os\nif not os.path.isfile('.specops.json'):\n sys.exit(0)\nspecs = json.load(open('.specops.json')).get('specsDir', '.specops')\nmarker = os.path.join(specs, '.plan-pending-conversion')\nif not os.path.isfile(marker):\n sys.exit(0)\ntry:\n data = json.load(sys.stdin)\n fp = data.get('file_path', '')\nexcept Exception:\n sys.exit(0)\nallowed = [specs + '/', '.claude/plans/', '.claude/memory/']\nif any(a in fp for a in allowed):\n sys.exit(0)\nprint('SPECOPS ENFORCEMENT: A plan was approved but not yet converted to a spec.', file=sys.stderr)\nprint('Run /specops from-plan to convert the plan before implementing.', file=sys.stderr)\nprint(f'Blocked write to: {fp}', file=sys.stderr)\nsys.exit(2)\n\" # specops-plan-guard" | ||
| } | ||
| ] |
There was a problem hiding this comment.
This design doc’s state machine and PreToolUse guard example no longer match the implemented hook logic: it references enforcement pass “step 6.5” (now step 7), reads fp = data.get('file_path', '') (actual hook reads data['tool_input']['file_path']), and uses substring allowlisting (any(a in fp ...)) rather than the abspath + commonpath containment check used in the installer scripts. Please update the example to match the current hook behavior to prevent copy/paste of a broken guard.
Comment on lines
+35
to
+38
| > - Dependency introduction gate: 5-criteria evaluation before any new package install | ||
| > - Dependency safety scanning: CVE and EOL detection with configurable severity thresholds | ||
| > - Drift detection: 5 automated checks with audit and reconcile commands | ||
| > - Task delegation: fresh sub-agent contexts per task to prevent context exhaustion |
There was a problem hiding this comment.
Documentation mismatch: this list still says “Drift detection: 5 automated checks”, but audit/reconciliation now defines 7 drift checks (including Dependency Drift). Update the marketing copy to reflect the current check count so users aren’t confused when audit reports show 7 categories.
Comment on lines
96
to
99
| | Agent hallucinates vague acceptance criteria | EARS notation for precise requirements: `WHEN [event] THE SYSTEM SHALL [behavior]` | | ||
| | Specs drift from codebase after implementation | 5 automated drift checks with audit and reconcile commands | | ||
| | AI adds packages without checking maintenance or license | Dependency introduction gate: 5-criteria evaluation (scope, maintenance, size, security, license) before any install | | ||
| | Agent marks its own work as "done" without scrutiny | Adversarial evaluation: separate evaluator scores specs and implementations against hard thresholds | |
There was a problem hiding this comment.
The Problems table says “5 automated drift checks with audit and reconcile commands”, but audit/reconciliation has been updated to run 7 drift checks (including Dependency Drift). Please update this row to keep README consistent with the current audit mode behavior.
9 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
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
core/dependency-introduction.mdwith Install Command Patterns (7 ecosystems), Build-vs-Install Evaluation Framework, Maintenance Profile Intelligence, and Phase 2/3 integrationcore/from-plan.mdChanges
core/dependency-introduction.md-- new module for dependency introduction governancecore/evaluation.md-- bias hardening: score variance enforcement, mandatory findings, evidence-first scoringcore/from-plan.md-- plan-mode marker detection (step 1.5), lint fix for ordered list numberingcore/dispatcher.md,core/reconciliation.md,core/steering.md,core/workflow.md-- integration touchpointsplatforms/claude/install.sh,scripts/remote-install.sh-- PreToolUse Write|Edit guard for plan-mode blockinggenerator/generate.py,generator/validate.py,generator/templates/*.j2-- pipeline wiring for dependency introductiontests/test_platform_consistency.py-- DEPENDENCY_INTRODUCTION_MARKERS consistency checkdocs/REFERENCE.md-- added Antigravity to invocation, taskDelegation and runLogging config options, version 1.7.0docs/STRUCTURE.md-- fixed mode count 13→15, added missing doc/test/script entries, version 1.7.0docs/COMMANDS.md-- added Google Antigravity platform sectionREADME.md-- added dependency introduction gate to problems table and differentiatorsQUICKSTART.md-- added production learnings and evaluation to Next Stepsdocs/COMPARISON.md-- fixed platform count 4→5, added dependency governance rowdocs/TOKEN-USAGE.md-- added Evaluation Overhead and Learnings Overhead sectionsdocs/TEAM_GUIDE.md-- added Antigravity column to Platform Review Behavior tabledocs/MARKETPLACE_SUBMISSIONS.md-- updated v1.1.0→v1.7.0, refreshed all feature descriptions, added Antigravity sectiondocs/SECURITY-AUDIT.md-- added Post-Audit Feature Review (v1.5.0-v1.7.0) tabledocs/DIAGRAMS.md-- added Adversarial Evaluation and Production Learnings Lifecycle Mermaid diagrams.specops/-- spec artifacts for dependency-introduction-gate, evaluation-bias-hardening, plan-mode-blocking-enforcementTest Plan
Summary by CodeRabbit
New Features
Quality & Safety
Audit Enhancements
Greptile Summary
This PR adds three new SpecOps enforcement features — a dependency introduction gate, evaluation bias hardening, and plan-mode blocking — together with a broad documentation refresh across 11 files and a new Google Antigravity platform. The three previously reported P0/P1 issues (relative-path prefix deadlock in
install.sh/remote-install.sh, unbounded variance re-evaluation loop incore/evaluation.md, and too-narrow spec status scope in the dependency drift check) are all resolved.Key changes:
core/dependency-introduction.md— new module: 5-criterion Build-vs-Install framework, 3-layer Maintenance Profile Intelligence, Phase 2 gate procedure, Phase 3 enforcement, and auto-policy accumulation independencies.mdplatforms/claude/install.sh/scripts/remote-install.sh— PostToolUse hook upgraded to a marker-creating version; new PreToolUse Write/Edit guard usingos.path.commonpath+os.path.abspath(fixes the prior absolute-path deadlock)core/evaluation.md— evidence-first scoring, mandatory findings per dimension, score variance re-check capped at one retry (fixes the prior infinite loop)core/reconciliation.md— 7th drift check for unapproved packages; approved-set now includes"implementing"and"in-review"specs (fixes the prior false-positive issue)generator/validate.py—DEPENDENCY_INTRODUCTION_MARKERSwired into consistency validation;EVALUATION_MARKERSadded to cross-platform consistency loopRemaining findings (all P2):
"protocol breach"inDEPENDENCY_INTRODUCTION_MARKERSis trivially satisfied by the dispatcher routing table already present in all generated files — it's a no-op validatorcore/from-plan.mdfires unconditionally without checking thermexit codeConfidence Score: 5/5
Safe to merge — all prior P0/P1 issues are addressed; remaining findings are P2 suggestions that do not affect correctness in normal operation.
All three previously flagged critical issues (absolute-path deadlock, infinite variance loop, false-positive drift check) have been resolved. The remaining three findings are edge cases that do not affect normal workflow execution and are appropriate to address in a follow-up.
core/dependency-introduction.md (>10-dep silent cap), core/from-plan.md (unconditional rm notification), generator/validate.py (no-op protocol breach marker)
Important Files Changed
Sequence Diagram
sequenceDiagram participant U as User participant CC as Claude Code participant PostHook as PostToolUse Hook participant PreHook as PreToolUse Guard participant FP as from-plan mode participant FS as File System U->>CC: Approves plan (ExitPlanMode) CC->>PostHook: Trigger ExitPlanMode hook PostHook->>FS: touch .specops/.plan-pending-conversion PostHook-->>CC: Marker set — Write/Edit blocked CC->>U: Notify: run /specops from-plan U->>CC: /specops from-plan CC->>FP: Route to from-plan mode FP->>FS: Read plan content FP->>FS: Write spec artifacts (.specops/name/*.md) Note over PreHook,FS: Write to .specops/ is allowed — guard passes FP->>FP: Run 8 post-conversion enforcement checks FP->>FS: rm -f .specops/.plan-pending-conversion FP-->>U: Marker removed — Write/Edit unblocked CC->>U: Attempt write to src/app.ts CC->>PreHook: Trigger PreToolUse Write|Edit PreHook->>FS: Check .plan-pending-conversion exists? FS-->>PreHook: No (removed) PreHook-->>CC: exit(0) — allow writeReviews (3): Last reviewed commit: "fix: correct remote-install.sh PreToolUs..." | Re-trigger Greptile