feat: capture Victoria provider source shape (#97)

Merged after all required GitHub checks passed.

Author: edithatogo

.changeset/victoria-source-shape.md

@@ -0,0 +1,5 @@
+---
+'nz-legislation-tool': patch
+---
+
+Record the official Victorian legislation source shape and keep Victoria runtime support explicitly planned, unsupported, and gated.

conductor/tracks/anz-provider-victoria/plan.md

@@ -2,49 +2,49 @@
 
 ## Phase 0: Source-shape discovery
 
-**Status:** Not started.
+**Status:** Complete for source-shape discovery; runtime adapter remains gated.
 
-- [ ] Capture the official Victorian legislation source entry points and access
+- [x] Capture the official Victorian legislation source entry points and access
       terms.
-- [ ] Record machine-readable source-shape details: document types, URL
+- [x] Record machine-readable source-shape details: document types, URL
       patterns, identifiers, version cues, and provenance fields.
-- [ ] Mark ambiguous or unsupported cases explicitly instead of inferring
+- [x] Mark ambiguous or unsupported cases explicitly instead of inferring
       placeholder behavior.
 
 ## Phase 1: Authoritative formats and adapter mapping
 
-**Status:** Not started.
+**Status:** Documented; implementation remains blocked on machine-readable evidence.
 
-- [ ] Choose the authoritative formats the future Victoria adapter will trust.
-- [ ] Map discovery, retrieval, versioning, export, and provenance behavior to
+- [x] Choose the authoritative formats the future Victoria adapter will trust.
+- [x] Map discovery, retrieval, versioning, export, and provenance behavior to
       the provider contract.
-- [ ] Record unsupported capability boundaries so the adapter can fail
+- [x] Record unsupported capability boundaries so the adapter can fail
       truthfully.
 
 ## Phase 2: Fixtures and tests
 
-**Status:** Not started.
+**Status:** Complete for metadata-only fixtures and unsupported-path tests.
 
-- [ ] Build source-backed fixtures that reflect the recorded Victoria shapes.
-- [ ] Add tests for no-placeholder legal data, parsing, normalization, and
+- [x] Build source-backed metadata fixtures that reflect the recorded Victoria shapes.
+- [x] Add tests for no-placeholder legal data, parsing, normalization, and
       unsupported capability errors.
-- [ ] Add manifest/provider alignment checks for Victoria.
+- [x] Add manifest/provider alignment checks for Victoria.
 
 ## Phase 3: MCP/export and provenance
 
-**Status:** Not started.
+**Status:** Gated; provider-aware unsupported boundaries are covered.
 
-- [ ] Define Victoria source cards and provenance metadata for export output.
-- [ ] Route MCP/export behavior through provider-aware gates.
-- [ ] Keep Victoria unsupported in the manifest until source-backed evidence
+- [x] Define Victoria source cards and provenance metadata for export output.
+- [x] Route MCP/export behavior through provider-aware gates.
+- [x] Keep Victoria unsupported in the manifest until source-backed evidence
       is complete.
 
 ## Phase 4: Docs and release notes
 
-**Status:** Not started.
+**Status:** Complete for gated docs and release-note posture.
 
-- [ ] Draft Victoria-specific docs language that stays truthful about support
+- [x] Draft Victoria-specific docs language that stays truthful about support
       state.
-- [ ] Draft release-note language that distinguishes NZ stable support from
+- [x] Draft release-note language that distinguishes NZ stable support from
       Victoria prerelease or unsupported status.
-- [ ] Re-check the track against the release gates before any public claim.
+- [x] Re-check the track against the release gates before any public claim.

docs/maintainers/victoria-provider-readiness.md

@@ -0,0 +1,45 @@
+# Victoria Source Validation
+
+Validated on 2026-07-13 against the official Victorian legislation and Gazette
+entry points.
+
+## Official source
+
+- Victorian legislation: `https://www.legislation.vic.gov.au/`
+- Legislation in force: `https://www.legislation.vic.gov.au/in-force`
+- Repealed or revoked legislation: `https://www.legislation.vic.gov.au/repealed-revoked`
+- Legislative information: `https://www.legislation.vic.gov.au/legislative-information`
+- Victoria Government Gazette: `https://www.gazette.vic.gov.au/`
+
+## Verified boundaries
+
+- The Victorian legislation website is the primary official source for current
+  and superseded Acts and statutory rules.
+- The website provides separate in-force and repealed/revoked collections and
+  publishes legislation in HTML and PDF representations.
+- A public machine-readable API or feed was not verified in this discovery
+  pass. The future adapter must not infer one from page markup or download
+  links.
+- The Victoria Government Gazette is a separate official publication surface;
+  Gazette ingestion remains a separate gated capability.
+
+## Current repository posture
+
+Victoria remains explicitly planned and unsupported. No runtime search,
+retrieval, version, export, citation, or MCP capability is enabled, and this
+change adds no legal records. The provider must continue returning structured
+`unsupported_provider_capability` responses until source-backed adapter
+fixtures, provenance, and live-access evidence exist.
+
+## Before enabling runtime support
+
+1. Capture and review an official machine-readable contract, if one becomes
+   available, without committing credentials or private access details.
+2. Map authoritative formats, version history, licensing, and update cadence
+   into the provider contracts.
+3. Add source-shaped fixtures with no placeholder legal text and provenance
+   assertions.
+4. Add opt-in live smoke tests that respect Victorian source terms and rate
+   limits.
+5. Update release notes to distinguish NZ stable support from Victoria gated
+   support.

docs/maintainers/victoria-provider-source-shape.json

@@ -0,0 +1,53 @@
+{
+  "jurisdiction": "au-vic",
+  "providerId": "victorian-legislation",
+  "sourceAuthority": "Victorian Office of the Chief Parliamentary Counsel",
+  "sourceEntryPoints": [
+    "https://www.legislation.vic.gov.au/",
+    "https://www.legislation.vic.gov.au/in-force",
+    "https://www.legislation.vic.gov.au/repealed-revoked",
+    "https://www.legislation.vic.gov.au/legislative-information",
+    "https://www.gazette.vic.gov.au/"
+  ],
+  "accessTerms": {
+    "publicAccess": "free public access to the Victorian legislation website",
+    "machineReadableAccess": "no public machine-readable API or feed verified in this discovery pass",
+    "copyright": "Victorian Government copyright and website terms apply"
+  },
+  "authoritativeFormats": ["HTML", "PDF"],
+  "convenienceFormats": ["HTML", "PDF"],
+  "collections": ["in-force", "repealed-or-revoked", "legislative-information"],
+  "urlPatterns": [
+    "https://www.legislation.vic.gov.au/in-force",
+    "https://www.legislation.vic.gov.au/repealed-revoked",
+    "https://www.legislation.vic.gov.au/sites/default/files/{year}-{month}/{filename}.pdf"
+  ],
+  "identifierCues": [
+    "title and year displayed by the Victorian legislation website",
+    "Act and statutory-rule version history",
+    "consolidated current and superseded versions"
+  ],
+  "versionCues": [
+    "current and superseded versions in the in-force collection",
+    "repealed or revoked status",
+    "version history and commencement information",
+    "point-in-time material where published"
+  ],
+  "adapterMapping": {
+    "search": "Not enabled; use official browse/search pages only after a machine-readable contract is verified.",
+    "retrieval": "Future adapter may retrieve authoritative PDF or HTML pages with format and authority labels.",
+    "versioning": "Use published version history, commencement, and superseded/repealed cues; do not infer versions from filenames alone.",
+    "export": "Unsupported until a source-backed parser and provenance-preserving export exists.",
+    "provenance": "Emit sourceAuthority, jurisdiction, source URL, format, authority status, and retrieval timestamp.",
+    "unsupported": "Return structured unsupported_provider_capability for runtime operations until tests and fixtures prove the adapter."
+  },
+  "edgeCases": [
+    "the website distinguishes Acts from statutory rules",
+    "repealed or revoked material is separate from in-force material",
+    "PDF and HTML representations may have different authority or convenience status",
+    "no public machine-readable API or feed was verified in this discovery pass",
+    "the Victoria Government Gazette is a separate official publication surface"
+  ],
+  "runtimeStatus": "unsupported",
+  "fixturePolicy": "metadata-only source-shape fixture; no legal text or fabricated records"
+}

tests/victoria-provider-source-shape.test.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+import {
+  getProviderCapability,
+  getUnsupportedProviderCapability,
+} from '../src/providers/capability-manifest.ts';
+import { getProviderSourceCard } from '../src/providers/source-cards.ts';
+
+const fixture = JSON.parse(
+  readFileSync('docs/maintainers/victoria-provider-source-shape.json', 'utf8')
+) as {
+  jurisdiction: string;
+  providerId: string;
+  sourceEntryPoints: string[];
+  authoritativeFormats: string[];
+  collections: string[];
+  runtimeStatus: string;
+  fixturePolicy: string;
+  adapterMapping: Record<string, string>;
+};
+
+describe('Victoria provider source shape', () => {
+  it('records official metadata without legal records', () => {
+    expect(fixture).toMatchObject({
+      jurisdiction: 'au-vic',
+      providerId: 'victorian-legislation',
+      authoritativeFormats: ['HTML', 'PDF'],
+      collections: expect.arrayContaining(['in-force', 'repealed-or-revoked']),
+      runtimeStatus: 'unsupported',
+      fixturePolicy: expect.stringContaining('metadata-only'),
+    });
+    for (const url of fixture.sourceEntryPoints) {
+      expect(new URL(url).protocol).toBe('https:');
+      expect(new URL(url).hostname).toMatch(/(?:legislation\.vic\.gov\.au|gazette\.vic\.gov\.au)$/);
+    }
+  });
+
+  it('keeps Victoria blocked in capability, source-card, and unsupported contracts', () => {
+    expect(getProviderCapability('au-vic')).toMatchObject({
+      providerId: fixture.providerId,
+      releaseChannel: 'planned',
+      sourceAuthority: 'Victorian legislation website',
+    });
+    expect(getUnsupportedProviderCapability('au-vic', 'search')).toMatchObject({
+      error: 'unsupported_provider_capability',
+      jurisdiction: 'au-vic',
+      providerId: fixture.providerId,
+    });
+    expect(getProviderSourceCard('au-vic')).toMatchObject({
+      runtimeSupported: false,
+      runtimeKind: 'planned-au-provider',
+      releaseGate: { status: 'blocked' },
+      submissionGate: { status: 'blocked' },
+    });
+    expect(fixture.adapterMapping.export).toMatch(/Unsupported/);
+  });
+});