archivebox-api 1.0.1__tar.gz → 2.5.0__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.
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/.pre-commit-config.yaml +33 -46
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/AGENTS.md +54 -28
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/LICENSE +1 -1
- {archivebox_api-1.0.1/archivebox_api.egg-info → archivebox_api-2.5.0}/PKG-INFO +116 -90
- archivebox_api-1.0.1/PKG-INFO → archivebox_api-2.5.0/README.md +105 -106
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/__init__.py +34 -22
- archivebox_api-2.5.0/archivebox_api/__main__.py +4 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/api/api_client_auth.py +1 -3
- archivebox_api-2.5.0/archivebox_api/api/api_client_base.py +82 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/api/api_client_cli.py +2 -7
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/api/api_client_core.py +2 -9
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/auth.py +10 -5
- archivebox_api-2.5.0/archivebox_api/connector_manifest.yml +172 -0
- archivebox_api-2.5.0/archivebox_api/connectors/mcp_source_presets.json +18 -0
- archivebox_api-2.5.0/archivebox_api/connectors/tool_schema_fingerprints.json +8 -0
- archivebox_api-2.5.0/archivebox_api/kg_ingest.py +433 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/mcp_config.json +8 -3
- archivebox_api-2.5.0/archivebox_api/mcp_server.py +432 -0
- archivebox_api-2.5.0/archivebox_api/ontology/__init__.py +7 -0
- archivebox_api-2.5.0/archivebox_api/ontology/archivebox.ttl +99 -0
- archivebox_api-2.5.0/archivebox_api/ontology/certification.json +36 -0
- archivebox_api-2.5.0/archivebox_api/ontology/fixtures/records.json +21 -0
- archivebox_api-2.5.0/archivebox_api/ontology/mappings/source.yaml +20 -0
- archivebox_api-2.5.0/archivebox_api/ontology/migrations/manifest.json +6 -0
- archivebox_api-2.5.0/archivebox_api/ontology/shapes/connector.shacl.ttl +44 -0
- archivebox_api-2.5.0/archivebox_api/prompts/web_archivist_specialist.json +43 -0
- archivebox_api-2.5.0/archivebox_api/skills/__init__.py +0 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/SKILL.md +33 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/agents/openai.yaml +4 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/references/catalog.md +7 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-kg-ingestion/SKILL.md +91 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-kg-ingestion/WORKFLOW.md +77 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-snapshot-search/SKILL.md +94 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-snapshot-search/WORKFLOW.md +80 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-web-archiving/SKILL.md +96 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-web-archiving/WORKFLOW.md +82 -0
- archivebox_api-2.5.0/archivebox_api/web_source.py +281 -0
- archivebox_api-2.5.0/archivebox_api/web_source_contract.py +199 -0
- archivebox_api-1.0.1/README.md → archivebox_api-2.5.0/archivebox_api.egg-info/PKG-INFO +132 -78
- archivebox_api-2.5.0/archivebox_api.egg-info/SOURCES.txt +69 -0
- archivebox_api-2.5.0/archivebox_api.egg-info/entry_points.txt +14 -0
- archivebox_api-2.5.0/archivebox_api.egg-info/requires.txt +14 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api.egg-info/top_level.txt +3 -0
- archivebox_api-2.5.0/connector_manifest.yml +172 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/mkdocs.yml +2 -1
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/opencode.json +3 -3
- archivebox_api-2.5.0/pyproject.toml +80 -0
- archivebox_api-2.5.0/release-readiness.json +16811 -0
- archivebox_api-2.5.0/requirements.txt +1 -0
- archivebox_api-2.5.0/scripts/security_sanitizer.py +318 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/scripts/verify_api_integration.py +153 -112
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/tests/conftest.py +2 -2
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/tests/test_action_discovery.py +2 -2
- archivebox_api-2.5.0/tests/test_archivebox_api_brute_force_coverage.py +166 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/tests/test_archivebox_coverage.py +63 -65
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/tests/test_archivebox_coverage_extra.py +62 -157
- archivebox_api-2.5.0/tests/test_conformance.py +159 -0
- archivebox_api-2.5.0/tests/test_kg_ingest.py +184 -0
- archivebox_api-2.5.0/tests/test_kg_media.py +111 -0
- archivebox_api-2.5.0/tests/test_web_source.py +242 -0
- archivebox_api-1.0.1/archivebox_api/__main__.py +0 -4
- archivebox_api-1.0.1/archivebox_api/agent_server.py +0 -95
- archivebox_api-1.0.1/archivebox_api/api/api_client_base.py +0 -63
- archivebox_api-1.0.1/archivebox_api/mcp/__init__.py +0 -15
- archivebox_api-1.0.1/archivebox_api/mcp/mcp_authentication.py +0 -58
- archivebox_api-1.0.1/archivebox_api/mcp/mcp_cli.py +0 -57
- archivebox_api-1.0.1/archivebox_api/mcp/mcp_core.py +0 -63
- archivebox_api-1.0.1/archivebox_api/mcp_server.py +0 -242
- archivebox_api-1.0.1/archivebox_api/prompts/main_agent.json +0 -18
- archivebox_api-1.0.1/archivebox_api/skills/archivebox-starter/SKILL.md +0 -19
- archivebox_api-1.0.1/archivebox_api.egg-info/SOURCES.txt +0 -48
- archivebox_api-1.0.1/archivebox_api.egg-info/entry_points.txt +0 -9
- archivebox_api-1.0.1/archivebox_api.egg-info/requires.txt +0 -16
- archivebox_api-1.0.1/pyproject.toml +0 -65
- archivebox_api-1.0.1/requirements.txt +0 -1
- archivebox_api-1.0.1/scripts/security_sanitizer.py +0 -160
- archivebox_api-1.0.1/tests/test_archivebox_api_brute_force_coverage.py +0 -154
- archivebox_api-1.0.1/tests/test_concept_parity.py +0 -87
- archivebox_api-1.0.1/tests/test_startup.py +0 -12
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/CHANGELOG.md +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/CLAUDE.md +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/MANIFEST.in +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/api/__init__.py +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api/api_client.py +0 -0
- {archivebox_api-1.0.1/archivebox_api/prompts → archivebox_api-2.5.0/archivebox_api/connectors}/__init__.py +0 -0
- {archivebox_api-1.0.1/archivebox_api/skills → archivebox_api-2.5.0/archivebox_api/prompts}/__init__.py +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/archivebox_api.egg-info/dependency_links.txt +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/setup.cfg +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/tests/test_basic.py +0 -0
- {archivebox_api-1.0.1 → archivebox_api-2.5.0}/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.
|
|
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:
|
|
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.
|
|
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:
|
|
74
|
-
name:
|
|
75
|
-
entry:
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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-
|
|
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-
|
|
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
|
|
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-
|
|
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-
|
|
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
|
-
-
|
|
104
|
+
- Removing or renaming public tool functions.
|
|
105
105
|
|
|
106
106
|
**Never do:**
|
|
107
107
|
- Commit `.env` files or secrets.
|
|
108
|
-
- Modify `agent-
|
|
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-
|
|
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.
|
|
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,
|
|
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
|
|
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
|
|
195
|
-
it
|
|
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
|
|
198
|
-
even where
|
|
199
|
-
orphaned; if
|
|
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
|
|
201
|
+
get fixed in either case of who introduced them. In short: **surgical on behavior, clean on
|
|
202
202
|
lint.**
|
|
203
|
-
- **
|
|
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
|
|
219
|
-
|
|
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** (
|
|
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
|
|
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> # ->
|
|
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
|
|
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
|
|
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
|
|
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-
|
|
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-
|
|
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).
|