morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #2179] fix(docs): readiness stage table names an unsupported identifier #725

New issue

Closed

opened 2026-10-15 18:27:43 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:27:43 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2179

Summary

The reconstruction readiness guide lists declare-request as its third required stage. The documented maintainer evaluator instead accepts acquire-authority. Copying the guide's identifier into an otherwise valid conformance input causes a validation error before a report is produced. The same row describes declaring a target, operation, and lifecycle, while the implemented stage requires four grant-related checks. This is a documentation mismatch in the internal conformance guide.

Affected area

Area: Documentation. Interface: Other, the maintainer conformance verifier. Earliest failure stage: Request parsing or validation. Target context: the source-owned synthetic readiness input. The public CLI and MCP have no readiness-report operation.

Runtime or environment

Source checkout at c22111eca2, using its existing cached runtime build, and the installed published rea-agents 6.4.0 package were checked separately. Both probes used Node.js 24.21.0 on darwin arm64, within the package's supported runtime range. The contributor pin is Node.js 24.18.0 and was not exercised. The guide at release tag rea-agents-6.4.0, commit a56f7bb668, was byte-identical to the checkout guide; the npm package omits the guide but contains the evaluator, schema, and synthetic example.

Steps to reproduce

Read the third row of the Required stages table in docs/reconstruction-readiness.md. It names declare-request and describes carrying the exact target, operation, and lifecycle in the request before launch. From a checkout with its runtime already built, run the following script. For the runtime comparison, run the same script from the installed package root.

node --input-type=module <<'JS'
import assert from "node:assert/strict";
import { RECONSTRUCTION_READINESS_EXAMPLE as example } from "./dist/contracts/reconstructionReadinessExample.js";
import { reconstructionReadinessInputSchema as schema } from "./dist/domain/reconstructionReadinessSchemas.js";
import { createReconstructionReadinessReport as evaluate } from "./dist/domain/reconstructionReadiness.js";
import { READINESS_REQUIRED_CHECKS as checks } from "./dist/domain/reconstructionReadinessJourneyFindings.js";

assert.equal(schema.safeParse(example).success, true);
assert.equal(evaluate(example).status, "pass");
console.log("example: accepted, report pass");

const input = structuredClone(example);
const stage = input.stages.find(row => row.stage_id === "acquire-authority");
assert.ok(stage);
stage.stage_id = "declare-request";
const parsed = schema.safeParse(input);
assert.equal(parsed.success, false);
console.log("documented ID:", parsed.error.issues[0].code,
  parsed.error.issues[0].path.join("."));
assert.throws(() => evaluate(input), /Invalid option/);

stage.stage_id = "acquire-authority";
assert.equal(evaluate(input).status, "pass");
console.log("actual ID: accepted, report pass");
console.log("required checks:", checks["acquire-authority"].join(", "));

for (const checkId of checks["acquire-authority"]) {
  const control = structuredClone(example);
  const authority = control.stages.find(row => row.stage_id === "acquire-authority");
  authority.checks = authority.checks.filter(check => check.check_id !== checkId);
  assert.equal(schema.safeParse(control).success, true);
  const report = evaluate(control);
  assert.equal(report.status, "fail");
  assert.ok(report.findings.some(finding => finding.code === "missing-stage-check"
    && finding.stage_id === "acquire-authority"
    && finding.detail.includes(checkId)));
}
console.log("each required-check omission: report fail");
JS

Expected behavior

The guide's required-stage table should describe the stages and checks accepted by the conformance contract it documents. Its third row should allow a maintainer to recognize the actual stage and understand its required proof. The guide explicitly presents this as an internal project verifier using a public typed synthetic input.

Actual behavior

The script produced the following output in both builds, with exit status zero because it asserts the observed mismatch:

example: accepted, report pass
documented ID: invalid_value stages.2.stage_id
actual ID: accepted, report pass
required checks: missing-scope-reported, narrow-grant-resumed, expansion-reprompted, denial-launched-nothing
each required-check omission: report fail

The invalid identifier also throws from the evaluator before report creation. Reading all nine documented identifiers against the enum found exactly one rejected identifier, declare-request. The unchanged example produces nine passing required stages and zero findings. The built evaluator behaves consistently with its schema; the contrary observation is the guide's stage row.

Evidence

Expected source: docs/reconstruction-readiness.md:27 defines the internal project conformance contract, :33 introduces the Required stages table, and :47 requires every stage and check exactly once. src/domain/reconstructionReadinessSchemas.ts:23 defines the nine accepted stage IDs and :225 requires nine unique stages. src/domain/reconstructionReadinessJourneyFindings.ts:26 defines the four authority checks.
Failure source: docs/reconstruction-readiness.md:39 names declare-request and describes request declaration. The executed script above observes its rejection at stages.2.stage_id in both runtime builds, while the actual stage passes and each required-check omission fails.
Evidence provenance: observed
Local verification: reproduced
Reproduction completeness: complete

The direct calls use the same built example and evaluator imported by scripts/verify-reconstruction-readiness.mjs:11 and :14; that verifier clones the example at :68 before evaluating it at :98. The fixture's grants, outcomes, provider identities, and checks are synthetic assertions. No real Hopper, Ghidra, IDA, or application runtime was exercised. The full maintainer verifier and CI artifacts were not run. There is no demonstrated production path that consumes the Markdown table as input, so this report makes no claim that ordinary CLI/MCP readiness or provider behavior fails. The live hosted documentation deployment was not inspected.

Restoration check

Check that every identifier in the Required stages table agrees with the maintained conformance schema and example, and that the third row's proof describes the checks required for that stage. An otherwise valid input using the documented identifiers should validate. Retain the controls that the valid example passes and that omitting each required authority check produces a failing report. Restore documentation and contract agreement without weakening readiness validation; the implementation and wording are left open.

Triage assessment

Impact level: P3
Assessment status: supported
Impact basis: The guide contains an incorrect stage identifier and proof description. The evaluator rejects the copied identifier with an error listing the accepted values, and no incorrect readiness verdict or real-provider failure was observed. The verified consequence is misleading maintainer documentation.
Workaround status: available
Workaround basis: Use the stage identifier and required checks from the checked-in synthetic example or schema. This was executed in both builds and produced a passing report without any code or configuration change.

Originally created by @coygeek on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2179 ## Summary The reconstruction readiness guide lists `declare-request` as its third required stage. The documented maintainer evaluator instead accepts `acquire-authority`. Copying the guide's identifier into an otherwise valid conformance input causes a validation error before a report is produced. The same row describes declaring a target, operation, and lifecycle, while the implemented stage requires four grant-related checks. This is a documentation mismatch in the internal conformance guide. ## Affected area Area: Documentation. Interface: Other, the maintainer conformance verifier. Earliest failure stage: Request parsing or validation. Target context: the source-owned synthetic readiness input. The public CLI and MCP have no readiness-report operation. ## Runtime or environment Source checkout at c22111eca2c4bc84a084f12711f405b3e7422a40, using its existing cached runtime build, and the installed published `rea-agents` 6.4.0 package were checked separately. Both probes used Node.js 24.21.0 on darwin arm64, within the package's supported runtime range. The contributor pin is Node.js 24.18.0 and was not exercised. The guide at release tag `rea-agents-6.4.0`, commit a56f7bb668ab23fec8d33f7af353ac7ed2fe1895, was byte-identical to the checkout guide; the npm package omits the guide but contains the evaluator, schema, and synthetic example. ## Steps to reproduce Read the third row of the Required stages table in `docs/reconstruction-readiness.md`. It names `declare-request` and describes carrying the exact target, operation, and lifecycle in the request before launch. From a checkout with its runtime already built, run the following script. For the runtime comparison, run the same script from the installed package root. ```sh node --input-type=module <<'JS' import assert from "node:assert/strict"; import { RECONSTRUCTION_READINESS_EXAMPLE as example } from "./dist/contracts/reconstructionReadinessExample.js"; import { reconstructionReadinessInputSchema as schema } from "./dist/domain/reconstructionReadinessSchemas.js"; import { createReconstructionReadinessReport as evaluate } from "./dist/domain/reconstructionReadiness.js"; import { READINESS_REQUIRED_CHECKS as checks } from "./dist/domain/reconstructionReadinessJourneyFindings.js"; assert.equal(schema.safeParse(example).success, true); assert.equal(evaluate(example).status, "pass"); console.log("example: accepted, report pass"); const input = structuredClone(example); const stage = input.stages.find(row => row.stage_id === "acquire-authority"); assert.ok(stage); stage.stage_id = "declare-request"; const parsed = schema.safeParse(input); assert.equal(parsed.success, false); console.log("documented ID:", parsed.error.issues[0].code, parsed.error.issues[0].path.join(".")); assert.throws(() => evaluate(input), /Invalid option/); stage.stage_id = "acquire-authority"; assert.equal(evaluate(input).status, "pass"); console.log("actual ID: accepted, report pass"); console.log("required checks:", checks["acquire-authority"].join(", ")); for (const checkId of checks["acquire-authority"]) { const control = structuredClone(example); const authority = control.stages.find(row => row.stage_id === "acquire-authority"); authority.checks = authority.checks.filter(check => check.check_id !== checkId); assert.equal(schema.safeParse(control).success, true); const report = evaluate(control); assert.equal(report.status, "fail"); assert.ok(report.findings.some(finding => finding.code === "missing-stage-check" && finding.stage_id === "acquire-authority" && finding.detail.includes(checkId))); } console.log("each required-check omission: report fail"); JS ``` ## Expected behavior The guide's required-stage table should describe the stages and checks accepted by the conformance contract it documents. Its third row should allow a maintainer to recognize the actual stage and understand its required proof. The guide explicitly presents this as an internal project verifier using a public typed synthetic input. ## Actual behavior The script produced the following output in both builds, with exit status zero because it asserts the observed mismatch: ```text example: accepted, report pass documented ID: invalid_value stages.2.stage_id actual ID: accepted, report pass required checks: missing-scope-reported, narrow-grant-resumed, expansion-reprompted, denial-launched-nothing each required-check omission: report fail ``` The invalid identifier also throws from the evaluator before report creation. Reading all nine documented identifiers against the enum found exactly one rejected identifier, `declare-request`. The unchanged example produces nine passing required stages and zero findings. The built evaluator behaves consistently with its schema; the contrary observation is the guide's stage row. ## Evidence - Expected source: `docs/reconstruction-readiness.md:27` defines the internal project conformance contract, `:33` introduces the Required stages table, and `:47` requires every stage and check exactly once. `src/domain/reconstructionReadinessSchemas.ts:23` defines the nine accepted stage IDs and `:225` requires nine unique stages. `src/domain/reconstructionReadinessJourneyFindings.ts:26` defines the four authority checks. - Failure source: `docs/reconstruction-readiness.md:39` names `declare-request` and describes request declaration. The executed script above observes its rejection at `stages.2.stage_id` in both runtime builds, while the actual stage passes and each required-check omission fails. - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete The direct calls use the same built example and evaluator imported by `scripts/verify-reconstruction-readiness.mjs:11` and `:14`; that verifier clones the example at `:68` before evaluating it at `:98`. The fixture's grants, outcomes, provider identities, and checks are synthetic assertions. No real Hopper, Ghidra, IDA, or application runtime was exercised. The full maintainer verifier and CI artifacts were not run. There is no demonstrated production path that consumes the Markdown table as input, so this report makes no claim that ordinary CLI/MCP readiness or provider behavior fails. The live hosted documentation deployment was not inspected. ## Restoration check Check that every identifier in the Required stages table agrees with the maintained conformance schema and example, and that the third row's proof describes the checks required for that stage. An otherwise valid input using the documented identifiers should validate. Retain the controls that the valid example passes and that omitting each required authority check produces a failing report. Restore documentation and contract agreement without weakening readiness validation; the implementation and wording are left open. ## Triage assessment - Impact level: P3 - Assessment status: supported - Impact basis: The guide contains an incorrect stage identifier and proof description. The evaluator rejects the copied identifier with an error listing the accepted values, and no incorrect readiness verdict or real-provider failure was observed. The verified consequence is misleading maintainer documentation. - Workaround status: available - Workaround basis: Use the stage identifier and required checks from the checked-in synthetic example or schema. This was executed in both builds and produced a passing report without any code or configuration change.

bsakaguchi

2026-10-15 18:27:43 +00:00

closed this issue
added the
area: runtime

bug
labels

bsakaguchi referenced this issue

2026-10-17 21:09:09 +00:00

[PR #1160] [MERGED] feat(javascript): report observed export property presence #2694

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#725

No description provided.

Rows
Columns