feat: adopt local SQLite engineering memory and quality gates
This commit is contained in:
@@ -0,0 +1,421 @@
|
||||
# SQLite persistence: legacy mapping and migration cases
|
||||
|
||||
This is the implementation map for WRK-000D / DEC-0001 / PLN-0001, starting with
|
||||
TSK-0001. It describes the inspected file backend and the invariants the SQLite
|
||||
implementation must preserve. The implementation sections below record the completed SQLite integration; the
|
||||
source inventory also documents the supported legacy backend.
|
||||
|
||||
The active CLI and this repository's canonical `.ai-engineering` remain on the file
|
||||
backend. Native installation, replacement of active binaries/libraries/shortcuts,
|
||||
and migration of consumer projects are deferred by explicit human instruction.
|
||||
Implementation and verification use fixtures, disposable copies and build outputs.
|
||||
|
||||
## Persistence boundary
|
||||
|
||||
One SQLite database, `.ai-engineering/aie.db`, will own a local project's Work
|
||||
memory. Keep discovery/configuration/agent entry files small and explicit where
|
||||
bootstrap needs them. A file named `aie.db` alone does not establish that migration
|
||||
completed or that the installed CLI can read its schema.
|
||||
|
||||
Store domain fields and relationships, not files encoded as BLOB, base64 or a large
|
||||
TEXT document. Ordered child data belongs to typed dependent rows; constrained
|
||||
operational structures may use an explicit codec when they are not independently
|
||||
queried. Do not put every aggregate into a serialized `work.md` column.
|
||||
|
||||
Generated contexts, readiness/evaluation reports, suggested actions and freshness
|
||||
flags are projections, not additional authorities. Rebuild them from the applicable
|
||||
records in a consistent read transaction. File payloads remain outside SQLite.
|
||||
|
||||
## Source-to-target inventory
|
||||
|
||||
Table names below identify logical groups for the schema step, not a final SQL
|
||||
migration. Preserve ordered lists and nullable/omitted historical values where they
|
||||
affect interpretation or digests. Do not change externally visible identities.
|
||||
|
||||
| Source and owner | Domain data to preserve | Target groups and invariants |
|
||||
|---|---|---|
|
||||
| `ai-engineering.yaml`; `ProjectService`, `ProjectConfig` | Project identity/name; repositories, paths/type/language/access/validation commands; general/activity adapters, profile/model/timeout and archive policy | Bootstrap configuration and typed configuration records; one authority per field. Empty repositories are valid. Repository access defaults to read-only. A source repository is optional. |
|
||||
| `protocol.json`, entry README/AGENTS; `ProtocolGuide`, `ProtocolContract` | Contract/schema versions, capabilities, startup and managed instruction boundaries | Explicit storage/schema discovery and compatibility. Preserve external project rules. Unsupported contracts fail before writes. `onboard` is not data migration. |
|
||||
| `works/.sequence.yaml`; `WorkService.Sequence` | Highest reserved Work number, including gaps | Transactional project-local allocation. Preserve legacy high-water interpretation; never recompute solely from surviving Works or rename decimal-looking historical IDs. |
|
||||
| `work.md`; `Work` | ID, title, description, goal, motivation, ordered constraints/acceptance criteria, status, timestamps, author, repository revisions and all child references | `works`, ordered scope/revision rows and owned references. A Work ID is project-wide; `(work_id, child_id)` identifies a Work-local child. Preserve terminal/editability/archive/reopen semantics. |
|
||||
| Work guidance; `WorkGuidance` | Mode, approval policy, explicit choice history and decision requests, with actor/reason/time/human attestation | Guidance/choice/request rows. Absence in a historical Work differs from newly UNSPECIFIED guidance. Only recorded human instructions change authority. |
|
||||
| Work completion/events; `Work.Completion` | Criterion texts and evidence references; scope hash, integrations, summary, origin, delegation/aggregation, actor/time and lifecycle events | Completion/criterion/integration/event rows. Preserve HUMAN, SYSTEM_EPIC and SYSTEM_PLANS provenance, not just COMPLETED status. Do not invent approval during migration. |
|
||||
| `discussions/DSC-*.md`; `DiscussionEntry` | Work/thread/topic, kind, author/time, exact narrative, optional earlier response target | Discussion entries and response edges in source order. QUESTION/ISSUE remains pending until an explicit linked RESPONSE/CONCLUSION. Preserve UTF-8, Markdown and whitespace. |
|
||||
| `topics/TOP-*.md`, `.history`; `TopicService` | Title/description, ordered source discussion IDs, revision/hash/editor/reason/time | Topic/current revision/source rows. Legacy threads remain implicit topic views, without fabricated formal topic history. |
|
||||
| `surveys/SVY-*.md`, `.history`; `SurveyService` | Questions/options/recommendation/multiple flag/topic/sources; every answer, selected choices, author/time and supersedes link | Survey/question/option/answer/choice rows and revision provenance. Recommendations are not answers. Superseded answers remain available; latest answer determines pending state. |
|
||||
| `dispositions/DSP-*.md`; `DispositionService` | Target entry, ARCHIVE/RESTORE, reason/evidence, author/time | Owned disposition/evidence references. Archive remains subject to the configured policy; restore does not delete the original proposal. |
|
||||
| `decisions/DEC-*.md`, `.history`; `DecisionService` | Narrative/context/approach/rationale, alternatives/risks/criteria/evidence, approval status/history, revisions and revises/supersededBy | Decision/revision/approval/list/reference rows. DIRECT and SYSTEM_PLAN approval provenance stay distinct; preserve causal Plan IDs and no-human-attestation semantics of permitted system promotion. |
|
||||
| `plans/PLN-*.md`, `.history`; `PlanService` | Narrative, decisions, steps and ordered criteria/dependencies/results/evidence; status/revisions; scope exclusions; experiments | Plan/revision/step/dependency/exclusion/experiment rows. Excluding cancelled scope does not satisfy a dependency; completed steps still require results and applicable checks. |
|
||||
| Plan experiments; `Experiment` | Hypothesis, criterion, invocation, step, author/time; observed outcome, interpretation/next action/evidence, retry/reconsideration, questioned DEC | Experiment/result/reference rows. Criteria precede results; failed retries require reconsideration. Open experiments and unresolved DEC concerns continue to block affected execution. |
|
||||
| `epic/WRK-*.md`, `.history`; `EpicService` | RESULTS/DECOMPOSITION, ordered children/importance, revision/hash, explicit scope-bound authorization | EPIC policy/revision/link/authorization rows. Enforce existing forest topology, one parent, no cycles and no authorization inferred from status. |
|
||||
| `agent-runs/RUN-*.md`; `AgentService`, `AgentRun` | Request identity/task/activity/requester/executor/source hash; APPLYING/COMPLETED/FAILED, typed proposal, applied references, diagnostic and invocation provenance | Run/proposal/applied-reference/invocation rows. Preserve idempotency and interrupted publication diagnostics; do not retain raw transport, environment or credentials. |
|
||||
| `artifacts/evidence/ART-*/artifact.yaml`; `ArtifactService` | Work-local identity, origin/purpose/path, SHA-256, size, author/time | Artifact metadata and references. New temporary evidence needs explicit lifecycle state. Payload bytes are external; their absence is not success unless legitimate post-check disposal is recorded. |
|
||||
| Plan/EPIC completion and DF-import receipt payloads | Typed receipt identity, inputs, referenced source revisions/hashes and producer provenance | Typed internal receipt/source rows. These are protocol state; parse only recognized owned receipts, not arbitrary user payloads. Preserve legacy payload/representation provenance when required. |
|
||||
| `runs/`, `artifacts/outputs`, references and experiment files | Temporary execution files, requested deliverables and external references | Filesystem lifecycle/paths only when needed. A RUN record differs from the ignored `runs/` folder. Do not promote every generated file into permanent evidence. |
|
||||
|
||||
### Current gate boundary
|
||||
|
||||
`ProjectConfig.Repository.validationCommands` describes repository validation
|
||||
commands. The legacy baseline did not expose a complete project-level and
|
||||
per-Work gate-result catalog; QualityGates now supplies that contract in SQLite. Completion enforces mechanical protocol checks,
|
||||
recorded results and owned evidence; it does not itself execute those commands.
|
||||
|
||||
TSK-0007 adds the project gate baseline and Work additions while preserving this
|
||||
execution boundary. A historical COMPLETED label or an ART reference is not proof
|
||||
that a newly introduced gate was executed. Imported approvals retain their original
|
||||
meaning; new gate results must record actual observations of the applicable state.
|
||||
|
||||
## Hashes and historical representations
|
||||
|
||||
There are several distinct digests, with different source material:
|
||||
|
||||
1. **Revision chain:** `Revisions.chain` hashes the preceding file's exact UTF-8
|
||||
content. Parsing and reserializing YAML can change bytes without changing the
|
||||
domain object. Keep the original source representation/provenance available
|
||||
for legacy chain checks; never replace a historical hash with a new one merely
|
||||
to make import pass. Retained migration originals stay outside database TEXT.
|
||||
2. **Work completion scope:** `VerificationService.scopeHash` hashes deterministic
|
||||
JSON of selected domain fields and ordered child records. Optional legacy
|
||||
fields are conditionally omitted. Do not normalize missing guidance to a new
|
||||
choice, add optional empty collections to old digest inputs, or reorder lists.
|
||||
3. **Plan/EPIC receipt sources:** source Plan revisions and child completions bind
|
||||
to their semantic digests and producer/authority metadata. Importing a receipt
|
||||
does not authorize re-completion, reevaluation or a new human approval.
|
||||
4. **Artifact integrity:** SHA-256 is over exact payload bytes; retain size/path
|
||||
ownership checks and the distinction between a user file and a protocol receipt.
|
||||
5. **Adapter and import fingerprints:** preserve source fingerprints, request IDs
|
||||
and import source identities. An identical retry is not a new Work or RUN;
|
||||
changed input with the same identity requires existing rejection/review rules.
|
||||
|
||||
Storage schema, manifest schema, protocol contract and Markdown document versions
|
||||
are separate. Existing record schema is 1, Work sequence reads versions 1/2,
|
||||
narrative Markdown reads document versions 1/2 and protocol contracts read 1/2/3.
|
||||
A new SQLite schema does not mean historical documents were rewritten.
|
||||
|
||||
## Unit-of-work and file lifecycle map
|
||||
|
||||
| Operation | Records that must publish coherently | External boundary |
|
||||
|---|---|---|
|
||||
| Create Work | Reserved high-water and initial identity/guidance | Bootstrap and legacy source discovery; no ID reuse on retry |
|
||||
| Add discussion/answer | Entry or revised survey, source links and Work references/timestamp | No implicit evidence attachment or human answer |
|
||||
| Accept/revise/supersede DEC | Approval and revision, replacement links and affected references | Preserve immutable accepted content and causal authority |
|
||||
| Create/update Plan or finish step | Eligible decision promotion, Plan revision, step/result/evidence references | Evidence must be available and valid during dependent checks |
|
||||
| Apply agent proposal | RUN state, typed proposals/applied references and resulting records | Provider call stays outside a write lock; recheck source state before application; preserve idempotent retry |
|
||||
| Complete Plan/Work or coordinate EPIC | Source revisions, internal receipt, completion and applicable propagation | No automatic completion from an empty set; retain reopen/authorization rules |
|
||||
| Retire temporary evidence | Completed dependent checks, minimal result and legitimate disposal state | File deletion follows committed result/disposal intent; interruption is recoverable; requested outputs are protected |
|
||||
| Migrate file backend | Imported rows, mapping/provenance and activation state | Stable source snapshot, migration safety copy and staged database; never switch before verification |
|
||||
|
||||
Keep local write transactions short; provider calls and external quality commands
|
||||
must not hold the database write lock. A read of related context uses one coherent
|
||||
view. Waits have a duration limit and an actionable diagnostic.
|
||||
|
||||
File publication and removal are not SQLite transactions. Define interruption
|
||||
cases explicitly: unreferenced staged file; committed reference with missing input;
|
||||
committed checked result pending cleanup; process interrupted before completion.
|
||||
Only the third case is eligible for post-check disposal. Removing one evidence
|
||||
file must consider every dependent check, including other Plans or Work completion.
|
||||
|
||||
## Representative corpus and expected outcomes
|
||||
|
||||
Use the existing resource bytes and workflow builders. All mutations below are
|
||||
against temporary copies/projects. Do not regenerate frozen resources with the new
|
||||
writer to obtain expected values.
|
||||
|
||||
| Corpus/case | Existing source | Required result of future migration/SQLite checks |
|
||||
|---|---|---|
|
||||
| Frozen pre-contract delivered Work | `src/test/resources/compatibility/baseline-v1/.ai-engineering`; `CompatibilityTest` | Keep 9 original files unchanged, implicit contract 1 and sequence schema 1 readable, accepted DEC plus draft history, legacy defaults and exact frozen scope hash. SQLite import yields equivalent meaning without rewriting or reopening the source. |
|
||||
| Missing optional refinement/guidance | `CompatibilityTest`, `RefinementSafetyTest`, `WorkGuidanceTest` | Interpret defaults in memory; no invented mode, waiver, answer or approval. New guided Works still require human choices. |
|
||||
| Current refinement/history | `DiscussionRefinementTest`, `RefinementSafetyTest`, `DiscussionMarkdownTest` | Preserve UTF-8/body text, response links, implicit/formal topics, all survey answers and latest-answer semantics, reversible dispositions. |
|
||||
| DEC and Plan authority | `WorkGuidanceTest`, `PlanDecisionPromotionTest`, `OperationalSafetyTest` | Preserve direct versus system approvals, exact causal links, accepted-content immutability, revised decision blocking and Plan authority. |
|
||||
| Plan consolidation/recovery | `PlanConsolidationTest`, `PlanConsolidationSafetyTest` | Preserve actual completed Plan sources, exclusions, incomplete scopes, existing receipt reuse, reopen semantics and pending questions. Tampered evidence fails before the step write. |
|
||||
| EPIC delegation/history | `EpicWorkflowTest`, `EpicSafetyTest` | Keep important/optional children, authorization invalidation, nested forest and historical hashes; reproduce recovery without duplicating completions. |
|
||||
| Import receipts and colliding source-local IDs | `src/test/resources/discussion-import/alpha`, `beta`; `DiscussionImportTest`, `legacyimport/DiscussionImportRecoveryTest` | Preserve stable source identity and original evidence; distinguish sources that reused DSC IDs; identical reimport/recovery does not duplicate Works or overwrite changed inputs. |
|
||||
| Fresh processes without Git | `ProcessContinuityTest`, `scripts/native-smoke.sh` | Reconstruct the same memory in a new process without Git installed; preserve source files and avoid a server dependency. |
|
||||
| Evidence missing/tampered before check | `IntegrityTest`, `PlanConsolidationSafetyTest` | Reject size/hash/path/ownership failures and do not publish successful checks. |
|
||||
| Explicitly retired temporary evidence | New scenario in TSK-0008/0009 | Check while present, persist minimal result, retire only after all consumers finish; historical queries remain valid; pending consumers prevent deletion. This behavior is not implemented in the current backend. |
|
||||
| Unsupported versions/unknown fields | `CompatibilityTest`, `OperationalSafetyTest` | Reject malformed, future or inconsistent records before activation; a current manifest cannot hide unsupported history; preview does not modify source. |
|
||||
| Traversal, symlink, foreign ownership | `IntegrityTest`, `RefinementSafetyTest`, `EpicSafetyTest` | Refuse unsafe paths/identities without reading a symlink target, leaking its contents or publishing partial records. Apply the same boundary to database and sidecar paths. |
|
||||
| Interrupted conversion/retry | New scenario in TSK-0010; existing import recovery pattern | Fail before activation, retain usable legacy state, expose recovery state and retry without duplicate IDs/approvals/completions. Two usable writers must not become independent authorities. |
|
||||
| Local concurrent writers/rollback | New scenario in TSK-0003 | Enforce ownership/foreign keys and whole-operation rollback; no duplicate allocated identity; bounded lock contention. Multi-machine reconciliation is out of scope. |
|
||||
|
||||
### Frozen anchors
|
||||
|
||||
The frozen baseline's expected completed Work scope hash is
|
||||
`72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02`.
|
||||
Its accepted DEC is revision 2; `previousHash` and the original draft's byte digest
|
||||
are `545dc8e36da222fdeaf9458f77880bf2d1842738b82bac5296cddf62452a7e01`.
|
||||
The ART-0001 payload digest is
|
||||
`98545564d0747210b91b933bf8554c4b7e36ba878e6662cb48156b08ff74e1ee`.
|
||||
These anchors were inspected from existing resources, not generated by SQLite.
|
||||
|
||||
## Mapping to implementation steps
|
||||
|
||||
- TSK-0002/0003 establish the driver, native loading, schema and unit of work.
|
||||
- TSK-0004/0005 map investigation and implementation records while retaining authority.
|
||||
- TSK-0006 maps RUNs, source fingerprints and deterministic coordination/receipts.
|
||||
- TSK-0007/0008 add gate records and temporary evidence lifecycle.
|
||||
- TSK-0009 builds projections without repeated unrelated reads.
|
||||
- TSK-0010 exercises the corpus before any activation and implements public migration.
|
||||
- TSK-0011 declares storage compatibility and initializes local ignored state.
|
||||
- TSK-0012 prepares the distribution with disposable installer fixtures only.
|
||||
- TSK-0013 updates public operational documentation once the commands exist.
|
||||
- TSK-0014 verifies the integrated result and hands a reproducible workload to WRK-000C.
|
||||
|
||||
This mapping does not change DEC authority, weaken a gate or authorize installation.
|
||||
Successful legacy tests characterize the source backend; they do not yet prove
|
||||
equivalence of a SQLite importer. Future steps must exercise these same expectations
|
||||
through the implemented database path.
|
||||
|
||||
## Driver and Native Image proof (TSK-0002)
|
||||
|
||||
The selected candidate is `org.xerial:sqlite-jdbc:3.54.1.0` (SQLite 3.54.1).
|
||||
`src/sqliteProbe` is a build-only entry point, separate from the installed CLI and
|
||||
project discovery. `sqliteProbe` exercises create/read/write/rollback/reopen in a
|
||||
JVM; `nativeSqliteProbeCompile` builds the same entry point with its JNI library
|
||||
exported beside the executable. The native binary explicitly selects a GraalVM
|
||||
Java 25 toolchain; selecting the Gradle JVM alone did not select the correct
|
||||
Native Image launcher in the first local build attempt.
|
||||
|
||||
Example disposable verification, using the repository's pinned GraalVM:
|
||||
|
||||
```sh
|
||||
mkdir -p build/sqlite-probe/disposable
|
||||
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
|
||||
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
|
||||
./gradlew nativeSqliteProbeCompile
|
||||
bash scripts/sqlite-probe.sh /absolute/path/to/build/native/nativeSqliteProbeCompile/aie-sqlite-probe
|
||||
```
|
||||
|
||||
The shell proof creates its own temporary database and starts separate native
|
||||
processes, checks a UTF-8 value and rollback, disables temporary-library extraction
|
||||
and verifies that an isolated executable fails when its companion library is absent.
|
||||
These are build/driver checks; they do not install the native application, activate
|
||||
the database backend or establish the end-to-end latency of the AIE CLI.
|
||||
|
||||
## Transaction foundation (TSK-0003)
|
||||
|
||||
`SqliteDatabase` now provides explicit initialization and command-scoped read/write
|
||||
transactions. Opening a missing database does not create files. Its application ID,
|
||||
`user_version` and schema metadata must agree before domain operations proceed.
|
||||
Initialization uses WAL with FULL synchronization; connection foreign keys are
|
||||
enabled explicitly, and writer transactions begin IMMEDIATE with a bounded busy
|
||||
timeout (2 seconds by default).
|
||||
|
||||
Nested operations share their connection. A nested failure makes the enclosing
|
||||
write rollback-only even if its caller catches the exception. Read transactions
|
||||
use a read-only SQLite connection and cannot be upgraded implicitly to writes.
|
||||
Related reads retain a stable snapshot while another local writer commits.
|
||||
|
||||
`sqlite/schema-v1.sql` establishes the ownership/revision/reference keys and local
|
||||
identity high-water marks. Domain field tables will be integrated in TSK-0004
|
||||
through TSK-0007; the foundation does not yet route the CLI's Works to SQLite.
|
||||
References are deferred until commit so related revisions can publish together.
|
||||
Missing target ownership aborts the transaction. Database and sidecar symlinks,
|
||||
nonregular paths and orphan sidecars during initialization require inspection.
|
||||
|
||||
`SqliteDatabaseTest` covers initialization, path encoding, rollback, foreign keys,
|
||||
nested failures, read-only access, snapshot consistency, writer contention,
|
||||
unsupported schemas and filesystem boundaries. The build-only native probe also
|
||||
creates and reopens the foundation schema, verifying its resource loading and
|
||||
transaction entry points in Native Image without installing the application.
|
||||
|
||||
## Investigation record integration (TSK-0004)
|
||||
|
||||
`ProjectService.initializeSqlite` is the explicit backend entry point used by
|
||||
disposable integration projects. The public `init` default is still the legacy
|
||||
backend until the storage-contract/initialization step. Existing projects are not
|
||||
converted by the presence of an arbitrary database file: the bootstrap configuration
|
||||
must explicitly select SQLite.
|
||||
|
||||
`SqliteRecords` maps record scalar fields to typed columns in domain-specific
|
||||
tables. Ordered fields use dependent tables and ordinals; structured operational
|
||||
items (such as an answer or completion) have an explicit JSON representation per
|
||||
item, not a serialized source document or entire Work. Work-owned references also
|
||||
bind to the shared revision identity keys. Tables/columns come from trusted domain
|
||||
record definitions, while identities and values use bound SQL parameters.
|
||||
|
||||
`RecordStorage` adapts the existing record codec and revision operations without
|
||||
placing canonical Markdown files in SQLite projects. New revision hashes bind to
|
||||
deterministic materializations of the typed record; migration can retain original
|
||||
source paths/digests for legacy representations. `WorkService` loads a selected
|
||||
Work by identity, allocates IDs transactionally and preserves its folder location
|
||||
when the title changes. Discussions, topic revisions, survey/answer history and
|
||||
dispositions use the same transaction as their Work references.
|
||||
|
||||
Integration checks cover rejected publication rollback, missing owned references,
|
||||
concurrent local allocation, selecting one Work without parsing an unrelated broken
|
||||
record, UTF-8 and explicit guidance/decision requests. A fresh JVM reconstructs
|
||||
discussion/survey context, and the native probe creates and reopens a Work and its
|
||||
discussion in separate processes using the application's AOT metadata. These checks
|
||||
do not yet migrate DECs, Plans or the active workspace to the new backend.
|
||||
|
||||
## Decision and Plan integration (TSK-0005)
|
||||
|
||||
Decisions, approvals, supersession and Plan/experiment revisions now use the typed
|
||||
record adapter. SQLite Plan creation publishes permitted draft promotions, the
|
||||
Plan and its Work reference in one transaction. The legacy backend retains its
|
||||
file-publication recovery path; SQL publication does not compensate by writing
|
||||
Markdown files. A requested rollback of a prepared SQL promotion marks the whole
|
||||
unit of work rollback-only.
|
||||
|
||||
The existing domain checks still enforce pending discussion, approval policy,
|
||||
accepted decision references, step dependencies, experiment outcomes and required
|
||||
owned evidence. Artifact metadata is mapped into SQLite as foundational support
|
||||
for these checks; payloads remain files and are still retained at this step. The
|
||||
temporary-artifact lifecycle and disposal policy belong to TSK-0008.
|
||||
|
||||
`SqliteImplementationTest` covers human acceptance and immutability, atomic system
|
||||
promotion rollback/retry under an explicit fixture waiver, supersession and Plan
|
||||
reconsideration, dependencies, owned evidence and the OODA experiment/retry loop.
|
||||
Existing file-backend authority, promotion and experiment tests remain applicable.
|
||||
### TSK-0006 — RUNs e coordenação
|
||||
|
||||
RUNs e políticas de EPIC usam registros tipados no SQLite. Idempotência e
|
||||
fingerprints continuam derivados do contexto; a aplicação de propostas é uma
|
||||
transação. Uma falha reverte todo o bundle e publica, em transação posterior,
|
||||
somente o RUN falho com diagnóstico e referências aplicadas vazias. Não há
|
||||
transporte bruto ou logs no banco. A coordenação conserva os recibos existentes
|
||||
até a integração de seu ciclo de vida no TSK-0008.
|
||||
|
||||
Verificação: 30 cenários distintos de SqliteCoordinationTest, EpicWorkflowTest,
|
||||
EpicSafetyTest, RefinementSafetyTest e ArchitectureTest passaram, incluindo
|
||||
idempotência, falha intermediária via trigger SQL, RESULTS/DECOMPOSITION,
|
||||
aprovação explícita, revisão de política, propagação e reabertura.
|
||||
|
||||
### TSK-0007 — gates obrigatórios
|
||||
|
||||
Definições de gates do projeto e adicionais por Work são cumulativas. Cada gate
|
||||
declara procedimento e caminhos avaliados; não executa comandos. O registro exige
|
||||
atestado de observação, fingerprint prévio, resultado, invocação e resumo curto.
|
||||
Arquivos, escopo/guidance do Work e revisões das DECs compõem o fingerprint;
|
||||
mudanças relevantes ou na definição exigem nova avaliação. Bookkeeping do Plan
|
||||
não invalida um resultado. Anexos obrigatórios passam pela integridade existente.
|
||||
|
||||
Conclusões humanas, por Plans e por EPICs verificam os gates e congelam referências
|
||||
e hashes dos resultados entregues na mesma transação. A consulta histórica não
|
||||
reaplica regras configuradas depois da entrega. Testes focados de gates,
|
||||
coordenação, infraestrutura e arquitetura: 23 cenários passaram. Instalação e
|
||||
workspace canônico permanecem no formato legado.
|
||||
|
||||
### TSK-0008 — anexos temporários e recuperação
|
||||
|
||||
O Work aberto conserva seus anexos porque outros checks ainda podem precisar
|
||||
deles. A conclusão valida os anexos e registra DISCARD_PENDING na transação;
|
||||
somente após commit remove os payloads e reconhece DISCARDED. Interrupções entre
|
||||
essas fases são repetíveis por `artifact recover WRK`. Ausência sem validação
|
||||
prévia continua inválida. Novas avaliações exigem entradas disponíveis, inclusive
|
||||
após reabrir um Work; o histórico usa o resultado mínimo persistido.
|
||||
|
||||
Recibos de Plans/EPICs novos são fatos tipados, sem arquivos JSON. As origens
|
||||
legadas de importação permanecem preservadas, assim como futuras cópias de
|
||||
migração. Publicações temporárias usam um pequeno journal operacional, removido
|
||||
após commit/rollback; recuperação distingue órfão próprio de payload já publicado.
|
||||
Rollback de preparação remove diretórios vazios próprios e preserva resíduos
|
||||
desconhecidos. Outputs solicitados fora do estado AIE não são alvos da limpeza.
|
||||
|
||||
EXP-0002: 32 cenários distintos focados passaram em duas rodadas. Cobertura inclui
|
||||
arquivo perdido antes de check, recusa de reuso após descarte, rollback da
|
||||
conclusão, interrupção após commit e após unlink, publicação interrompida,
|
||||
repetição, preservação de output e originais legados, recibos e coordenação.
|
||||
|
||||
### TSK-0009 — consultas e diagnóstico
|
||||
|
||||
Contexto, status, next-actions e validação usam snapshots SQLite para leituras
|
||||
relacionadas. Parent/links de EPIC têm índice relacional com unicidade de pai e
|
||||
FKs. Consultar um Work selecionado não carrega outros Works por conveniência:
|
||||
um registro alheio inválido não bloqueia seu contexto. Validação global continua
|
||||
inspecionando o projeto, contador, grafo, FK e integridade SQLite.
|
||||
|
||||
Compatibilidade inspeciona registros tipados e revisões no banco, sem procurar
|
||||
Markdown inexistente nem converter arquivos. Contexto expõe gates e disponibilidade
|
||||
dos anexos. Next-actions sinaliza descarte interrompido sem fazê-lo durante leitura.
|
||||
15 testes focados passaram, incluindo contexto em JVM separado, snapshot com outro
|
||||
escritor, isolamento de Work inválido, histórico com formato não suportado e leitura
|
||||
sem limpeza. A regressão legada de compatibilidade também passou na rodada anterior.
|
||||
|
||||
### TSK-0010 — migração explícita
|
||||
|
||||
`storage migrate` apresenta prévia sem escrita; `--apply --expect HASH` prepara
|
||||
uma base separada, importa registros tipados e compara DTOs, revisões, autoridade
|
||||
e integridade antes de selecionar SQLite. `--recover` e `--rollback` usam o
|
||||
fingerprint da operação. A cópia de segurança conserva originais e fontes exatas
|
||||
dos hashes; o staging é removido após êxito. Os arquivos legados existentes
|
||||
permanecem em seus destinos, sem alteração ou remoção de arquivos rastreados.
|
||||
|
||||
Contrato 4 e um marcador visível em `works/` impedem escrita por CLI antiga,
|
||||
inclusive comandos que já aguardavam o lock. Escritores modernos compartilham
|
||||
uma fronteira de publicação com espera limitada e recusam mudança de backend
|
||||
durante a espera. Leituras não precisam desse lock. A recuperação recusa ativação
|
||||
se o legado mudou; rollback preserva essas alterações e exige nova prévia. Depois
|
||||
de novas gravações SQLite, rollback é recusado para não perder memória.
|
||||
|
||||
A prova encontrou e corrigiu a distinção entre lista nula e vazia (especialmente
|
||||
exclusions de Plan). Essa presença é tipada no esquema e os hashes originais
|
||||
continuam ancorados em bytes externos, com comparação contra o registro tipado.
|
||||
EXP-0003: 34 testes na rodada final passaram, incluindo cinco pontos de falha,
|
||||
corpus congelado, Plan/survey ativo, EPIC/RUN, IDs reservados e compatibilidade.
|
||||
Nenhum consumidor nem este workspace foi migrado.
|
||||
|
||||
### TSK-0011 — inicialização local
|
||||
|
||||
`init` prepara SQLite e bootstrap antes de publicar o workspace. Acrescenta
|
||||
`/.ai-engineering/` ao .gitignore sem exigir Git, preservando instruções externas
|
||||
e regras anteriores. `--version-state` deixa essa política ao desenvolvedor;
|
||||
`--storage legacy` é explícito para compatibilidade. Nenhum comando remove arquivos
|
||||
rastreados ou converte projetos existentes durante onboard/leitura.
|
||||
|
||||
Bootstrap SQLite exige contrato 4 antes de acessar a base; esquemas/contratos
|
||||
incompatíveis são diagnosticados. As instruções distribuídas exigem CLI compatível
|
||||
para ler SQLite e proíbem interpretar memória ilegível como projeto vazio. Testes
|
||||
de continuidade passaram em seis cenários JVM separados, inclusive sem Git no PATH.
|
||||
A rodada consolidada de init, migração, compatibilidade, protocolo e arquitetura
|
||||
também passou após explicitar o backend das fixtures legadas.
|
||||
|
||||
### TSK-0012 — pacote preparado, instalação adiada
|
||||
|
||||
`nativePackage` reúne AIE nativo, bibliotecas companheiras e CLI sqlite3 em
|
||||
`build/native/package`; distribuições usam esse diretório completo. SQLite 3.54.1
|
||||
é compilado de fonte oficial com SHA3-256 fixado em scripts/sqlite-version.json.
|
||||
O verificador confere componentes/hashes/versões, inicializa um projeto descartável
|
||||
com AIE nativo e lê sua base com o sqlite3 do pacote.
|
||||
|
||||
O instalador preparado aceita bin-dir/lib-dir, verifica uma release completa antes
|
||||
de alternar current e publicar atalhos aie/ai-engineering/aie-sqlite3. Uma falha na
|
||||
troca dos atalhos restaura a release e os atalhos anteriores. 17 testes com
|
||||
ferramentas simuladas passaram, inclusive falha parcial de ativação. O pacote real
|
||||
de build foi verificado em macOS arm64; Linux está coberto pelas fixtures de
|
||||
instalação, sem prova nativa física nesta máquina.
|
||||
|
||||
Nenhuma instalação real foi executada: binários/bibliotecas/atalhos ativos e
|
||||
projetos consumidores permanecem intactos.
|
||||
|
||||
### TSK-0013 — contrato documentado
|
||||
|
||||
README, arquitetura, protocolo, compatibilidade e recursos de entrada agora
|
||||
descrevem memória local SQLite, gates e anexos temporários. O procedimento público
|
||||
está em docs/storage-migration.md. A referência detalhada do backend de arquivos
|
||||
foi mantida separadamente como legado explícito. Os dois ciclos, OODA e autoridade
|
||||
humana permanecem; instalação/migração reais continuam adiadas. Links locais foram
|
||||
verificados e os testes de init, compatibilidade e Work guidance passaram.
|
||||
|
||||
### TSK-0014 — regressão integrada e handoff
|
||||
|
||||
`./gradlew check` passou com 230 testes JVM, zero falhas/erros/skips, além dos 11
|
||||
cenários do fixture Jenkins. O ajuste final do importador SQLite passou em rodada
|
||||
focada de 17 testes (importação/recuperação e arquitetura). As 17 fixtures finais do
|
||||
instalador passaram com ferramentas simuladas; nenhuma instalação real ocorreu.
|
||||
|
||||
O pacote final e arquivos ZIP/TAR foram gerados com GraalVM e tiveram componentes,
|
||||
hashes, versões e permissões verificados. O smoke nativo completo passou, incluindo
|
||||
legado, continuidade, guidance/OODA e os novos cenários SQLite de gate pendente,
|
||||
conclusão, descarte, recusa de reuso e migração do corpus congelado. O diagnóstico de
|
||||
processos do macOS exigiu execução fora do sandbox; a repetição autorizada passou.
|
||||
Uma cópia isolada do pacote abriu SQLite com extração temporária sem escrita; uma
|
||||
cópia sem a biblioteca JDBC foi corretamente recusada.
|
||||
|
||||
O gerador de latência foi verificado com um Work/uma nota sintéticos, sem medição.
|
||||
docs/latency-scenario.md e scripts/latency-fixture.py foram encaminhados por Discussion
|
||||
ao WRK-000C, que permanece OPEN. Adoção do banco não foi declarada prova de melhora.
|
||||
A verificação física foi macOS arm64; Linux/Windows permanecem dependentes da matriz
|
||||
CI para confirmação nativa. Instalação ativa, workspace canônico e consumidores
|
||||
continuam no estado anterior, sem migração real.
|
||||
Reference in New Issue
Block a user