Skip to content

Commit 8e21fa8

Browse files
thegeekybengthegeekybeng
committed
fix: close all 4 open findings from FULL_AUDIT.md
S-01 (Moderate — already closed in Sprint 2): - Verified: .env gitignore mandate at governance-framework.md:140 G-01 (Governance — mac-global-workflows undiscoverable): - Add mac-global-workflows/README.md with full file index, environment guidance, precedence order, and cross-references to parent framework SC-01 (Scalability — no context-window budget guidance): - Add tiered loading strategy table to how-to-deploy.md section 9 (4 tiers: Minimal <16K, Standard 16-32K, Full 32-128K, Optimal 128K+) - Add approximate token cost table per file (~35K total for full load) - Add resolution steps referencing token-optimisation.md TD-01 (Technical Debt — stale frontmatter dates): - Bulk update all last_updated fields from 2026-03-19/23 to 2026-05-15 - 13 files updated: all global/, all modes/, docker-compose-workflow.md, system-log-entry-template.md, scoring-rubric.md, tdr-template.md All 4 FULL_AUDIT.md findings now resolved.
1 parent 4cd692b commit 8e21fa8

15 files changed

Lines changed: 102 additions & 18 deletions

‎global/anti-regression-rules.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-19
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

‎global/loop-breaking-protocol.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-19
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

‎global/mandatory-documentation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-19
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

‎global/pc2e-framework.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-19
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

‎how-to-deploy.md‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -503,13 +503,45 @@ Document the pinned version in your `SYSTEM_LOG.md`.
503503

504504
**Cause:** Context window overflow. The governance files exceed what the IDE loads per session.
505505

506+
#### Context-Window Budget — Tiered Loading Strategy
507+
508+
Use this table to decide what to load based on your agent's context window size:
509+
510+
| Tier | Context Window | Load These Files | Skip |
511+
| --- | --- | --- | --- |
512+
| **Tier 1 — Minimal** | < 16K tokens | `governance-framework.md`, `pc2e-framework.md`, `loop-breaking-protocol.md` | All mode files, anti-regression, documentation |
513+
| **Tier 2 — Standard** | 16K–32K tokens | Tier 1 + `anti-regression-rules.md` + active mode file only | Inactive modes, `mandatory-documentation.md` |
514+
| **Tier 3 — Full** | 32K–128K tokens | All `global/` files + active mode + project context | Inactive modes |
515+
| **Tier 4 — Optimal** | 128K+ tokens | All governance files + all modes + full project context | Nothing |
516+
517+
**Approximate token cost per file** (uncompressed):
518+
519+
| File | Approx. Tokens |
520+
| --- | --- |
521+
| `governance-framework.md` | ~3,500 |
522+
| `pc2e-framework.md` | ~2,800 |
523+
| `loop-breaking-protocol.md` | ~2,000 |
524+
| `anti-regression-rules.md` | ~3,200 |
525+
| `mandatory-documentation.md` | ~3,000 |
526+
| `prompt-injection-defence.md` | ~2,500 |
527+
| `privacy-pdpa.md` | ~2,800 |
528+
| `token-optimisation.md` | ~2,200 |
529+
| Any single mode file | ~2,000–3,000 |
530+
| **Total (all global + all modes)** | **~35,000** |
531+
506532
**Resolution:**
533+
507534
1. Use the hybrid deployment (Method C) — put only project context in workspace rules
508-
2. Reduce global rules to the most critical files only:
509-
- `governance-framework.md` (imperatives)
510-
- `pc2e-framework.md` (PC2E pillars)
511-
- `loop-breaking-protocol.md` (loop prevention)
512-
3. Reference mode-specific files inline at task start rather than loading all modes globally
535+
2. Apply prompt caching at the governance block boundary (see `global/token-optimisation.md`)
536+
3. For Tier 1/2 contexts, load mode files inline at task start rather than globally:
537+
538+
```markdown
539+
## Task Context
540+
Current mode: [paste contents of modes/code.md here]
541+
```
542+
543+
4. Use hierarchical references: reference file paths without embedding content
544+
when your IDE supports on-demand file loading
513545

514546
---
515547

‎mac-global-workflows/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Mac Global Workflows
2+
3+
This directory contains Mac-specific governance workflows and bootstrap configurations
4+
for the PC2E Agent Governance Framework. These workflows are used when running AI agents
5+
directly on macOS (e.g., Claude Desktop, Cursor, or other IDE-integrated agents) rather
6+
than through the NAS Docker stack.
7+
8+
---
9+
10+
## Contents
11+
12+
| File | Purpose |
13+
| --- | --- |
14+
| [00_pc2e_governance_bootstrap.md](00_pc2e_governance_bootstrap.md) | Bootstrap script for loading the full governance context into a Mac-based agent session |
15+
| [globaldockerworkflow.md](globaldockerworkflow.md) | Docker workflow adapted for Mac — supplements the NAS-targeted `workflows/docker-compose-workflow.md` |
16+
| [resolving-errors.md](resolving-errors.md) | Debug mode supplement — error resolution patterns for Mac environment |
17+
| [workflow-docker.md](workflow-docker.md) | Code mode supplement — Docker-specific implementation guidance for Mac |
18+
19+
---
20+
21+
## When to Use These Workflows
22+
23+
Use this directory when your AI agent is running on **macOS** — either locally or
24+
via a remote IDE session connected to the Mac.
25+
26+
Use the root [`workflows/`](../workflows/) directory for NAS/Linux/Docker environments.
27+
28+
---
29+
30+
## Relationship to Parent Framework
31+
32+
These files supplement (not replace) the core governance rules:
33+
34+
```text
35+
Precedence order:
36+
global/ ← Universal — applies everywhere
37+
modes/ ← Universal — applies everywhere
38+
mac-global-workflows/ ← Mac-specific supplements only
39+
workflows/ ← NAS/Linux-specific supplements only
40+
```
41+
42+
Mac workflow files MUST NOT contradict global or mode rules. If a conflict exists,
43+
the global rule takes precedence and the Mac workflow must be updated.
44+
45+
---
46+
47+
## Cross-References
48+
49+
- [Global Governance](../global/governance-framework.md) — Core imperatives that apply universally
50+
- [Operational Modes](../modes/) — Mode-specific entry/exit gates
51+
- [Docker Compose Workflow](../workflows/docker-compose-workflow.md) — NAS equivalent
52+
- [How to Deploy](../how-to-deploy.md) — Full deployment guide covering both environments

‎modes/architect.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-23
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

‎modes/ask.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-23
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

‎modes/code.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-23
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

‎modes/debug.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
trigger: always_on
3-
last_updated: 2026-03-23
3+
last_updated: 2026-05-15
44
pc2e_version: 1.0
55
---
66

0 commit comments

Comments
 (0)