Release v5.0.0

[5.0.0] - 2026-09-18

Supersedes the unreleased 4.3.1 and 4.4.0: neither was ever tagged or published,
the Marketplace still carries 4.2.0, and this release contains every commit of
both. One delivery, one changelog entry, one tag. The major is for the plugin
layout and the per-surface artifact roots below; everything else is additive.

Breaking Changes

• The Claude Code plugin is generated, and its layout changed. commands/ no
  longer exists: the ten slash commands are skills with disable-model-invocation,
  and /aldc:al-agent-instructions-create is now /aldc:al-agent-instructions.
  rules-templates/ is now rules/. Agent frontmatter no longer declares
  maxTurns. Re-run /aldc:al-initialize after upgrading.
• Requirement artifacts follow the surface. A project worked from Claude Code
  keeps its plans under .claude/plans, and one worked from Codex under
  .agents/plans, with audits alongside them. Copilot and the VS Code extension
  keep .github/plans. Every consumer now reads plans.root and audits.root
  from aldc.yaml, so a project that wants the old location sets it there and
  nothing else changes. Move the folder or declare the root; the shipped
  aldc.yaml is seeded and never overwrites a project's own.
• The VS Code extension's Viewer reads .github/plans, so it does not yet see
  plans written from Claude Code or Codex. That is tracked in the extension
  repository and is not addressed here.

Added

• VS Code extension 4.3.0 (distributed separately as the VSIX): the Project Manager
  panel and Explorer view to install, update, verify, restore and run Doctor with
  previews and confirmations; the ALDC Visor tree of plan artifacts per requirement;
  the AL Collection: Run Doctor command rendering the packaged Doctor report.

• Bilingual installation journey with a surface selector for VS Code, Copilot CLI,
  Claude Code and Codex, copyable steps and a bounded first request. Published
  extension and source routes are explicitly separated.

• Structured installer output for hosts: install, status, verify-install and
  rollback accept --json. Previews carry a plan digest and --expect-plan
  refuses to apply a plan that changed after the preview. Each file reports whether
  a replace overwrites a local customization. Human output is unchanged.

• Upgrades from a release that recorded no receipt no longer ask about the toolkit's
  own untouched files. known-installations.json records what previous releases
  wrote at each path, generated by installing each release from its tag
  (npm run build:known-hashes), so the installer recognises its own content and
  reserves the collision question for files that were really edited. Upgrading an
  untouched 4.2.0 installation with two customized files goes from 35 collisions to
  2. The manifest is consulted only when no receipt exists, never for seeded files,
  and every replacement is still previewed, backed up and reversible.

• solution anchor in aldc.yaml: workspaceFile and roots.application /
  roots.test declare the multi-root layout of the AL solution. The installer
  detects the folders that exist (AL-Go appFolders / testFolders first, then
  discovery) and writes them there; it never creates a folder.

• aldc solution reports the declared layout against the folders on disk and, with
  --write, rewrites solution.roots in place: the two values change and every
  comment and every other setting in aldc.yaml survives, with the previous file kept
  under .aldc-install. A root that still holds its app.json is never overridden —
  with several apps only the developer knows which one the solution means — and a root
  that lost its manifest is reported, never cleared. Detection used to run only at
  installation, so a customized aldc.yaml froze the layout it was installed with.

• aldc.code-workspace is generated from that layout at installation instead of
  copied: root, application, tests, and the BCQuality root when the configured mode
  is external-multiroot. It stays a seeded file, so it is written once and then
  belongs to the developer.

• The installation marker records the installed version, and status reports it as
  installedVersion so a host can compare it with what it packages. Markers written
  before this release report null and are never repaired.

• tools/bcquality/config.js reports toolkitRoot and solution alongside the
  BCQuality configuration, so every Node consumer reads one source of truth. Doctor
  still receives --toolkit explicitly, now resolved by its caller from that value.

• Doctor reports manifests that declare different BC application targets (for
  example an App on BC28 next to a Test on BC27) as an advisory configuration
  problem. The exit code is unchanged; the compiler adjudicates.

• Read-only installation inspection (inspect) reporting absent, invalid, matching
  and drifted receipts and whether the last transaction can be restored. Receipts
  whose file map is not an object or contains an unsafe path are reported as
  invalid, never thrown or planned against. status and verify-install report
  the target recorded by the receipt (receiptTarget) and refuse to verify another
  requested --target-dir (targetMismatch).

• Developer Reviewer for independent direct-increment review, with a shared review
  pipeline, one bounded correction round and human approval.

• Explicit BCQuality plugin mode alongside external multiroot, with shared provider
  identity, stage evidence and native fallback rules across review agents.

• Doctor configuration snapshots and BCQuality observations distinguish discovery,
  loading, execution and best-effort knowledge-index generation.

• Architecture-led specification decomposition with stable unit ownership, separate
  authoring/implementation dependencies and joint review of current revisions.

• Dedicated Spec Agent and a shared specification entrypoint, with human approval
  before implementation and contracts proportionate to requirement complexity.

• Read-only Doctor diagnostics for specification, App compilation, Test compilation
  and test execution, with configuration and runtime observations reported separately.

• Opt-in BC29-native profile for Copilot Chat, with role-specific AL tool permissions
  and AL18 guidance. BC28 remains the default for new installations.

• Canonical adapters for Claude Code, Copilot CLI and Codex, with generated content
  integrity checks and project initialization.

• Installation previews, collision reporting, verification receipts and recoverable
  updates that preserve existing project memory and protect subsequent edits.

• BCQuality knowledge index. The multiroot installers build it through PowerShell 7
  right after the pinned checkout and record a receipt naming the corpus revision it
  was built over; aldc bcq-index [--build] reports that state and builds it on
  request, and aldc status shows it with the command to fix it. This earns a new
  index state, prebuilt: weaker than generated, because it asserts a prior
  authorized build rather than one in this invocation, and claimable only with the
  receipt's generator, index path, SHA-256 and corpus revision. Missing PowerShell 7
  is never fatal — reviewers fall back to path-based discovery.

• BCQuality in the design phases. Until now the knowledge layer was reachable only
  during review, so an architect could contradict a house rule and learn about it
  from a finding two phases later, and a spec could declare acceptance criteria
  unrelated to the knowledge the reviewer would judge against. Architect and Spec
  Agent now read the corpus as context.

• docs/templates/bcquality-design-guidance.md is the single source of the read
  path: where the corpus lives, which frontmatter filters decide inclusion, layer
  precedence (custom over community over microsoft, recording the displaced path),
  how to select without loading the index, the selection file to write and the
  evidence line to carry. Both roles link it; neither copies it. Every step is a
  directory listing or a file read, so it works on hosts where a role cannot
  execute anything, and it needs no PowerShell, no Node and no index.

• The architect writes {req}.bcq-constraints.md — house rules first and
  uncapped, then platform constraints by design area — and {req}.bcq-selection.json.
  Deviating from a house rule is allowed and recorded with its reason in the
  architecture decisions; it reaches the human gate that already exists.

• The spec declares, under section 11, a Review criteria (BCQuality) table:
  one row per object with the cited knowledge path, what the reviewer will check
  and the layer, mirrored to {req}.bcq-criteria.json. The table states what will
  be reviewed; it does not judge the spec.

• review.criteria in the review report: each declared criterion comes back met,
  unmet or not evaluated, with house rules counted separately, and the Conductor
  renders the delta in the Checkpoint card and the phase-complete document.

• One author for every surface. claude-plugin/ was the only place in the
  repository with hand-written primitives, and .claude/, the Copilot CLI plugin
  and the Codex plugin are generated from it — so all three inherited its drift
  from the canonical trees that ship in the VSIX. The generator now emits every
  file of all three packages, and the line that adopted anything it did not produce
  is gone: delete a package, regenerate, and it returns byte-identical.

• Each adapted file carries the path and SHA-256 of its canonical source, plus a
  binding table translating every Copilot surface to its host equivalent. The
  adapter may change four things — frontmatter, paths, tool vocabulary and that
  preamble — and nothing else.

• Role entry skills for the nine user-invocable roles (/aldc:architect, :spec,
  :conduct, :develop, :review, :triage, :presales, :agent-builder,
  :audit). The three TDD subagents are user-invocable: false in the canonical
  and get none; only the Conductor launches them.

• al-agent-build-instructions exists as a workflow on Claude Code for the first
  time, and the twelve Codex role profiles declare sandbox_mode, derived from the
  tool grant each canonical contract already makes.

Changed

• aldc.code-workspace is now a seeded file: the installer creates it when it is
  missing and never replaces it afterwards, not even with --force. The multi-root
  workspace definition belongs to the developer, like project memory. Previously a
  profile switch or a replace policy overwrote a customized workspace file.

• Aligned canonical package, plugin and catalog versions to 4.3.0 for the
  upcoming release; previously built artifacts remain unchanged.

• Specifications capture technical contracts and acceptance criteria without
  anticipating AL implementation bodies at MEDIUM complexity.

• Agent routing preserves approved architecture and passes approved specifications
  to Conductor or Developer according to complexity.

• Instruction and domain-guide references are retained for continuation from the
  current artifacts; native capabilities can satisfy relevant tool requirements.

• The configured BCQuality skill is al-code-review at 0.2.0. The previous default
  named a skill upstream had removed, so plugin mode looked for something that no
  longer existed, found nothing, reported nothing and silently reviewed with native
  rules only. An installation exposing the pre-0.2.0 name is now an incompatible
  provider, never a renamed match.

• pilotSkills is empty, which means the full corpus. It previously pinned the run to
  three review leaves, so fifteen never executed; Entry's own relevance decides now,
  and a leaf whose domain the diff does not touch returns not-applicable cheaply.
  Entry can also dispatch more than one first-level skill, so every returned report is
  retained instead of only the first.

• Review findings gate on evidence, not severity alone. A finding gates when it is
  blocker/major and either knowledge-backed at confidence: high or a native
  check with an applicable rule; native checks gate on severity alone, because their
  capped confidence records the absence of a citable article, not doubt. Agent
  findings never gate. Only gating findings and non-gating findings carrying
  suggested-code become implementer work; the rest are recorded as recommendations.
  Conductor recomputes this from findings[], since summary.counts cannot express it.

• The evidence validator checks what it previously only carried: severity and
  confidence against their vocabularies, a cited finding's id against
  references[0].path, and the advisory caps on native:/agent: findings.

• The review phase closes that loop without gaining authority over it. Reporting
  the criteria is bookkeeping over findings that already exist: it adds no finding,
  changes no severity and never alters the verdict, which still depends only on
  findings[].

• validate_evidence.py checks the two things a criteria block can get wrong: the
  buckets must add up to what was declared, and an unmet criterion must be cited by
  a finding that actually exists — matched across sub-results, where provider
  findings live.

• Four of the eight always-on AL rules had been widened to every .al file in the
  Claude Code plugin, applying Codeunit- and Query-scoped guidance where it does not
  hold. Each generated rule now declares exactly the globs its canonical applyTo
  declares. al-agent-toolkit had also lost its description and its four specific
  globs.

• The human gate that Copilot's handoffs: button supplied has no equivalent in
  Claude Code or Codex, where an agent delegates through a tool with no click. It is
  carried as an adapter concern — a row in the mapping table, a line in the Codex
  host preface — rather than as canonical text that would restate for Copilot what
  its own host already enforces.

• Six agent descriptions gained the sentence that says when to use them, and
  al-developer's was corrected: it claimed the agent builds via the terminal and
  validates with tests, which stopped being true.

Removed

• skill-manifest, the end-of-pipeline handoff contract for the sibling
  collections CIRCE (Copilot Studio) and DELFOS (Power BI). It shipped in the
  VS Code and npm distributions and was absent from the Claude Code, Copilot CLI
  and Codex plugins; it is now withdrawn from every surface, along with its
  declaration in aldc.yaml and its row in the Core Spec. Projects that already
  installed it keep the files on disk; the installer stops writing them.

Fixed

• The BCQuality index was invisible from every package. aldc status reported it
  unobserved whatever its real state and aldc bcq-index could not load at all,
  because the installer required ../tools/bcquality/index-state literally — a path
  that exists only in this repository. Packaged, install.js sits at the package root
  with the toolkit trees wherever ALDC_PACKAGE_DIR points, which is how the payload
  it copies was already resolved; the index now resolves the same way. The gap was that
  nothing ever ran the installer from that shape, so a new test does, and a require
  written against __dirname now fails there instead of in someone's editor.

• Requirement-set validation never ran. tools/aldc-validate read only the flat plans
  root, while every agent and workflow writes .github/plans/{req_name}/{req_name}.*.md,
  so incompleteRequirementSets reported "no requirement sets found" on every correctly
  laid out project and a requirement missing its test-plan passed clean. The validator now
  reads each requirement folder, treats the folder name as the requirement, accepts the
  Architect-assigned unit specs of a decomposed requirement in place of {req}.spec.md,
  skips the archive folder, and reports contracts left in the plans root instead of
  ignoring them. The specification said flat where the contracts say folder-per-requirement;
  it now says folder-per-requirement, and states that the plans root is host-neutral
  (configurable under plans.root, the same location for every surface) unlike toolkitRoot.

• The installer and Doctor now read the same solution. The installer walks for
  app.json (at most three levels, pruning hidden folders, dependencies, build
  output and symlinks) instead of probing src, app, test and tests, and both
  treat a folder ending in .Test or .Tests as the test project. AL-Go names the
  app folder after the app, so the usual layout — MiExtension next to
  MiExtension.Test — previously left solution.roots empty and the generated
  workspace without its project folders, while Doctor classified the suite as a
  second app.

• Doctor reads the solution, not just the folder it was pointed at. A manifest was
  classified by the path segments below the scanned root, so scanning the test folder
  itself left no segment to judge by and its suite was reported as an application; the
  scanned folder's own name now answers for a manifest at the root. Configuration is
  read per project as well: the .vscode of every discovered project, not only the
  root's, which is where mcp.json, settings.json, tasks.json and launch.json
  actually live in an AL-Go layout. Pointed at app/ or test/ Doctor reported no
  plans folder and no MCP servers while both existed one level up or down — a solution
  read as three unrelated projects.

• Review coverage now distinguishes provider execution from index generation and
  incomplete audits from zero-finding completed reviews. Dredd remains advisory
  and supports explicit file scope and chat-only reports when writes are forbidden.

• Profile projection with CRLF files, packaged template references and cross-host
  role links.

• Incomplete payloads, installation recovery edge cases and inconsistent role counts.

• Package provenance no longer lists derived build artifacts as sources. Python
  writes __pycache__ the first time a shipped script is imported, so it exists on
  a developer's disk and in a real installation but never in a clean checkout;
  listing one made the Copilot CLI, Claude and Codex sync --check runs drift on
  CI while passing locally, and would make a user's own installation look tampered
  with. Shipped sources are still hash-checked individually.

Compatibility

• Node.js 20+ for command-line installation; Python 3.9+ for Doctor.
• BC29-native selection does not upgrade BC, AL Language or project manifests.
• Extension and registry releases are separate; canonical package, plugin and catalog
  metadata declare 4.3.0. Earlier VSIX files retain their original version.
• Persisted BCQuality evidence written before this release may now fail the
  bcquality-evidence workflow: reports carrying an invalid severity, a cited
  finding whose id is not its knowledge path, or an agent: finding at
  blocker/major were always outside the contract and were simply not checked.
  Re-run the review to regenerate the report; the reports themselves are evidence and
  are not edited by hand.
• aldc bcq-index exits 1 when a usable index is missing on a machine that could
  build one, so a script can branch on it. It exits 0 when there is nothing to do,
  including on a machine without PowerShell 7, where no run could build one.

What's Changed

• fix(conductor): ruta .github/-prefijada para las micro-reglas (resto … by @javiarmesto in #76
• docs(spec): Core Spec v1.2 - tiers normalizados, BCQuality, tooling d… by @javiarmesto in #77
• chore(f2): .claude/ como espejo del plugin con check en CI + banners … by @javiarmesto in #78
• docs: restructure README presentation with hero banner and discovery-first layout by @javiarmesto in #80
• docs: use blueprint PNG as README hero banner by @javiarmesto in #81
• feat(claude-plugin): remove skill-extension-manifest (CIRCE/DELFOS) by @javiarmesto in #88
• fix(plugin): add root marketplace.json so remote /plugin install works (#84) by @javiarmesto in #85
• Use the official Microsoft Learn MCP endpoint for microsoft-docs by @DigiTecKid in #90
• feat(brand): align ALDC with the Open Engineering visual identity by @javiarmesto in #93
• refactor(brand): simplify and strengthen the ALDC mark by @javiarmesto in #94
• refactor(brand): move ALDC toward an engineering notebook by @javiarmesto in #95
• Github Copilot plugin by @lewishyettFGT in #96
• fix(claude-plugin): remove leftover VS Code Copilot tool references by @javiarmesto in #89
• feat: adaptación BC29/AL18 para Copilot Chat y plugins Claude/CLI by @javiarmesto in #97
• feat: recoverable canonical plugin packaging and Codex bootstrap by @javiarmesto in #100
• feat: canonical Doctor with independent operation readiness by @javiarmesto in #101
• feat: canonical Spec Agent with shared contract and host adapters by @javiarmesto in #102
• feat(claude-plugin): generate the whole plugin from the canonical sources by @javiarmesto in #104
• feat(codex): plans root, audits root, sandbox_mode and a manifest verified against the host by @javiarmesto in #105
• release: ALDC 5.0.0 — one delivery across every surface by @javiarmesto in #103
• fix(install): resolve the BCQuality index from the package, not from this repo by @javiarmesto in #106

New Contributors

• @DigiTecKid made their first contribution in #90
• @lewishyettFGT made their first contribution in #96

Full Changelog: v4.2.0...v5.0.0