docs(sdd): bootstrap react-widgets specifications - #1468
Conversation
|
This pull request is automatically being deployed by Amplify Hosting (learn more). |
akulakum
left a comment
akulakum
left a comment
There was a problem hiding this comment.
SDD spec-validation review
Verdict: Blocked (methodology/process gates — doc content quality is otherwise strong)
Blocking
validation.source_commitis base SHA, not PR HEAD- Missing
validation.statuswhile docs claim validation passed - No reviewable conformance / questionnaire / source-fidelity evidence for reconcile bootstrap
- PR template incomplete;
validatedlabel premature
Important
- Restore template metadata HTML blocks on all generated Markdown files
- Sync module spec Validation status rows with manifest after re-validation
Passed checks
- Comprehensive
CONTRACTS.md - K1 Blocking in
REVIEW_CHECKLIST.md - Honest reconcile handling of stale README/event examples
- Detailed module specs with error sections where profiles require them
Please address inline comments and re-run independent spec-validator at 990470ca before merge.
| "runtime_fallback_tier": "different-runtime", | ||
| "minimum_independence": "different-runtime", | ||
| "blocking_severities": ["Blocking"], | ||
| "source_commit": "145a23ef33af4e74d8790832062d9910cd66b3de", |
There was a problem hiding this comment.
validation.source_commit is set to the merge-base SHA (145a23ef…), not this PR's HEAD (990470ca…). That makes the validation record non-reproducible against the docs being reviewed.
Please update the full validation block atomically after re-validation at HEAD:
source_commit:990470cac7cee8abecac62ad385cbdc6adb85412validation.status:pass-with-warningsorblocked(not omitted)validator_runtime,validator_run_id,runtime_fallback_tier, etc.
Do not update only source_commit while leaving the old validator_run_id.
There was a problem hiding this comment.
Manifest source commit and validation provenance
Fixed locally. .sdd/manifest.json now includes the independently validated commit, Cursor runtime, run ID, validation date, result, and finding counts.
| { | ||
| "path": "packages/node_modules/@webex/widget-space/", | ||
| "coverage_status": "Partial", | ||
| "coverage_evidence": "Documentation assessment 94%: public exports, events, configuration, state, UI, error paths, and journey intent are covered; independent Cursor validation passed, while the last-five-PR drift gate still blocks promotion.", |
There was a problem hiding this comment.
All modules show 91–96% documentation scores but remain Partial. That may be correct (promotion-history / drift gates), but it is not obvious from the PR alone.
Please add a short note in the PR description explaining why high scores still map to Partial (e.g. last-five-PR drift gate, characterization gaps, promotion history).
There was a problem hiding this comment.
Clarified that documentation coverage is high, but modules remain Partial because some evidence is still weak/characterization-based and the five-PR promotion requirement is not yet satisfied.
|
|
||
| --- | ||
|
|
||
| Per-module coverage state lives in `.sdd/manifest.json` and is mirrored in `ai-docs/SPEC_INDEX.md`. Independent Cursor validation passed on 2026-07-23; the bootstrap specs remain `Partial` until their documented weak-evidence gaps and the promotion-history gate are satisfied. |
There was a problem hiding this comment.
This states "Independent Cursor validation passed on 2026-07-23," but .sdd/manifest.json has no validation.status and source_commit points at base, not HEAD.
Please align narrative with committed validation metadata, or downgrade the claim until validation at 990470ca is recorded.
There was a problem hiding this comment.
Updated to match the manifest and clearly distinguish Codex generation from independent Cursor validation.
| | Coverage score | 93% assessed 2026-07-22; enhancer order, host APIs, auth, teardown, and demo boundaries covered | | ||
| | Generated from | `module-spec` @ SDLC template library `0.2.1` | | ||
| | generated_by / approved_by / updated_at | `codex-desktop` / repository owner / 2026-07-23 | | ||
| | Validation status | independent Cursor validation passed on 2026-07-23 with zero Blocking findings | |
There was a problem hiding this comment.
Metadata says "independent Cursor validation passed … zero Blocking findings," but manifest validation metadata is incomplete and not tied to HEAD.
Please sync Validation status rows in all module specs with committed manifest after re-validation, e.g.:
pass-with-warnings, validator codex-agent-session, assessed YYYY-MM-DD (0 blocking)
Keep approved_by: pending PR approval until merge if still draft. (Same comment applies to all ai-docs/modules/*-spec.md files.)
There was a problem hiding this comment.
Updated all 10 module specifications with consistent validation results. approved_by remains pending PR approval, as requested.
| "blocking_severities": ["Blocking"], | ||
| "source_commit": "145a23ef33af4e74d8790832062d9910cd66b3de", | ||
| "base_ref": "master", | ||
| "head_ref": "react-widgets-migrate-into-sdd-bootstrap" |
There was a problem hiding this comment.
The manifest records validator runtime/run id but has no validation.status. Meanwhile AGENTS.md and module specs say "Independent Cursor validation passed."
Either:
- Record the approved verdict in manifest (
pass-with-warnings/pass/blocked), or - Change doc wording to "validation pending" until Session B metadata is committed at HEAD.
Same issue fixed in webex/components#859.
There was a problem hiding this comment.
Added status: pass-with-warnings with 0 blocking findings.
| @@ -0,0 +1,113 @@ | |||
| # AGENTS.md — react-widgets | |||
There was a problem hiding this comment.
These generated docs are missing the hidden template metadata block (Template, Template-ID, Generates, library version, last updated). Footer Generated from rows are helpful but do not replace the template-library provenance block.
Please restore it across all generated Markdown files (standing docs, patterns, rules, module specs, ADRs) per template-library v0.2.1 — same fix required in components#859.
There was a problem hiding this comment.
Added the required hidden template metadata blocks to all 27 template-backed generated documents. Directory README files were excluded because their templates do not define those blocks.
|
|
||
| ## Decision | ||
|
|
||
| Preserve protected source documents unchanged. Reorganize supported meaning into canonical SDD sections, use current source/tests to resolve conflicts, and keep unit-level disposition in ignored source-fidelity inventories. Canonical specs do not embed full-file snapshots. |
There was a problem hiding this comment.
Reconcile mode requires reviewable source-fidelity evidence (A14). This ADR says inventories live only in gitignored .generated/, which reviewers cannot verify from the PR.
Please attach a redacted summary in the PR (unit counts: mapped / stale / conflicting / native-reference) so we can confirm protected READMEs/events/testplan meaning was preserved without full-file snapshots.
There was a problem hiding this comment.
Completed all 10 source-fidelity inventories:
709 total source units
148 placed
412 retained as native references
19 stale
130 not applicable
0 conflicts
0 unresolved
| | `rw.cmd.publish` | build-release-tooling | `npm run publish:components` | CI/registry environment | nonzero on build/publish failure | protected release operation | `package.json`, `scripts/utils/publish.js` | | ||
| | `rw.cmd.release` | build-release-tooling | `npm run release` | standard-version args | nonzero on version/changelog failure | Conventional Commits | `package.json` | | ||
|
|
||
| ## Requires — what this repo depends on |
There was a problem hiding this comment.
The Requires table content is strong, but column headers differ from the template (Schema / detail link, Availability assumption, Fallback on failure, Version floor).
Consider aligning column naming/shape with template-library v0.2.1 for conformance consistency.
There was a problem hiding this comment.
Updated the Requires table headers to exactly match template version v0.2.1.
|
|
||
| | # | Check | When it applies | What it verifies | Severity | | ||
| |---|---|---|---|---| | ||
| | K1 | Regression guard | Any Partial/Untracked module or MODIFIED/REMOVED guarantee | A characterization/targeted baseline protects unchanged behavior with positive and negative cases. | Blocking | |
There was a problem hiding this comment.
K1 is correctly Blocking with positive/negative characterization semantics — matches template v0.2.1. Good improvement vs early components bootstrap drafts.
There was a problem hiding this comment.
This was positive feedback, so no file change was required. Reply: “Thanks for confirming. No change required for this item.”
Reset validation to not-run so Session B can pin HEAD provenance after the 0.2.2 reseed. Co-authored-by: Cursor <cursoragent@cursor.com>
Record the implemented remove(), store/Provider, barrel, and publish-gate semantics so Session B can re-validate against code. Co-authored-by: Cursor <cursoragent@cursor.com>
Align AGENTS.md and RULES.md with current redux-module barrels and not-run validator status. Co-authored-by: Cursor <cursoragent@cursor.com>
Record the independent Codex validator Pass and align standing-doc status so coverage stays Partial. Co-authored-by: Cursor <cursoragent@cursor.com>
|
@codex review |
2 participants
COMPLETES #https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-838196
This pull request addresses
The repository did not have a canonical, code-grounded SDD documentation tree for its widget runtime, packages, state modules, public contracts, build/release tooling, and browser test architecture.
This follow-up also closes the akulakum review threads on this PR and upgrades the generated SDD tree from template-library 0.2.1 to 0.2.2, then records an independent Codex Session B Pass at HEAD-minus-pin.
by making the following changes
TEST_INDEX.md, and.sdd/manifest.jsonrouting..sdd/templates/and upgrades hidden template metadata blocks to template-library 0.2.2 (0aa65d93).ai-docs/SDD_BOOTSTRAP_EVIDENCE.md(A14 reviewable without.generated/paths)..sdd/config/sdd-manifest.schema.jsonthat includestest_index_path,template_library_*,has_submodules, and validation status fields.CONTRACTS.mdRequires columns with the current template headers.widget.remove(callback?)always returns a Promise; the callback path invokes the callback and leaves the Promise pending; the no-callback path resolves.@webex/redux-module-*barrels export actions, reducers, constants, helpers, and/or thunks — not selectors. View selectors live in widget/container packages.withInitialStateskips the Redux Provider whenprops.sparkis supplied.version_and_publishrequiresinstallonly; lint/Jest and Chrome/Firefox journeys are sibling jobs.events.md,@ciscospark/*rename notices,test/journeys/testplan.md).Current HEAD and validation
290710ad—docs(sdd): pin Session B Pass provenance at 548a0312548a0312718835b08faf225187951a05eabc42ba0aa65d93f019e5313ec2ddfac9b0c7352a2882cc)cursor-agentcodex-desktop(different-runtime)validation.statuspasssource_commit548a0312(inspected commit, not the pin commit)validation.source_commitidentifies the commit independently inspected by Codex Session B. The following metadata-only pin (290710ad) records that provenance and aligns standing-doc status so A8 does not regress.Change Type
The following scenarios were tested
Validation and testing
ai-docs/SDD_BOOTSTRAP_EVIDENCE.md..sdd/config/sdd-manifest.schema.json.548a0312: Pass; 0 Blocking, 0 Important, 0 Medium, 0 Minor. Draft report was chat-only (no.generated/write, no PR auto-post).remove(), redux-module barrels/selectors,props.sparkProvider skip, CI publishrequires, AGENTS/RULES leftovers.redux-module-media,redux-module-spaces,redux-module-users, andreact-redux-sparksuites. This documentation-only PR does not modify those modules.Reconcile evidence summary
akulakum review-thread closure (2026-09-03)
validation.source_commit/ SHA drift548a0312; pin records that SHA,status: pass, runtime, counts, and 10 module Validation rows548a0312, modules remain Partialai-docs/SDD_BOOTSTRAP_EVIDENCE.md(not only a review reply)GitHub threads may still show unresolved until the reviewer marks them resolved.
The GAI Coding Policy And Copyright Annotation Best Practices
Checklist before merging