Skip to content

feat: DeepSchema system for rich file schemas - #313

Merged
nhorton merged 15 commits into
mainfrom
deepspec
Mar 30, 2026
Merged

feat: DeepSchema system for rich file schemas#313
nhorton merged 15 commits into
mainfrom
deepspec

Conversation

@nhorton

@nhorton nhorton commented Mar 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Implements the DeepSchema feature: rich file-level schemas with automatic validation and review generation
  • Named schemas (.deepwork/schemas/, standard_schemas/, DEEPWORK_ADDITIONAL_SCHEMAS_FOLDERS env var) and anonymous schemas (.deepschema.<filename>.yml)
  • PostToolUse write hook validates json_schema_path and verification_bash_command on every Write/Edit, injects conformance notes
  • Generates synthetic DeepReview rules from schemas, integrated into /review and finished_step quality gate
  • Parent schema inheritance with circular reference detection

Test plan

  • 67 new unit tests across 6 test files (config, discovery, matcher, resolver, review_bridge, write_hook)
  • All 763 existing tests still pass
  • ruff lint clean
  • Manual: create a named schema with matchers + requirements, run /review to see synthetic review tasks
  • Manual: create a schema with verification_bash_command, write a violating file, verify error message

🤖 Generated with Claude Code

nhorton and others added 15 commits March 30, 2026 10:28
@nhorton
inital spec file
9df3542
@nhorton @claude
feat: implement DeepSchema system for rich file schemas with validati…
dc12f7f 
…on and review generation

DeepSchemas enrich the DeepReview system with file-level schemas that provide
automatic validation (JSON Schema + bash commands) on writes and synthetic
review rule generation at /review and finished_step time.

- Core module: src/deepwork/deepschema/ (config, discovery, matcher, resolver, review_bridge)
- Write hook: PostToolUse on Write/Edit validates and injects conformance notes
- Multi-source named schema discovery: project-local, standard_schemas/, DEEPWORK_ADDITIONAL_SCHEMAS_FOLDERS env var
- Parent schema inheritance with circular reference detection
- 67 new tests across 6 test files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
feat: add standard deepschema for deepschema files, review fixes, tes…
12d522d 
…t fixture

- Add self-describing DeepSchema in standard_schemas/deepschema/ with JSON
  Schema validation and 8 RFC 2119 requirements for deepschema.yml files
- Move deferred imports to top-level in review/mcp.py and quality_gate.py
  (review finding: DRY violation)
- Remove fragile string splitting for schema error paths (review finding)
- Add without_standard_schemas pytest fixture in conftest.py for clean
  test environments
- Fix tests to account for standard schemas being auto-discovered

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
docs: update documentation to reflect DeepSchema subsystem
366a2c1 
Update project structure trees, review pipeline descriptions, quality
gate docs, MCP tool descriptions, and hooks README to include the new
deepschema/ package, standard_schemas/, and write hook.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
chore: symlink job.schema.json into job_yml standard schema, update A…
d1fece9 
…GENTS.md

- Replace remote json_schema_path reference with local symlink
- Update AGENTS.md project structure tree for DeepSchema subsystem

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
fix: resolve ruff lint errors (import ordering, unused import)
93be21a 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
chore: gitignore .claude/worktrees/
5bc30a3 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
feat: add get_named_schemas MCP tool for schema discovery
17d6fc6 
Exposes named DeepSchema info (name, summary, matchers) via an MCP tool
so agents can discover what file schemas are defined in the project.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
fix: route hook context to agent via additionalContext instead of sys…
d22ce40 
…temMessage

systemMessage is displayed to the user but not the agent, so DeepSchema
conformance notes and validation errors were invisible to the model.
Switch all platforms to use hookSpecificOutput.additionalContext which
is injected into the agent's conversation context.

Also adds YAML file parsing support for JSON Schema validation in the
write hook (from another agent's fix).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
chore: add .deepreview rule for hook output routing to agent
e1b8f9b 
Ensures hooks use additionalContext (agent-visible) instead of
systemMessage (user-only) when the agent needs to act on the output.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
docs: add /deepschema skill and DeepSchemas section to README
9be31cb 
Adds a user-facing skill explaining how to create and manage DeepSchemas
(named and anonymous), plus a README section covering the feature.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
feat: add DW-REQ-011 DeepSchema requirements spec, review improvements
1420d63 
- Create formal requirements spec for the DeepSchema subsystem
- Add DW-REQ-006.6 reference to hook_output_routing .deepreview rule
- Update suggest_new_reviews to suggest both DeepSchemas and .deepreview rules
- Replace deepschema_schema.json copy with symlink (matches job_yml pattern)
- Apply ruff format fix to server.py

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
docs: fix stale documentation found during review
ef73918 
- Add deepschema skill to directory trees in architecture.md and CLAUDE.md
- Add get_named_schemas tool (#9) to architecture.md MCP tools section
- Update hooks README event mapping (add before_model, after_model, SubagentStop)
- Update hooks README tool mapping (add web_fetch, web_search, task)
- Add .deepreview to hooks README files table

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
docs: add deepschema skill to AGENTS.md project structure
20dbc39 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton @claude
docs: add RFC 2119 review severity logic to DW-REQ-011.8
f844229 
Captures how reviewers should treat MUST/SHOULD/MAY violations in
DeepSchema compliance reviews, matching the original design intent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nhorton
nhorton added this pull request to the merge queue Mar 30, 2026
Merged via the queue into main with commit 8de157c Mar 30, 2026
5 checks passed
@nhorton
nhorton deleted the deepspec branch March 30, 2026 18:39
ncrmro added a commit that referenced this pull request Mar 31, 2026
@ncrmro @claude
feat: DeepSchema system for rich file schemas (#313)
9ef68a4 
* inital spec file

* feat: implement DeepSchema system for rich file schemas with validation and review generation

DeepSchemas enrich the DeepReview system with file-level schemas that provide
automatic validation (JSON Schema + bash commands) on writes and synthetic
review rule generation at /review and finished_step time.

- Core module: src/deepwork/deepschema/ (config, discovery, matcher, resolver, review_bridge)
- Write hook: PostToolUse on Write/Edit validates and injects conformance notes
- Multi-source named schema discovery: project-local, standard_schemas/, DEEPWORK_ADDITIONAL_SCHEMAS_FOLDERS env var
- Parent schema inheritance with circular reference detection
- 67 new tests across 6 test files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add standard deepschema for deepschema files, review fixes, test fixture

- Add self-describing DeepSchema in standard_schemas/deepschema/ with JSON
  Schema validation and 8 RFC 2119 requirements for deepschema.yml files
- Move deferred imports to top-level in review/mcp.py and quality_gate.py
  (review finding: DRY violation)
- Remove fragile string splitting for schema error paths (review finding)
- Add without_standard_schemas pytest fixture in conftest.py for clean
  test environments
- Fix tests to account for standard schemas being auto-discovered

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update documentation to reflect DeepSchema subsystem

Update project structure trees, review pipeline descriptions, quality
gate docs, MCP tool descriptions, and hooks README to include the new
deepschema/ package, standard_schemas/, and write hook.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: symlink job.schema.json into job_yml standard schema, update AGENTS.md

- Replace remote json_schema_path reference with local symlink
- Update AGENTS.md project structure tree for DeepSchema subsystem

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: resolve ruff lint errors (import ordering, unused import)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: gitignore .claude/worktrees/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add get_named_schemas MCP tool for schema discovery

Exposes named DeepSchema info (name, summary, matchers) via an MCP tool
so agents can discover what file schemas are defined in the project.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: route hook context to agent via additionalContext instead of systemMessage

systemMessage is displayed to the user but not the agent, so DeepSchema
conformance notes and validation errors were invisible to the model.
Switch all platforms to use hookSpecificOutput.additionalContext which
is injected into the agent's conversation context.

Also adds YAML file parsing support for JSON Schema validation in the
write hook (from another agent's fix).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: add .deepreview rule for hook output routing to agent

Ensures hooks use additionalContext (agent-visible) instead of
systemMessage (user-only) when the agent needs to act on the output.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add /deepschema skill and DeepSchemas section to README

Adds a user-facing skill explaining how to create and manage DeepSchemas
(named and anonymous), plus a README section covering the feature.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add DW-REQ-011 DeepSchema requirements spec, review improvements

- Create formal requirements spec for the DeepSchema subsystem
- Add DW-REQ-006.6 reference to hook_output_routing .deepreview rule
- Update suggest_new_reviews to suggest both DeepSchemas and .deepreview rules
- Replace deepschema_schema.json copy with symlink (matches job_yml pattern)
- Apply ruff format fix to server.py

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: fix stale documentation found during review

- Add deepschema skill to directory trees in architecture.md and CLAUDE.md
- Add get_named_schemas tool (#9) to architecture.md MCP tools section
- Update hooks README event mapping (add before_model, after_model, SubagentStop)
- Update hooks README tool mapping (add web_fetch, web_search, task)
- Add .deepreview to hooks README files table

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add deepschema skill to AGENTS.md project structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add RFC 2119 review severity logic to DW-REQ-011.8

Captures how reviewers should treat MUST/SHOULD/MAY violations in
DeepSchema compliance reviews, matching the original design intent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nhorton