Skip to content

Commit 4fd6334

Browse files
CopilotSteake
Copilot
and
Steake
committed
feat: add §15 machine-readable companion files, §14 priority order, §16 agent instruction contract
Add three machine-readable policy files required by GODELOS_REPO_IMPLEMENTATION_CHARTER §15: - docs/repo_architect/policy.json — modes, canonical entrypoint, protected paths, priority order (§14), agent instruction contract (§16), architectural invariants - docs/repo_architect/mutation_lanes.json — all 10 charter lanes with purpose, constraints, automation status, preferred methods, validation floor, mutation budget - docs/repo_architect/dependency_contract.json — layer order, allowed direction, hard prohibitions, circular import policy, ownership hints Add Python constants: - CHARTER_PRIORITY_ORDER — §14 8-item priority stack - CHARTER_COMPANION_FILES — §15 file paths - AGENT_INSTRUCTION_CONTRACT — §16 8-rule minimal agent policy Wire companion file discovery into load_charter_context(). Update OPERATOR_GUIDE with §15 companion files section. Add 13 new tests (154 total). CodeQL: 0 alerts. Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
1 parent 3c85d4e commit 4fd6334

File tree

6 files changed

+415
-2
lines changed

6 files changed

+415
-2
lines changed

‎docs/repo_architect/OPERATOR_GUIDE.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -394,4 +394,18 @@ The system tries a **preferred** model first and automatically retries with a **
394394
python -m unittest tests.test_repo_architect -v
395395
```
396396

397-
The test suite covers: branch suffix generation, model fallback, `ast.parse` gate, campaign aggregation, output schema stability, lane priority, `entrypoint_consolidation`, lane scoping, `validate_change`, charter context, issue fingerprint generation, issue body rendering, deduplication behavior, label assignment, gap diagnosis, `run_issue_cycle` output schema, and charter-validated mode notices.
397+
The test suite covers: branch suffix generation, model fallback, `ast.parse` gate, campaign aggregation, output schema stability, lane priority, `entrypoint_consolidation`, lane scoping, `validate_change`, charter context, issue fingerprint generation, issue body rendering, deduplication behavior, label assignment, gap diagnosis, `run_issue_cycle` output schema, charter-validated mode notices, module-name normalization, and companion file existence.
398+
399+
---
400+
401+
## Machine-Readable Companion Files (Charter §15)
402+
403+
The implementation charter (§15) requires machine-readable policy files that encode mutation lanes, dependency contracts, and architectural invariants. These files live alongside the OPERATOR_GUIDE:
404+
405+
| File | Charter ref | Contents |
406+
|---|---|---|
407+
| [`policy.json`](policy.json) | §15 | Operating modes, canonical entrypoint, protected paths, priority order (§14), agent instruction contract (§16), architectural invariants |
408+
| [`mutation_lanes.json`](mutation_lanes.json) | §10, §11 | All 10 charter-defined lanes with purpose, constraints, automation status, preferred methods, validation floor, and mutation budget policy |
409+
| [`dependency_contract.json`](dependency_contract.json) | §6 | Layer order, allowed dependency direction, hard prohibitions, circular import policy, ownership hints |
410+
411+
Agents should consume these files before proposing code changes. The constants `CHARTER_COMPANION_FILES`, `CHARTER_PRIORITY_ORDER`, and `AGENT_INSTRUCTION_CONTRACT` in `repo_architect.py` encode the same data as Python tuples for runtime use.

‎docs/repo_architect/dependency_contract.json‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{
2+
"$schema": "docs/repo_architect/dependency_contract.json",
3+
"description": "Machine-readable dependency direction contract from GODELOS_REPO_IMPLEMENTATION_CHARTER §6.",
4+
"charter_source": "docs/architecture/GODELOS_REPO_IMPLEMENTATION_CHARTER.md",
5+
"charter_section": "§6 Dependency Direction Contract",
6+
"layer_order": [
7+
"interface",
8+
"agents",
9+
"knowledge",
10+
"core",
11+
"runtime"
12+
],
13+
"layer_descriptions": {
14+
"interface": "External API surface, protocol handling, presentation",
15+
"agents": "Agent orchestration, lifecycle, message routing",
16+
"knowledge": "Knowledge substrate, persistent store adapters, semantic memory",
17+
"core": "Core cognitive processing, state management, operator logic",
18+
"runtime": "Process orchestration, scheduling, lifecycle, messaging, runtime state"
19+
},
20+
"allowed_direction": "interface → agents → knowledge → core → runtime (dependencies flow inward)",
21+
"hard_prohibitions": [
22+
"interface importing deep internal concrete storage implementations directly",
23+
"knowledge adapters importing runtime orchestration logic",
24+
"agent modules reaching through interface modules to access runtime internals",
25+
"circular imports between backend/core and backend/runtime",
26+
"circular imports between godelOS/core_kr interface and concrete store implementations"
27+
],
28+
"circular_import_policy": {
29+
"stance": "Any import cycle is presumed architectural debt",
30+
"acceptable_responses": [
31+
"dependency inversion",
32+
"interface extraction",
33+
"event-based decoupling",
34+
"message boundary insertion",
35+
"module split",
36+
"relocation of misplaced logic"
37+
],
38+
"forbidden": "Never patch cycles by adding local imports inside functions unless explicitly temporary, commented as debt, and tracked for removal"
39+
},
40+
"canonical_entrypoint": "backend/unified_server.py",
41+
"ownership_hints": {
42+
"backend/runtime/": "Runtime Kernel — process orchestration, scheduling, lifecycle",
43+
"backend/core/": "Core Cognitive Engine — reasoning, state update, operator logic",
44+
"godelOS/core_kr/": "Knowledge Substrate — persistent knowledge, semantic storage",
45+
"backend/agents/": "Agent Framework — agent lifecycle, message routing, boundary enforcement",
46+
"backend/interface/": "Interface Layer — external API surface",
47+
"backend/consciousness/": "Consciousness Instrumentation — metrics, traces, self-observation"
48+
}
49+
}

‎docs/repo_architect/mutation_lanes.json‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
{
2+
"$schema": "docs/repo_architect/mutation_lanes.json",
3+
"description": "Machine-readable mutation lane definitions from GODELOS_REPO_IMPLEMENTATION_CHARTER §10.",
4+
"charter_source": "docs/architecture/GODELOS_REPO_IMPLEMENTATION_CHARTER.md",
5+
"charter_section": "§10 Repo-Architect Mutation Lanes",
6+
"lanes": {
7+
"0": {
8+
"name": "report",
9+
"title": "Report generation",
10+
"subsystem": "reporting",
11+
"purpose": "Generate architecture packets, refresh inventories, update risk docs.",
12+
"allowed_outputs": ["docs only", "metadata only", "analysis files only"],
13+
"hard_constraints": [],
14+
"automated": true,
15+
"automation_lane": "report"
16+
},
17+
"1": {
18+
"name": "hygiene",
19+
"title": "Hygiene",
20+
"subsystem": "runtime",
21+
"purpose": "Remove marked debug prints, eliminate dead local noise, simplify obvious internal clutter.",
22+
"allowed_outputs": ["code changes"],
23+
"hard_constraints": ["no semantics change unless trivial and provable"],
24+
"automated": true,
25+
"automation_lane": "hygiene"
26+
},
27+
"2": {
28+
"name": "parse_errors",
29+
"title": "Parse repair",
30+
"subsystem": "runtime",
31+
"purpose": "Repair syntax errors, restore parsability, unblock analysis and test execution.",
32+
"allowed_outputs": ["code changes"],
33+
"hard_constraints": [
34+
"preserve intended semantics where inferable",
35+
"if intent is unclear, prefer minimal repair plus note"
36+
],
37+
"automated": true,
38+
"automation_lane": "parse_errors"
39+
},
40+
"3": {
41+
"name": "import_cycles",
42+
"title": "Circular dependency elimination",
43+
"subsystem": "runtime",
44+
"purpose": "Break import cycles by structural means.",
45+
"allowed_outputs": ["code changes"],
46+
"hard_constraints": ["do not merely hide the cycle"],
47+
"preferred_methods": [
48+
"interface extraction",
49+
"inversion of dependency",
50+
"event dispatch separation",
51+
"module split"
52+
],
53+
"automated": true,
54+
"automation_lane": "import_cycles"
55+
},
56+
"4": {
57+
"name": "entrypoint_consolidation",
58+
"title": "Entrypoint consolidation",
59+
"subsystem": "runtime",
60+
"purpose": "Reduce runtime duplication, delegate launchers to canonical runtime root.",
61+
"allowed_outputs": ["code changes"],
62+
"hard_constraints": ["no breaking of demos or scripts without wrapper preservation"],
63+
"automated": true,
64+
"automation_lane": "entrypoint_consolidation"
65+
},
66+
"5": {
67+
"name": "contract_repair",
68+
"title": "Contract repair",
69+
"subsystem": "core",
70+
"purpose": "Normalise interfaces, repair adapter mismatches, align implementations with substrate boundaries.",
71+
"allowed_outputs": ["code changes"],
72+
"hard_constraints": [],
73+
"automated": false,
74+
"automation_lane": null,
75+
"gap_detection": "dependency direction violation detection"
76+
},
77+
"6": {
78+
"name": "runtime_extraction",
79+
"title": "Runtime extraction",
80+
"subsystem": "runtime",
81+
"purpose": "Move orchestration logic out of scripts or ad hoc files into runtime modules.",
82+
"allowed_outputs": ["code changes"],
83+
"hard_constraints": [],
84+
"automated": false,
85+
"automation_lane": null,
86+
"gap_detection": null
87+
},
88+
"7": {
89+
"name": "agent_boundary",
90+
"title": "Agent boundary enforcement",
91+
"subsystem": "agents",
92+
"purpose": "Isolate agent internal state, replace direct cross-module reach-through with messages or interfaces.",
93+
"allowed_outputs": ["code changes"],
94+
"hard_constraints": [],
95+
"automated": false,
96+
"automation_lane": null,
97+
"gap_detection": "agent boundary violation detection"
98+
},
99+
"8": {
100+
"name": "knowledge_normalisation",
101+
"title": "Knowledge substrate normalisation",
102+
"subsystem": "knowledge",
103+
"purpose": "Centralise persistent knowledge access, remove direct concrete-store entanglement.",
104+
"allowed_outputs": ["code changes"],
105+
"hard_constraints": [],
106+
"automated": false,
107+
"automation_lane": null,
108+
"gap_detection": null
109+
},
110+
"9": {
111+
"name": "consciousness_instrumentation",
112+
"title": "Consciousness instrumentation",
113+
"subsystem": "consciousness",
114+
"purpose": "Add metrics, traces, validation hooks, and introspection paths relevant to recursive self-awareness research.",
115+
"allowed_outputs": ["code changes"],
116+
"hard_constraints": ["instrumentation must remain evidence-oriented, not rhetorical"],
117+
"automated": false,
118+
"automation_lane": null,
119+
"gap_detection": null
120+
}
121+
},
122+
"automation_priority_order": [
123+
"parse_errors",
124+
"import_cycles",
125+
"entrypoint_consolidation",
126+
"hygiene",
127+
"report"
128+
],
129+
"validation_floor": {
130+
"description": "Any self-modifying mutation must at minimum satisfy (§9.3)",
131+
"requirements": [
132+
"repository compiles or targeted files compile where relevant",
133+
"changed tests pass, or a clear debt note explains why not",
134+
"architectural invariants are not worsened",
135+
"the PR explains the lane and intended convergence effect"
136+
]
137+
},
138+
"mutation_budget_policy": {
139+
"description": "Autonomous changes must be thin and rapid, but never indiscriminate (§11).",
140+
"default_budget": 1,
141+
"default_max_slices": 3,
142+
"single_pr_scope": [
143+
"fix one parse error cluster",
144+
"break one import cycle",
145+
"consolidate one entrypoint family",
146+
"extract one interface boundary",
147+
"add one instrumentation seam"
148+
]
149+
}
150+
}

‎docs/repo_architect/policy.json‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"$schema": "docs/repo_architect/policy.json",
3+
"description": "Machine-readable repo-architect policy derived from GODELOS_REPO_IMPLEMENTATION_CHARTER §15.",
4+
"charter_sources": [
5+
"docs/architecture/GODELOS_ARCHITECTURAL_CHARTER.md",
6+
"docs/architecture/GODELOS_REPO_IMPLEMENTATION_CHARTER.md"
7+
],
8+
"default_mode": "issue",
9+
"modes": {
10+
"issue": {
11+
"description": "Default safe governance mode. Diagnoses gaps and opens/updates GitHub Issues with Copilot-ready prompts.",
12+
"charter_basis": ["§14 Effective Gödel-Machine Program", "§15 Self-Modification Doctrine", "§20 Automation Policy"],
13+
"permissions_required": ["issues:write", "models:read"],
14+
"produces_code": false
15+
},
16+
"analyze": {
17+
"description": "Build analysis and write .agent/ artifacts. No GitHub API calls.",
18+
"charter_basis": ["§20 Automation Policy"],
19+
"permissions_required": [],
20+
"produces_code": false
21+
},
22+
"report": {
23+
"description": "Refresh docs/repo_architect/ documentation reports.",
24+
"charter_basis": ["Lane 0 (Report generation)"],
25+
"permissions_required": [],
26+
"produces_code": false
27+
},
28+
"mutate": {
29+
"description": "Attempt one direct code mutation via charter-validated lanes.",
30+
"charter_basis": ["§9 Self-Modification Contract", "§10 Mutation Lanes"],
31+
"permissions_required": ["contents:write", "pull-requests:write", "models:read"],
32+
"produces_code": true
33+
},
34+
"campaign": {
35+
"description": "Run multiple mutation slices across charter-validated lanes.",
36+
"charter_basis": ["§9 Self-Modification Contract", "§10 Mutation Lanes", "§11 Mutation Budget Policy"],
37+
"permissions_required": ["contents:write", "pull-requests:write", "models:read"],
38+
"produces_code": true
39+
}
40+
},
41+
"canonical_entrypoint": "backend/unified_server.py",
42+
"protected_paths": [
43+
"docs/architecture/GODELOS_ARCHITECTURAL_CHARTER.md",
44+
"docs/architecture/GODELOS_REPO_IMPLEMENTATION_CHARTER.md"
45+
],
46+
"architectural_invariants": [
47+
"No circular imports between backend/core and backend/runtime",
48+
"No circular imports between godelOS/core_kr interface and concrete store implementations",
49+
"Interface modules must not import deep internal concrete storage implementations directly",
50+
"Knowledge adapters must not import runtime orchestration logic",
51+
"Agent modules must not reach through interface modules to access runtime internals",
52+
"Canonical runtime convergence toward backend/unified_server.py"
53+
],
54+
"priority_order": [
55+
"restore or preserve parse correctness",
56+
"eliminate import cycles",
57+
"reduce runtime entrypoint ambiguity",
58+
"normalise knowledge substrate boundaries",
59+
"isolate agent boundaries",
60+
"add explicit machine-consciousness instrumentation seams",
61+
"build toward durable Gödlø-P persistence semantics",
62+
"progressively enable validated self-modification loops"
63+
],
64+
"agent_instruction_contract": [
65+
"Work only in one mutation lane at a time.",
66+
"Preserve canonical runtime convergence toward backend/unified_server.py.",
67+
"Break import cycles structurally, not cosmetically.",
68+
"Do not widen coupling between runtime, core, knowledge, agents, and interface layers.",
69+
"Do not bypass knowledge-store interfaces for persistent memory operations.",
70+
"Do not make claims about consciousness without adding measurable instrumentation or evidence paths.",
71+
"Prefer thin, verifiable PRs over broad rewrites.",
72+
"Every PR must explain objective, architectural effect, validation, and next follow-up lane."
73+
]
74+
}

‎repo_architect.py‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,11 +106,39 @@
106106
8: ("knowledge_normalisation", "knowledge", "Knowledge substrate normalisation — centralise persistent knowledge access"),
107107
9: ("consciousness_instrumentation", "consciousness", "Consciousness instrumentation — metrics, traces, introspection paths"),
108108
}
109+
# Charter §14 Current Priority Order (GODELOS_REPO_IMPLEMENTATION_CHARTER)
110+
CHARTER_PRIORITY_ORDER: Tuple[str, ...] = (
111+
"restore or preserve parse correctness",
112+
"eliminate import cycles",
113+
"reduce runtime entrypoint ambiguity",
114+
"normalise knowledge substrate boundaries",
115+
"isolate agent boundaries",
116+
"add explicit machine-consciousness instrumentation seams",
117+
"build toward durable Gödlø-P persistence semantics",
118+
"progressively enable validated self-modification loops",
119+
)
120+
# Machine-readable companion files (§15 GODELOS_REPO_IMPLEMENTATION_CHARTER)
121+
CHARTER_COMPANION_FILES: Tuple[str, ...] = (
122+
"docs/repo_architect/policy.json",
123+
"docs/repo_architect/mutation_lanes.json",
124+
"docs/repo_architect/dependency_contract.json",
125+
)
109126
# Canonical architectural charter files (relative to git root)
110127
CHARTER_PATHS: Tuple[str, ...] = (
111128
"docs/architecture/GODELOS_ARCHITECTURAL_CHARTER.md",
112129
"docs/architecture/GODELOS_REPO_IMPLEMENTATION_CHARTER.md",
113130
)
131+
# §16 Minimal Agent Instruction Contract (GODELOS_REPO_IMPLEMENTATION_CHARTER)
132+
AGENT_INSTRUCTION_CONTRACT: Tuple[str, ...] = (
133+
"Work only in one mutation lane at a time.",
134+
"Preserve canonical runtime convergence toward backend/unified_server.py.",
135+
"Break import cycles structurally, not cosmetically.",
136+
"Do not widen coupling between runtime, core, knowledge, agents, and interface layers.",
137+
"Do not bypass knowledge-store interfaces for persistent memory operations.",
138+
"Do not make claims about consciousness without adding measurable instrumentation or evidence paths.",
139+
"Prefer thin, verifiable PRs over broad rewrites.",
140+
"Every PR must explain objective, architectural effect, validation, and next follow-up lane.",
141+
)
114142
# Maximum characters from each charter file injected into model context
115143
_MAX_CHARTER_CHARS_PER_FILE = 3000
116144
# Maximum characters of source code sent to the model per file snippet
@@ -1647,13 +1675,14 @@ def build_analysis(root: pathlib.Path) -> Dict[str, Any]:
16471675
# -----------------------------
16481676

16491677
def load_charter_context(git_root: pathlib.Path) -> Dict[str, Any]:
1650-
"""Load architectural charter files if present.
1678+
"""Load architectural charter files and companion policy files if present.
16511679
16521680
Returns a dict with:
16531681
- loaded_files: list of relative paths that were successfully read
16541682
- content_hash: hex digest of combined content (None if no files loaded)
16551683
- applied: False initially; callers set True when charter was injected
16561684
- content: truncated combined charter text for model injection
1685+
- companion_files: list of §15 companion file paths that exist
16571686
"""
16581687
loaded_files: List[str] = []
16591688
contents: List[str] = []
@@ -1666,13 +1695,19 @@ def load_charter_context(git_root: pathlib.Path) -> Dict[str, Any]:
16661695
contents.append(f"### {rel}\n\n{text[:_MAX_CHARTER_CHARS_PER_FILE]}")
16671696
except OSError:
16681697
pass
1698+
# §15 companion files — record existence for diagnostics
1699+
companion_files: List[str] = []
1700+
for rel in CHARTER_COMPANION_FILES:
1701+
if (git_root / rel).exists():
1702+
companion_files.append(rel)
16691703
combined = "\n\n".join(contents)
16701704
content_hash = hashlib.sha256(combined.encode("utf-8")).hexdigest()[:16] if combined else None
16711705
return {
16721706
"loaded_files": loaded_files,
16731707
"content_hash": content_hash,
16741708
"applied": False,
16751709
"content": combined,
1710+
"companion_files": companion_files,
16761711
}
16771712

16781713

0 commit comments

Comments
 (0)