fix: track spec files in git and regenerate ERROR_CODES.md (G-081 + M1-26)

.forge/specs/explain/spec.md

@@ -0,0 +1,16 @@
+# Spec: explain
+
+## What
+explain
+
+## Why
+<!-- fill in business rationale -->
+
+## Acceptance Criteria
+- [ ] <!-- add at least one criterion (Given/When/Then) -->
+
+## Non-Functional Requirements
+- [ ] <!-- latency / throughput / availability -->
+
+## Out of scope
+<!-- list explicit exclusions -->

.forge/specs/explain/spec.yml

@@ -0,0 +1,19 @@
+# forge spec manifest — auto-generated by `forge ship spec`
+# Edit spec.md instead; this file is regenerated on each `forge ship spec` run.
+schema_version: 1
+id: explain
+feature: explain
+status: draft
+created_at: "2026-05-21T16:13:56Z"
+acceptance_criteria:
+    - <!-- latency / throughput / availability -->
+scan_policy:
+    families:
+        - secrets
+        - sca
+        - sast
+        - license
+        - iac
+        - container
+        - api
+        - supply-chain

.forge/specs/forge-ship-v2-rfc-005-p1-p2-token-efficiency-and-context-bud/arch.md

@@ -0,0 +1,78 @@
+```markdown
+# Architecture Decision Record: Forge Ship V2 Token-Efficiency and Context-Budget Improvements
+
+## 1. Component Topology
+The Forge Ship V2 pipeline has the following components:
+- **Input Processor:** Pre-tokenizes and preprocesses user input.
+- **Context Manager:** Manages token pruning, prioritization of high-value context, and boundary handling.
+- **Model Runner:** Handles encoding, attention mechanisms, and decoding via Transformer-based architecture.
+- **Output Processor:** Post-processes responses, including token-optimization adaptations.
+
+### Boundaries:
+- **Input Processor ↔ Context Manager:** Passes tokenized input with metadata for contextual prioritization.
+- **Context Manager ↔ Model Runner:** Exchanges context-prioritized input token lists.
+- **Model Runner ↔ Output Processor:** Transmits raw model-generated output for semantic validation and token efficiency reconciliation.
+
+### Relationships:
+- Input Processor → Context Manager → Model Runner → Output Processor → End User
+
+## 2. API Contracts
+All enhancements will interact with client systems through a standard RESTful interface.
+
+- API Style: **Resource-oriented paths (REST)**
+- Referenced Contract: See OpenAPI spec appended below.
+
+Primary APIs:
+- `POST /api/v1/token-efficiency`: Optimizes token usage for provided input contexts.
+- `POST /api/v1/context-budget`: Prioritizes and trims context to maximize contextual relevance and utilization within token limits.
+
+## 3. Data Model & Consistency
+### Data Entities:
+- **TokenMetadata:** Encodes token properties such as importance, source, and sequence context.
+- **ContextState:** Tracks current context composition and trims prioritized portions.
+- **ProcessingMetrics:** Logs efficiency statistics, e.g., reductions achieved and latency impacts.
+
+### Migration Strategy:
+No structural database migrations are needed. Any new metadata (e.g., context prioritization logs) will be stored in existing operational event pipelines.
+
+### Consistency Model:
+Eventual consistency is sufficient for metrics aggregation. Critical path (context and token reduction) operates in strongly consistent mode to ensure processing integrity.
+
+## 4. Non-Functional Requirements
+- **p99 Latency:** ≤ 5% increase over baseline latencies for high-complexity inputs.
+- **Throughput:** Sustained processing at scale for 50,000 context requests/hour with linear scaling.
+- **Availability:** ≥ 99.95%.
+
+## 5. Security Threat Model
+### STRIDE Threats:
+1. **Spoofing:** Secure token handling through strict validation of input integrity.
+2. **Tampering:** Context-manager operations restricted by role-permission boundaries.
+3. **Repudiation:** Log key operations (context prioritization, token reductions) with traceable request IDs.
+4. **Information Disclosure:** Ensure context trimming doesn’t inadvertently retain sensitive user data.
+5. **Denial of Service:** Rate limits and backpressure mechanisms on API endpoints.
+6. **Elevation of Privileges:** Authenticate all traffic using JWTs scoped to user roles.
+
+### Mitigations:
+- **Authentication:** Supabase anon/service-role JWT tokens.
+- **Authorization:** Enforce resource-scoped access control at API and context-management layers.
+- **Transport Security:** Enforce HTTPS.
+
+## 6. Deployment & Observability
+### Deployment Topology:
+- Horizontal scaling for all pipeline components, with autoscaling policies based on token complexity metrics.
+
+### Observability:
+- **Health Checks:** Liveness and readiness endpoints for each service.
+- **Metrics:** Include token inefficiency rates, context prioritization accuracy, and processing latency.
+- **Tracing:** Use OpenTelemetry to trace requests through each pipeline stage.
+- **Disaster Recovery Plan:** RPO < 5 minutes, RTO < 30 minutes, cross-region deployments.
+
+---
+
+## ADR Summary
+- **Status:** Accepted.
+- **Context:** Improvements to token-efficiency and context-budget management for scaling Forge Ship V2.
+- **Decision:** Introduce token-reduction heuristics and dynamic context prioritization logic. Implement interfaces for runtime operation with backward compatibility.
+- **Consequences:** Achieves measurable cost and performance benefits but requires API consumers to validate against new contracts and metrics.
+
+> See [openapi.yaml](openapi.yaml) for the full API contract.

.forge/specs/forge-ship-v2-rfc-005-p1-p2-token-efficiency-and-context-bud/breakdown.md

@@ -0,0 +1,158 @@
+```markdown
+# Task Breakdown for Forge Ship V2 - RFC-005 P1+P2 Token-Efficiency and Context-Budget Improvements
+
+---
+
+## Task List
+
+### **1. OpenAPI Schema Verification**
+**Task ID:** FS2-RFC005-T001  
+**Title:** Validate OpenAPI schema compatibility  
+**Description:** Review the provided OpenAPI schema to ensure it aligns with the Forge Ship V2 system's current and planned capabilities for token-efficiency and context-budget operations. Confirm schema structure, types, and definitions are syntactically correct and implementable.  
+**Effort:** S  
+**Dependencies:** None  
+**Acceptance Criteria:**  
+- OpenAPI schema passes validation using OpenAPI validators.  
+- All defined endpoints, operations, and schemas are determined to adhere to existing system constraints.
+
+---
+
+### **2. Setup Testing Framework**
+**Task ID:** FS2-RFC005-T002  
+**Title:** Configure testing environment for token efficiency and context-budget improvements  
+**Description:** Set up a testing and benchmarking framework to measure token usage, latency, and context prioritization success rates.  
+**Effort:** M  
+**Dependencies:** None  
+**Acceptance Criteria:**  
+- Testing framework successfully runs against Forge Ship V2's development environment.  
+- Metrics (e.g., token usage reduction, context pruning success rates, and latency) can be tracked for every iteration.
+
+---
+
+### **3. Benchmark Current Metrics**
+**Task ID:** FS2-RFC005-T003  
+**Title:** Establish baseline metrics for the current system  
+**Description:** Measure token usage, context utilization, and processing latency in the existing Forge Ship V2 system to establish benchmarks for comparison.  
+**Effort:** M  
+**Dependencies:** FS2-RFC005-T002  
+**Acceptance Criteria:**  
+- Benchmark data recorded for token usage, context spending efficiency, and average latency values under different input cases.  
+- Benchmarks documented and shared with the team.
+
+---
+
+### **4. Optimize Token Redundancy**
+**Task ID:** FS2-RFC005-T004  
+**Title:** Implement token redundancy detection and optimization logic  
+**Description:** Create and integrate logic to identify and optimize redundant token patterns in user-provided inputs and system outputs, ensuring semantic integrity.  
+**Effort:** L  
+**Dependencies:** FS2-RFC005-T003  
+**Acceptance Criteria:**  
+- 10% or higher reduction in token usage for highly redundant inputs without altering user-intended semantics.  
+- New logic passes unit tests and integrates into the core Forge Ship V2 pipeline.
+
+---
+
+### **5. Implement Token Optimization API**
+**Task ID:** FS2-RFC005-T005  
+**Title:** Implement `/api/v1/token-efficiency` endpoint operation  
+**Description:** Develop the backend logic for the `optimizeTokens` API endpoint, connecting the token optimization logic to a callable service.  
+**Effort:** S  
+**Dependencies:** FS2-RFC005-T004  
+**Acceptance Criteria:**  
+- API endpoint processes requests and applies the token optimization logic.  
+- Successful responses return optimized tokens in the defined format.
+
+---
+
+### **6. Optimize Context Pruning**
+**Task ID:** FS2-RFC005-T006  
+**Title:** Implement logic for dynamic context pruning and prioritization  
+**Description:** Create and integrate functionality to prioritize relevant high-value context while dynamically trimming irrelevant or redundant information.  
+**Effort:** L  
+**Dependencies:** FS2-RFC005-T003  
+**Acceptance Criteria:**  
+- System prunes and prioritizes context dynamically, with success in at least 95% of operations.  
+- Context prioritization results are logged and reviewed for consistency.
+
+---
+
+### **7. Implement Context Budget API**
+**Task ID:** FS2-RFC005-T007  
+**Title:** Implement `/api/v1/context-budget` endpoint operation  
+**Description:** Develop the backend logic for the `adjustContext` API endpoint, connecting the context pruning and prioritization logic to a callable service.  
+**Effort:** S  
+**Dependencies:** FS2-RFC005-T006  
+**Acceptance Criteria:**  
+- API endpoint processes requests and applies dynamic context prioritization logic.  
+- Successful responses return trimmed/prioritized context in the defined format.
+
+---
+
+### **8. Implement Batching Support**
+**Task ID:** FS2-RFC005-T008  
+**Title:** Add support for batching in token optimization and context management  
+**Description:** Enhance processing pipelines to support batch optimization for efficient handling of multiple operations without degradation in latency or performance.  
+**Effort:** M  
+**Dependencies:** FS2-RFC005-T004, FS2-RFC005-T006  
+**Acceptance Criteria:**  
+- Batching support integrated for token optimization and context-management pipelines.  
+- Batch processing performance matches single-turn benchmarks within acceptable deviations.
+
+---
+
+### **9. Maintain Backward Compatibility**
+**Task ID:** FS2-RFC005-T009  
+**Title:** Ensure backward compatibility across all changes  
+**Description:** Verify the implemented changes do not break compatibility with current client integrations. Introduce versioning schemes or compatibility patches if necessary.  
+**Effort:** M  
+**Dependencies:** FS2-RFC005-T005, FS2-RFC005-T007, FS2-RFC005-T008  
+**Acceptance Criteria:**  
+- All existing clients continue working seamlessly with the new APIs and optimizations.  
+- Compatibility verified through integration tests.
+
+---
+
+### **10. Security Review**
+**Task ID:** FS2-RFC005-T010  
+**Title:** Conduct security assessment for new optimizations  
+**Description:** Assess the risk of inadvertent exposure of sensitive context data during token optimization and context adjustment operations. Implement mitigations if needed.  
+**Effort:** S  
+**Dependencies:** FS2-RFC005-T005, FS2-RFC005-T007  
+**Acceptance Criteria:**  
+- No security vulnerabilities found related to context data exposure.  
+- System preserves and enforces all privacy and security guidelines established for Forge Ship V2.
+
+---
+
+### **11. Performance Testing and Validation**
+**Task ID:** FS2-RFC005-T011  
+**Title:** Validate performance and scalability of the updated system  
+**Description:** Perform extensive testing with real-world and synthetic datasets to ensure latency and scalability meet the defined criteria.  
+**Effort:** L  
+**Dependencies:** FS2-RFC005-T005, FS2-RFC005-T007, FS2-RFC005-T008  
+**Acceptance Criteria:**  
+- Processing latency does not exceed a 5% increase under high-complexity inputs.  
+- System scales to handle 4096-token inputs without a quality drop.
+
+---
+
+### **12. Documentation and Deployment**
+**Task ID:** FS2-RFC005-T012  
+**Title:** Finalize documentation and deploy feature updates  
+**Description:** Update the documentation to reflect new token-efficiency and context-budget APIs. Coordinate deployment to production systems.  
+**Effort:** S  
+**Dependencies:** FS2-RFC005-T011  
+**Acceptance Criteria:**  
+- API documentation updates completed and reviewed.  
+- Successful deployment of updates with no major issues reported.
+
+---
+
+## Summary of Effort
+
+- XS: 1 Task  
+- S: 5 Tasks  
+- M: 4 Tasks  
+- L: 3 Tasks  
+```