feat(resource): add deferred physical resource types

Add 11 deferred physical resource types covering the git object taxonomy
(git, git-remote, git-branch, git-tag, git-commit, git-tree, git-tree-entry,
git-stash, git-submodule) and filesystem link types (fs-symlink, fs-hardlink).

- YAML configs under examples/resource-types/
- Bootstrap registration via _resource_registry_physical.py module
- Auto-discovery rules with bounded scan_depth (1-2) for git object graph
- fs-directory scan_depth=1 (immediate children only)
- git-branch scan_depth=1 (single HEAD), git-tree scan_depth=2 (capped)
- Updated fs-directory child_types/parent_types/auto_discovery
- Updated git-checkout child_types to include git
- Fixed git-tag child_types to include git-commit (DAG consistency)
- Behave tests, Robot tests, ASV benchmarks
- Documentation in docs/reference/resource_types_builtin.md

ISSUES CLOSED: #330

examples/resource-types/fs-directory.yaml

@@ -10,18 +10,23 @@ cli_args:
     type: path
     required: true
     description: "Path to the directory"
-parent_types: ["git-checkout", "fs-directory", "fs-mount"]
-child_types: ["fs-directory", "fs-file", "fs-symlink", "fs-hardlink"]
+parent_types: ["git-checkout", "fs-directory"]
+child_types: ["fs-directory", "fs-file", "fs-symlink", "fs-hardlink", "devcontainer-instance", "devcontainer-file"]
 auto_discovery:
   enabled: true
+  scan_depth: 1
   rules:
     - type: fs-directory
       pattern: "*/"
     - type: fs-file
       pattern: "*"
+    - type: fs-symlink
+      pattern: "symlink:*"
+    - type: fs-hardlink
+      pattern: "hardlink:*"
 capabilities:
   read: true
   write: true
   sandbox: true
   checkpoint: false
-handler: "cleveragents.resource.handlers.fs_directory"
+handler: "cleveragents.resource.handlers.fs_directory:FsDirectoryHandler"

examples/resource-types/fs-hardlink.yaml

@@ -0,0 +1,16 @@
+schema_version: "1.0"
+name: fs-hardlink
+description: "A hard link on the local filesystem — a file with link count > 1"
+resource_kind: physical
+sandbox_strategy: copy_on_write
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["fs-directory"]
+child_types: []
+capabilities:
+  read: true
+  write: true
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.fs_file:FilesystemHandler"

examples/resource-types/fs-symlink.yaml

@@ -0,0 +1,16 @@
+schema_version: "1.0"
+name: fs-symlink
+description: "A symbolic link on the local filesystem"
+resource_kind: physical
+sandbox_strategy: copy_on_write
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["fs-directory"]
+child_types: []
+capabilities:
+  read: true
+  write: false
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.fs_file:FilesystemHandler"

examples/resource-types/git-branch.yaml

@@ -0,0 +1,22 @@
+schema_version: "1.0"
+name: git-branch
+description: "A named branch ref (e.g., main, feature/auth)"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["git"]
+child_types: ["git-commit"]
+auto_discovery:
+  enabled: true
+  scan_depth: 1
+  rules:
+    - type: git-commit
+      pattern: "HEAD"
+capabilities:
+  read: true
+  write: true
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitRefHandler"

examples/resource-types/git-commit.yaml

@@ -0,0 +1,24 @@
+schema_version: "1.0"
+name: git-commit
+description: "A specific commit object"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+# Spec §23518 omits git-tag as parent; added because annotated tags
+# target commits directly, so the relationship is semantically correct.
+parent_types: ["git-branch", "git-tag", "git"]
+child_types: ["git-tree"]
+auto_discovery:
+  enabled: true
+  scan_depth: 1
+  rules:
+    - type: git-tree
+      pattern: "tree"
+capabilities:
+  read: true
+  write: false
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitObjectHandler"

examples/resource-types/git-remote.yaml

@@ -0,0 +1,16 @@
+schema_version: "1.0"
+name: git-remote
+description: "A remote URL configured on a git repo"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["git"]
+child_types: []
+capabilities:
+  read: true
+  write: false
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitConfigHandler"

examples/resource-types/git-stash.yaml

@@ -0,0 +1,16 @@
+schema_version: "1.0"
+name: git-stash
+description: "A stash entry (e.g., stash@{0})"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["git"]
+child_types: []
+capabilities:
+  read: true
+  write: true
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitRefHandler"

examples/resource-types/git-submodule.yaml

@@ -0,0 +1,16 @@
+schema_version: "1.0"
+name: git-submodule
+description: "A submodule reference — a pointer to another git repository at a specific commit and path"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["git"]
+child_types: []
+capabilities:
+  read: true
+  write: false
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitConfigHandler"

examples/resource-types/git-tag.yaml

@@ -0,0 +1,18 @@
+schema_version: "1.0"
+name: git-tag
+description: "A tag ref — lightweight or annotated (e.g., v1.0.0)"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["git"]
+# Annotated tags target commits; added for DAG consistency with
+# git-commit listing git-tag as a parent.
+child_types: ["git-commit"]
+capabilities:
+  read: true
+  write: true
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitRefHandler"

examples/resource-types/git-tree-entry.yaml

@@ -0,0 +1,16 @@
+schema_version: "1.0"
+name: git-tree-entry
+description: "A blob entry in a tree — a specific file's content at a specific path and mode"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["git-tree"]
+child_types: []
+capabilities:
+  read: true
+  write: false
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitObjectHandler"

examples/resource-types/git-tree.yaml

@@ -0,0 +1,25 @@
+schema_version: "1.0"
+name: git-tree
+description: "A tree object — a directory listing at a specific commit"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: false
+built_in: true
+cli_args: []
+parent_types: ["git-commit", "git-tree"]
+child_types: ["git-tree-entry", "git-tree"]
+auto_discovery:
+  enabled: true
+  scan_depth: 2
+  # Capped at 2 -- discovery engine must enforce global max_depth
+  rules:
+    - type: git-tree-entry
+      pattern: "blob *"
+    - type: git-tree
+      pattern: "tree *"
+capabilities:
+  read: true
+  write: false
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitObjectHandler"

examples/resource-types/git.yaml

@@ -0,0 +1,44 @@
+schema_version: "1.0"
+name: git
+description: "A git repository — the object database, refs, and full history"
+resource_kind: physical
+sandbox_strategy: none
+user_addable: true
+built_in: true
+cli_args:
+  - name: path
+    type: path
+    required: false
+    description: "Path to the local .git directory"
+  - name: url
+    type: string
+    required: false
+    description: "Remote URL of the git repository"
+parent_types: ["git-checkout"]
+child_types:
+  - "git-remote"
+  - "git-branch"
+  - "git-tag"
+  - "git-commit"
+  - "git-stash"
+  - "git-submodule"
+auto_discovery:
+  enabled: true
+  scan_depth: 1
+  rules:
+    - type: git-remote
+      pattern: "refs/remotes/*"
+    - type: git-branch
+      pattern: "refs/heads/*"
+    - type: git-tag
+      pattern: "refs/tags/*"
+    - type: git-stash
+      pattern: "refs/stash"
+    - type: git-submodule
+      pattern: ".gitmodules"
+capabilities:
+  read: true
+  write: false
+  sandbox: false
+  checkpoint: false
+handler: "cleveragents.resource.handlers.git:GitHandler"