qctl/docs/internal/session-state.md

Session State

Last updated: 2026-10-30

Native CI qualification fixes (2026-10-30)

Local native CI exposed three defects: --no-prompt omitted declared defaults, unknown templates still entered interactive selection, and Windows backslashes escaped Velocity path variables. Defaults now apply with validated explicit overrides; unknown templates return NOT_FOUND without reading stdin; path separators are normalized before interpolation. Interactive fallback remains covered separately.

Four non-interactive regressions and a Windows-path regression failed before the fixes. On macOS27.2 ARM64/GraalVM21.0.12, full Maven verification, native packaging and verification with the built binary passed235 tests across26 reports with zero failures/errors/skips. Native tests must run after building the binary; the earlier build-before-test arrangement silently skipped10 native E2E cases. Exact-commit Gitea macOS/Windows verification and normal PR review remain pending.

Current Status

Stories #18-25 complete. All qqq template system stories finished except #26 (merge mode). Ready for Story #26 or to start Epic #11 (qbit package management).

Recently Completed

Story #25 - Improve Error Messages (2026-01-04)

Implemented structured error handling with recovery suggestions:

• Created SuggestionEngine with Levenshtein distance for fuzzy matching
• Created TemplateError with categories mapped to exit codes
• Created ErrorFormatter for consistent ANSI-colored output
• Added "Did you mean?" suggestions for mistyped template names
• Added --verbose flag to show stack traces
• Added 27 unit tests (13 SuggestionEngine, 6 TemplateError, 8 ErrorFormatter)
• Updated InitCommand and ListCommand to use structured errors

Story #24 - Add Prompt Validation (2026-01-03)

Implemented input validation with retry loop for template prompts:

• Created PromptValidation record for validation rules (pattern, length, range, enum)
• Created PromptValidator class with support for required, pattern, length, range, and enum validation
• Updated PromptRunner to validate input and re-prompt on failure
• Added validation for --var CLI overrides with fallback to interactive prompt
• Added ConsoleUI methods for validation feedback (error checkmark, success checkmark, warning)
• Added 20 unit tests for PromptValidator

Manifest schema now supports:

prompts:
  - name: packageName
    message: "Java package"
    required: true
    validation:
      pattern: "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
      message: "Must be a valid Java package name"

Story #23 - Voyage Mock API Integration (2026-01-03)

Implemented TemplateRegistry abstraction for template management:

• Created TemplateRegistry interface with list/get/download/refresh methods
• Created TemplateInfo record for template metadata
• Created MockTemplateRegistry with embedded template data
• Created GitHubTemplateRegistry wrapping existing TemplatesHub
• Created TemplateRegistryFactory for registry selection via env var
• Refactored ListCommand to use TemplateRegistry with --refresh flag
• Refactored InitCommand to use TemplateRegistry
• Added 13 unit tests for registry classes
• Added native-image reflection config for TemplateInfo

Story #22 - Migrate templates-hub to Velocity (2026-01-03)

Completed migration of new-qqq-application-template:

• Restructured template repo with template/ subdirectory
• Converted all Java files to Velocity syntax ($variable, ${variable})
• Fixed pom.xml with literal blocks (#[[${maven.prop}]]#) for Maven properties
• Added native-image reflection config for Velocity runtime classes
• Implemented verbatim file handling for shell scripts (mvnw, gradlew)
• Added Maven property detection to skip validation for ${prop.name} patterns
• All changes pushed to both template repo and templates-hub

Story #21 - Template Manifest Schema v2 (2026-01-03)

Updated manifest schema to v2 with backward compatibility:

• Added schemaVersion field (Integer) to TemplateManifest and TemplateEntry
• Added minimumQctlVersion field with version check in InitCommand
• Added required field (Boolean) to Prompt record
• Added phase field (String) to PostGenHook record
• Added getEffectiveSchemaVersion() helper method (defaults to 1)
• Added isVersionSatisfied() and parseVersion() helpers in InitCommand
• Updated TemplateEngineTest constructor calls (9 → 11 params)

Simplified scope (per user agreement):

• Deferred prompts[].validation to Story #24
• Deferred conditional fields to future story

Story #20 - Directory Transforms (2026-01-03)

Implemented post-render file transforms for template processing:

• Created Transform.java record with type, pattern, replacement fields
• Created TransformExecutor.java for rename/delete operations using glob patterns
• Added transforms field to TemplateManifest and TemplatesHub.TemplateEntry
• Integrated transform execution in InitCommand.java after rendering
• Added 13 tests for TransformExecutor

Simplified scope (per user agreement):

• Only rename and delete transforms (dropped move as redundant with path variables)
• Glob pattern matching with ${varName} substitution in replacement strings

Manifest schema now supports:

transforms:
  - type: rename
    pattern: "**/*Template*.java"
    replacement: "${appClassName}.java"
  - type: delete
    pattern: "**/.gitkeep"

Story #19 - Computed Variables (2026-01-04)

Implemented computed variable support for template manifests:

• Added replace() method to StringTool.java for string substitution
• Created ComputedVariable.java record for manifest definitions
• Added computed field to TemplateManifest and TemplatesHub.TemplateEntry
• Added evaluateComputed() method to TemplateEngine.java
• Updated InitCommand.java to evaluate computed vars after prompts
• Added 16 new tests (9 ComputedVariable + 7 StringTool.replace)

Manifest schema now supports:

computed:
  - name: packagePath
    expression: "$str.replace($packageName, '.', '/')"
  - name: appClassName
    expression: "$str.pascal($appName)"

Story #18 - Velocity Engine (2026-01-04)

Implemented Apache Velocity template engine replacing Handlebars:

• Created StringTool.java with transformation methods ($str.camel(), etc.)
• Created TemplateRenderException.java for fail-fast error handling
• Refactored TemplateEngine.java to use VelocityEngine
• Added 51 unit tests (15 new + 36 existing)
• Updated native-image reflect-config.json for Velocity classes

Epic #13-17 Story Details (2026-01-04)

Fleshed out all remaining stories for Epics #13-17:

• Epic #13 (qrun Build & Publish): #36-42 - Jib integration, OCI packaging, publishing, labels, digest verification, release channels, rollback
• Epic #14 (qrun Service Operations): #43-49 - Status, logs (SSE streaming), stop, start, restart, deployment history, scale
• Epic #15 (qstudio AI Planning): #50-53 - Code indexing, plan generation (multi-LLM), path policies, plan ledger
• Epic #16 (Authentication & Security): #54-57 - OIDC device flow, service accounts, signature verification (Sigstore/PGP), OS keychain integration
• Epic #17 (Enterprise Features): #58-61 - SSO (SAML/OIDC), RBAC, audit logging, org/team management

Epic #12 Story Details (2026-01-04)

Fleshed out all 9 stories for Epic #12 (qqq - Template System) with:

• User stories and design specs
• Architecture diagrams (current vs target state)
• Files to create/modify tables
• Implementation task checklists
• Acceptance criteria

Stories updated: #18-26 (Velocity, computed vars, transforms, manifest v2, templates migration, Voyage mock, validation, errors, merge mode)

Epic #11 Story Details (2026-01-04)

Fleshed out all 9 stories for Epic #11 (qbit - Package Management) with:

• User stories and design specs
• Command interfaces with examples
• Files to create/modify tables
• Implementation task checklists
• Acceptance criteria

Stories updated: #27-35 (search, add, remove, update, list, SemVer, conflicts, vendor, integrity)

Roadmap & Issue Creation (2026-01-03)

Created comprehensive roadmap and GitHub project structure:

1. Roadmap document - docs/ROADMAP.md with user journey focus
2. Milestones - v0.2.0, v0.3.0, v1.0.0
3. Epics - 7 epic issues (#11-#17) with proper labels
4. Stories - 44 story issues (#18-#61) linked as sub-issues
5. Issue types - Epic for #11-17, Feature for #18-61
6. Sub-issues - All stories linked to parent epics

Epic Summary

Epic	Milestone	Stories
#11 qbit - Package Management	v0.2.0	#27-35 (9)
#12 qqq - Template System	v0.2.0	#18-26 (9)
#13 qrun - Build & Publish	v0.3.0	#36-42 (7)
#14 qrun - Service Operations	v0.3.0	#43-49 (7)
#15 qstudio - AI Planning	v1.0.0	#50-53 (4)
#16 Authentication & Security	v1.0.0	#54-57 (4)
#17 Enterprise Features	v1.0.0	#58-61 (4)

Key Design Decisions

• Template engine: Apache Velocity (not Handlebars) for QQQ consistency
• Voyage integration: Mock APIs for now, real integration when ready
• User journey focus: Roadmap organized by concrete use cases

Current Branch State

• Branch: develop
• Clean: Yes (no uncommitted changes)

Next Steps / TODO

v0.2.0 - Create & Manage (Priority)

Epic #12 - qqq Template System (in progress):

1. #18 - Replace Handlebars with Apache Velocity DONE
2. #19 - Add computed variables support DONE
3. #20 - Implement directory transforms DONE
4. #21 - Update template manifest schema v2 DONE
5. #22 - Migrate templates-hub to Velocity DONE
6. #23 - Integrate template listing with Voyage mock DONE
7. #24 - Add prompt validation DONE
8. #25 - Improve error messages DONE
9. #26 - Implement --merge mode (next)

Epic #11 - qbit Package Management (after qqq):

1. #27 - qbit search command
2. #28 - qbit add with version constraints
3. #29 - qbit remove command
4. #30 - qbit update command
5. #31 - qbit list command
6. #32 - SemVer constraint resolution
7. #33 - Dependency conflict detection
8. #34 - Vendor directory layout
9. #35 - SHA-512 integrity verification

Infrastructure

• GitHub project: https://github.com/orgs/QRun-IO/projects/12

How to Continue

When starting a new session, say "continue from last session" and Claude will:

1. Read this file for context
2. Check git status for any pending work
3. Review GitHub project for current sprint

Key Files

File	Purpose
CLAUDE.md	Project overview and build commands
docs/ROADMAP.md	User journey roadmap
docs/internal/session-state.md	This file - session continuity
.github/workflows/build.yml	CI/CD pipeline