📝 Documenation
This commit is contained in:
Jonas Bengtsson
+110
@@ -0,0 +1,110 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to the **AquaCom Integration Gateway** project are documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
|
||||
[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Until the first implementation release, changes are
|
||||
grouped per working session; version numbers begin with the first production-capable release (roadmap G14, see
|
||||
[ExecPlan 001](docs/exec-plans/active/001-implementation-roadmap.md)).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### 2026-10-06 — Project surface
|
||||
|
||||
#### Added
|
||||
|
||||
- `README.md` — project overview: capabilities, architecture summary (Mermaid), documentation map with
|
||||
precedence, protocol-evidence policy, current repository layout, status checklist, third-party copyright
|
||||
notice for the vendor protocol document, license placeholder.
|
||||
- `CHANGELOG.md` — this file.
|
||||
- `docs/exec-plans/active/001-implementation-roadmap.md` — **ExecPlan 001, the umbrella implementation
|
||||
roadmap**: verified current-state snapshot; open decisions D-001 (technology selection — blocking) through
|
||||
D-006; phase/gate table for Phases 0–14 (G0–G14) with exit criteria and gap dependencies; §79 task mapping
|
||||
(T001–T020); protocol-gap consumption schedule; failure-handling, testing and compatibility commitments;
|
||||
progress log; decisions log (DR-001…DR-011); acceptance-evidence plan for the §77 DoD.
|
||||
|
||||
### 2026-10-05 — Protocol evidence layer
|
||||
|
||||
#### Added
|
||||
|
||||
- `docs/protocol/AquaCom_RTU_1_6_eng.pdf` — authoritative AquaCom protocol source: *Technical description –
|
||||
AquaCom – RTU level*, Rev 1.6, ITT Flygt AB, July 2004 (evidence class: SPECIFICATION).
|
||||
- `docs/protocol/AquaCom_RTU_1_6_eng_markdown/` — markdown conversion of the source (lossy at specific
|
||||
tables; PDF is authoritative — see gap registry AQ-GAP-001).
|
||||
- `docs/protocol/known-operations.md` — operations registry: OPS-001…OPS-012 (session ops OK/BRK/EBR/caller-ID;
|
||||
live WGS; alarms WCA/ALR/ALN/ALO; history WGH; reports WGD; configuration MCC/MAS/MAT/SLT; fixed answers
|
||||
SCO/SCE/NDA/Wait), each with evidence sections, scope status (control/setpoint writes OUT-OF-SCOPE) and an
|
||||
evidence-complete implementation order.
|
||||
- `docs/protocol/protocol-gaps.md` — gap registry with 10 entries (AQ-GAP-001…010) in the mandated entry format,
|
||||
including working hypotheses for WGS `alp` semantics and WGH block value counts.
|
||||
- `docs/protocol/test-vectors.md` — test-vector catalogue: **35 source checksum vectors verified by
|
||||
recomputation** against the §2.4 algorithm (including the §3.6.4 Wait-byte pair), framing/session vectors,
|
||||
WGS/WGH/WGD decode scenarios, simulator scenario requirements, and 4 synthetic vectors covering the 16-bit
|
||||
wraparound branches (values computed and verified).
|
||||
|
||||
#### Verified
|
||||
|
||||
- Checksum algorithm (§2.4): exact match on all 35 single-line source examples — confirms summed range
|
||||
(after SOH/STX, excluding `#`), space inclusion around `#`, and Wait-byte (DC3) exclusion.
|
||||
- §3.6.4 Wait-byte pair: both forms sum to 2925 — proves in-telegram Wait bytes must be stripped and are
|
||||
excluded from the checksum.
|
||||
|
||||
#### Found (in the 2004 source document)
|
||||
|
||||
- MAT fetch request prints checksum 557; recomputes to 540 (557 is the SLT fetch checksum — copy-paste error).
|
||||
The MAT fetch answer verifies exactly (353).
|
||||
- Narrative/destination mismatches in examples (§2.2.3.1 "plant number 89" vs telegram dest 86; §3.4.10.2
|
||||
fixed-line dest given as plant number).
|
||||
- WCA hour range typo (0–24 vs ALR's 0–23).
|
||||
- All findings recorded in the gap registry with handling instructions; none block implementation.
|
||||
|
||||
### 2026-10-05 — Documentation baseline (commit `08d44ba`, "Update documents")
|
||||
|
||||
#### Fixed
|
||||
|
||||
- **Markdown formatting restored in all five guidance documents** — the files had been JSON-escaped
|
||||
(`\#`, `\*\*`, ` ` entities, `# `-prefixed lines in `ARCHITECTURE.md`, double-escaping in the
|
||||
implementation specification). Approximately 25,500 lines of escaped text normalized to clean Markdown;
|
||||
verified zero residual artifacts.
|
||||
|
||||
#### Changed
|
||||
|
||||
- `AGENTS.md` reduced from a 35-section duplicate specification (1,403 lines) to the short entry-point form
|
||||
(≈70 lines) its own specification mandates (§4/§6): document table with roles, non-negotiable rules,
|
||||
evidence rules, testing/security/uncertainty guidance.
|
||||
- `ARCHITECTURE.md` §1 now defines **document roles and precedence** (software-spec = requirements;
|
||||
ARCHITECTURE = structure; implementation-spec = process; configuration-reference = config semantics;
|
||||
`AGENTS.md` never overrides).
|
||||
- Watermark semantics defined precisely (§21): advances on **durable spool commit**, not final delivery —
|
||||
new invariants INV-013…INV-016 added (out-of-order arrival, watermark scope, dedup across restart,
|
||||
timestamp quarantine).
|
||||
- `software-specification.md`: RFC 2119 keyword definitions added (§2); `REJECT_CONFLICT` made the default
|
||||
duplicate strategy (§13); missing-timestamp records **quarantined with diagnostics** (§10); shared/multi-drop
|
||||
transport requirement with arbitration (§5.1); repository interface naming aligned to `ARCHITECTURE.md` §25.
|
||||
- Implementation specification made agent-neutral ("the implementation agent"); config-key naming aligned
|
||||
(`maxValuesPerRead`); conflict-policy mapping documented; **evidence-acquisition plan** added (§17) —
|
||||
resolved the next day by the arrival of the Rev 1.6 source.
|
||||
- `configuration-reference.md`: default storage routing made deterministic (§60); overflow policies that
|
||||
discard data must emit diagnostics (§27.5); administrative channel defined as config-file mechanism until
|
||||
a real interface is specified (§81).
|
||||
|
||||
#### Added
|
||||
|
||||
- `missing_docs.md` — registry of planned documents that do not exist yet, with references and priorities;
|
||||
updated as items are created.
|
||||
|
||||
### 2026-10-05 — Initial documentation set (commit `fbec27f`, "Initial commit")
|
||||
|
||||
#### Added
|
||||
|
||||
- `ARCHITECTURE.md` — system structure, boundaries, canonical model, timestamp discipline, historical
|
||||
pipeline, OPC UA architecture, invariants INV-001…INV-012.
|
||||
- `docs/product/software-specification.md` — functional requirements with design objectives and the
|
||||
requirement summary table (AQG-001…AQG-030).
|
||||
- `docs/product/codex-implementation-specification.md` — implementation process: phases 0–14, task sizing,
|
||||
test pyramid, completion criteria, ExecPlan requirements.
|
||||
- `docs/configuration/configuration-reference.md` — full configuration model with field-by-field
|
||||
semantics, validation rules and examples.
|
||||
- `AGENTS.md` (original, long form — replaced in the 2026-10-05 documentation-baseline session above).
|
||||
|
||||
[Unreleased]: https://example.invalid/aquacom-gateway/compare/initial-commit...HEAD
|
||||
Reference in New Issue
Block a user