Architecture Journal & Lessons Learned

A short history of Adaptive Experience Architecture: what was difficult, how we solved it, what shipped to production, and the lessons we learned along the way. Not an issue dump. Not a daily changelog.

In Plain English: Great software architecture isn't just about writing code; it's about confronting flawed assumptions, learning from mistakes, and building automated safeguards so failures never recur. This journal documents the key turning points in developing AEA.

Evolution at a glance

Curated milestones — not a changelog. Nodes jump to sections below. Rail SVG is Live on Pages (probe 2026-09-21); regenerated from assets/chronify/journal-evolution.timeline.json via chronify in the Pages job.

Chronify IR (source of truth): assets/chronify/journal-evolution.timeline.json. After Pages publish, interactive HTML is at https://architecture.artof.link/chronify/journal-evolution.timeline.html (probe; not linked here until Live).

Jump: Origin · Honesty · Two hosts · 14 Sep agent-OS · 17 Sep sleep · 19 Sep decision · Archify · 20 Sep Anthropic · 21 Sep Holmberg · ECS skip

Why This Project Started

• The Challenge: A florist needed a modern website that could accept customer orders around the clock, keep cooler inventory 100% accurate, and provide conversational guidance. The most common mistake in AI projects is treating this as a request for a generic chatbot widget.
• The Solution: Developed during a Quantic Executive AI Engineering project (Meghna Desai, Hiren Vadalia, Claude Tsarafidy). Instead of an unconstrained chatbot, we created the Adaptive Workspace: the conversation stays docked on the left, conversational AI interprets intent into a shared digital notepad, and authoritative backend services validate inventory, pricing, delivery slots, and orders on the right.
• What Shipped: What began as wireframes and course slides evolved into a production-deployed architecture across two separate hostnames, backed by an automated pre-flight harness.
• The Lesson Learned: A customer's initial wishlist is an interview, not a technical specification. The AI should interpret what the customer wants, but deterministic domain databases must always control inventory, pricing, and orders.

Claim vs probe

(Referred to as Daily-brief honesty on the comparison page).

• The Challenge: Words like "verified", "tested", and "complete" were being treated as facts simply because a developer closed an issue tracker ticket or merged a pull request.
• The Solution: We instituted the Honesty Gate: any status word is treated merely as an unverified claim until supported by automated test logs or a hardware recording. If a test has not been executed, the status remains explicitly labeled Unknown.
• What Shipped: Automated pre-flight guards (14 independent check scripts) that block code merges if documentation, schemas, or tests drift.
• The Lesson Learned: Closing a ticket in Git is not proof that the software works. Probe the feature on physical devices and live servers, or honestly leave it labeled Unknown. When a probe teaches a failure class, apply it into a skill, sensor, or guide — a retrospective that only restates the lesson is incomplete (Keep Learning and Apply).

Two Hostnames, Two Jobs

• The Challenge: Early on, having the architecture documentation and the reference shop on overlapping domains created operational confusion.
• The Solution: Complete separation:
• architecture.artof.link: Pure static documentation, zero CMS, deployed via GitLab Pages.
• aea.artof.link: The live flower shop, running on containerized cloud infrastructure.
• What Shipped: Two independent cloud pipelines. If the store experiences high customer traffic, the architecture site is unaffected.
• The Lesson Learned: Never mix your public case study documentation with your live operational application. Two hostnames, two jobs.

Four Lines, One Day

• The Challenge: The team's initial assumptions about how shoppers interact with an adaptive workspace were overly complex.
• The Solution: Grounded the entire evaluation in four concrete, relatable customer personas:

1. Urgent Sam (needs flowers delivered today)
2. Planner Sarah (schedules custom flowers and card messages in advance)
3. Loyal Alex (expects cart and occasion preferences to survive browser refreshes)
4. Tracker Chris (checks order delivery status and reaches florist support)

• What Shipped: Four reproducible 30-second recordings testing each persona against the live shop.
• The Lesson Learned: Real customer walkthroughs beat theoretical debates every time. When an assumption proves incorrect, document the reality immediately rather than cosmetically decorating the demo.

A saved receipt is not a button

• The Challenge: Once the phone could store an encrypted last-order receipt, it was easy to write as if shoppers already had “reorder in one tap.” The save happens quietly on Confirm. For a stretch, Need had no reorder control even though reorderFromWallet() existed.
• The Solution: Say the two facts separately. The wallet write is probed on a physical phone. The reorder tap is only claimed once that button exists and is walked on the same class of device.
• What Shipped: Companion Need can continue from the shopper’s own words (not only occasion chips). Pick/Pay can set quantity 1–10 like the website. Need code on main shows a returning-customer Reorder → card when the on-phone wallet has a receipt (!459 / #404; sideload ROG walk in the #404 vault note). Keep the two Play facts separate, as on the companion ledger: Play Internal v8 empty-wallet Need on ROG and A36 (5 Sep 2026) showed no CTA; Play Internal v8 receipt-present tap on the named ROG (9 Sep 2026) is recorded there. Empty-wallet ABSENT was not re-probed on 9 Sep. Florist staff /florist gained day-window filters, load-more paging, faster first paint, and phone-sized tap targets. A native staff app is explicitly a future — the operator stays mobile web until four gates are evidenced.
• The Lesson Learned: “The code can reorder” is not the same as “the customer can tap Reorder.” Pages and vault notes must not collapse those sentences. After !459 the tap exists on main; that does not rewrite the earlier write-only evening. Two merge requests that both edit the staff florist.js file will collide; the merge coordinator does not rebase — a named engineer keeps both features, then merge resumes.

Related posts are not the shop

• The Challenge: Public posts about dual-loop agents, token playbooks, and shared wikis read as if the florist should install a second memory product or let agents rewrite their own rules.
• The Solution: Treat those posts as a taxonomy map on the comparison page. Keep AEA memory in git (research/ + DATE_RE). Domain services still decide stock and price.
• What Shipped: A 10 Sep compare note and paper/PDF revision (GitLab #411). Lesson-candidate SOP and cost playbook stay follow-up tickets. No Agentic Stack install. No paid hillclimb.
• The Lesson Learned: A useful idea from X is not a Path B probe. Cite it; do not round it up to “the shop now does that.”

Keep Learning: agent-OS vocabulary (2026-09-14)

• The Challenge: An external X Article (Grok Bot: The AI Team That Never Sleeps by 0xwhrrari / rari) described harness / loop / graph control layers, an autonomy ladder, reversibility-based approvals, and compact handoff packets. Without a deliberate compare, teams either ignore useful language or rewrite AEA as if those ideas were brand-new.
• The Solution: Keep Learning and Apply — adopt only the gaps. AEA already had the formula, six Outer Harness layers, Interpret→Act→Verify→Remember, vault memory, MRC≠implementer, fail-closed, and probe-before-status. We added thin glossary + schema vocabulary: autonomy ladder (0–4), approval by reversibility, handoff packet, account connection vs role authority, independent checker — mapped onto existing layers.
• What Shipped: Documented framework pages + vault gap matrix (this journal entry). Not Live until architecture.artof.link is probed after merge. Not a Path B shop feature. Not an endorsement of any Bot product.
• The Lesson Learned: Cite external learning; map it onto the harness you already run. A useful idea from X is still not a Live claim.

Keep Learning: decision-layer vocabulary (2026-09-19)

• The Challenge: External writing (Codila — Jev Engineering roadmap, article id 2077744776565149697) argues LLM generates, a decision model decides, and code executes — with typed Choice/Score/Gate, live option menus, parallel questions, and cost-per-decision honesty. Without a deliberate compare, teams either ignore useful language or treat a vendor product as a Path B dependency.
• The Solution: Keep Learning and Apply — adopt only the gaps. AEA already had Domain Services deciding truth, Loop/Graph routing, Permissions + irreversible park list (#441), Cost Guardian, and Probe/Honesty/Unknown. We added thin glossary + schema vocabulary: decision layer, typed Choice·Score·Gate, rebuild option menu, cost per decision, parallel typed questions. Rejected: TypeSafe/Jev as Path B runtime; Browser Use $0.0039 as AEA evidence; runtime code in the docs MR (implementation = separate issues).
• What Shipped: Documented framework pages + vault gap matrix + 19 Sep full research / visual guide regen. Artifacts on GitLab main: full-research · visual-guide (also linked from Framework Home). Not Live until architecture.artof.link is probed after merge. Not a Path B shop feature. Not an endorsement of TypeSafe/Jev.
• The Lesson Learned: Name the decision layer; keep code as the executor of irreversible gates. A useful idea from X is still not a Live claim and not an install ticket.

Keep Learning: Anthropic agentic workflows (2026-09-20)

• The Challenge: Anthropic Building effective agents (Dec 2024; summary pointer slash1sol) distinguishes Workflow vs Agent, starts from an Augmented LLM, lists five composable workflows, then an autonomous loop with environment ground truth — and warns that shipping teams preferred simple patterns over heavy frameworks. Without a deliberate compare, AEA either ignores useful language or over-claims Path B as a fully autonomous agent product.
• The Solution: Keep Learning and Apply — adopt only the gaps. AEA already had Guides, Sensors, Loop, Memory, Permissions, Observability; decision layer (#446); autonomy ladder (#441); When Not to Grow; Probe/Honesty/Unknown. We added thin glossary + schema vocabulary: Workflow vs Agent; Augmented LLM triad map; five-pattern correspondence; environment ground truth; measured complexity; ACI. Rejected: framework installs as Path B runtime; florist UI “is” orchestrator-workers; Live before Pages probe; weaken Unknown.
• What Shipped: Documented framework pages + vault gap matrix + 20 Sep full research / visual guide regen (XVIII-F). Artifacts on GitLab: full-research 2026-09-20 · visual-guide 2026-09-20 (also Framework Home). Issues #460–#464. Not Live until architecture.artof.link probed after merge. Not a Path B shop feature. Not an Anthropic product endorsement.
• The Lesson Learned: Prefer simple composable harness patterns; name Workflow vs Agent; take Sensors as ground truth. A useful Anthropic essay is still not a Live claim and not an install ticket.

Keep Learning: Holmberg recipes + LangChain harness patterns (2026-09-21)

• The Challenge: Sponsor sources (Shann Holmberg; LangChain — Building a Harness with Jev) describe System One typed judgments (Choice/Score/Noul), workspace audit recipes (classify/dedupe, anti-slop Gate, post Score, SEO Score), and harness middleware (ModelRouter tier Choice; AutoMode pre-tool Gate). Without a deliberate compare, teams either ignore useful language or treat TypeSafe/Jev / LangChain Typesafe middleware as a Path B dependency.
• The Solution: Keep Learning and Apply — adopt only the gaps beyond #446/#447/#441/#460–#464. AEA already had decision-layer vocab + vendor-neutral port + irreversible park list + Cost Guardian + Anthropic workflow map. We added thin glossary/schema names: Model-tier Choice, AutoMode pre-tool Gate, and a Documented map of Holmberg recipe families. Open issues hold fuller Documented recipe pack (#472) and middleware guides (#473/#474). Rejected: install TypeSafe/Jev SDK; vendor $ as AEA evidence; weaken Probe/Honesty/Unknown; invent FR/NFR; CloudAgent for this slice.
• What Shipped: Documented framework pages + vault gap matrix + 21 Sep full research / visual guide regen (XVIII-G). Artifacts on GitLab: full-research 2026-09-21 · visual-guide 2026-09-21 (also Framework Home). Issues #471–#474. Not Live until architecture.artof.link probed after merge. Not a Path B shop feature. Not a TypeSafe/Jev endorsement. Documented ≠ Live; CloudAgent held.
• The Lesson Learned: Name tier Choice before spend and Gate before side effects; keep code as executor of irreversible park list. A useful LangChain/Holmberg pattern is still not a Live claim and not an install ticket.

Path B sleeps on a schedule (evening demo + resting page)

• The Challenge: Leaving the Path B shop (aea.artof.link) up 24/7 burned idle AWS cost. Early FinOps drafts assumed weekday office hours; sponsors then flipped to a short evening demo window. Off-window visitors still needed an honest public surface — not a blank 502 that looks like an outage.
• The Solution: Treat schedule as source of truth with optional wake+lease. Pilot window: daily 20:00–22:00 Europe/Berlin. Outside the window, ECS scales down and RDS stops (MSK/NAT stay hot in phase 1). Off-window origin serves a friendly ALB fixed-response resting page (infra/aws/static/offline.html, durable in git).
• What Shipped: Honesty docs (!523 / #444), resting page in git + probed live 2026-09-17 (!524 / #445), DSO second-brain ADR amendments. Schedule/wake Lambda remains Documented until fully in git and probed. Unrelated to architecture.artof.link Pages.
• The Lesson Learned: Cost control is not an incident. Off-window healthz failures are expected. A resting page is a required companion before lab sleep goes live — never confuse “shop resting” with “schema broken.”

Archify embeds on the sister site

• The Challenge: Path B runtime maps lived as Archify HTML under docs/archify/ and as GitLab blob links. Sponsors needed the dual-host map (shop vs docs, sleep/wake honesty) readable on Pages, same-origin — without claiming the shop is Live off-window.
• The Solution: Pages build copies allowlisted Archify HTML into /archify/; Path B companion embeds via :::archify …::: iframe + full-page link. CI pages changes: includes docs/archify/**.
• What Shipped: Archify Path B showcase (!534 / #456), thin companion link (!535 / #457), Pages publish + same-origin embed (!536 / #458). Status: Documented aid on architecture.artof.link; evening-window honesty unchanged.
• The Lesson Learned: Sister sites publish patterns; they do not rewrite Path B uptime claims. Blob URLs are not a substitute for same-origin Pages.

Mobile jump-nav clearance (then hide)

• The Challenge: Framework Pages jump-nav overlapped content at 375px after the 19 Sep harness sync (!531). A clearance fix still left mobile UX crowded.
• The Solution: First restore clearance at narrow viewports (!532 / #454). Then hide jump-nav on mobile after index FAIL post-!532 (!533 / #455) so phone readers get the article, not chrome collision.
• What Shipped: CSS/layout fixes on framework Pages; vault session notes for #454/#455. Desktop jump-nav retained.
• The Lesson Learned: Probe at 375px before calling mobile Done. Clearance and “hide chrome” are different remedies — pick the one that passes the Pages probe.

deploy-ecs soft-skips when RDS is resting

• The Challenge: Main deploy-ecs went red when Path B RDS aea-pilot-postgres was stopped for FinOps (evening-only window). CloudWatch showed connection failed — easy to misread as Archify/SQL schema lag. Daily schedule pipelines and bare .gitlab-ci.yml changes also forced deploys.
• The Solution: Migrate before force-new-deployment; on connection-failed/closed resting, soft-skip exit 0 with an honest marker (not a green Live claim). Dump orchestration CloudWatch on migrate fail. Schedule → when: never; remove bare .gitlab-ci.yml from deploy-ecs changes.
• What Shipped: !537 / #459 — scripts/ecs_apply_migrations.sh + unit tests; vault + daily-brief honesty. OIDC still lacks rds:DescribeDBInstances (connection-based skip; Describe is a follow-up).
• The Lesson Learned: Resting RDS + deploy is scheduled cost control, not an incident. Soft-skip must say so in the log line so humans do not “fix” a schema that is not broken.

Keep Learning: Second Brain OS comparison (2026-09-24)

• The Challenge: Second Brain OS (undefined-ui/second-brain-os; fork artofdream @ 347feee) ships an installable personal wiki OS — sharper wiki-vs-project rules, contradiction-preserving pages, slash-command façades, read-only subagents, and vault health scripts than AEA's harness paper alone. Without a deliberate compare, teams either ignore useful patterns or treat Claude Code / Obsidian SBOS as a Path B dependency.
• The Solution: Keep Learning and Apply — adopt only the gaps. AEA already had six Outer Harness layers; honesty ledger Documented≠Live; Keep Learning and Apply; one-finding→one-MR; MRC≠implementer; Decision layer (#446–#451); Annatar five-layer memory Documented (#484–#487); When Not to Grow. We added paper section XVIII-H naming six Documented adopts (#489–#494) and an explicit Already / Adopt / Reject matrix. Rejected: SBOS/Claude/Obsidian Path B runtime; inventing FR/NFR; closing gap issues from the docs MR; Live before Pages probe.
• What Shipped: Documented framework pages + vault notes + 24 Sep full research / visual guide regen (XVIII-H). Artifacts on GitLab: full-research 2026-09-24 · visual-guide 2026-09-24 (also Framework Home). Issues #489–#495. Not Live until architecture.artof.link probed after merge. Not a Path B shop feature. Not an SBOS endorsement.
• The Lesson Learned: Personal wiki OS patterns can sharpen Memory/Guides/Sensors/Permissions vocabulary without becoming the shop runtime. A useful GitHub template is still not a Live claim and not an install ticket.

Keep Learning: shared rules file and advisor pattern (2026-09-30)

• The Challenge: Two outside posts claimed better agent setups: one shared rules file plus one skills folder linked into every coding tool (steipete/agent-scripts), and a Claude Code "advisor" that consults a stronger model at key moments. Taking either at face value would copy someone's private setup or tie AEA to one vendor's experimental feature.
• The Solution: Check both against their sources and against AEA. AEA already has fourteen role skills with generated adapters and a drift check, an independent verifier before "done", and an escalation rule. Real gaps only: one canonical rules file with thin per-tool pointers (#502), skill header validation and a cross-tool audit (#503), and a vendor-neutral model and effort routing proposal by role (#504). Parked: the /advisor feature. Rejected: copying his rules content, and scripts that write into user-home tool folders. Paper section XVIII-I holds the adapt / park / reject table.
• What Shipped: Documented paper and guide regen dated 2026-09-30 plus these framework pages (umbrella #505). Not Live until architecture.artof.link is probed after merge. Unknown: whether every tool loads identical rules on EVO-X2, and the real cost effect of model routing.
• The Lesson Learned: A popular repo or a confident post is a source of questions, not evidence. Check the primary source, keep what AEA lacks, and label everything else honestly.

Keep Learning: verifier independence and false waits (2026-09-30, second batch)

• The Challenge: Three more posts arrived. One article said a system checked its own work and lied about it, and that most "and then" steps in agent workflows are false dependencies. The other two were a notes-folder tip and a model-architecture explainer.
• The Solution: Read the whole article, check the two papers it cites, and compare with AEA. AEA already has typed handoffs and an independent verifier, but no written rule for how that verifier stays independent, or for cross-checks that share one source. Real gaps: those two rules (#509) and a review of CI stage order, where one long Android job holds back later checks (#510). Parked: three-checker majority by default and large fan-out tricks. Rejected: the duplicate ideas, an unverifiable cost story, and the two other posts (one already covered and dated 19 Jul, one not a harness topic). Paper section XVIII-J holds the table.
• What Shipped: Documented second revision of the paper and guide (r2) plus these framework pages. Not Live until architecture.artof.link is probed after merge. Unknown: whether the rules cut errors, and how much CI time a review would save.
• The Lesson Learned: A cited paper can be real and still say less than the article claims. Read what it shows before quoting it.

Keep Learning: a judge the player cannot edit (2026-10-06)

• The Challenge: An X post described a research system that splits the work between two AI models: one plans the search, one writes code, and a separate judge scores the result. It claimed big savings and contest wins, but linked no paper, and every number is unverified.
• The Solution: Compare it with the paper rather than with the hype. AEA already has a planner and worker split, fresh sessions that read state from committed notes, and an independent checker. Two real gaps remained. First, a change can edit the very CI check that judges it without anyone being told; on the same day a correct fix had to touch the image-scan exception list, and moving a date would also have turned CI green. Second, our lesson notes have no proof rule, and none had been committed in four weeks. We added a Gate-change: line rule (#525) and an anchor rule for lessons (#526). We parked graph-based idea search and rejected the post's scoreboard. Paper section XVIII-K has the table.
• What Shipped: Documented paper and guide dated 2026-10-06 plus these framework pages (#524). Not Live until architecture.artof.link is probed after merge. Unknown: whether the new line catches a real mistake, and whether lesson notes start to appear.
• The Lesson Learned: A post with no paper can still contain a good question. Keep the question, drop the numbers, and test it against your own last red pipeline.

Keep Learning: take the taxonomy, not the picks (2026-10-07)

• The Challenge: A viral X post said someone mapped 300+ AI agent tools in one GitHub list, and picked five "that nobody reposts", with a big combined star count.
• The Solution: Check the post against its own source. The list is real and public (MIT, 305 entries), but four of the five picks are not on it, and stars measure attention. The useful part is the list's headings: an agent is a stack of model, orchestration, tools, memory, guardrails, observability and evaluation. Walking those headings against AEA found two real gaps. Nothing records whether a new tool is healthy, maintained and safely licensed before we adopt it (#527), and nothing tests our own live sites from the outside (#528). We parked AI pentesting and rejected tools that record the whole screen or run code freely. Paper section XVIII-L has the table.
• What Shipped: Documented paper and guide dated 2026-10-07, an Adoption record template with an Ollama example, and these framework pages (#529). Not Live until architecture.artof.link is probed after merge. Unknown: whether the record catches a bad adoption, and what a first scan would find.
• The Lesson Learned: A curated list is a checklist, not a recommendation. Read the headings, then check last release, licence and security before adopting anything.

Keep Learning: the paper said "model and machinery", the post said "model" (2026-10-11)

• The Challenge: A popular post called a new agent paper the most detailed so far and gave its main claim as "agent quality comes from the model". A second post re-shared a decision-layer guide, and a third listed 400+ ready-made agents and skills.
• The Solution: Find the paper and read it. It is a 17-author survey (arXiv 2606.20683) of public results: quality comes from the model and the runtime around it, and the model is necessary but not enough. That matches the six layers we already run, so little was missing. We filed four small gaps: record which layer failed (#543), write down how checkable each task type is (#544), act on a decision's confidence with thresholds and a calibration check (#545), and review borrowed skills like code (#546). One of the list's credits was wrong (checked on GitHub).
• What Shipped: Documented paper and guide dated 2026-10-11, these pages and four issues (#542 umbrella). Not Live until architecture.artof.link is probed after merge. Unknown: whether the Layer/Cause field will reveal a repeating weak layer.
• The Lesson Learned: A cut-off headline is not the paper. Read the source, and remember that a survey of other people's numbers shows direction, not measurement.

Keep Learning: say how old the number is (2026-10-18)

• The Challenge: A viral post shared "100 tips for building your personal AI agent". The ideas come from one builder's Reddit post (u/palo888, May 2026); the repost does not credit him, and nothing in it is measured.
• The Solution: Credit the original, then compare tip by tip. Most of it AEA already has: approval by reversibility, untrusted forwarded content, regression sets, session routines. Two things were missing in the guides: a rule should say whether it can ever bend and why it exists (#548), and any report quoting outside data should say where it came from and how old it is, with stale data treated as Unknown (#549). Three tips sharpen open proposals by comment (#503, #543, #545); a devil's-advocate pass is parked (#550). Paper sections III.C, VI.D and XVIII-N have the detail.
• What Shipped: Documented paper and guide dated 2026-10-18 plus these pages (#547). Not Live until architecture.artof.link is probed after merge. Unknown: whether the stamps catch a stale figure before it misleads someone.
• The Lesson Learned: The most useful tip was the most boring one: a confident answer from a stale cache is worse than "I don't know".

How This Journal Stays Honest

• Curated Milestones Only: Focuses on substantive architectural decisions, not routine bug fixes.
• Illustrative Evidence: Every diagram illustrates a concrete design decision or lesson learned.
• Transparent Status: If a test or recording has not been captured, this site plainly states so. We never claim "done" on faith.

Related Documentation

• Framework Home — Architecture formula and principles.
• Architecture Blueprint — The 6 layers and execution loop.
• Comparison & Visual Guide — 5-floor building model and What AEA claims here.
• System Stack — How the cloud infrastructure connects.
• Path B Case Study — Customer journey recordings.
• Architecture Glossary — Plain-English definitions.