archivebox-api 1.0.1__tar.gz → 2.5.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/.pre-commit-config.yaml +33 -46
  2. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/AGENTS.md +54 -28
  3. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/LICENSE +1 -1
  4. {archivebox_api-1.0.1/archivebox_api.egg-info → archivebox_api-2.5.1}/PKG-INFO +116 -90
  5. archivebox_api-1.0.1/PKG-INFO → archivebox_api-2.5.1/README.md +105 -106
  6. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/__init__.py +34 -22
  7. archivebox_api-2.5.1/archivebox_api/__main__.py +4 -0
  8. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/api/api_client_auth.py +1 -3
  9. archivebox_api-2.5.1/archivebox_api/api/api_client_base.py +82 -0
  10. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/api/api_client_cli.py +2 -7
  11. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/api/api_client_core.py +2 -9
  12. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/auth.py +10 -5
  13. archivebox_api-2.5.1/archivebox_api/connector_manifest.yml +172 -0
  14. archivebox_api-2.5.1/archivebox_api/connectors/mcp_source_presets.json +18 -0
  15. archivebox_api-2.5.1/archivebox_api/connectors/tool_schema_fingerprints.json +8 -0
  16. archivebox_api-2.5.1/archivebox_api/kg_ingest.py +433 -0
  17. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/mcp_config.json +8 -3
  18. archivebox_api-2.5.1/archivebox_api/mcp_server.py +432 -0
  19. archivebox_api-2.5.1/archivebox_api/ontology/__init__.py +7 -0
  20. archivebox_api-2.5.1/archivebox_api/ontology/archivebox.ttl +99 -0
  21. archivebox_api-2.5.1/archivebox_api/ontology/certification.json +36 -0
  22. archivebox_api-2.5.1/archivebox_api/ontology/fixtures/records.json +21 -0
  23. archivebox_api-2.5.1/archivebox_api/ontology/mappings/source.yaml +20 -0
  24. archivebox_api-2.5.1/archivebox_api/ontology/migrations/manifest.json +6 -0
  25. archivebox_api-2.5.1/archivebox_api/ontology/shapes/connector.shacl.ttl +44 -0
  26. archivebox_api-2.5.1/archivebox_api/prompts/web_archivist_specialist.json +43 -0
  27. archivebox_api-2.5.1/archivebox_api/skills/__init__.py +0 -0
  28. archivebox_api-2.5.1/archivebox_api/skills/archivebox-api-operations/SKILL.md +33 -0
  29. archivebox_api-2.5.1/archivebox_api/skills/archivebox-api-operations/agents/openai.yaml +4 -0
  30. archivebox_api-2.5.1/archivebox_api/skills/archivebox-api-operations/references/catalog.md +7 -0
  31. archivebox_api-2.5.1/archivebox_api/skills/archivebox-kg-ingestion/SKILL.md +91 -0
  32. archivebox_api-2.5.1/archivebox_api/skills/archivebox-kg-ingestion/WORKFLOW.md +77 -0
  33. archivebox_api-2.5.1/archivebox_api/skills/archivebox-snapshot-search/SKILL.md +94 -0
  34. archivebox_api-2.5.1/archivebox_api/skills/archivebox-snapshot-search/WORKFLOW.md +80 -0
  35. archivebox_api-2.5.1/archivebox_api/skills/archivebox-web-archiving/SKILL.md +96 -0
  36. archivebox_api-2.5.1/archivebox_api/skills/archivebox-web-archiving/WORKFLOW.md +82 -0
  37. archivebox_api-2.5.1/archivebox_api/web_source.py +290 -0
  38. archivebox_api-2.5.1/archivebox_api/web_source_contract.py +199 -0
  39. archivebox_api-1.0.1/README.md → archivebox_api-2.5.1/archivebox_api.egg-info/PKG-INFO +132 -78
  40. archivebox_api-2.5.1/archivebox_api.egg-info/SOURCES.txt +69 -0
  41. archivebox_api-2.5.1/archivebox_api.egg-info/entry_points.txt +14 -0
  42. archivebox_api-2.5.1/archivebox_api.egg-info/requires.txt +14 -0
  43. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api.egg-info/top_level.txt +3 -0
  44. archivebox_api-2.5.1/connector_manifest.yml +172 -0
  45. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/mkdocs.yml +2 -1
  46. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/opencode.json +3 -3
  47. archivebox_api-2.5.1/pyproject.toml +80 -0
  48. archivebox_api-2.5.1/release-readiness.json +16811 -0
  49. archivebox_api-2.5.1/requirements.txt +1 -0
  50. archivebox_api-2.5.1/scripts/security_sanitizer.py +318 -0
  51. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/scripts/verify_api_integration.py +153 -112
  52. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/tests/conftest.py +2 -2
  53. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/tests/test_action_discovery.py +2 -2
  54. archivebox_api-2.5.1/tests/test_archivebox_api_brute_force_coverage.py +166 -0
  55. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/tests/test_archivebox_coverage.py +63 -65
  56. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/tests/test_archivebox_coverage_extra.py +62 -157
  57. archivebox_api-2.5.1/tests/test_conformance.py +159 -0
  58. archivebox_api-2.5.1/tests/test_kg_ingest.py +184 -0
  59. archivebox_api-2.5.1/tests/test_kg_media.py +111 -0
  60. archivebox_api-2.5.1/tests/test_web_source.py +277 -0
  61. archivebox_api-1.0.1/archivebox_api/__main__.py +0 -4
  62. archivebox_api-1.0.1/archivebox_api/agent_server.py +0 -95
  63. archivebox_api-1.0.1/archivebox_api/api/api_client_base.py +0 -63
  64. archivebox_api-1.0.1/archivebox_api/mcp/__init__.py +0 -15
  65. archivebox_api-1.0.1/archivebox_api/mcp/mcp_authentication.py +0 -58
  66. archivebox_api-1.0.1/archivebox_api/mcp/mcp_cli.py +0 -57
  67. archivebox_api-1.0.1/archivebox_api/mcp/mcp_core.py +0 -63
  68. archivebox_api-1.0.1/archivebox_api/mcp_server.py +0 -242
  69. archivebox_api-1.0.1/archivebox_api/prompts/main_agent.json +0 -18
  70. archivebox_api-1.0.1/archivebox_api/skills/archivebox-starter/SKILL.md +0 -19
  71. archivebox_api-1.0.1/archivebox_api.egg-info/SOURCES.txt +0 -48
  72. archivebox_api-1.0.1/archivebox_api.egg-info/entry_points.txt +0 -9
  73. archivebox_api-1.0.1/archivebox_api.egg-info/requires.txt +0 -16
  74. archivebox_api-1.0.1/pyproject.toml +0 -65
  75. archivebox_api-1.0.1/requirements.txt +0 -1
  76. archivebox_api-1.0.1/scripts/security_sanitizer.py +0 -160
  77. archivebox_api-1.0.1/tests/test_archivebox_api_brute_force_coverage.py +0 -154
  78. archivebox_api-1.0.1/tests/test_concept_parity.py +0 -87
  79. archivebox_api-1.0.1/tests/test_startup.py +0 -12
  80. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/CHANGELOG.md +0 -0
  81. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/CLAUDE.md +0 -0
  82. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/MANIFEST.in +0 -0
  83. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/api/__init__.py +0 -0
  84. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api/api_client.py +0 -0
  85. {archivebox_api-1.0.1/archivebox_api/prompts → archivebox_api-2.5.1/archivebox_api/connectors}/__init__.py +0 -0
  86. {archivebox_api-1.0.1/archivebox_api/skills → archivebox_api-2.5.1/archivebox_api/prompts}/__init__.py +0 -0
  87. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/archivebox_api.egg-info/dependency_links.txt +0 -0
  88. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/setup.cfg +0 -0
  89. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/tests/test_basic.py +0 -0
  90. {archivebox_api-1.0.1 → archivebox_api-2.5.1}/tests/test_init_dynamics.py +0 -0
@@ -1,5 +1,11 @@
1
+ # Without this, `pre-commit install` wires ONLY the pre-commit hook, so `git push`
2
+ # runs nothing and every hook staged pre-push is silently dead code.
3
+ default_install_hook_types: [pre-commit, pre-push]
1
4
  default_language_version:
2
5
  python: python3
6
+ # Phase 0 dev-velocity contract (arbora-completion-program): a hook with no
7
+ # explicit `stages:` below is commit-only, never both.
8
+ default_stages: [pre-commit]
3
9
  exclude: 'dotnet|node_modules'
4
10
  ci:
5
11
  autofix_prs: true
@@ -8,7 +14,7 @@ ci:
8
14
 
9
15
  repos:
10
16
  - repo: https://github.com/pre-commit/pre-commit-hooks
11
- rev: v6.0.0
17
+ rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # v6.0.0
12
18
  hooks:
13
19
  - id: check-added-large-files
14
20
  args: ["--maxkb=2000"]
@@ -26,7 +32,7 @@ repos:
26
32
  - id: end-of-file-fixer
27
33
  - id: no-commit-to-branch
28
34
  - repo: https://github.com/astral-sh/ruff-pre-commit
29
- rev: v0.15.12
35
+ rev: 38bfb07c0c64c304f47eb52090f8288150c77730 # frozen: v0.17.1
30
36
  hooks:
31
37
  - id: ruff-check
32
38
  args: ["--fix", "--ignore=E402,B008,E501"]
@@ -34,53 +40,54 @@ repos:
34
40
  - id: ruff-format
35
41
  exclude: ^(tests/|test/|scripts/|script/)
36
42
  - repo: https://github.com/pre-commit/mirrors-mypy
37
- rev: v1.20.2
43
+ rev: 2834ec6639549dd6796205c8f011dedcd587288b # frozen: v2.4.0
38
44
  hooks:
39
45
  - id: mypy
40
- additional_dependencies: [pydantic, types-PyYAML, types-requests,
41
- types-setuptools]
46
+ additional_dependencies: [pydantic==2.13.4, types-PyYAML==6.0.12.20260518, types-requests==2.33.0.20260518,
47
+ types-setuptools==83.0.0.20260706]
42
48
  args: ["--ignore-missing-imports"]
43
49
  - repo: https://github.com/jendrikseipp/vulture
44
- rev: v2.16
50
+ rev: 258fe6a1974e89a2add9a45519a9e9dd9f46154e # frozen: v2.16
45
51
  hooks:
46
52
  - id: vulture
47
53
  pass_filenames: false
48
54
  args: [".", "--min-confidence", "95", "--exclude", "node_modules,dotnet,.venv,venv,node_modules,.git,build,dist"]
49
55
  require_serial: true
50
56
  - repo: https://github.com/codespell-project/codespell
51
- rev: v2.4.2
57
+ rev: 57b21406f092110c18776e39b0bda50d37c945c8 # frozen: v2.4.3
52
58
  hooks:
53
59
  - id: codespell
54
60
  args: ["-L", "ans,linar,nam,tread,ot,", "--ignore-words=.codespellignore"]
55
61
  exclude: ^(tests/|test/|scripts/|script/|.*lock.*)
56
62
  - repo: https://github.com/PyCQA/bandit
57
- rev: 1.9.4
63
+ rev: 92ae8b82fb422a639f0ed8d99e96cea769594e08 # 1.9.4
58
64
  hooks:
59
65
  - id: bandit
60
66
  args: ["--skip", "B101,B404,B603"]
61
67
  exclude: ^(tests/|test/|scripts/|script/|__tests__/)
62
68
  - repo: https://github.com/nbQA-dev/nbQA
63
- rev: 1.9.1
69
+ rev: f96ec7f3b26a32619435686eb5813235f7e3327e # frozen: 1.9.1
64
70
  hooks:
65
71
  - id: nbqa-ruff
66
72
  args: ["--fix"]
67
- - repo: https://github.com/astral-sh/uv-pre-commit
68
- rev: 0.11.8
69
- hooks:
70
- - id: uv-lock
71
73
  - repo: local
72
74
  hooks:
73
- - id: check-mermaid
74
- name: Check Mermaid syntax
75
- entry: python3 /home/apps/workspace/agent-packages/agent-utilities/scripts/mermaid_linter.py
75
+ - id: dependency-readiness
76
+ name: Dependency readiness — every declared intra-fleet constraint is installable
77
+ entry: bash -c 'P=""; d="$PWD"; while [ "$d" != "/" ]; do [ -d "$d/agent-packages/agents/repository-manager" ] && { P="$d/agent-packages/agents/repository-manager"; break; }; d=$(dirname "$d"); done; [ -n "$P" ] || P=repository-manager; uv run --no-project --python 3.12 --prerelease=allow --with "$P" python -m repository_manager.dependency_readiness .'
76
78
  language: system
77
- files: \.md$
78
- pass_filenames: true
79
- - id: check-stubs
80
- name: Check for Active Stubs and TODOs
81
- entry: python3 /home/apps/workspace/agent-packages/agent-utilities/scripts/check_stubs.py
79
+ pass_filenames: false
80
+ always_run: true
81
+ stages: [manual, pre-push]
82
+ - id: uv-lock
83
+ name: uv-lock (verify, never mutate)
84
+ entry: uv lock --check
82
85
  language: system
83
- types: [python]
86
+ files: ^(uv\.lock|pyproject\.toml|uv\.toml)$
87
+ pass_filenames: false
88
+ stages: [pre-push, manual]
89
+ - repo: local
90
+ hooks:
84
91
  - id: mermaid-validate
85
92
  name: mermaid-validate
86
93
  entry: mermaid-validate
@@ -102,30 +109,9 @@ repos:
102
109
  language: system
103
110
  pass_filenames: false
104
111
  always_run: true
105
- - id: mcp-readme-table
106
- name: sync MCP tools table in README
107
- entry: |-
108
- bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.readme_tools; else python -m agent_utilities.mcp.readme_tools; fi'
109
- language: system
110
- files: ^(README\.md|.*/mcp_server\.py|.*/mcp/.*\.py)$
111
- pass_filenames: false
112
- - id: readme-env-vars
113
- name: sync env-vars table in README
114
- entry: |-
115
- bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.readme_env_vars; else python -m agent_utilities.mcp.readme_env_vars; fi'
116
- language: system
117
- files: ^(README\.md|\.env\.example)$
118
- pass_filenames: false
119
- - id: readme-mcp-examples
120
- name: sync mcp_config examples in README + env blocks
121
- entry: |-
122
- bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.readme_mcp_examples; else python -m agent_utilities.mcp.readme_mcp_examples; fi'
123
- language: system
124
- files: ^(README\.md|\.env\.example|mcp_config.*\.json|.*/mcp_config.*\.json|.*/mcp_server\.py)$
125
- pass_filenames: false
126
112
  - id: env-var-drift
127
113
  name: check env-var/config drift
128
- entry: bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.check_env_var_drift --check; else python -m agent_utilities.mcp.check_env_var_drift --check; fi'
114
+ entry: bash -c 'if [ -f uv.lock ]; then uv run python -m agent_connector_sdk.mcp.env_drift --check; else python -m agent_connector_sdk.mcp.env_drift --check; fi'
129
115
  language: system
130
116
  pass_filenames: false
131
117
  files: ^(README\.md|\.env\.example|mcp_config.*\.json|.*/mcp_config.*\.json|docker/.*compose.*\.ya?ml|.*/auth\.py|.*/mcp_server\.py)$
@@ -145,8 +131,9 @@ repos:
145
131
  types: [python]
146
132
  pass_filenames: false
147
133
  always_run: true
134
+ stages: [pre-push, manual]
148
135
  - repo: https://github.com/AleksaC/hadolint-py
149
- rev: v2.14.0
136
+ rev: 6e7504451511eaeb62a3e7f14d63b0296cbf86eb # frozen: v2.15.1
150
137
  hooks:
151
138
  - id: hadolint
152
139
  args:
@@ -156,7 +143,7 @@ repos:
156
143
  - --ignore=DL4006
157
144
  - --ignore=SC2102
158
145
  - repo: https://github.com/IamTheFij/docker-pre-commit
159
- rev: v3.0.1
146
+ rev: f626253b23de45412865c07fd076ff95d4cd77a7 # v3.0.1
160
147
  hooks:
161
148
  - id: docker-compose-check
162
149
 
@@ -5,7 +5,7 @@
5
5
 
6
6
  ## Tech Stack & Architecture
7
7
  - Language/Version: Python 3.10+
8
- - Core Libraries: `agent-utilities`, `fastmcp`, `pydantic-ai`
8
+ - Core Libraries: `agent-connector-sdk`, `fastmcp`, `pydantic-ai`
9
9
  - Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution.
10
10
  - Architecture:
11
11
  - `mcp_server.py`: Main MCP server entry point and tool registration.
@@ -65,14 +65,14 @@ pre-commit run --all-files
65
65
 
66
66
  ## Code Style & Conventions
67
67
  **Always:**
68
- - Use `agent-utilities` for common patterns (e.g., `create_mcp_server`, `create_agent`).
68
+ - Use `agent-connector-sdk` for common patterns (e.g., `create_mcp_server`, `create_agent`).
69
69
  - Define input/output models using Pydantic.
70
70
  - Include descriptive docstrings for all tools (they are used as tool descriptions for LLMs).
71
71
  - Check for optional dependencies using `try/except ImportError`.
72
72
 
73
73
  **Good example:**
74
74
  ```python
75
- from agent_utilities import create_mcp_server
75
+ from agent_connector_sdk import create_mcp_server
76
76
  from mcp.server.fastmcp import FastMCP
77
77
 
78
78
  mcp = create_mcp_server("my-agent")
@@ -86,7 +86,7 @@ async def my_tool(param: str) -> str:
86
86
  ## Dos and Don'ts
87
87
  **Do:**
88
88
  - Run `pre-commit` before pushing changes.
89
- - Use existing patterns from `agent-utilities`.
89
+ - Use existing patterns from `agent-connector-sdk`.
90
90
  - Keep tools focused and idempotent where possible.
91
91
 
92
92
  **Don't:**
@@ -97,19 +97,19 @@ async def my_tool(param: str) -> str:
97
97
  ## Safety & Boundaries
98
98
  **Always do:**
99
99
  - Run lint/test via `pre-commit`.
100
- - Use `agent-utilities` base classes.
100
+ - Use `agent-connector-sdk` base classes.
101
101
 
102
102
  **Ask first:**
103
103
  - Major refactors of `mcp_server.py` or `agent_server.py`.
104
- - Deleting or renaming public tool functions.
104
+ - Removing or renaming public tool functions.
105
105
 
106
106
  **Never do:**
107
107
  - Commit `.env` files or secrets.
108
- - Modify `agent-utilities` or `universal-skills` files from within this package.
108
+ - Modify `agent-connector-sdk` or `universal-skills` files from within this package.
109
109
 
110
110
  ## When Stuck
111
111
  - Propose a plan first before making large changes.
112
- - Check `agent-utilities` documentation for existing helpers.
112
+ - Check `agent-connector-sdk` documentation for existing helpers.
113
113
 
114
114
 
115
115
  ## Graph Architecture
@@ -133,7 +133,7 @@ stateDiagram-v2
133
133
 
134
134
  ## Testing with Timeout
135
135
 
136
- To run tests with a timeout to prevent hanging, use the `pytest-timeout` plugin. You can combine it with the `-k` flag to run specific tests:
136
+ To run tests with a timeout to prevent hanging, use the `pytest-timeout` plugin. The operator can combine it with the `-k` flag to run specific tests:
137
137
 
138
138
  ```bash
139
139
  uv run pytest --timeout=60 -k "test_name_pattern"
@@ -180,27 +180,27 @@ and erodes a pristine codebase.
180
180
  `~/workspace/reports/` (command output); tests go in `tests/` (pytest).
181
181
  Before finishing a task, run `git status` and confirm no stray root files were added.
182
182
 
183
- ## Working Discipline — think, simplify, stay surgical, verify
183
+ ## Working Discipline — think, simplify, stay surgical, check
184
184
 
185
185
  These four habits cut the most common LLM coding mistakes. For trivial tasks, use
186
186
  judgment; the bias here is correctness over speed.
187
187
 
188
- - **Think before coding.** State your assumptions explicitly. If a request has more than
188
+ - **Think before coding.** State the operator's assumptions explicitly. If a request has more than
189
189
  one reasonable reading, surface the options instead of silently picking one. If a
190
190
  simpler approach exists, say so and push back when warranted. When something is
191
191
  genuinely unclear, stop and name what's confusing — ask, don't guess.
192
192
  - **Simplicity first.** Write the minimum code that solves the stated problem — no
193
193
  speculative features, no abstraction for single-use code, no configurability that
194
- wasn't requested, no error handling for impossible states. If you wrote 200 lines and
195
- it could be 50, rewrite it. (Name code from its purpose, never `wave0`/`phase2`/`v2`.)
194
+ wasn't requested, no error handling for impossible states. If the operator wrote 200 lines and
195
+ it can be 50, rewrite it. (Name code from its purpose, never `wave0`/`phase2`/`v2`.)
196
196
  - **Stay surgical.** Every changed line should trace directly to the task. Don't refactor,
197
- reformat, or "improve" working code adjacent to your change; match the existing style
198
- even where you'd do it differently. Remove only the imports/symbols your own change
199
- orphaned; if you spot unrelated dead code, mention it rather than deleting it inline.
197
+ reformat, or "improve" working code adjacent to the operator's change; match the existing style
198
+ even where the operator'd do it differently. Remove only the imports/symbols the operator's own change
199
+ orphaned; if the operator spot unrelated dead code, mention it rather than removing it inline.
200
200
  *Exception — the Quality Bar below:* lint/format/type errors the pre-commit gate flags
201
- get fixed regardless of who introduced them. In short: **surgical on behavior, clean on
201
+ get fixed in either case of who introduced them. In short: **surgical on behavior, clean on
202
202
  lint.**
203
- - **Verify against a goal.** Turn the task into a checkable outcome before you start:
203
+ - **Check against a goal.** Turn the task into a checkable outcome before the operator start:
204
204
  "fix the bug" → "write a failing test that reproduces it, then make it pass"; "add
205
205
  validation" → "tests for the invalid inputs pass". For multi-step work, state the short
206
206
  plan and the check for each step, then loop until the checks pass.
@@ -215,8 +215,8 @@ pre-commit run --all-files
215
215
  ```
216
216
 
217
217
  Resolve **every** issue it reports — failures, lint errors, type errors, and
218
- warnings — **including problems that pre-date your change and were not caused by
219
- your edits**. The standing goal is a clean, working codebase with **no errors and
218
+ warnings — **including problems that pre-date the operator's change and were not caused by
219
+ the operator's edits**. The standing goal is a clean, working codebase with **no errors and
220
220
  no warnings**. Do not silence checks (`# noqa`, `# type: ignore`, `SKIP=`,
221
221
  `--no-verify`) to force green unless the exception is already documented in this
222
222
  file as a known, unavoidable limitation. Only commit once `pre-commit run
@@ -226,23 +226,23 @@ why rather than bypassing it.
226
226
  ## Working with Git Worktrees (multi-session)
227
227
 
228
228
  Multiple agents/sessions work the `agent-packages/*` repos concurrently. **Do not
229
- edit the canonical checkout** (`/home/apps/workspace/agent-packages/<repo>`) — a
229
+ edit the canonical checkout** (`${WORKSPACE_ROOT}/agent-packages/<repo>`) — a
230
230
  background `repository-manager` sync can reset its working tree and discard
231
- uncommitted edits. Take your own git worktree on your own branch instead:
231
+ uncommitted edits. Take the operator's own git worktree on the operator's own branch instead:
232
232
 
233
233
  ```bash
234
234
  # preferred — repository-manager MCP:
235
- rm_worktree add <repo> <your-branch> # -> /home/apps/worktrees/<repo>/<your-branch>
235
+ rm_worktree add <repo> <your-branch> # -> ${WORKTREE_ROOT}/<repo>/<your-branch>
236
236
 
237
237
  # raw-git fallback:
238
238
  git -C agent-packages/<repo> checkout main
239
- git -C agent-packages/<repo> worktree add /home/apps/worktrees/<repo>/<branch> -b <branch>
239
+ git -C agent-packages/<repo> worktree add ${WORKTREE_ROOT}/<repo>/<branch> -b <branch>
240
240
  ```
241
241
 
242
242
  Work in the worktree and **commit often** (commits survive a working-tree reset).
243
243
  Each session must use a **distinct branch** — git allows a branch in only one
244
244
  worktree, which is what keeps concurrent sessions from colliding. Worktrees live
245
- under `/home/apps/worktrees/` (outside the workspace scan, so the sync leaves them
245
+ under `${WORKTREE_ROOT}/` (outside the workspace scan, so the sync leaves them
246
246
  alone).
247
247
 
248
248
  **Finishing work in a worktree** — run this sequence before calling it done:
@@ -251,7 +251,7 @@ alone).
251
251
  2. **Commit** in the worktree.
252
252
  3. **Merge to main locally** — `rm_worktree merge <repo> <branch> --into main`
253
253
  (or `git merge --no-ff`). Push only when the user asks.
254
- 4. **Clean up** — remove the worktree and delete the merged branch:
254
+ 4. **Clean up** — remove the worktree and remove the merged branch:
255
255
  `rm_worktree remove <repo> <branch> --delete-branch`; `rm_worktree prune` clears
256
256
  stale entries. (Raw-git: `git worktree remove <path> && git branch -d <branch>`.)
257
257
 
@@ -261,8 +261,34 @@ alone).
261
261
  Working in parallel with other sessions/worktrees? **Reserve a concept id before you write its `CONCEPT:` marker** so two sessions never collide:
262
262
 
263
263
  ```bash
264
- agent-utilities --json concept reserve --ns KG-2 # or a package prefix, e.g. KEY
264
+ agent-connector-sdk --json concept reserve --ns EG-KG.compute.backend # or a package prefix, e.g. KEY
265
265
  ```
266
266
 
267
- Full protocol (ledger, merge=union, reconcile, MCP/REST): <https://knuckles-team.github.io/agent-utilities/concept_coordination/>
267
+ Full protocol (ledger, merge=union, reconcile, MCP/REST): <https://knuckles-team.github.io/agent-connector-sdk/concept_coordination/>
268
268
  <!-- END concept-coordination (generated) -->
269
+
270
+ ## Version & lockfile drift edict (keep the version mirrors AND the lock in sync)
271
+
272
+ The two most common release-breakers in this fleet are **version drift** (the version in
273
+ `pyproject.toml`/`.bumpversion.cfg` advancing while `README.md`, `docker/Dockerfile`, and the
274
+ module `__version__`s lag) and a **stale `uv.lock`** (shipping known-vulnerable transitive deps).
275
+ A version mismatch makes the next `bump-my-version` throw `VersionNotFoundException`; a stale lock
276
+ is what Dependabot flags. Rules:
277
+
278
+ 1. **Never hand-edit a version string.** Change the version ONLY via
279
+ `bump-my-version bump {patch|minor|major}` (a.k.a. `bump2version`), which rewrites every file
280
+ registered in `.bumpversion.cfg` in one atomic, tagged commit. If the operator edited the version in
281
+ `pyproject.toml` by hand, the operator created drift — revert and use the bumper.
282
+ 2. **Every version-bearing file must be registered in `.bumpversion.cfg`** — at minimum
283
+ `pyproject.toml` AND `README.md`, plus `docker/Dockerfile` and any module `__version__`. Never
284
+ add a file that embeds the version without a `[bumpversion:file:...]` entry for it.
285
+ 3. **Re-lock on every dependency change.** After editing `pyproject.toml` deps/extras, run
286
+ `uv lock` and commit `uv.lock` in the SAME change. The `uv-lock` pre-commit hook runs with
287
+ `--locked` and fails on drift — never bypass it. The committed `uv.lock` is the
288
+ Dependabot/security surface.
289
+ 4. **Patch CVEs with a version floor at the source, then re-lock.** `uv` resolves one version
290
+ graph-wide, so a lower-bound in the extra that pulls a dependency raises it for the whole lock.
291
+
292
+ ## Specs: extend first
293
+
294
+ Find the spec row that owns the behavior before any code change. Search with `git grep -n "<term>" -- specs`. Cite the row ID in the commit `Spec:` trailer. Extend the owning spec before any new spec text. Add a child row, a new rollup, or a dated `plan.md` "Amendments" entry. Create a new spec only for a capability that no spec owns. Audits, reviews, and carry-overs land in the owning spec. They never get a spec directory. Reuse an existing function, module, or store before adding one. The rules are the ecosystem [spec standard](https://github.com/Knuckles-Team/pipelines/blob/main/reference/spec-standard.md).
@@ -1,4 +1,4 @@
1
- Copyright (c) 2012-2023 Audel Rouhi
1
+ Copyright (c) 2012-2023 Project Maintainers
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the