Skip to content

Commit 36cca10

Browse files
Sistema2DSistema2D
authored
Merge pull request #35 from Sistema2D/fix/v0.10.3-governance-jit
fix(governance): patch release JIT triggers and release validation coherence
2 parents 633cf3f + a370185 commit 36cca10

24 files changed

Lines changed: 1009 additions & 657 deletions

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Follow the instructions in 'AGENTS.md' and: <action>
2525

2626
## Selective Loading by Session Type
2727

28-
Load only the documents relevant to the session context. All files (except this AGENTS.md and editor configs) reside inside the `FCVW/` folder.
28+
Load only the documents relevant to the session context. This `AGENTS.md` file is the primary entrypoint; `FCVW/CONTEXT_MAP.md` is the first auxiliary map for token-efficient document selection. All files (except this AGENTS.md and editor configs) reside inside the `FCVW/` folder.
2929

3030
| Session Type | Priority Documents |
3131
|---|---|
@@ -37,7 +37,7 @@ Load only the documents relevant to the session context. All files (except this
3737
| Code hygiene / anti-monolith | `AGENTS.md`, `FCVW/REFACTORING.md`, `FCVW/PLANNING.md`, `FCVW/skills/anti-monolith-guard/SKILL.md`, `FCVW/skills/code-hygiene-refactor/SKILL.md` |
3838
| Agent / skill creation | `AGENTS.md`, `FCVW/AI.md`, `FCVW/PLANNING.md`, `FCVW/skills/agent-factory/SKILL.md` |
3939
| Skill / agent self-improvement | `AGENTS.md`, `FCVW/AI.md`, `FCVW/PLANNING.md`, `FCVW/AUDIT.md`, `FCVW/skills/self-improvement/SKILL.md` |
40-
| Release | `FCVW/CONTEXT_MAP.md`, `FCVW/skills/` (release-checklist load JIT) |
40+
| Release | `AGENTS.md`, `FCVW/skills/release-checklist/SKILL.md`, `FCVW/VERSIONING.md` (on demand) |
4141
| Security / data | `AGENTS.md`, `FCVW/SECURITY.md`, `FCVW/DATA.md`, `FCVW/ENVIRONMENT.md` |
4242
| AI / RAG / wiki | `AGENTS.md`, `FCVW/AI.md`, `FCVW/wiki/schema.md` |
4343
| Document audit | `AGENTS.md`, `FCVW/MANIFEST.md`, `FCVW/AUDIT.md` |

‎FCVW/CONTEXT_MAP.md‎

Lines changed: 91 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,109 @@
1-
# CONTEXT_MAP.md
2-
3-
Selective context loading map for AI agents and human contributors.
4-
5-
This document is designed to be the **first document read** in any session — before `AGENTS.md`. It provides a compact, scannable reference for which documents to load (and which to skip) based on session type, minimizing unnecessary token consumption.
6-
7-
> For full operational rules, always consult `AGENTS.md`. This map is a navigation shortcut, not a replacement.
8-
9-
---
10-
11-
## Session Type Reference Table
12-
13-
| Session Type | Load Immediately | Load On Demand | Skip Unless Crossing Domain |
14-
|---|---|---|---|
15-
| **Bugfix / Troubleshooting** | `AGENTS.md §checklist`, `TROUBLESHOOTING.md`, `PLANNING.md` | `troubleshooting/<record>`, `wiki/failures/` | `DESIGN.md`, `DATA.md`, `RELEASE.md` |
16-
| **New Feature** | `AGENTS.md §checklist`, `SCOPE.md`, `PLANNING.md` | `DESIGN.md` (if UI), `AI.md` (if AI), `wiki/index.md` | `SECURITY.md`, `REFACTORING.md`, `RELEASE.md` |
17-
| **Application Module Docs** | `AGENTS.md checklist`, `APPLICATION_DOCUMENTATION.md`, `PLANNING.md` | `governance/TEMPLATE_MODULE_DOCUMENTATION.md`, `governance/TEMPLATE_FLOW_DOCUMENTATION.md` | `DESIGN.md`, `DATA.md`, `RELEASE.md` |
1+
# CONTEXT_MAP.md
2+
3+
Selective context loading map for AI agents and human contributors.
4+
5+
This document is designed to be the **first auxiliary document consulted after `AGENTS.md`** in any governed session. It provides a compact, scannable reference for which documents to load (and which to skip) based on session type, minimizing unnecessary token consumption.
6+
7+
> For full operational rules, always consult `AGENTS.md` first. This map is a navigation shortcut, not a replacement.
8+
9+
---
10+
11+
## Session Type Reference Table
12+
13+
| Session Type | Load Immediately | Load On Demand | Skip Unless Crossing Domain |
14+
|---|---|---|---|
15+
| **Bugfix / Troubleshooting** | `AGENTS.md §checklist`, `TROUBLESHOOTING.md`, `PLANNING.md` | `troubleshooting/<record>`, `wiki/failures/` | `DESIGN.md`, `DATA.md`, `RELEASE.md` |
16+
| **New Feature** | `AGENTS.md §checklist`, `SCOPE.md`, `PLANNING.md` | `DESIGN.md` (if UI), `AI.md` (if AI), `wiki/index.md` | `SECURITY.md`, `REFACTORING.md`, `RELEASE.md` |
17+
| **Application Module Docs** | `AGENTS.md checklist`, `APPLICATION_DOCUMENTATION.md`, `PLANNING.md` | `governance/TEMPLATE_MODULE_DOCUMENTATION.md`, `governance/TEMPLATE_FLOW_DOCUMENTATION.md` | `DESIGN.md`, `DATA.md`, `RELEASE.md` |
1818
| **UI / Components** | `AGENTS.md §checklist`, `DESIGN.md` | `wiki/patterns/` | `DATA.md`, `SECURITY.md`, `RELEASE.md` |
1919
| **Refactoring** | `AGENTS.md §checklist`, `REFACTORING.md`, `PLANNING.md` | `wiki/refactorings/`, `TESTS.md` | `DESIGN.md`, `DATA.md`, `RELEASE.md` |
2020
| **Code Hygiene / Anti-Monolith** | `AGENTS.md §checklist`, `REFACTORING.md`, `PLANNING.md`, `skill:anti-monolith-guard`, `skill:code-hygiene-refactor` | `TESTS.md`, `APPLICATION_DOCUMENTATION.md`, `wiki/refactorings/` | `DESIGN.md`, `DATA.md`, `RELEASE.md` |
2121
| **Agent / Skill Creation** | `AGENTS.md §checklist`, `AI.md §AI Skills Engine`, `PLANNING.md`, `skill:agent-factory` | `governance/TEMPLATE_AGENT_OR_SKILL_PROPOSAL.md`, `skills/README.md`, `STACK.md` | Unrelated domain docs, release docs |
2222
| **Skill / Agent Self-Improvement** | `AGENTS.md §checklist`, `AI.md §AI Skills Engine`, `PLANNING.md`, `skill:self-improvement` | `AUDIT.md`, `governance/TEMPLATE_SELF_IMPROVEMENT_REPORT.md`, `skills/README.md`, `STACK.md` | Unrelated feature docs |
23-
| **Release** | `AGENTS.md §checklist`, `skill:release-checklist` | `VERSIONING.md`, `AUDIT.md`, `RELEASE.md` | `DESIGN.md`, `REFACTORING.md` |
24-
| **Briefing / Instantiation** | `AGENTS.md §checklist`, `INSTANTIATION.md`, `BRIEFING.md` | `skill:project-instantiation`, `MANIFEST.md`, `STACK.md` | `REFACTORING.md`, `RELEASE.md` |
25-
| **Retroactive Instantiation / Migration** | `AGENTS.md §checklist`, `RETROACTIVE_INSTANTIATION.md`, `INSTANTIATION.md` | `CONTEXT_MAP.md`, `skill:retroactive-instantiation`, `MANIFEST.md`, `STACK.md` | `DESIGN.md`, `REFACTORING.md`, `RELEASE.md` |
26-
| **Wiki / Knowledge** | `AGENTS.md §checklist`, `wiki/schema.md`, `wiki/index.md` | `skill:wiki-lint`, `wiki/log.md` | `DESIGN.md`, `DATA.md`, `SECURITY.md` |
27-
| **Security / Data** | `AGENTS.md §checklist`, `SECURITY.md`, `DATA.md` | `AI.md`, `TESTS.md` | `DESIGN.md`, `REFACTORING.md` |
28-
| **Document Audit** | `AGENTS.md §checklist`, `MANIFEST.md`, `AUDIT.md` | `skill:governance-validator`, `wiki/index.md`, `changelogs/` | `DESIGN.md`, `DATA.md` |
29-
| **Pull Request / Code Review** | `AGENTS.md §Code Review and Pull Requests` | `FCVW/refactoring-guide/17-branch-and-pull-request-policy.md` (if refactoring PR), `PLANNING.md` (risk gates) | Most governance docs |
30-
| **Deploy / Environment Promotion** | `AGENTS.md §checklist`, `ENVIRONMENT.md §5` | `RELEASE.md §Deployment and Environment Promotion`, `skill:release-checklist` (if release) | `DESIGN.md`, `REFACTORING.md`, `AI.md` |
31-
| **Multi-Agent / Collaboration** | `AGENTS.md §Multi-Agent Concurrency` | `FCVW/Plans/in_progress/` (check active plans), `wiki/agents/` (agent journals) | Most governance docs unless crossing domain |
32-
| **Git / Commit / Tag** | `skill:git-conventional-commits` | `VERSIONING.md` | Most governance docs |
33-
34-
---
35-
36-
## Skills Quick Reference
37-
38-
| Skill | Trigger Keywords | Size Saved vs. Full Docs |
39-
|---|---|---|
40-
| `skills/agent-aegis/SKILL.md` | security scan, vulnerability, harden | Focused security-agent checklist |
23+
| **Release / Version / Changelog** | `AGENTS.md §checklist`, `skill:release-checklist` | `VERSIONING.md`, `AUDIT.md`, `RELEASE.md`, `skill:governance-validator` | `DESIGN.md`, `REFACTORING.md` |
24+
| **Briefing / Instantiation** | `AGENTS.md §checklist`, `INSTANTIATION.md`, `BRIEFING.md` | `skill:project-instantiation`, `MANIFEST.md`, `STACK.md` | `REFACTORING.md`, `RELEASE.md` |
25+
| **Retroactive Instantiation / Migration** | `AGENTS.md §checklist`, `RETROACTIVE_INSTANTIATION.md`, `INSTANTIATION.md` | `CONTEXT_MAP.md`, `skill:retroactive-instantiation`, `MANIFEST.md`, `STACK.md` | `DESIGN.md`, `REFACTORING.md`, `RELEASE.md` |
26+
| **Wiki / Knowledge** | `AGENTS.md §checklist`, `wiki/schema.md`, `wiki/index.md` | `skill:wiki-lint`, `wiki/log.md` | `DESIGN.md`, `DATA.md`, `SECURITY.md` |
27+
| **Security / Data** | `AGENTS.md §checklist`, `SECURITY.md`, `DATA.md` | `AI.md`, `TESTS.md`, `skill:agent-aegis` | `DESIGN.md`, `REFACTORING.md` |
28+
| **Document Audit** | `AGENTS.md §checklist`, `MANIFEST.md`, `AUDIT.md` | `skill:governance-validator`, `skill:agnix-linter`, `wiki/index.md`, `changelogs/` | `DESIGN.md`, `DATA.md` |
29+
| **Pull Request / Code Review** | `AGENTS.md §Code Review and Pull Requests` | `FCVW/refactoring-guide/17-branch-and-pull-request-policy.md` (if refactoring PR), `PLANNING.md` (risk gates) | Most governance docs |
30+
| **Deploy / Environment Promotion** | `AGENTS.md §checklist`, `ENVIRONMENT.md §5` | `RELEASE.md §Deployment and Environment Promotion`, `skill:release-checklist` (if release) | `DESIGN.md`, `REFACTORING.md`, `AI.md` |
31+
| **Multi-Agent / Collaboration** | `AGENTS.md §Multi-Agent Concurrency` | `FCVW/Plans/in_progress/` (check active plans), `wiki/agents/` (agent journals) | Most governance docs unless crossing domain |
32+
| **Git / Commit / Tag** | `skill:git-conventional-commits` | `VERSIONING.md`, `skill:release-checklist` (if version/tag/release) | Most governance docs |
33+
34+
---
35+
36+
## Skills Quick Reference
37+
38+
| Skill | Trigger Keywords | Size Saved vs. Full Docs |
39+
|---|---|---|
40+
| `skills/agent-aegis/SKILL.md` | security scan, vulnerability, harden, segurança, vazamento de dados | Focused security-agent checklist |
4141
| `skills/agent-factory/SKILL.md` | create skill, create agent, specialized skill | Controlled creation gate for new skills and agent profiles |
42-
| `skills/agent-hephaestus/SKILL.md` | ux polish, accessibility, improve ui | Focused UX/accessibility-agent checklist |
43-
| `skills/agent-hermes/SKILL.md` | performance, optimize, bottleneck | Focused performance-agent checklist |
42+
| `skills/agent-hephaestus/SKILL.md` | ux polish, accessibility, improve ui, interface, acessibilidade | Focused UX/accessibility-agent checklist |
43+
| `skills/agent-hermes/SKILL.md` | performance, optimize, bottleneck, desempenho, lentidão | Focused performance-agent checklist |
4444
| `skills/agnix-linter/SKILL.md` | governance audit, AI instructions, dead links | Validates FCVW structural consistency |
4545
| `skills/aicc-compact/SKILL.md` | shift close, compact session, close session, log sync | Reduces close turn overhead |
4646
| `skills/anti-monolith-guard/SKILL.md` | monolith, large file, new module, module boundary | Blocks mixed-responsibility artifacts before edits |
4747
| `skills/brainstorming-and-tdd/SKILL.md` | new feature, fixing a bug, implementing a plan | Enforces specification and Red/Green workflow |
48-
| `skills/code-hygiene-refactor/SKILL.md` | code hygiene, duplication, stale files, dead code, cleanup | Guides active cleanup without scripts |
48+
| `skills/code-hygiene-refactor/SKILL.md` | code hygiene, duplication, stale files, dead code, higiene de código | Guides active cleanup without scripts |
4949
| `skills/git-conventional-commits/SKILL.md` | commit, tag, push, release notes | Replaces ad-hoc reinstructions |
50-
| `skills/memory-rotation/SKILL.md` | context bloat, clean sessions, rotate memory | Keeps session memory bounded |
51-
| `skills/obsidian-markdown/SKILL.md` | wikilink, frontmatter, Obsidian note | Replaces ad-hoc formatting instructions |
52-
| `skills/orchestrator/SKILL.md` | large refactoring, complex plans, parallel tasks | Coordinates subagent-style task decomposition |
53-
| `skills/project-instantiation/SKILL.md` | bootstrap, new project, instantiate, initialize | Safely sets up workspace |
54-
| `skills/release-checklist/SKILL.md` | release, publish, version bump | ~2.7k tokens vs. RELEASE+VERSIONING+AUDIT |
55-
| `skills/self-improvement/SKILL.md` | improve skill, improve agent, skill failed | Evidence-based gate for modifying skills and agent profiles |
50+
| `skills/governance-validator/SKILL.md` | validate governance, verify filesystem, document integrity, plan state coherence | Validates governance integrity and plan-state consistency |
51+
| `skills/memory-rotation/SKILL.md` | context bloat, clean sessions, rotate memory | Keeps session memory bounded |
52+
| `skills/obsidian-markdown/SKILL.md` | wikilink, frontmatter, Obsidian note | Replaces ad-hoc formatting instructions |
53+
| `skills/orchestrator/SKILL.md` | large refactoring, complex plans, parallel tasks | Coordinates subagent-style task decomposition |
54+
| `skills/project-instantiation/SKILL.md` | bootstrap, new project, instantiate, initialize | Safely sets up workspace |
55+
| `skills/release-checklist/SKILL.md` | release, publish, version bump, changelog, publicar versão | ~2.7k tokens vs. RELEASE+VERSIONING+AUDIT |
56+
| `skills/self-improvement/SKILL.md` | improve skill, improve agent, skill failed, gatilho falhou | Evidence-based gate for modifying skills and agent profiles |
5657
| `skills/systematic-debugging/SKILL.md` | debugging, fixing an error, stack trace | Enforces hypothesis-based debugging |
57-
| `skills/governance-validator/SKILL.md` | validate governance, verify filesystem, check document integrity, pre-audit check, structural audit | Replaces reading FILESYSTEM.md + AUDIT.md + TESTS.md for validation purposes |
58-
| `skills/wiki-lint/SKILL.md` | lint, wiki audit, orphan pages | ~275 lines vs. reading schema.md §12 |
59-
60-
---
61-
62-
## AICC Session Ingestion Quick Steps
63-
64-
1. List `wiki/sessions/` → identify file with highest `S{num}`
65-
2. Read that file only
66-
3. Align with: completed tasks, active next steps, open risks
67-
4. Confirm alignment to user before starting work
68-
69-
---
70-
71-
## Document Size Reference (V0.10.2)
72-
73-
> Use to make informed decisions about what to load. Larger files cost more tokens.
74-
75-
| Document | Size | Load Priority |
76-
|---|---|---|
77-
| `AGENTS.md` | ~12 KB | Always (first) |
58+
| `skills/wiki-lint/SKILL.md` | lint, wiki audit, orphan pages | ~275 lines vs. reading schema.md §12 |
59+
60+
---
61+
62+
## AICC Session Ingestion Quick Steps
63+
64+
1. List `wiki/sessions/` → identify file with highest `S{num}`
65+
2. Read that file only
66+
3. Align with: completed tasks, active next steps, open risks
67+
4. Confirm alignment to user before starting work
68+
69+
---
70+
71+
## Document Size Reference (V0.10.3)
72+
73+
> Use to make informed decisions about what to load. Larger files cost more tokens.
74+
75+
| Document | Size | Load Priority |
76+
|---|---|---|
77+
| `AGENTS.md` | ~12 KB | Always first |
78+
| `CONTEXT_MAP.md` | ~3 KB | First auxiliary document after AGENTS.md |
7879
| `REFACTORING.md` | ~14 KB | On demand |
7980
| `skills/anti-monolith-guard/SKILL.md` | ~4 KB | Use for module/file growth gates |
8081
| `skills/code-hygiene-refactor/SKILL.md` | ~4 KB | Use for cleanup/refactoring triage |
8182
| `skills/agent-factory/SKILL.md` | ~4 KB | Use for controlled skill/agent creation |
8283
| `skills/self-improvement/SKILL.md` | ~4 KB | Use for evidence-based skill/agent changes |
8384
| `AI.md` | ~11 KB | On demand (AI sessions) |
84-
| `APPLICATION_DOCUMENTATION.md` | ~4 KB | On demand (application module docs) |
85-
| `FCVW/README.md` | ~13 KB | Rarely (framework orientation only) |
86-
| `wiki/schema.md` | ~9 KB | Use `skill:wiki-lint` instead |
87-
| `SECURITY.md` | ~7 KB | On demand (security sessions) |
88-
| `ENVIRONMENT.md` | ~6 KB | On demand (environment sessions) |
89-
| `PERFORMANCE.md` | ~5 KB | On demand (performance sessions) |
90-
| `DESIGN.md` | ~7 KB | On demand (UI sessions) |
91-
| `TESTS.md` | ~7 KB | On demand |
92-
| `MANIFEST.md` | ~11 KB | On demand (audit / identity) |
93-
| `DATA.md` | ~9 KB | On demand (persistence sessions) |
94-
| `SCOPE.md` | ~4 KB | On demand (new feature) |
95-
| `PLANNING.md` | ~3 KB | Most sessions |
96-
| `TROUBLESHOOTING.md` | ~5 KB | Bugfix sessions |
97-
| `VERSIONING.md` | ~5 KB | Use `skill:release-checklist` instead |
98-
| `RELEASE.md` | ~3 KB | Use `skill:release-checklist` instead |
99-
| `AUDIT.md` | ~4 KB | Use `skill:release-checklist` instead |
100-
| `CONTEXT_MAP.md` | ~3 KB | Always first (this file) |
101-
102-
---
103-
104-
## Related Documents
105-
106-
- `AGENTS.md` — full operational guide, checklists, and document index
107-
- `AI.md §Token Efficiency` — detailed token optimization rules
108-
- `skills/README.md` — skills catalog and usage guidelines
109-
- `wiki/sessions/` — AICC session syntheses (latest = current context)
85+
| `APPLICATION_DOCUMENTATION.md` | ~4 KB | On demand (application module docs) |
86+
| `FCVW/README.md` | ~13 KB | Rarely (framework orientation only) |
87+
| `wiki/schema.md` | ~9 KB | Use `skill:wiki-lint` instead |
88+
| `SECURITY.md` | ~7 KB | On demand (security sessions) |
89+
| `ENVIRONMENT.md` | ~6 KB | On demand (environment sessions) |
90+
| `PERFORMANCE.md` | ~5 KB | On demand (performance sessions) |
91+
| `DESIGN.md` | ~7 KB | On demand (UI sessions) |
92+
| `TESTS.md` | ~7 KB | On demand |
93+
| `MANIFEST.md` | ~11 KB | On demand (audit / identity) |
94+
| `DATA.md` | ~9 KB | On demand (persistence sessions) |
95+
| `SCOPE.md` | ~4 KB | On demand (new feature) |
96+
| `PLANNING.md` | ~3 KB | Most sessions |
97+
| `TROUBLESHOOTING.md` | ~5 KB | Bugfix sessions |
98+
| `VERSIONING.md` | ~5 KB | Use `skill:release-checklist` instead |
99+
| `RELEASE.md` | ~3 KB | Use `skill:release-checklist` instead |
100+
| `AUDIT.md` | ~4 KB | Use `skill:release-checklist` or `skill:governance-validator` when applicable |
101+
102+
---
103+
104+
## Related Documents
105+
106+
- `AGENTS.md` — full operational guide, checklists, and document index
107+
- `AI.md §Token Efficiency` — detailed token optimization rules
108+
- `skills/README.md` — skills catalog and usage guidelines
109+
- `wiki/sessions/` — AICC session syntheses (latest = current context)

0 commit comments

Comments
 (0)