From f5e40a1881cf4a01fed5d6cc0bf345a32c3dc71a Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 19:51:10 +0900 Subject: [PATCH 01/17] test(docs): define maintenance and hyperlink reconciliation RED --- ...autonomousMaintenanceDocumentation.test.ts | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 src/autonomousMaintenanceDocumentation.test.ts diff --git a/src/autonomousMaintenanceDocumentation.test.ts b/src/autonomousMaintenanceDocumentation.test.ts new file mode 100644 index 00000000..bfa7e416 --- /dev/null +++ b/src/autonomousMaintenanceDocumentation.test.ts @@ -0,0 +1,81 @@ +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; + +import { describe, expect, it } from 'vitest'; + +const repositoryFile = (path: string): string => + readFileSync(resolve(process.cwd(), path), 'utf8'); + +const assessmentPath = + 'docs/assessments/2026-08-10-conversation-documentation-reassessment.md'; + +describe('autonomous maintenance and acquisition documentation', () => { + it('treats user-reported premature stopping as a control-plane incident', () => { + const agents = repositoryFile('AGENTS.md'); + const claude = repositoryFile('CLAUDE.md'); + + for (const guidance of [agents, claude]) { + expect(guidance).toContain('scheduler-control incident'); + expect(guidance).toContain('zero completion credit'); + expect(guidance).toContain('two materially distinct executable repository actions'); + expect(guidance).toContain('reset the two-sweep count'); + expect(guidance).toContain('simplify the external prompt'); + } + }); + + it('keeps the dated whole-conversation reassessment discoverable', () => { + const index = repositoryFile('docs/README.md'); + const assessment = repositoryFile(assessmentPath); + + expect(index).toContain( + 'assessments/2026-08-10-conversation-documentation-reassessment.md', + ); + expect(assessment).toContain( + 'main@f2a87bc32710574b54c0ccd1a4f33fee2c6f2224', + ); + expect(assessment).toContain('## Fitness matrix'); + expect(assessment).toContain('## Whole-conversation coverage decision'); + expect(assessment).toContain('## Sufficiency decision'); + expect(assessment).toContain('physical relational ERD'); + expect(assessment).toContain('`not_applicable`'); + }); + + it('keeps release source readiness separate from registry operational acceptance', () => { + const assessment = repositoryFile(assessmentPath); + + expect(assessment).toContain('protected manifests agree at `0.6.0`'); + expect(assessment).toContain( + 'Registry operational acceptance remains open under issue #118', + ); + expect(assessment).toContain( + 'Source integration does not prove that `v0.6.0` exists', + ); + }); + + it('reconciles the protected DOCX hyperlink decision', () => { + const adr = repositoryFile( + 'docs/adr/0026-bounded-docx-external-hyperlinks.md', + ); + const adrIndex = repositoryFile('docs/adr/README.md'); + const fitness = repositoryFile('docs/DOCUMENTATION_FITNESS.md'); + const traceability = repositoryFile('docs/TRACEABILITY.md'); + const changelog = repositoryFile('CHANGELOG.md'); + + expect(adr).toContain('Status: Accepted'); + expect(adr).toContain('implemented on protected `main` through PR #137'); + expect(adr).not.toContain('Protected `main` does **not** yet expose'); + expect(adr).not.toContain('active PR #137 implements'); + expect(adrIndex).toMatch( + /\[0026\][^\n]*\| Accepted \| Bounded external hyperlinks/u, + ); + expect(fitness).toMatch( + /DOCX bounded external hyperlinks[^\n]*present_current[^\n]*implemented_on_protected_main/u, + ); + expect(traceability).toMatch( + /DOCX bounded external hyperlinks[^\n]*protected-main #137/u, + ); + expect(changelog).toMatch( + /Expanded deterministic DOCX fidelity[^\n]*bounded external HTTP\(S\) hyperlinks/u, + ); + }); +}); From 94b401beedc7cbae0c0107a8d57bba36a21566c6 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 19:56:00 +0900 Subject: [PATCH 02/17] docs(agent): make premature-stop recovery executable --- AGENTS.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 108387c3..d1a287a1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,15 @@ Do not infer shipped behavior from conversation history, PR bodies, model output When an external scheduler or autonomous maintainer is operating on Inkspan, repository work is **work-conserving**: after every mutation, proof, merge, closure, review/check observation, or defer decision, select the next highest-value safe Inkspan action while practical execution budget remains. A blocked PR blocks only that lane; queued CI, reviewer latency, provider cooldown, a read-only dependency, or missing approval must not freeze unrelated work. -A status report, prompt update, documentation assessment, green check, PR creation, review request, or one completed product slice is an intermediate result rather than repository completion while another safe action exists. Before ending an autonomous run, re-scan open PRs/issues, protected `main`, changed branches, reviews/checks/security findings, documentation fitness, release evidence, and buyer-visible gaps; continue if any executable item remains. +A status report, prompt update, documentation assessment, green check, PR creation, review request, or one completed product slice is an intermediate result rather than repository completion while another safe action exists. Before ending an autonomous run, perform two fresh whole-repository sweeps across open PRs/issues, protected `main`, changed branches, reviews/checks/security findings, documentation fitness, release evidence, and buyer-visible gaps. If either sweep finds an executable item, execute it and reset the two-sweep count. + +### User-redirection and scheduler-control incident rule + +If the user says that work stopped early, that other work remained, or that the prompt must be updated because execution ended prematurely, treat that statement as a **scheduler-control incident** rather than a request for another status recap. A prompt edit, inventory, documentation-only change, PR creation, review request, queued check, or local artifact receives zero completion credit. + +After repairing the control instruction when needed, immediately rebuild the live Inkspan queue and continue repository execution in the same invocation. When safe work exists, complete at least **two materially distinct executable repository actions** before considering termination. If exactly one safe action exists, execute it and then prove through a fresh queue rebuild that every other lane is currently non-actionable under the writer lease, dependency order, repository policy, and safety constraints. + +When a generic scheduled-task error or repeated missed run suggests prompt-size or control-plane fragility, keep detailed product truth in the canonical GitHub documentation graph and simplify the external prompt instead of appending historical snapshots. Scheduler failure is local operational debt; it is never evidence that Inkspan product work is complete. The external scheduler remains the execution authority for cadence and run continuation. These repository instructions define Inkspan-specific writer, evidence, product, and safety discipline only; they do not make scheduling or autonomous orchestration an Inkspan runtime capability. From 89203e70cd45be304a2861f0c86506de658a33c4 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 19:56:44 +0900 Subject: [PATCH 03/17] docs(agent): bind user redirection to continued execution --- CLAUDE.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6b725289..a28a8203 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,7 +31,15 @@ A queued, pending, cancelled, skipped-required, stale-head, predecessor-head, st When an external scheduler or autonomous maintainer drives Inkspan work, execution is **work-conserving**. After each mutation, proof, merge, closure, review/check observation, or defer decision, choose the next highest-value safe Inkspan item while practical execution budget remains. A blocked PR blocks only that lane; do not let queued CI, reviewer latency, provider cooldown, a read-only dependency, or missing approval freeze unrelated source, documentation, operability, or product work. -Do not use a status report, prompt update, documentation assessment, green check, PR creation, review request, or one completed product slice as a stopping condition while another safe action exists. Before ending an autonomous run, re-scan open PRs/issues, protected `main`, changed branches, review/check/security evidence, canonical-document fitness, release readiness, and buyer-visible gaps; continue when an executable item remains. +Do not use a status report, prompt update, documentation assessment, green check, PR creation, review request, or one completed product slice as a stopping condition while another safe action exists. Before ending an autonomous run, perform two fresh whole-repository sweeps across open PRs/issues, protected `main`, changed branches, review/check/security evidence, canonical-document fitness, release readiness, and buyer-visible gaps. If either sweep finds an executable item, execute it and reset the two-sweep count. + +### Premature-stop recovery + +When the user says that execution stopped early, that other work remained, or that the prompt must be updated because work was left behind, treat the statement as a **scheduler-control incident**. Do not answer it with another inventory or status recap. A prompt update, documentation-only change, PR creation, review request, queued check, or local artifact receives zero completion credit. + +Repair the control instruction only when necessary, then rebuild the live Inkspan queue and continue repository execution in the same invocation. When safe work exists, complete at least **two materially distinct executable repository actions** before considering termination. If exactly one safe action exists, perform it and use a fresh queue rebuild to prove that every other lane is currently non-actionable under the writer lease, dependency order, repository policy, and safety constraints. + +If repeated generic scheduled-task errors suggest prompt-size or control-plane fragility, move durable product detail into the canonical GitHub graph and simplify the external prompt instead of appending incident history. Scheduler failure is local operational debt, not Inkspan product completion. The external scheduler remains the execution authority for cadence and continuation. This file constrains repository-specific writer/evidence/product/safety behavior and does not make scheduling or autonomous orchestration part of Inkspan runtime architecture. From f64ec18f83d55783d8c9e40af751150e2faf8520 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 19:57:22 +0900 Subject: [PATCH 04/17] docs(index): expose whole-conversation reassessment --- docs/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 759ed3d5..2b617f7c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,7 @@ This directory is the discoverable index for Inkspan's product, technical, secur | [`../ARCHITECTURE.md`](../ARCHITECTURE.md) | Current protected-main implementation architecture and bounded-context ownership | | [`../SECURITY.md`](../SECURITY.md) | Protected-main private vulnerability reporting, supported security lines, coordinated disclosure, and claim limits | | [`DOCUMENTATION_FITNESS.md`](DOCUMENTATION_FITNESS.md) | Acquisition completeness matrix, implementation maturity, deliberate non-applicability and remaining canonical gaps | +| [`assessments/2026-08-10-conversation-documentation-reassessment.md`](assessments/2026-08-10-conversation-documentation-reassessment.md) | Dated whole-conversation reassessment, protected/operational deltas, and scheduler-control remediation | | [`PRD.md`](PRD.md) | Product users, jobs, buyer outcomes, non-goals, acceptance and claim boundaries | | [`TRD.md`](TRD.md) | Technical invariants, runtime boundaries, failure semantics and release evidence | | [`CONTRACTS.md`](CONTRACTS.md) | Public package/API/event/schema/plugin/collaboration and host-integration contracts | @@ -27,6 +28,8 @@ This directory is the discoverable index for Inkspan's product, technical, secur Root `SECURITY.md` is now implemented on protected `main` and remains the normative reporting/disclosure policy. ADR 0017 records the durable architecture/process decision and ownership/claim boundaries without duplicating policy prose. `CHANGELOG.md` records shipped/reviewable change history, while `AGENTS.md` and `CLAUDE.md` point contributors back to this canonical graph rather than becoming parallel architecture specifications. +Dated reassessments capture a reviewed source generation and its active or operational deltas without placing mutable workflow-run identities into timeless architecture. They do not override protected `main`, accepted ADRs, or current exact-head evidence. + ## Status discipline Use these terms consistently: @@ -51,4 +54,4 @@ Inkspan owns deterministic editor/conversion behavior, versioned document/eviden A material contract change should update the smallest affected set of PRD/TRD/CONTRACTS/Architecture/ADR/UML/data-model/security/test/operability/traceability records and corresponding machine-checkable documentation contracts. If a document is unaffected, preserve it rather than performing churn solely for consistency optics. -Stable architectural documents should avoid embedding transient PR heads, workflow run IDs, or temporary provider states. Put dated operational evidence in bounded doctoring/evidence records instead. \ No newline at end of file +Stable architectural documents should avoid embedding transient PR heads, workflow run IDs, or temporary provider states. Put dated operational evidence in bounded doctoring/evidence records instead. From 3a53f3e50a03193032b0ba7362dac482d2b0f538 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 19:58:31 +0900 Subject: [PATCH 05/17] docs(assessment): re-evaluate whole-conversation baseline --- ...conversation-documentation-reassessment.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/assessments/2026-08-10-conversation-documentation-reassessment.md diff --git a/docs/assessments/2026-08-10-conversation-documentation-reassessment.md b/docs/assessments/2026-08-10-conversation-documentation-reassessment.md new file mode 100644 index 00000000..1baacec4 --- /dev/null +++ b/docs/assessments/2026-08-10-conversation-documentation-reassessment.md @@ -0,0 +1,99 @@ +# Inkspan conversation-to-GitHub documentation reassessment — 2026-08-10 + +Status: Reviewable protected-main reassessment with explicit operational deltas + +## Purpose + +This assessment answers whether an independent product, engineering, security, operations, or acquisition reviewer can reconstruct the durable Inkspan decisions established through the project conversation from GitHub alone. It compares the canonical documentation graph with protected `main`, the current issue queue, and protected implementation evidence. It does not treat conversation text, a pull-request body, a model response, or predecessor evidence as shipped authority. + +## Evidence generation reviewed + +- Protected implementation generation reviewed: `main@f2a87bc32710574b54c0ccd1a4f33fee2c6f2224`, including the unified Inkspan 0.6.0 source candidate from #135 and bounded DOCX external hyperlinks from #137. +- Release operational-acceptance line reviewed separately: issue #118. +- Repository guidance reviewed: `AGENTS.md`, `CLAUDE.md`, `docs/README.md`, `docs/DOCUMENTATION_FITNESS.md`, `docs/PRD.md`, `docs/TRD.md`, `ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/UML.md`, `docs/DATA_MODEL.md`, `SECURITY.md`, `docs/THREAT_MODEL.md`, `docs/TEST_STRATEGY.md`, `docs/OPERABILITY.md`, `docs/TRACEABILITY.md`, and the ADR index. + +Mutable heads, checks, reviews, workflow runs, releases, tags, and registry records must still be re-fetched immediately before any merge or release decision. The immutable generation above records the basis for this dated documentation assessment only. + +## Fitness matrix + +| Documentation family | Fitness | Implementation interpretation | Reassessment conclusion | +| --- | --- | --- | --- | +| PRD | `present_current` | Protected product scope plus explicitly labeled planned work | Users, buyer jobs, deterministic authoring/conversion, accessibility, standalone/MSA behavior, host ownership, non-goals, and acceptance are reconstructable. | +| TRD | `present_current` | Protected runtime and package authority | Validation, evidence, packaging, browser, Office, failure, security, and release semantics are reconstructable. | +| Root Architecture | `present_current` | `implemented_on_protected_main` for current bounded contexts | Standalone operation, naruon/CWL composition, host-owned transport/persistence/tenancy, trust boundaries, and deployment responsibilities are explicit. | +| Contracts | `present_current` | Protected public package/API/schema/plugin/collaboration contracts | Consumers do not need implementation archaeology to identify public authority or degraded behavior. | +| ADR graph | `present_current` after this reconciliation | Accepted decisions through ADR 0026 are protected | Alternatives, consequences, compatibility, failure/recovery, security, verification, rollback, and supersession are reconstructable without leaving the merged hyperlink capability marked Proposed. | +| UML | `present_current` | Protected components, sequences, states, deployments, and authority flows | Current runtime/control/evidence interactions are diagrammed as code; a new diagram is not required for the bounded run-level hyperlink extension. | +| DATA_MODEL / conceptual ERD | `present_current` | Current logical document/evidence/conversion/release values plus explicit host-owned entities | The logical model is sufficient for Inkspan-owned state and evidence. | +| Physical relational ERD | `not_applicable` | `out_of_scope` while Inkspan owns no application database | Creating tables merely to satisfy an ERD checklist would falsify the product boundary. A physical ERD becomes mandatory only if an accepted decision moves persistence into Inkspan. | +| Security / Threat Model | `present_current` | Protected disclosure and runtime/supply-chain boundaries | Private reporting, bounded diagnostics, untrusted input, host authority, Office, browser, collaboration, package, and release threats are reconstructable. | +| Test Strategy | `present_current` | Protected deterministic, package, browser, Office, security, accessibility, and exact-coverage evidence | Evidence classes and claim limits remain separate from badges or model prose. | +| Operability / release / rollback | `present_current` | Protected release source path plus live operational prerequisites | Failure ownership, partial publication, rollback, and protected-main acceptance are documented. | +| Traceability / doctoring | `present_current` after this reconciliation | Protected standards-to-decision-to-test mapping | Current primary technical and standards bases are discoverable with bounded claim language. | +| Autonomous maintenance governance | `present_current` after this reconciliation | `out_of_scope` as Inkspan runtime behavior | Repository guidance now treats user-reported premature stopping as a scheduler-control incident, gives prompt/document-only work zero completion credit, requires continued repository execution, and keeps cadence authority external. | + +## Material findings and GitHub remediation + +### 1. Premature stopping was a control-plane defect, not repository completion + +The repeated user correction that work remained is evidence that prior invocation exit selection was defective. A prompt edit or documentation assessment was being treated too much like a terminal artifact even though another safe repository lane existed. + +The exact provider-side cause of each generic scheduled-task error is not observable from repository state, so this assessment does **not** invent a prompt-size, provider, permission, or runtime root cause. The repository-owned correction is narrower and testable: + +- `AGENTS.md` and `CLAUDE.md` classify user-reported early termination as a `scheduler-control incident`; +- prompt edits, inventories, documentation-only changes, PR creation, review requests, queued checks, and local artifacts receive zero completion credit; +- when safe work exists after a redirection, the invocation completes at least two materially distinct executable repository actions, or executes the sole safe action and proves the remainder non-actionable through a fresh queue rebuild; +- either exit sweep finding work resets the two-sweep count; and +- repeated generic scheduler errors require a thinner external prompt whose durable product detail is delegated to this canonical GitHub graph. + +The external scheduler still owns cadence and invocation execution. These repository instructions do not claim that scheduling is an Inkspan runtime feature. + +### 2. The source-level stable-version mismatch is resolved; registry acceptance is not + +The protected manifests agree at `0.6.0` through PR #135. The former npm `0.5.29` versus Office `0.1.0` source mismatch is therefore no longer an open design or source-preparation defect. + +Registry operational acceptance remains open under issue #118. Source integration does not prove that `v0.6.0` exists, that GitHub Release publication succeeded, that npm and PyPI Trusted Publishers are configured, that both registries published the exact release artifacts, or that public artifact digests match release evidence. Those checks remain operational release evidence, not documentation or source-readiness evidence. + +### 3. DOCX external hyperlinks are protected behavior and the decision record was stale + +Protected `main` implements bounded external HTTP(S) hyperlinks for DOCX rich-text runs through PR #137. The merged contract preserves visible Unicode text and existing bold/italic/underline formatting under a relationship-backed `w:hyperlink`, accepts only a bounded printable-ASCII absolute HTTP(S) target subset, performs no network access, and leaves destination authorization, phishing policy, internationalized URI preparation, tenant policy, and distribution to hosts. + +The implementation reached protected `main` while ADR 0026 and its index remained Proposed and described #137 as active. This reconciliation changes only documentation maturity and release notes; it does not broaden URI vocabulary or runtime authority. ADR 0026 becomes Accepted, the protected evidence is added to fitness and traceability, and the 0.6.0 source-candidate changelog records the feature. + +## Whole-conversation coverage decision + +The canonical graph covers the durable Inkspan decisions established through this project: + +- Markdown/HTML WYSIWYG authoring and deterministic conversion; +- strict link, image, clipboard, document-envelope, revision, selection, and transition evidence boundaries; +- offline/local assets and font licensing; +- framework-neutral Markdown, autosave, revision, selector, and converter package surfaces; +- deterministic email and Office rendering; +- bounded DOCX figures, rich runs, paragraph alignment, heading alignment, and external hyperlinks; +- provider-neutral Yjs collaboration with host-owned provider, room, persistence, authorization, and awareness policy; +- SSR/native-form behavior and accessible editor/toolbar/placeholder/print semantics; +- naruon/CWL modular composition without a required runtime dependency; +- model assistance as an untrusted proposal; +- exact-head/live-base/check/review/release evidence separation; +- OIDC npm/PyPI release-source authority and partial-publication recovery; and +- work-conserving external autonomous maintenance without representing the scheduler as product runtime. + +No material protected product-architecture decision identified by this reassessment remains only in chat. Registry publication and post-publication verification under issue #118 remain intentionally separate from protected-main source truth. + +## Sufficiency decision + +The ADR, PRD, TRD, Architecture, Contracts, UML, conceptual ERD/data model, Security, Threat Model, Test Strategy, Operability, release/rollback guidance, Traceability, contributor guidance, and APA-7 doctoring are **sufficient for acquisition reconstruction under the current Inkspan ownership boundary**. + +This is not a claim that Inkspan is commercially complete, that 0.6.0 has been publicly released, that external scheduler failures are resolved, or that current protected source can reuse historical release evidence. Exact protected-main validation, registry operational acceptance, artifact provenance, buyer workflows, and future documentation reconciliation remain independent executable gates. + +## Reassessment trigger + +Repeat this assessment when any of the following changes materially: + +- Inkspan assumes application-database, tenant, transport, credential, durable-audit, or collaboration-provider authority; +- a public document/evidence/package schema changes; +- an Office fidelity contract integrates or is superseded; +- the supported browser/runtime/release line changes; +- 0.6.0 is publicly published or partially published; +- the external autonomous-maintenance control contract changes; or +- a protected implementation contradicts a current canonical document. From 829ce6b3d4a8cb3cba064fb319e07e576823fb7f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 19:59:33 +0900 Subject: [PATCH 06/17] docs(adr): accept protected DOCX hyperlink decision --- .../0026-bounded-docx-external-hyperlinks.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/adr/0026-bounded-docx-external-hyperlinks.md b/docs/adr/0026-bounded-docx-external-hyperlinks.md index 25f6c5fc..b24acfe6 100644 --- a/docs/adr/0026-bounded-docx-external-hyperlinks.md +++ b/docs/adr/0026-bounded-docx-external-hyperlinks.md @@ -1,14 +1,14 @@ # ADR 0026: Bounded external hyperlinks in deterministic DOCX rich text -Status: Proposed +Status: Accepted ## Context -Inkspan Office already preserves bounded DOCX rich-text runs, paragraph/heading alignment, and informative inline PNG figures. Protected `main` does **not** yet expose a hyperlink target in `rich_paragraph.runs[]`; active PR #137 implements that additive fidelity surface. Without a public contract, hosts either flatten linked text to plain text or invent private OOXML outside Inkspan's deterministic renderer. +Inkspan Office already preserves bounded DOCX rich-text runs, paragraph/heading alignment, and informative inline PNG figures. Protected `main` now exposes an optional hyperlink target in `rich_paragraph.runs[]`, implemented on protected `main` through PR #137. Without the public contract, hosts would have to flatten linked text to plain text or invent private OOXML outside Inkspan's deterministic renderer. WordprocessingML represents a hyperlink with a `w:hyperlink` element whose `r:id` identifies a relationship carrying the target. ECMA-376 defines the Office Open XML vocabulary and package model, and Microsoft documents the `w:hyperlink r:id` relationship structure. `python-docx` 1.2.0 can read hyperlinks but still documents external hyperlink creation as not yet implemented, so Inkspan cannot rely on a stable public `Paragraph.add_hyperlink()` writer API. -The design must preserve Inkspan's network-free Office boundary while avoiding a second broad URL policy that silently expands the interactive editor's authority. +The design preserves Inkspan's network-free Office boundary while avoiding a second broad URL policy that silently expands the interactive editor's authority. ## Alternatives considered @@ -20,7 +20,7 @@ The design must preserve Inkspan's network-free Office boundary while avoiding a ## Decision -An active `rich_paragraph.runs[]` item may optionally declare `href` under the following bounded contract: +A `rich_paragraph.runs[]` item may optionally declare `href` under the following bounded contract: - type: JSON string; - length: 1 through 4,096 characters; @@ -35,7 +35,7 @@ The renderer creates the normal formatted Word run first, then moves that exact Visible run text remains fully Unicode-capable. The ASCII restriction applies only to the external target string. A host that needs an internationalized destination must supply an already authorized ASCII URI representation before calling Inkspan Office. -This ADR remains **Proposed** while #137 is an active PR. It becomes eligible for `Accepted` only after the unchanged implementation is integrated on protected `main` with the repository's applicable exact-head verification evidence. +This decision is Accepted because the unchanged implementation integrated on protected `main` through PR #137 with the repository's applicable exact-head CI, Security Scan, SAST, Office Python 3.11–3.14, branch-coverage, docstring, package, schema, and deterministic OOXML evidence. ## Consequences and ownership trade-offs @@ -57,13 +57,13 @@ A syntactically accepted URL is not a safety or trust verdict. Hosts remain resp ## Compatibility and migration -The schema change is additive for producers that omit `href`. Older Inkspan Office versions reject the new field because rich-run objects are strict; producers requiring hyperlink preservation must negotiate/target a renderer version that advertises this contract or omit the field. +The schema change is additive for producers that omit `href`. Older Inkspan Office versions reject the new field because rich-run objects are strict; producers requiring hyperlink preservation must negotiate or target a renderer version that advertises this contract, or omit the field. No database, persisted schema, document-envelope, or host migration is introduced. If a future contract broadens URI support, it must specify normalization, cross-language parity, migration/compatibility, and security evidence explicitly rather than silently widening this decision. ## Verification and acceptance evidence -Active PR #137 is required to prove the boundary at the produced OOXML package, not merely through visible text: +Protected PR #137 proves the boundary at the produced OOXML package rather than merely through visible text: - `w:hyperlink@r:id` resolves through `word/_rels/document.xml.rels`; - relationship type is the external hyperlink relationship and `TargetMode` is `External`; @@ -71,10 +71,10 @@ Active PR #137 is required to prove the boundary at the produced OOXML package, - existing bold/italic/underline formatting and visible text are preserved; - malformed, local, executable/data/mail/telephone, relative/protocol-relative, credential-bearing, whitespace/control/backslash, oversized, non-string, mapping/proxy-like, and non-ASCII targets fail closed without target reflection; - repeated rendering of the same accepted request is byte-identical; -- Python 3.11–3.14 Office lanes retain 100% shipped production statement/branch coverage, 100% shipped-symbol docstrings, wheel/schema/license checks, and existing deterministic/atomic-publication behavior; -- repository CI, Security Scan, SAST, live-base compatibility, and applicable review/merge policy pass on the unchanged final head. +- Python 3.11–3.14 Office lanes retain 100% shipped production statement/branch coverage, 100% shipped-symbol docstrings, wheel/schema/license checks, and existing deterministic/atomic-publication behavior; and +- repository CI, Security Scan, SAST, live-base compatibility, and applicable review/merge policy passed on the unchanged integrated head. -Historical failed heads are diagnostic evidence only and do not transfer acceptance to a changed head. +Historical failed heads remain diagnostic evidence only and do not transfer acceptance to a changed head or later release candidate. ## Rollback or supersession From 399aee7aa353cbfe15d6c39bfb73a05289b0b8c2 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:00:08 +0900 Subject: [PATCH 07/17] docs(adr): index accepted hyperlink decision --- docs/adr/README.md | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/docs/adr/README.md b/docs/adr/README.md index 24391e9e..5cfa2b2f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -31,7 +31,7 @@ This index records durable architectural decisions. Protected-main implementatio | [0023](0023-bounded-docx-rich-text-runs.md) | Accepted | Bounded rich-text runs in deterministic DOCX output | | [0024](0024-bounded-docx-paragraph-alignment.md) | Accepted | Bounded paragraph alignment in deterministic DOCX output | | [0025](0025-bounded-docx-heading-alignment.md) | Accepted | Bounded heading alignment in deterministic DOCX output | -| [0026](0026-bounded-docx-external-hyperlinks.md) | Proposed | Bounded external hyperlinks in deterministic DOCX rich text | +| [0026](0026-bounded-docx-external-hyperlinks.md) | Accepted | Bounded external hyperlinks in deterministic DOCX rich text | ## Decision discipline @@ -42,19 +42,3 @@ This index records durable architectural decisions. Protected-main implementatio ADR decision status and implementation maturity are related but distinct. An ADR file may be present on protected `main` while its decision remains Proposed; conversely, an implemented capability can expose stale documentation until the ADR is reconciled. Canonical fitness and traceability records state implementation maturity explicitly, and an ADR cannot promote an unmerged feature to shipped behavior. When a decision changes materially, add or supersede an ADR rather than silently rewriting history. - -## ADR quality requirements - -Every material ADR records explicit sections for: - -1. context and the problem boundary; -2. materially distinct alternatives considered; -3. the selected decision; -4. consequences and ownership trade-offs; -5. failure and recovery semantics; -6. security and privacy impact; -7. compatibility and migration behavior; -8. verification/acceptance evidence; and -9. rollback or explicit supersession conditions. - -Accessibility, operability, research/standards traceability, and release implications are included wherever the decision affects them. Canonical PRD, TRD, Architecture, contracts, UML, data/evidence model, threat model, test strategy, operability, and traceability documents must remain synchronized with Accepted decisions. From 34c7a2f3992215c325f679207d7e6fb0f9f4d4cb Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:01:43 +0900 Subject: [PATCH 08/17] docs(fitness): reconcile protected hyperlinks and release operations --- docs/DOCUMENTATION_FITNESS.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/DOCUMENTATION_FITNESS.md b/docs/DOCUMENTATION_FITNESS.md index dbd41567..cdb52e18 100644 --- a/docs/DOCUMENTATION_FITNESS.md +++ b/docs/DOCUMENTATION_FITNESS.md @@ -60,17 +60,18 @@ Document fitness and implementation maturity are independent. A `present_current | DOCX bounded rich-text runs | ADR 0023, Office schema/renderer/tests and doctoring | `present_current` | `implemented_on_protected_main` | Ordered bold/italic/underline runs preserve common inline fidelity under one bounded deterministic contract. | | DOCX bounded paragraph alignment | ADR 0024, Office schema/renderer/tests, Office guidance and doctoring | `present_current` | `implemented_on_protected_main` | `paragraph` and `rich_paragraph` preserve explicit left/center/right/justify alignment while omission retains inherited/default behavior. | | DOCX bounded heading alignment | ADR 0025, Office schema/renderer/tests, Office guidance and doctoring | `present_current` | `implemented_on_protected_main` | `heading` preserves the same exact left/center/right/justify contract through the shared paragraph-alignment authority while omission retains heading-style/default behavior. | +| DOCX bounded external hyperlinks | ADR 0026, Office schema/renderer/tests, Office guidance and doctoring | `present_current` | `implemented_on_protected_main` | Optional rich-run hyperlinks preserve exact accepted external HTTP(S) targets and existing run emphasis through deterministic relationship-backed OOXML without network, credential, local-file, tenant, persistence, or destination-trust authority. | | THREAT_MODEL | `docs/THREAT_MODEL.md` | `present_current` | Covers current trust boundaries and explicitly proposed extensions | Clipboard, evidence, Office, SSR/form, Yjs, model, host-authority and supply-chain threats are reconstructable. | -| TEST_STRATEGY | `docs/TEST_STRATEGY.md` | `present_current` | Protected deterministic/browser/Office evidence plus active feature-specific test contracts | Test authority, exact source-head evidence and claim limits are explicit rather than inferred from CI badges. | +| TEST_STRATEGY | `docs/TEST_STRATEGY.md` | `present_current` | Protected deterministic/browser/Office evidence plus feature-specific test contracts | Test authority, exact source-head evidence and claim limits are explicit rather than inferred from CI badges. | | OPERABILITY | `docs/OPERABILITY.md` | `present_current` | Current product responsibilities plus protected browser/release recovery boundaries | Conflict, collaboration, conversion, registry partial-publication recovery and rollback ownership are explicit. | | Release / rollback / provenance | TRD, OPERABILITY and release ADRs | `present_current` | `implemented_on_protected_main` gates plus explicitly labeled future hardening | Exact-source release authority, stale-evidence rejection and rollback are reconstructable. | | TRACEABILITY | `docs/TRACEABILITY.md` | `present_current` | Protected requirements/standards/evidence mapping | Acquisition reviewers can distinguish protected evidence from active or planned work. | | Contributor/agent authority | `AGENTS.md`, `CLAUDE.md`, `docs/README.md` | `present_current` | Protected-main-first decision discipline | Agents are directed back to the same canonical graph rather than parallel private memory. | -| Autonomous maintenance governance | `AGENTS.md`, `CLAUDE.md` plus the external scheduler | `present_current` | `out_of_scope` as Inkspan runtime behavior | Work-conserving execution, lane-local waiting and external scheduler authority are reconstructable without pretending automation is an Inkspan API. | +| Autonomous maintenance governance | `AGENTS.md`, `CLAUDE.md` plus the external scheduler | `present_current` | `out_of_scope` as Inkspan runtime behavior | Work-conserving execution, user-redirection incident recovery, lane-local waiting and external scheduler authority are reconstructable without pretending automation is an Inkspan API. | ## Conversation-to-GitHub reconciliation -The canonical graph retains durable product decisions from the project conversation only when they agree with live implementation or are explicitly labeled target/active architecture. The reviewed baseline covers Markdown/HTML WYSIWYG authoring; strict link/image/SafeClipboard boundaries; local/offline fonts; deterministic Markdown/HTML/email/plain-text conversion; independently reusable Office rendering; provider-neutral Yjs collaboration with host-owned provider/persistence authority; bounded autosave lifecycle observation; SSR/native-form serialization; accessibility metadata; revision-scoped evidence and W3C text-position selectors; naruon modular composition; model assistance as an untrusted proposal; host-owned transport/authentication/authorization/tenant isolation/persistence/credentials/migration/retention/deployment/durable audit/model policy; cross-engine browser assurance; OIDC trusted publishing; framework-neutral Markdown packaging; CSS paged-media presentation; and bounded DOCX figure/rich-text/paragraph/heading alignment fidelity. +The canonical graph retains durable product decisions from the project conversation only when they agree with live implementation or are explicitly labeled target/active architecture. The reviewed baseline covers Markdown/HTML WYSIWYG authoring; strict link/image/SafeClipboard boundaries; local/offline fonts; deterministic Markdown/HTML/email/plain-text conversion; independently reusable Office rendering; provider-neutral Yjs collaboration with host-owned provider/persistence authority; bounded autosave lifecycle observation; SSR/native-form serialization; accessibility metadata; revision-scoped evidence and W3C text-position selectors; naruon modular composition; model assistance as an untrusted proposal; host-owned transport/authentication/authorization/tenant isolation/persistence/credentials/migration/retention/deployment/durable audit/model policy; cross-engine browser assurance; OIDC trusted publishing; framework-neutral Markdown packaging; CSS paged-media presentation; and bounded DOCX figure/rich-text/paragraph/heading/hyperlink fidelity. Autonomous commercial-maintenance scheduling and no-early-stop execution are control-plane governance, not shipped Inkspan runtime capability. The external scheduler owns cadence and continuation. Where older conversation, issue, PR body, or plan conflicts with protected `main`, it is historical. Where a requirement is only on an active PR, this documentation uses `implemented_on_active_pr` and never presents it as shipped. @@ -78,7 +79,7 @@ Autonomous commercial-maintenance scheduling and no-early-stop execution are con The documentation pack is substantially complete for acquisition review, but repository closure is not documentation closure: -1. The unified OIDC release workflow is source-integrated, but issue #118 remains open because the next stable registry release still requires one coherent npm/Office/tag version plus live npm/PyPI publication and post-publication digest verification. +1. The protected manifests now agree at `0.6.0`, while registry operational acceptance remains open under issue #118 because the exact protected release still needs its tag/GitHub Release, live npm/PyPI Trusted Publisher execution, and public artifact digest verification. 2. Future protected-source changes must continue to reconcile PRD/TRD/Architecture/ADR/UML/DATA_MODEL/security/test/operability/traceability semantics rather than treating this baseline as permanently complete. 3. Documentation becoming mergeable, green, or protected-merged is never a reason for the commercial loop to stop; the next safe product, release, security, accessibility, package, Office-fidelity, or interoperability lane continues. From 5f1eaf7d1d435aab2839ba78e9f5bd5339497c45 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:03:36 +0900 Subject: [PATCH 09/17] docs(traceability): bind protected DOCX hyperlinks --- docs/TRACEABILITY.md | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/TRACEABILITY.md b/docs/TRACEABILITY.md index e99901e3..d120cec7 100644 --- a/docs/TRACEABILITY.md +++ b/docs/TRACEABILITY.md @@ -29,6 +29,7 @@ This record maps durable Inkspan product decisions to authoritative standards, p | DOCX bounded rich-text runs | `rich_paragraph` preserves ordered bold/italic/underline run emphasis through a strict bounded JSON contract | Office Open XML run semantics; python-docx run API | protected-main #124 renderer/schema/tests, ADR 0023 and rich-run doctoring | No arbitrary Word styles, font/color/size, hyperlink, field-code, tracked-change, raw-OOXML or source-format parsing authority is implied | | DOCX bounded paragraph alignment | `paragraph` and `rich_paragraph` optionally preserve exact `left`, `center`, `right`, or `justify`; omission preserves inherited/default Word alignment | Microsoft WordprocessingML paragraph documentation; python-docx paragraph API | protected-main #130 renderer/schema/tests, ADR 0024, Office guide and paragraph-alignment doctoring | Alignment is bounded to the protected paragraph contract; list/table/title/page-layout/style authority is not implied | | DOCX bounded heading alignment | `heading` optionally preserves the same exact `left`, `center`, `right`, or `justify` contract through the shared paragraph-alignment mapping; omission preserves inherited/default heading-style alignment | Microsoft WordprocessingML paragraph documentation; python-docx paragraph API | protected-main #134 renderer/schema/tests, ADR 0025, Office guide and heading-alignment doctoring | Heading alignment adds no arbitrary heading style, outline numbering, TOC, list/table/title/page-layout, source-format, network, model, credential or persistence authority | +| DOCX bounded external hyperlinks | `rich_paragraph.runs[]` optionally preserves one exact bounded printable-ASCII absolute HTTP(S) target as a relationship-backed external `w:hyperlink` while retaining visible Unicode text and run emphasis | ECMA-376 Office Open XML package/WordprocessingML semantics; Microsoft Open XML hyperlink/relationship documentation; python-docx 1.2.0 hyperlink feature analysis | protected-main #137 renderer/schema/OOXML tests, ADR 0026 and Office guidance | Accepted syntax is not destination trust; Inkspan performs no fetch, DNS, redirect, local-file read, credential use, tenant policy, phishing policy, internationalized-URI conversion, persistence, or distribution | | Release authority | Source movement invalidates exact-head evidence; stale assets/digest ambiguity fail closed; formal approval remains distinct from status/comments | GitHub protected-branch/review/release/attestation behavior and repository policy | release workflow tests, package checksums, browser evidence, SBOM/provenance, formal reviews | Local success or automated prose does not authorize protected merge/release | ## Current primary references @@ -37,41 +38,49 @@ Bray, T. (Ed.). (2015). *The I-JSON Message Format* (RFC 7493). RFC Editor. http Bray, T. (Ed.). (2017). *The JavaScript Object Notation (JSON) Data Interchange Format* (RFC 8259; STD 90). RFC Editor. https://doi.org/10.17487/RFC8259 +Ecma International. (2021). *ECMA-376: Office Open XML file formats* (5th ed.). https://ecma-international.org/publications-and-standards/standards/ecma-376/ + Ecma International. (2026). *ECMA-402: ECMAScript 2026 internationalization API specification* (13th ed.). https://402.ecma-international.org/ Fielding, R., Nottingham, M., & Reschke, J. (Eds.). (2022). *HTTP Semantics* (RFC 9110; STD 97). RFC Editor. https://doi.org/10.17487/RFC9110 MacFarlane, J. (2024, January 28). *CommonMark specification* (Version 0.31.2). CommonMark. https://spec.commonmark.org/0.31.2/ +Microsoft. (n.d.-a). *Browsers*. Playwright documentation. Retrieved August 10, 2026, from https://playwright.dev/docs/browsers + +Microsoft. (n.d.-b). *Hyperlink class (DocumentFormat.OpenXml.Wordprocessing)*. Microsoft Learn. Retrieved August 10, 2026, from https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.wordprocessing.hyperlink + +Microsoft. (n.d.-c). *HyperlinkRelationship class (DocumentFormat.OpenXml.Packaging)*. Microsoft Learn. Retrieved August 10, 2026, from https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.packaging.hyperlinkrelationship + +Microsoft. (n.d.-d). *Projects*. Playwright documentation. Retrieved August 10, 2026, from https://playwright.dev/docs/test-projects + +Microsoft. (n.d.-e). *Release notes: Version 1.62*. Playwright. Retrieved August 10, 2026, from https://playwright.dev/docs/release-notes + +Microsoft. (n.d.-f). *Working with paragraphs*. Microsoft Learn. Retrieved August 10, 2026, from https://learn.microsoft.com/en-us/office/open-xml/word/working-with-paragraphs + Node.js contributors. (2026). *Modules: Packages*. Node.js documentation. https://nodejs.org/api/packages.html ProseMirror. (n.d.). *ProseMirror reference manual*. Retrieved August 10, 2026, from https://prosemirror.net/docs/ref/ +python-docx. (n.d.-a). *Hyperlink — python-docx 1.2.0 documentation*. Retrieved August 10, 2026, from https://python-docx.readthedocs.io/en/latest/dev/analysis/features/text/hyperlink.html + +python-docx. (n.d.-b). *Working with text*. Retrieved August 10, 2026, from https://python-docx.readthedocs.io/en/latest/user/text.html + Rundgren, A., Jordan, B., & Erdtman, S. (2020). *JSON Canonicalization Scheme (JCS)* (RFC 8785). RFC Editor. https://doi.org/10.17487/RFC8785 Souppaya, M., Scarfone, K., & Dodson, D. (2022). *Secure Software Development Framework (SSDF) Version 1.1: Recommendations for Mitigating the Risk of Software Vulnerabilities* (NIST SP 800-218). National Institute of Standards and Technology. https://doi.org/10.6028/NIST.SP.800-218 Web Hypertext Application Technology Working Group. (2026). *HTML Standard: Parsing HTML documents* (Living Standard). Retrieved August 10, 2026, from https://html.spec.whatwg.org/multipage/parsing.html -World Wide Web Consortium. (2017, February 23). *Web Annotation Data Model*. https://www.w3.org/TR/annotation-model/ - -World Wide Web Consortium. (2026, June 24). *Clipboard API and events* (W3C Working Draft). https://www.w3.org/TR/2026/WD-clipboard-apis-20260624/ - -World Wide Web Consortium. (2024, December 12). *Web Content Accessibility Guidelines (WCAG) 2.2*. https://www.w3.org/TR/WCAG22/ - -World Wide Web Consortium. (2023, June 6). *Accessible Rich Internet Applications (WAI-ARIA) 1.2*. https://www.w3.org/TR/wai-aria-1.2/ - World Wide Web Consortium. (2013). *PROV-DM: The PROV Data Model*. https://www.w3.org/TR/prov-dm/ -Microsoft. (2026). *Release notes: Version 1.62*. Playwright. Retrieved August 10, 2026, from https://playwright.dev/docs/release-notes - -Microsoft. (n.d.-a). *Browsers*. Playwright documentation. Retrieved August 10, 2026, from https://playwright.dev/docs/browsers +World Wide Web Consortium. (2017, February 23). *Web Annotation Data Model*. https://www.w3.org/TR/annotation-model/ -Microsoft. (n.d.-b). *Projects*. Playwright documentation. Retrieved August 10, 2026, from https://playwright.dev/docs/test-projects +World Wide Web Consortium. (2023, June 6). *Accessible Rich Internet Applications (WAI-ARIA) 1.2*. https://www.w3.org/TR/wai-aria-1.2/ -Microsoft. (n.d.-c). *Working with paragraphs*. Microsoft Learn. Retrieved August 10, 2026, from https://learn.microsoft.com/en-us/office/open-xml/word/working-with-paragraphs +World Wide Web Consortium. (2024, December 12). *Web Content Accessibility Guidelines (WCAG) 2.2*. https://www.w3.org/TR/WCAG22/ -python-docx. (n.d.). *Working with text*. Retrieved August 10, 2026, from https://python-docx.readthedocs.io/en/latest/user/text.html +World Wide Web Consortium. (2026, June 24). *Clipboard API and events* (W3C Working Draft). https://www.w3.org/TR/2026/WD-clipboard-apis-20260624/ ## Research-backed concurrency rationale @@ -97,7 +106,7 @@ Lower levels may explain intent or history but cannot override a contradictory h - **Planned** means an accepted future direction without a protected implementation. - **Superseded** means retained for history but replaced by a later explicit decision. -Envelope identity routing, SafeClipboard, W3C text-position selector evidence, cross-engine browser assurance, headless deterministic Markdown serialization, CSS paged-media output, accessible placeholder semantics, DOCX informative PNG figures, bounded rich-text runs, bounded paragraph alignment, and bounded heading alignment are implemented on protected `main`. The W3C selector remains revision-scoped and projection-version-scoped and must satisfy `0 <= start <= end <= projectedCodePointLength`; protected integration does not transfer annotation persistence, source identity, authorization, or re-anchoring authority from the host. The browser gate being protected does not let a future release reuse historical browser evidence: the exact release candidate must generate fresh evidence bound to its own source, committed synthetic corpus, package-lock SHA-256, run identity, browser revisions, and packed npm artifact SHA-256. +Envelope identity routing, SafeClipboard, W3C text-position selector evidence, cross-engine browser assurance, headless deterministic Markdown serialization, CSS paged-media output, accessible placeholder semantics, DOCX informative PNG figures, bounded rich-text runs, bounded paragraph alignment, bounded heading alignment, and bounded external hyperlinks are implemented on protected `main`. The W3C selector remains revision-scoped and projection-version-scoped and must satisfy `0 <= start <= end <= projectedCodePointLength`; protected integration does not transfer annotation persistence, source identity, authorization, or re-anchoring authority from the host. The browser gate being protected does not let a future release reuse historical browser evidence: the exact release candidate must generate fresh evidence bound to its own source, committed synthetic corpus, package-lock SHA-256, run identity, browser revisions, and packed npm artifact SHA-256. Documentation must not promote Proposed or Planned capabilities to Implemented merely because a PR, issue, or design document is detailed. From 7260e468b7ac2aeb26d6fed3ce8141a338b77874 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:08:36 +0900 Subject: [PATCH 10/17] docs(assessment): separate hyperlink maturity from release notes --- .../2026-08-10-conversation-documentation-reassessment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/assessments/2026-08-10-conversation-documentation-reassessment.md b/docs/assessments/2026-08-10-conversation-documentation-reassessment.md index 1baacec4..71b02d4b 100644 --- a/docs/assessments/2026-08-10-conversation-documentation-reassessment.md +++ b/docs/assessments/2026-08-10-conversation-documentation-reassessment.md @@ -58,7 +58,7 @@ Registry operational acceptance remains open under issue #118. Source integratio Protected `main` implements bounded external HTTP(S) hyperlinks for DOCX rich-text runs through PR #137. The merged contract preserves visible Unicode text and existing bold/italic/underline formatting under a relationship-backed `w:hyperlink`, accepts only a bounded printable-ASCII absolute HTTP(S) target subset, performs no network access, and leaves destination authorization, phishing policy, internationalized URI preparation, tenant policy, and distribution to hosts. -The implementation reached protected `main` while ADR 0026 and its index remained Proposed and described #137 as active. This reconciliation changes only documentation maturity and release notes; it does not broaden URI vocabulary or runtime authority. ADR 0026 becomes Accepted, the protected evidence is added to fitness and traceability, and the 0.6.0 source-candidate changelog records the feature. +The implementation reached protected `main` while ADR 0026 and its index remained Proposed and described #137 as active. This reconciliation changes documentation maturity and traceability only; it does not broaden URI vocabulary or runtime authority. ADR 0026 becomes Accepted and the protected evidence is added to fitness and traceability. Release-note reconciliation for the post-#135 protected-source change remains an issue #118 prerequisite before any tag or registry publication. ## Whole-conversation coverage decision From eeafee21ce9013a465205327628a01bf75f2f1ef Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:09:06 +0900 Subject: [PATCH 11/17] test(docs): bind release-note handoff to issue 118 --- src/autonomousMaintenanceDocumentation.test.ts | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/autonomousMaintenanceDocumentation.test.ts b/src/autonomousMaintenanceDocumentation.test.ts index bfa7e416..14abd8aa 100644 --- a/src/autonomousMaintenanceDocumentation.test.ts +++ b/src/autonomousMaintenanceDocumentation.test.ts @@ -50,6 +50,9 @@ describe('autonomous maintenance and acquisition documentation', () => { expect(assessment).toContain( 'Source integration does not prove that `v0.6.0` exists', ); + expect(assessment).toContain( + 'Release-note reconciliation for the post-#135 protected-source change remains an issue #118 prerequisite', + ); }); it('reconciles the protected DOCX hyperlink decision', () => { @@ -59,7 +62,6 @@ describe('autonomous maintenance and acquisition documentation', () => { const adrIndex = repositoryFile('docs/adr/README.md'); const fitness = repositoryFile('docs/DOCUMENTATION_FITNESS.md'); const traceability = repositoryFile('docs/TRACEABILITY.md'); - const changelog = repositoryFile('CHANGELOG.md'); expect(adr).toContain('Status: Accepted'); expect(adr).toContain('implemented on protected `main` through PR #137'); @@ -74,8 +76,5 @@ describe('autonomous maintenance and acquisition documentation', () => { expect(traceability).toMatch( /DOCX bounded external hyperlinks[^\n]*protected-main #137/u, ); - expect(changelog).toMatch( - /Expanded deterministic DOCX fidelity[^\n]*bounded external HTTP\(S\) hyperlinks/u, - ); }); }); From 65b03d6a5bbe67178146764cda649b11afe710c8 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:14:35 +0900 Subject: [PATCH 12/17] docs(assessment): reconcile the current protected release candidate --- .../2026-08-10-conversation-documentation-reassessment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/assessments/2026-08-10-conversation-documentation-reassessment.md b/docs/assessments/2026-08-10-conversation-documentation-reassessment.md index 71b02d4b..0abd2657 100644 --- a/docs/assessments/2026-08-10-conversation-documentation-reassessment.md +++ b/docs/assessments/2026-08-10-conversation-documentation-reassessment.md @@ -8,7 +8,7 @@ This assessment answers whether an independent product, engineering, security, o ## Evidence generation reviewed -- Protected implementation generation reviewed: `main@f2a87bc32710574b54c0ccd1a4f33fee2c6f2224`, including the unified Inkspan 0.6.0 source candidate from #135 and bounded DOCX external hyperlinks from #137. +- Protected implementation generation reviewed: `main@02251db320b2b5ed7c284635c4f3103ec2f67eb6`, including the unified Inkspan 0.6.0 source candidate from #135, bounded DOCX external hyperlinks from #137, and the corresponding protected 0.6.0 release-note reconciliation from #138. - Release operational-acceptance line reviewed separately: issue #118. - Repository guidance reviewed: `AGENTS.md`, `CLAUDE.md`, `docs/README.md`, `docs/DOCUMENTATION_FITNESS.md`, `docs/PRD.md`, `docs/TRD.md`, `ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/UML.md`, `docs/DATA_MODEL.md`, `SECURITY.md`, `docs/THREAT_MODEL.md`, `docs/TEST_STRATEGY.md`, `docs/OPERABILITY.md`, `docs/TRACEABILITY.md`, and the ADR index. @@ -52,13 +52,13 @@ The external scheduler still owns cadence and invocation execution. These reposi The protected manifests agree at `0.6.0` through PR #135. The former npm `0.5.29` versus Office `0.1.0` source mismatch is therefore no longer an open design or source-preparation defect. -Registry operational acceptance remains open under issue #118. Source integration does not prove that `v0.6.0` exists, that GitHub Release publication succeeded, that npm and PyPI Trusted Publishers are configured, that both registries published the exact release artifacts, or that public artifact digests match release evidence. Those checks remain operational release evidence, not documentation or source-readiness evidence. +Release-note reconciliation is protected through PR #138: the dated 0.6.0 candidate now includes the bounded DOCX hyperlink capability integrated by #137. Registry operational acceptance remains open under issue #118. Source integration and complete release metadata do not prove that `v0.6.0` exists, that GitHub Release publication succeeded, that npm and PyPI Trusted Publishers are configured, that both registries published the exact release artifacts, or that public artifact digests match release evidence. Those checks remain operational release evidence, not documentation or source-readiness evidence. ### 3. DOCX external hyperlinks are protected behavior and the decision record was stale Protected `main` implements bounded external HTTP(S) hyperlinks for DOCX rich-text runs through PR #137. The merged contract preserves visible Unicode text and existing bold/italic/underline formatting under a relationship-backed `w:hyperlink`, accepts only a bounded printable-ASCII absolute HTTP(S) target subset, performs no network access, and leaves destination authorization, phishing policy, internationalized URI preparation, tenant policy, and distribution to hosts. -The implementation reached protected `main` while ADR 0026 and its index remained Proposed and described #137 as active. This reconciliation changes documentation maturity and traceability only; it does not broaden URI vocabulary or runtime authority. ADR 0026 becomes Accepted and the protected evidence is added to fitness and traceability. Release-note reconciliation for the post-#135 protected-source change remains an issue #118 prerequisite before any tag or registry publication. +The implementation and release note reached protected `main` while ADR 0026 and its index remained Proposed and described #137 as active. This reconciliation changes documentation maturity and traceability only; it does not broaden URI vocabulary or runtime authority. ADR 0026 becomes Accepted and the protected evidence is added to fitness and traceability. Issue #118 remains the tag, GitHub Release, Trusted Publisher, registry-publication, and public-digest operational-acceptance line. ## Whole-conversation coverage decision From 35d2d782acb6fbc4c4d0c445af45d20778450793 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:15:11 +0900 Subject: [PATCH 13/17] fix(test): match current assessment status and release metadata --- src/autonomousMaintenanceDocumentation.test.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/autonomousMaintenanceDocumentation.test.ts b/src/autonomousMaintenanceDocumentation.test.ts index 14abd8aa..904d6088 100644 --- a/src/autonomousMaintenanceDocumentation.test.ts +++ b/src/autonomousMaintenanceDocumentation.test.ts @@ -31,12 +31,12 @@ describe('autonomous maintenance and acquisition documentation', () => { 'assessments/2026-08-10-conversation-documentation-reassessment.md', ); expect(assessment).toContain( - 'main@f2a87bc32710574b54c0ccd1a4f33fee2c6f2224', + 'main@02251db320b2b5ed7c284635c4f3103ec2f67eb6', ); expect(assessment).toContain('## Fitness matrix'); expect(assessment).toContain('## Whole-conversation coverage decision'); expect(assessment).toContain('## Sufficiency decision'); - expect(assessment).toContain('physical relational ERD'); + expect(assessment.toLowerCase()).toContain('physical relational erd'); expect(assessment).toContain('`not_applicable`'); }); @@ -45,13 +45,13 @@ describe('autonomous maintenance and acquisition documentation', () => { expect(assessment).toContain('protected manifests agree at `0.6.0`'); expect(assessment).toContain( - 'Registry operational acceptance remains open under issue #118', + 'Release-note reconciliation is protected through PR #138', ); expect(assessment).toContain( - 'Source integration does not prove that `v0.6.0` exists', + 'Registry operational acceptance remains open under issue #118', ); expect(assessment).toContain( - 'Release-note reconciliation for the post-#135 protected-source change remains an issue #118 prerequisite', + 'Source integration and complete release metadata do not prove that `v0.6.0` exists', ); }); From 0643816954327a7d98ef6ead79b070d74f45f668 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:18:40 +0900 Subject: [PATCH 14/17] test(docs): preserve ADR quality requirements --- src/adrQualityContract.test.ts | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 src/adrQualityContract.test.ts diff --git a/src/adrQualityContract.test.ts b/src/adrQualityContract.test.ts new file mode 100644 index 00000000..7f5af056 --- /dev/null +++ b/src/adrQualityContract.test.ts @@ -0,0 +1,22 @@ +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; + +import { describe, expect, it } from 'vitest'; + +const repositoryFile = (path: string): string => + readFileSync(resolve(process.cwd(), path), 'utf8'); + +describe('ADR quality documentation contract', () => { + it('preserves the canonical ADR quality requirements on every reconciliation branch', () => { + const adrIndex = repositoryFile('docs/adr/README.md'); + + expect(adrIndex).toContain('## ADR quality requirements'); + expect(adrIndex).toContain('context and the problem boundary'); + expect(adrIndex).toContain('materially distinct alternatives considered'); + expect(adrIndex).toContain('failure and recovery semantics'); + expect(adrIndex).toContain('security and privacy impact'); + expect(adrIndex).toContain('compatibility and migration behavior'); + expect(adrIndex).toContain('verification/acceptance evidence'); + expect(adrIndex).toContain('rollback or explicit supersession conditions'); + }); +}); From 8ef83340ce41ba1bdeba52c9521c84a361827e9f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 20:19:16 +0900 Subject: [PATCH 15/17] fix(docs): preserve ADR quality requirements --- docs/adr/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/adr/README.md b/docs/adr/README.md index 5cfa2b2f..df8b7b80 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -42,3 +42,19 @@ This index records durable architectural decisions. Protected-main implementatio ADR decision status and implementation maturity are related but distinct. An ADR file may be present on protected `main` while its decision remains Proposed; conversely, an implemented capability can expose stale documentation until the ADR is reconciled. Canonical fitness and traceability records state implementation maturity explicitly, and an ADR cannot promote an unmerged feature to shipped behavior. When a decision changes materially, add or supersede an ADR rather than silently rewriting history. + +## ADR quality requirements + +Every material ADR records explicit sections for: + +1. context and the problem boundary; +2. materially distinct alternatives considered; +3. the selected decision; +4. consequences and ownership trade-offs; +5. failure and recovery semantics; +6. security and privacy impact; +7. compatibility and migration behavior; +8. verification/acceptance evidence; and +9. rollback or explicit supersession conditions. + +Accessibility, operability, research/standards traceability, and release implications are included wherever the decision affects them. Canonical PRD, TRD, Architecture, contracts, UML, data/evidence model, threat model, test strategy, operability, and traceability documents must remain synchronized with Accepted decisions. From da8d4d48bda809b0f223e2f07d08576cfb96772d Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 21:02:41 +0900 Subject: [PATCH 16/17] test(docs): bind premature-stop recovery semantics --- src/autonomousMaintenanceDocumentation.test.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/autonomousMaintenanceDocumentation.test.ts b/src/autonomousMaintenanceDocumentation.test.ts index 904d6088..6f7a1789 100644 --- a/src/autonomousMaintenanceDocumentation.test.ts +++ b/src/autonomousMaintenanceDocumentation.test.ts @@ -17,7 +17,11 @@ describe('autonomous maintenance and acquisition documentation', () => { for (const guidance of [agents, claude]) { expect(guidance).toContain('scheduler-control incident'); expect(guidance).toContain('zero completion credit'); + expect(guidance).toContain('rebuild the live Inkspan queue'); + expect(guidance).toContain('continue repository execution in the same invocation'); expect(guidance).toContain('two materially distinct executable repository actions'); + expect(guidance).toContain('fresh queue rebuild'); + expect(guidance).toContain('every other lane is currently non-actionable'); expect(guidance).toContain('reset the two-sweep count'); expect(guidance).toContain('simplify the external prompt'); } From 967721e86d5a7e3e3be8fe967054fbfcf888f076 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 10 Aug 2026 21:03:15 +0900 Subject: [PATCH 17/17] test(adr): enforce quality sections across detailed records --- src/adrQualityContract.test.ts | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/src/adrQualityContract.test.ts b/src/adrQualityContract.test.ts index 7f5af056..04dcef71 100644 --- a/src/adrQualityContract.test.ts +++ b/src/adrQualityContract.test.ts @@ -1,4 +1,4 @@ -import { readFileSync } from 'node:fs'; +import { readFileSync, readdirSync } from 'node:fs'; import { resolve } from 'node:path'; import { describe, expect, it } from 'vitest'; @@ -6,6 +6,23 @@ import { describe, expect, it } from 'vitest'; const repositoryFile = (path: string): string => readFileSync(resolve(process.cwd(), path), 'utf8'); +const detailedAdrFiles = (): string[] => + readdirSync(resolve(process.cwd(), 'docs/adr')) + .filter((name) => /^\d{4}-.+\.md$/u.test(name)) + .sort(); + +const requiredAdrHeadings = [ + /^## Context(?:\b|\s|$)/mu, + /^## Alternatives considered(?:\b|\s|$)/mu, + /^## Decision(?:\b|\s|$)/mu, + /^## Consequences(?:\b|\s|$)/mu, + /^## Failure and recovery(?:\b|\s|$)/mu, + /^## Security and privacy impact(?:\b|\s|$)/mu, + /^## Compatibility and migration(?:\b|\s|$)/mu, + /^## Verification(?:\b|\s|$)/mu, + /^## Rollback or supersession(?:\b|\s|$)/mu, +] as const; + describe('ADR quality documentation contract', () => { it('preserves the canonical ADR quality requirements on every reconciliation branch', () => { const adrIndex = repositoryFile('docs/adr/README.md'); @@ -19,4 +36,18 @@ describe('ADR quality documentation contract', () => { expect(adrIndex).toContain('verification/acceptance evidence'); expect(adrIndex).toContain('rollback or explicit supersession conditions'); }); + + it('applies the canonical quality sections to every detailed ADR', () => { + const adrFiles = detailedAdrFiles(); + + expect(adrFiles.length).toBeGreaterThan(0); + + for (const adrFile of adrFiles) { + const adr = repositoryFile(`docs/adr/${adrFile}`); + + for (const heading of requiredAdrHeadings) { + expect(adr, `${adrFile} is missing ${heading.source}`).toMatch(heading); + } + } + }); });